Add hash() (#1058)

- Modelled after [xxhashlite](https://github.com/coolbutuseless/xxhashlite) from @coolbutuseless
- Special thanks to the authors of the [xxHash](https://github.com/Cyan4973/xxHash) C library

Author: DavisVaughan

DESCRIPTION

@@ -7,6 +7,14 @@ Description: A toolbox for working with base types, core R features
 Authors@R: c(
     person("Lionel", "Henry", ,"[email protected]", c("aut", "cre")),
     person("Hadley", "Wickham", ,"[email protected]", "aut"),
+    person(given = "mikefc",
+           email = "[email protected]", 
+           role = "cph", 
+           comment = "Hash implementation based on Mike's xxhashlite"),
+    person(given = "Yann",
+           family = "Collet",
+           role = "cph", 
+           comment = "Author of the embedded xxHash library"),
     person("RStudio", role = "cph")
     )
 License: MIT + file LICENSE

LICENSE.note

@@ -0,0 +1,33 @@
+The implementation of `hash()` uses the xxHash library from Yann Collet, which
+is released under the BSD 2-Clause license. This library has been embedded into
+rlang, without modification, in `src/internal/xxhash/`. A copy of the
+BSD 2-Clause license is provided below.
+
+BSD 2-Clause License -----------------------------------------------------------
+
+xxHash Library
+Copyright (c) 2012-2020 Yann Collet
+All rights reserved.
+
+BSD 2-Clause License (https://www.opensource.org/licenses/bsd-license.php)
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this
+  list of conditions and the following disclaimer in the documentation and/or
+  other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

NAMESPACE

@@ -255,6 +255,7 @@ export(global_env)
 export(global_frame)
 export(has_length)
 export(has_name)
+export(hash)
 export(have_name)
 export(inform)
 export(inherits_all)

NEWS.md

@@ -1,5 +1,10 @@
 # rlang (development version)
 
+* New `hash()` function to generate 128-bit hashes for arbitrary R objects
+  using the xxHash library. The implementation is modeled after
+  [xxhashlite](https://github.com/coolbutuseless/xxhashlite), created
+  by @coolbutuseless.
+
 * New `check_installed()` function. Unlike `is_installed()`, it asks
   the user whether to install missing packages. If the user accepts,
   the packages are installed with `pak::pkg_install()` if available,

R/hash.R

@@ -0,0 +1,26 @@
+#' Hash an object
+#'
+#' @description
+#' `hash()` hashes an arbitrary R object.
+#'
+#' The generated hash is guaranteed to be reproducible across platforms, but
+#' not across R versions.
+#'
+#' @details
+#' `hash()` uses the XXH128 hash algorithm of the xxHash library, which
+#' generates a 128-bit hash. It is implemented as a streaming hash, which
+#' generates the hash with minimal extra memory usage.
+#'
+#' Objects are converted to binary using R's native serialization tools.
+#' On R >= 3.5.0, serialization version 3 is used, otherwise version 2 is used.
+#' See [serialize()] for more information about the serialization version.
+#'
+#' @param x An object.
+#'
+#' @export
+#' @examples
+#' hash(c(1, 2, 3))
+#' hash(mtcars)
+hash <- function(x) {
+  .Call(rlang_hash, x)
+}

man/hash.Rd

@@ -41,6 +41,7 @@ internal-files = \
         internal/expr-interp.c \
         internal/expr-interp-rotate.c \
         internal/fn.c \
+        internal/hash.c \
         internal/internal.c \
         internal/nse-defuse.c \
         internal/quo.c \

src/Makevars

@@ -143,6 +143,7 @@ extern sexp* rlang_raw_deparse_str(sexp*, sexp*, sexp*);
 extern sexp* rlang_env_browse(sexp*, sexp*);
 extern sexp* rlang_env_is_browsed(sexp*);
 extern sexp* rlang_ns_registry_env();
+extern sexp* rlang_hash(sexp*);
 
 
 // Library initialisation defined below
@@ -323,6 +324,7 @@ static const r_callable r_callables[] = {
   {"rlang_env_browse",                  (r_fn_ptr) &rlang_env_browse, 2},
   {"rlang_env_is_browsed",              (r_fn_ptr) &rlang_env_is_browsed, 1},
   {"rlang_ns_registry_env",             (r_fn_ptr) &rlang_ns_registry_env, 0},
+  {"rlang_hash",                        (r_fn_ptr) &rlang_hash, 1},
   {NULL, NULL, 0}
 };
 

src/export/init.c

@@ -9,6 +9,7 @@
 #include "internal/expr-interp.c"
 #include "internal/expr-interp-rotate.c"
 #include "internal/fn.c"
+#include "internal/hash.c"
 #include "internal/internal.c"
 #include "internal/nse-defuse.c"
 #include "internal/quo.c"