Export vec_locate_sorted_groups() (#1541)

* Rename `vec_order_locs()` to `vec_locate_sorted_groups()`

* Export `vec_locate_sorted_groups()`

* NEWS bullet

Author: DavisVaughan

NAMESPACE

@@ -563,6 +563,7 @@ export(vec_is_empty)
 export(vec_is_list)
 export(vec_list_cast)
 export(vec_locate_matches)
+export(vec_locate_sorted_groups)
 export(vec_match)
 export(vec_math)
 export(vec_math_base)

NEWS.md

@@ -1,5 +1,9 @@
 # vctrs (development version)
 
+* New experimental `vec_locate_sorted_groups()` for returning the locations of
+  groups in sorted order. This is equivalent to, but faster than, calling
+  `vec_group_loc()` and then sorting by the `key` column of the result.
+
 * New experimental `vec_locate_matches()` for locating where each observation
   in one vector matches one or more observations in another vector. It is
   similar to `vec_match()`, but returns all matches by default (rather than just

R/order.R

@@ -176,48 +176,69 @@ vec_sort_radix <- function(x,
   vec_slice(x, idx)
 }
 
-#' Identify ordered groups
+# ------------------------------------------------------------------------------
+
+#' Locate sorted groups
 #'
 #' @description
 #' `r lifecycle::badge("experimental")`
 #'
-#' `vec_order_locs()` returns a data frame containing a `key` column with
-#' sorted unique groups, and a `loc` column with the locations of each
+#' `vec_locate_sorted_groups()` returns a data frame containing a `key` column
+#' with sorted unique groups, and a `loc` column with the locations of each
 #' group in `x`. It is similar to [vec_group_loc()], except the groups are
 #' returned sorted rather than by first appearance.
 #'
+#' @details
+#' `vec_locate_sorted_groups(x)` is equivalent to, but faster than:
+#'
+#' ```
+#' info <- vec_group_loc(x)
+#' vec_slice(info, vec_order(info$key))
+#' ```
+#'
 #' @inheritParams order-radix
 #'
 #' @return
 #' A two column data frame with size equal to `vec_size(vec_unique(x))`.
-#'   * A `key` column of type `vec_ptype(x)`.
-#'   * A `loc` column of type list, with elements of type integer.
+#' * A `key` column of type `vec_ptype(x)`.
+#' * A `loc` column of type list, with elements of type integer.
 #'
-#' @section Dependencies of `vec_order_locs()`:
+#' @section Dependencies of `vec_locate_sorted_groups()`:
 #' * [vec_proxy_order()]
 #'
+#' @export
+#' @keywords internal
 #' @examples
 #' df <- data.frame(
 #'   g = sample(2, 10, replace = TRUE),
 #'   x = c(NA, sample(5, 9, replace = TRUE))
 #' )
 #'
-#' # `vec_order_locs()` is similar to `vec_group_loc()`, except keys are
-#' # returned ordered rather than by first appearance.
-#' vec_order_locs(df)
+#' # `vec_locate_sorted_groups()` is similar to `vec_group_loc()`, except keys
+#' # are returned ordered rather than by first appearance.
+#' vec_locate_sorted_groups(df)
 #'
 #' vec_group_loc(df)
-#' @noRd
-vec_order_locs <- function(x,
-                           ...,
-                           direction = "asc",
-                           na_value = "largest",
-                           nan_distinct = FALSE,
-                           chr_proxy_collate = NULL) {
+vec_locate_sorted_groups <- function(x,
+                                     ...,
+                                     direction = "asc",
+                                     na_value = "largest",
+                                     nan_distinct = FALSE,
+                                     chr_proxy_collate = NULL) {
   check_dots_empty0(...)
-  .Call(vctrs_order_locs, x, direction, na_value, nan_distinct, chr_proxy_collate)
+
+  .Call(
+    vctrs_locate_sorted_groups,
+    x,
+    direction,
+    na_value,
+    nan_distinct,
+    chr_proxy_collate
+  )
 }
 
+# ------------------------------------------------------------------------------
+
 vec_order_info <- function(x,
                            ...,
                            direction = "asc",

man/vec_locate_sorted_groups.Rd

@@ -127,7 +127,7 @@ extern SEXP vctrs_locate_complete(SEXP);
 extern SEXP vctrs_detect_complete(SEXP);
 extern SEXP vctrs_normalize_encoding(SEXP);
 extern SEXP vctrs_order(SEXP, SEXP, SEXP, SEXP, SEXP);
-extern SEXP vctrs_order_locs(SEXP, SEXP, SEXP, SEXP, SEXP);
+extern SEXP vctrs_locate_sorted_groups(SEXP, SEXP, SEXP, SEXP, SEXP);
 extern SEXP vctrs_order_info(SEXP, SEXP, SEXP, SEXP, SEXP, SEXP);
 extern SEXP vctrs_unrep(SEXP);
 extern SEXP vctrs_fill_missing(SEXP, SEXP, SEXP);
@@ -295,7 +295,7 @@ static const R_CallMethodDef CallEntries[] = {
   {"vctrs_detect_complete",                 (DL_FUNC) &vctrs_detect_complete, 1},
   {"vctrs_normalize_encoding",              (DL_FUNC) &vctrs_normalize_encoding, 1},
   {"vctrs_order",                           (DL_FUNC) &vctrs_order, 5},
-  {"vctrs_order_locs",                      (DL_FUNC) &vctrs_order_locs, 5},
+  {"vctrs_locate_sorted_groups",            (DL_FUNC) &vctrs_locate_sorted_groups, 5},
   {"vctrs_order_info",                      (DL_FUNC) &vctrs_order_info, 6},
   {"vctrs_unrep",                           (DL_FUNC) &vctrs_unrep, 1},
   {"vctrs_fill_missing",                    (DL_FUNC) &vctrs_fill_missing, 3},

src/init.c

@@ -211,28 +211,45 @@ SEXP vec_order(SEXP x,
 
 // -----------------------------------------------------------------------------
 
-static SEXP vec_order_locs(SEXP x,
-                           SEXP direction,
-                           SEXP na_value,
-                           bool nan_distinct,
-                           SEXP chr_proxy_collate);
+static SEXP vec_locate_sorted_groups(SEXP x,
+                                     SEXP direction,
+                                     SEXP na_value,
+                                     bool nan_distinct,
+                                     SEXP chr_proxy_collate);
 
 // [[ register() ]]
-SEXP vctrs_order_locs(SEXP x,
-                      SEXP direction,
-                      SEXP na_value,
-                      SEXP nan_distinct,
-                      SEXP chr_proxy_collate) {
+SEXP vctrs_locate_sorted_groups(SEXP x,
+                                SEXP direction,
+                                SEXP na_value,
+                                SEXP nan_distinct,
+                                SEXP chr_proxy_collate) {
   bool c_nan_distinct = parse_nan_distinct(nan_distinct);
-  return vec_order_locs(x, direction, na_value, c_nan_distinct, chr_proxy_collate);
-}
 
+  return vec_locate_sorted_groups(
+    x,
+    direction,
+    na_value,
+    c_nan_distinct,
+    chr_proxy_collate
+  );
+}
 
 static
-SEXP vec_order_locs(SEXP x, SEXP direction, SEXP na_value, bool nan_distinct, SEXP chr_proxy_collate) {
+SEXP vec_locate_sorted_groups(SEXP x,
+                              SEXP direction,
+                              SEXP na_value,
+                              bool nan_distinct,
+                              SEXP chr_proxy_collate) {
   const bool chr_ordered = true;
 
-  SEXP info = KEEP(vec_order_info(x, direction, na_value, nan_distinct, chr_proxy_collate, chr_ordered));
+  SEXP info = KEEP(vec_order_info(
+    x,
+    direction,
+    na_value,
+    nan_distinct,
+    chr_proxy_collate,
+    chr_ordered
+  ));
 
   SEXP o = r_list_get(info, 0);
   const int* p_o = r_int_cbegin(o);

src/order.c

@@ -1138,9 +1138,9 @@ test_that("can order data frames (and subclasses) with matrix columns", {
 })
 
 # ------------------------------------------------------------------------------
-# vec_order_locs()
+# vec_locate_sorted_groups()
 
-test_that("`vec_order_locs()` is working", {
+test_that("`vec_locate_sorted_groups()` is working", {
   x <- c(1, 3, 1, 5, 2, 5, 1)
 
   expect <- new_data_frame(
@@ -1150,7 +1150,7 @@ test_that("`vec_order_locs()` is working", {
     )
   )
 
-  expect_identical(vec_order_locs(x), expect)
+  expect_identical(vec_locate_sorted_groups(x), expect)
 })
 
 test_that("`chr_proxy_collate` can result in keys being seen as identical", {
@@ -1160,8 +1160,8 @@ test_that("`chr_proxy_collate` can result in keys being seen as identical", {
   x_expect <- data_frame(key = c("A", "b"), loc = list(c(2L, 3L), 1L))
   y_expect <- data_frame(key = c("a", "b"), loc = list(c(2L, 3L), 1L))
 
-  expect_identical(vec_order_locs(x, chr_proxy_collate = tolower), x_expect)
-  expect_identical(vec_order_locs(y, chr_proxy_collate = tolower), y_expect)
+  expect_identical(vec_locate_sorted_groups(x, chr_proxy_collate = tolower), x_expect)
+  expect_identical(vec_locate_sorted_groups(y, chr_proxy_collate = tolower), y_expect)
 })
 
 # ------------------------------------------------------------------------------