update UI

R/base.R

@@ -48,7 +48,7 @@
 #'     by the the 'Mbed TLS' library under the Trusted Firmware Project.
 #'
 #' @param x an object.
-#' @param size [default 256L] output size (bits) of the returned hash - uses the
+#' @param bits [default 256L] output size of the returned hash - uses the
 #'     relevant SHA-3 hash function if one of 224, 256, 384 or 512, or
 #'     else the SHAKE256 extendable-output function (XOF) for arbitrary values.
 #'     The supplied value must be between 8 and 2^24, and is automatically
@@ -73,7 +73,7 @@
 #'     a raw vector if 'convert' is FALSE.
 #'     
 #'     To hash to integer values, set convert to NA. For a single integer value
-#'     set size to '32'. These values may be supplied as random seeds for R's
+#'     set 'bits' to 32. These values may be supplied as random seeds for R's
 #'     pseudo random number generators (RNGs).
 #'
 #' @examples
@@ -84,17 +84,17 @@
 #' sha3("secret base", convert = FALSE)
 #' 
 #' # SHA3-224 hash as character string:
-#' sha3("secret base", size = 224)
+#' sha3("secret base", bits = 224)
 #' 
 #' # SHA3-384 hash as character string:
-#' sha3("secret base", size = 384)
+#' sha3("secret base", bits = 384)
 #' 
 #' # SHA3-512 hash as character string:
-#' sha3("secret base", size = 512)
+#' sha3("secret base", bits = 512)
 #' 
 #' # SHAKE256 hash to integer:
-#' sha3("secret base", size = 32L, convert = NA)
+#' sha3("secret base", bits = 32L, convert = NA)
 #'
 #' @export
 #'
-sha3 <- function(x, size = 256L, convert = TRUE) .Call(secretbase_sha3, x, size, convert)
+sha3 <- function(x, bits = 256L, convert = TRUE) .Call(secretbase_sha3, x, bits, convert)

README.Rmd

@@ -48,8 +48,8 @@ install.packages("secretbase", repos = "https://shikokuchuo.r-universe.dev")
 
 To use:
 
- - SHA-3 cryptographic hash algorithm, specify 'size' as one of `224`, `256`, `384` or `512`
- - SHAKE256 extendable-output function (XOF), specify any other arbitrary output size
+ - SHA-3 cryptographic hash algorithm, specify 'bits' as one of `224`, `256`, `384` or `512`
+ - SHAKE256 extendable-output function (XOF), specify any other arbitrary bit length
 
 ```{r secretbase}
 library(secretbase)
@@ -58,9 +58,9 @@ sha3("secret base")
 
 sha3("secret base", convert = FALSE)
 
-sha3("秘密の基地の中", size = 224)
+sha3("秘密の基地の中", bits = 224)
 
-sha3("", size = 512)
+sha3("", bits = 512)
 ```
 
 Hash arbitrary R objects:
@@ -69,25 +69,25 @@ Hash arbitrary R objects:
  - ensures portability by always using R serialization version 3, big endian representation, skipping the headers
 
 ```{r streaming}
-sha3(data.frame(a = 1, b = 2), size = 160)
+sha3(data.frame(a = 1, b = 2), bits = 160)
 
 sha3(NULL)
 ```
 
 To hash to integer:
 
- - specify convert as `NA`
- - specify size of `32` for a single integer value
+ - specify 'convert' as `NA`
+ - specify 'bits' as `32` for a single integer value
 
 ```{r readinteger}
 sha3("秘密の基地の中", convert = NA)
 
-sha3("秘密の基地の中", size = 32, convert = NA)
+sha3("秘密の基地の中", bits = 32, convert = NA)
 ```
 
 These values may be supplied as deterministic (but indistinguishable from random) seeds for R's pseudo random number generators (RNGs).
 
-For use in parallel computing, this is a valid method for reducing to a negligible probability that RNGs in each process may overlap. This is particularly useful when first-best alternatives such as using recursive streams are too expensive or unable to preserve reproducibility. <sup>[1]</sup>
+For use in parallel computing, this is a valid method for reducing to a negligible probability that RNGs in each process may overlap. This may be especially suitable when first-best alternatives such as using recursive streams are too expensive or unable to preserve reproducibility. <sup>[1]</sup>
 
 ### References
 

README.md

@@ -43,10 +43,10 @@ install.packages("secretbase", repos = "https://shikokuchuo.r-universe.dev")
 
 To use:
 
-- SHA-3 cryptographic hash algorithm, specify ‘size’ as one of `224`,
+- SHA-3 cryptographic hash algorithm, specify ‘bits’ as one of `224`,
   `256`, `384` or `512`
 - SHAKE256 extendable-output function (XOF), specify any other arbitrary
-  output size
+  bit length
 
 ``` r
 library(secretbase)
@@ -58,10 +58,10 @@ sha3("secret base", convert = FALSE)
 #>  [1] a7 21 d5 75 70 e7 ce 36 6a de e2 fc cb e9 77 07 23 c6 e3 62 25 49 c3 1c 7c
 #> [26] ab 9d bb 4a 79 55 20
 
-sha3("秘密の基地の中", size = 224)
+sha3("秘密の基地の中", bits = 224)
 #> [1] "d9e291d0c9f3dc3007dc0c111aea0b6a938929c8b4766332d8ea791a"
 
-sha3("", size = 512)
+sha3("", bits = 512)
 #> [1] "a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26"
 ```
 
@@ -73,7 +73,7 @@ Hash arbitrary R objects:
   endian representation, skipping the headers
 
 ``` r
-sha3(data.frame(a = 1, b = 2), size = 160)
+sha3(data.frame(a = 1, b = 2), bits = 160)
 #> [1] "bc5a411f87ef083296c60d6557f189b62ff9e7e6"
 
 sha3(NULL)
@@ -82,26 +82,26 @@ sha3(NULL)
 
 To hash to integer:
 
-- specify convert as `NA`
-- specify size of `32` for a single integer value
+- specify ‘convert’ as `NA`
+- specify ‘bits’ as `32` for a single integer value
 
 ``` r
 sha3("秘密の基地の中", convert = NA)
 #> [1]  1706118765  1394124073 -1208837861  -385136950  -692327823  -291994555
 #> [7]   528021721  -384171368
 
-sha3("秘密の基地の中", size = 32, convert = NA)
+sha3("秘密の基地の中", bits = 32, convert = NA)
 #> [1] 2000208511
 ```
 
 These values may be supplied as deterministic (but indistinguishable
 from random) seeds for R’s pseudo random number generators (RNGs).
 
 For use in parallel computing, this is a valid method for reducing to a
-negligible probability that RNGs in each process may overlap. This is
-particularly useful when first-best alternatives such as using recursive
-streams are too expensive or unable to preserve reproducibility.
-<sup>\[1\]</sup>
+negligible probability that RNGs in each process may overlap. This may
+be especially suitable when first-best alternatives such as using
+recursive streams are too expensive or unable to preserve
+reproducibility. <sup>\[1\]</sup>
 
 ### References
 

src/secret.c

@@ -235,19 +235,19 @@ static SEXP nano_hash_char(unsigned char *buf, const size_t sz) {
 
 // secretbase - exported functions ---------------------------------------------
 
-SEXP secretbase_sha3(SEXP x, SEXP size, SEXP convert) {
+SEXP secretbase_sha3(SEXP x, SEXP bits, SEXP convert) {
 
   const int conv = LOGICAL(convert)[0];
-  const int bits = Rf_asInteger(size);
-  if (bits < 8 || bits > (1 << 24))
-    Rf_error("'size' must be between 8 and 2^24");
+  const int size = Rf_asInteger(bits);
+  if (size < 8 || size > (1 << 24))
+    Rf_error("'bits' must be between 8 and 2^24");
 
-  const size_t outlen = (size_t) (bits / 8);
+  const size_t outlen = (size_t) (size / 8);
   unsigned char output[outlen];
   mbedtls_sha3_id id;
   SEXP out;
 
-  switch (bits) {
+  switch (size) {
   case 224:
     id = MBEDTLS_SHA3_224; break;
   case 256:

tests/tests.R

@@ -9,28 +9,24 @@ test_equal(sha3("", 224), "6b4e03423667dbb73b6e15454f0eb1abd4597f9a1b078e3f5b5a6
 test_equal(sha3("", 256), "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a")
 test_equal(sha3("", 384), "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004")
 test_equal(sha3("", 512), "a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26")
-
 # SHA-3 tests:
 test_equal(sha3("secret base"), "a721d57570e7ce366adee2fccbe9770723c6e3622549c31c7cab9dbb4a795520")
-test_equal(sha3("secret base", size = 224), "5511b3469d3f1a87b62ce8f0d2dc9510ec5e4547579b8afb32052f99")
-test_equal(sha3("secret base", size = 384L), "79e54f865df004dde10dc2f61baf47eb4637c68d87a2baeb7fe6bc0ac983c2154835ec7deb49b16c246c0dc1d43e32f9")
-test_equal(sha3("secret base", size = "512"), "31076b4690961320a761be0951eeaa9efd0c75c37137a2a50877cbebb8afcc6d7927c41a120ae8fa73fdce8fff726fcbc51d448d020240bc7455963a16e639b1")
+test_equal(sha3("secret base", bits = 224), "5511b3469d3f1a87b62ce8f0d2dc9510ec5e4547579b8afb32052f99")
+test_equal(sha3("secret base", bits = 384L), "79e54f865df004dde10dc2f61baf47eb4637c68d87a2baeb7fe6bc0ac983c2154835ec7deb49b16c246c0dc1d43e32f9")
+test_equal(sha3("secret base", bits = "512"), "31076b4690961320a761be0951eeaa9efd0c75c37137a2a50877cbebb8afcc6d7927c41a120ae8fa73fdce8fff726fcbc51d448d020240bc7455963a16e639b1")
 test_that(sha3("secret base", convert = FALSE), is.raw)
-
 # SHAKE256 tests:
-test_equal(sha3("secret base", size = 32), "995ebac1")
-test_equal(sha3(sha3("secret base", size = 32, convert = FALSE), size = 32), "4d872090")
-test_that(sha3(rnorm(1e5), size = 8196), is.character)
-test_equal(sha3("secret base", size = 32, convert = NA), -1044750695L)
-
+test_equal(sha3("secret base", bits = 32), "995ebac1")
+test_equal(sha3(sha3("secret base", bits = 32, convert = FALSE), bits = 32), "4d872090")
+test_that(sha3(rnorm(1e5), bits = 8196), is.character)
+test_equal(sha3("secret base", bits = 32, convert = NA), -1044750695L)
 # Streaming serialization tests:
 test_equal(sha3(data.frame(a = 1, b = 2)), "05d4308e79d029b4af5604739ecc6c4efa1f602a23add0ed2d247b7407d4832f")
 test_equal(sha3(c("secret", "base")), "d906024c71828a10e28865a80f5e81d2cb5cd74067d44852d7039813ba62b0b6")
 test_equal(sha3(NULL), "b3e37e4c5def1bfb2841b79ef8503b83d1fed46836b5b913d7c16de92966dcee")
 test_equal(sha3(substitute()), "9d31eb41cfb721b8040c52d574df1aacfc381d371c2b933f90792beba5160a57")
-test_equal(sha3(`class<-`(sha3(character(), size = 192, convert = FALSE), "hash"), size = "32", convert = NA), -111175135L)
-
+test_equal(sha3(`class<-`(sha3(character(), bits = 192, convert = FALSE), "hash"), bits = "32", convert = NA), -111175135L)
 # Error handling tests:
-test_error(sha3("secret base", size = 0), "'size' must be between 8 and 2^24")
-test_error(sha3("secret base", size = -1), "'size' must be between 8 and 2^24")
-test_error(sha3("secret base", size = 2^24 + 1), "'size' must be between 8 and 2^24")
+test_error(sha3("secret base", bits = 0), "'bits' must be between 8 and 2^24")
+test_error(sha3("secret base", bits = -1), "'bits' must be between 8 and 2^24")
+test_error(sha3("secret base", bits = 2^24 + 1), "'bits' must be between 8 and 2^24")