man-roxygen/class_container.R

In jeanmathieupotvin/cargo: Data containers, schemas and prototypes

# class_container.R


#' @name Container-class
#'
#' @title
#' Container: a class to hold data structures
#'
#' @description
#' A general, extensible and flexible container holding data and metadata.
#'
#' @section The Container class:
#' Class `Container` is a general container designed to hold any kind of data
#' in an explicit, formal and rigorous way. It can be viewed as a compound
#' structure type which structure is declared through an instance of the
#' [`Schema`][Schema-class] class.
#'
#' @section Advantages of using *Containers*:
#' There are four advantages to using the class.
#'
#' 1. Data manipulation is a seamless hybrid between
#' [`data.frame`][base::data.frame()] and
#' [`data.table`][data.table::data.table()] classes.
#'     * Expression arguments
#' passed to operator [`[`][Container-extractors] are viewed as
#' [`data.table`][data.table::data.table()] statements.
#'     * Non-expression arguments are viewed as classical
#' [`data.frame`][base::data.frame()] statements.
#'
#' 2. A **minimal** expected `table` structure is always enforced for increased
#' reliability. This is fundamental in every automated applications expecting
#' specific information.
#'
#' 3. You don't have to define low-level details and checks. This reduces
#' programming time while adding a negligible cost in compute time.
#'
#' 4. It is easier to share pre-defined Containers with structures
#' defined by [`Schema`][Schema-class] objects.
#'
#' @section Using the class:
#' * Create objects of class `Container` through the constructor function [Container()].
#' * Validate instances of the class by using [valid_container()].
#' * Test objects for class `Container` with introspector function [is_container()].
#' * Extract slots from instances of the class with functions [table()][table()]
#' and [schema()].
#' * Set new values to slots with functions [`table<-()`][table()],
#' and [`schema<-()`][schema()].
#' * Subset instances of the class by using the `Container` methods implemented
#' for operators [`[`][Container-extractors], [`[[`][Container-extractors] and
#' [`$`][Container-extractors].
#' * Methods for class `Container` are implemented for generic functions
#' [length()], [names()], [nrow()], [ncol()], [dim()] and [show()].
#'
#' @section Extending the Container class:
#' For most applications, the `Container` class will not be specific enough.
#' Users *should* extend it to a super-class with additional slots by using
#' package \pkg{methods}. Class [`GeoContainer`][GeoContainer-class] is a
#' simple example; it adds a sptial component to class `Container`.
#'
#' @family Container