man-roxygen/class_schema_setops.R

In jeanmathieupotvin/cargo: Data containers, schemas and prototypes

# class_schema_setops.R


#' @name Schema-setops
#'
#' @title
#' Schema: set operations for schemas
#'
#' @description
#' Similar to base \R set functions, but for objects of class
#' [`Schema`][Schema-class]. Functions [sintersect()], [sdiff()] and [sequal()]
#' compare any \R object that has a defined [as_schema()] method to an object
#' of class [`Schema`][Schema-class].
#'
#' @param x an object of class [`Schema`][Schema-class] or any other \R object
#' that has a defined [as_schema()] method.
#' @param y an object of class [`Schema`][Schema-class].
#' @param what a character equal to:
#'
#' * `"inputs"` (match inputs only),
#' * `"types"` (match prototypes' classes of common inputs) or
#' * `"strict"` (for [sequal()] only, match everything).
#'
#' Argument `what` is matched partially and can be abbreviated
#'
#' @details
#' These functions compare the structure of `x` to what `y` dictates. Comparisons
#' are always done with respect to `y`:
#'
#' * [sintersect()] returns the common inputs or prototypes between `y` and `x`.
#' * [sdiff()] returns the differences between inputs or prototypes of `y` and
#' `x`. If the underlying schema of `x` is a superset of `y`, then only the
#' intersection of `y` and `x` is looked at. The rest is ignored.
#'
#' Function [sequal()] is a wrapper to [sdiff()]. A `"strict"` comparison
#' checks both inputs and prototypes. If the intersection of `y` and `x` is `y`,
#' then `x` and `y` are considered to be equal schemas.
#'
#' ## Method dispatch
#'
#' If `x` is not an object of class [`Schema`][Schema-class], it it coerced to
#' such an object by using the appropriate [as_schema()] method. This is why
#' set functions are not generic functions, method dispath is implicitely done
#' by [as_schema()].
#'
#' ## Comparing prototypes
#'
#' Comparing prototypes makes sense only for common inputs to `y` and `x`.
#' Consequently, comparing prototypes triggers a comparison between inputs
#' first.
#'
#' @return
#' Functions [sintersect()] and [sdiff()] return a named character, possibly
#' empty. The output of [sintersect()] is the set of common inputs (in the sense
#' given by `what`) to `y` and `x`, while the output of [sdiff()] is the set of
#' inputs that are in `y` but not in `x`.
#'
#' Function [sequal()] returns a logical. A `TRUE` implies equality in the sense
#' given by `what`.
#'
#' @family Schema