Comparison and order proxy — vec_proxy

vec_proxy_compare() and vec_proxy_order() return proxy objects, i.e. an atomic vector or data frame of atomic vectors.

For vctrs_vctr objects:

vec_proxy_compare() determines the behavior of <, >, >= and <= (via vec_compare()); and min(), max(), median(), and quantile().
vec_proxy_order() determines the behavior of order() and sort() (via xtfrm()).

Usage

vec_proxy_compare(x, ...)

vec_proxy_order(x, ...)

Arguments

x: A vector x.
...: These dots are for future extensions and must be empty.

Value

A 1d atomic vector or a data frame.

Details

The default method of vec_proxy_compare() assumes that all classes built on top of atomic vectors or records are comparable. Internally the default calls vec_proxy_equal(). If your class is not comparable, you will need to provide a vec_proxy_compare() method that throws an error.

The behavior of vec_proxy_order() is identical to vec_proxy_compare(), with the exception of lists. Lists are not comparable, as comparing elements of different types is undefined. However, to allow ordering of data frames containing list-columns, the ordering proxy of a list is generated as an integer vector that can be used to order list elements by first appearance.

If a class implements a vec_proxy_compare() method, it usually doesn't need to provide a vec_proxy_order() method, because the latter is implemented by forwarding to vec_proxy_compare() by default. Classes inheriting from list are an exception: due to the default vec_proxy_order() implementation, vec_proxy_compare() and vec_proxy_order() should be provided for such classes (with identical implementations) to avoid mismatches between comparison and sorting.

Dependencies

vec_proxy_equal() called by default in vec_proxy_compare()
vec_proxy_compare() called by default in vec_proxy_order()

Examples

# Lists are not comparable
x <- list(1:2, 1, 1:2, 3)
try(vec_compare(x, x))
#> Error in vec_proxy_compare(x = x) : 
#>   `vec_proxy_compare.list()` not supported.

# But lists are orderable by first appearance to allow for
# ordering data frames with list-cols
df <- new_data_frame(list(x = x))
vec_sort(df)
#>      x
#> 1 1, 2
#> 2 1, 2
#> 3    1
#> 4    3