R: Number of observations

vec_size {vctrs} | R Documentation

## Number of observations

### Description

`vec_size(x)` returns the size of a vector. `vec_is_empty()` returns `TRUE` if the size is zero, `FALSE` otherwise.

The size is distinct from the `length()` of a vector because it generalises to the "number of observations" for 2d structures, i.e. it's the number of rows in matrix or a data frame. This definition has the important property that every column of a data frame (even data frame and matrix columns) have the same size. `vec_size_common(...)` returns the common size of multiple vectors.

### Usage

    vec_size(x)

    vec_size_common(..., .size = NULL, .absent = 0L)

    vec_is_empty(x)

### Arguments

`x, ...` | Vector inputs or `NULL`.
`.size` | If `NULL`, the default, the output size is determined by recycling the lengths of all elements of `...`. Alternatively, you can supply `.size` to force a known size; in this case, `x` and `...` are ignored.
`.absent` | The size used when no input is provided, or when all input is `NULL`. If left as `NULL` when no input is supplied, an error is thrown.

### Details

There is no vctrs helper that retrieves the number of columns: as this is a property of the type.

`vec_size()` is equivalent to `NROW()` but has a name that is easier to pronounce, and throws an error when passed non-vector inputs.

### Value

An integer (or double for long vectors).

`vec_size_common()` returns `.absent` if all inputs are `NULL` or absent, `0L` by default.

### Invariants

- `vec_size(dataframe)` == `vec_size(dataframe[[i]])`

- `vec_size(matrix)` == `vec_size(matrix[, i, drop = FALSE])`

- `vec_size(vec_c(x, y))` == `vec_size(x)` + `vec_size(y)`

### The size of NULL

The size of `NULL` is hard-coded to `0L` in `vec_size()`. `vec_size_common()` returns `.absent` when all inputs are `NULL` (if only some inputs are `NULL`, they are simply ignored).

A default size of 0 makes sense because sizes are most often queried in order to compute a total size while assembling a collection of vectors. Since we treat `NULL` as an absent input by principle, we return the identity of sizes under addition to reflect that an absent input doesn't take up any size.

Note that other defaults might make sense under different circumstances. For instance, a default size of 1 makes sense for finding the common size because 1 is the identity of the recycling rules.

### See Also

`vec_slice()` for a variation of `[` compatible with `vec_size()`, and `vec_recycle()` to recycle vectors to common length.

### Examples

    vec_size(1:100)
    vec_size(mtcars)
    vec_size(array(dim = c(3, 5, 10)))

    vec_size_common(1:10, 1:10)
    vec_size_common(1:10, 1)
    vec_size_common(integer(), 1)

[Package vctrs version 0.2.2 Index]