| Title: | Structs, Enums, and Traits with a 'Rust' Runtime |
|---|---|
| Description: | A developer-facing type system for R whose runtime is the 'rtemis-r8' 'Rust' crate, shared with other host languages. Types are structs, enums, and traits, declared in R or in 'Rust'; values are immutable and validated once per value. This version reports the version of the compiled 'rtemis-r8' crate; declarations, validation, and JSON encoding are under development. |
| Authors: | E.D. Gennatas [aut, cre, cph] (ORCID: <https://orcid.org/0000-0001-9280-3609>), Authors of the bundled Rust crates [ctb, cph] (Rust crates compiled into the package; see inst/AUTHORS) |
| Maintainer: | E.D. Gennatas <[email protected]> |
| License: | BSD_3_clause + file LICENSE |
| Version: | 0.2.0 |
| Built: | 2026-11-19 21:22:03 UTC |
| Source: | https://github.com/rtemis-org/r8 |
The facts of one field of a struct, a struct variant, or a table. A bare
field type is the short form of field(type).
field( type, default = NULL, description = "", sensitive = FALSE, unit = NULL, external = FALSE, unique = FALSE, optional = FALSE, extensions = NULL )field( type, default = NULL, description = "", sensitive = FALSE, unit = NULL, external = FALSE, unique = FALSE, optional = FALSE, extensions = NULL )
type |
An |
default |
Optional: The default value, used when the field is absent. |
description |
Character: What the field holds. |
sensitive |
Logical: Mask the value in printing, events, errors, and differences. |
unit |
Optional Character: A UCUM unit code, such as |
external |
Logical: |
unique |
Logical: A table column whose values are distinct. |
optional |
Logical: A table column that may be absent. |
extensions |
Optional named list: Namespaced extensions, such as
|
An r8_field.
field(type_double(exclusive_min = 0), default = 1, description = "Cost.")field(type_double(exclusive_min = 0), default = 1, description = "Cost.")
A generic is a function that dispatches on the R8 type of its first
argument to the method that implement() declares for that type. A
package assigns it to the generic's name, documents it with roxygen2, and
exports it. The generic is a trait with one method named as the generic,
ns::describe, which Rust and the C interface implement as any trait.
generic(name, args = "x", description = "") ## S3 method for class 'r8_generic' print(x, ...)generic(name, args = "x", description = "") ## S3 method for class 'r8_generic' print(x, ...)
name |
Character: The generic's name, an R8 name such as
|
args |
Character: The formal argument names. The first is the value
dispatched on; |
description |
Character: What the generic does. |
x |
A generic of class |
... |
Not used. |
generic(): The generic, a function of class r8_generic. print(): x, invisibly.
implement<- declares a method; r8_method() returns one.
op <- options(r8.namespace = "models") GBM <- new_struct("GBM", fields = list(n_trees = type_integer(min = 1L))) describe <- generic("describe", "x") implement(describe, GBM) <- function(x, ...) { paste("Gradient boosting,", x$n_trees, "trees") } describe(GBM(n_trees = 100L)) options(op)op <- options(r8.namespace = "models") GBM <- new_struct("GBM", fields = list(n_trees = type_integer(min = 1L))) describe <- generic("describe", "x") implement(describe, GBM) <- function(x, ...) { paste("Gradient boosting,", x$n_trees, "trees") } describe(GBM(n_trees = 100L)) options(op)
HashMap<String, T>: string keys, sorted at construction.
hashmap(type, keys = NULL)hashmap(type, keys = NULL)
type |
An |
keys |
Optional |
An r8_field_type.
hashmap(type_integer())hashmap(type_integer())
Defines a trait's methods for a type; a method the impl omits takes the trait's default. Rust's orphan rule applies: an impl is declared in the namespace of the trait or of the type. Implementing the same trait for the same type again replaces the impl.
impl(trait, type, methods = list(), tag_value = NULL)impl(trait, type, methods = list(), tag_value = NULL)
trait |
A trait object. |
type |
An R8 type object. |
methods |
Named list: One function per method. |
tag_value |
Optional Character: The value of the trait's tag member for this type; defaults to the type's name. |
NULL, invisibly.
op <- options(r8.namespace = "demo") Describe <- new_trait("Describe", methods = list(describe = trait_method(function(x) NULL))) Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) impl(Describe, Point, methods = list(describe = function(x) sprintf("(%g, %g)", x$x, x$y))) describe <- Describe@describe describe(Point(x = 1, y = 2)) options(op)op <- options(r8.namespace = "demo") Describe <- new_trait("Describe", methods = list(describe = trait_method(function(x) NULL))) Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) impl(Describe, Point, methods = list(describe = function(x) sprintf("(%g, %g)", x$x, x$y))) describe <- Describe@describe describe(Point(x = 1, y = 2)) options(op)
implement(generic, Type) <- function(x, ...) ... declares the method
that generic calls for values of Type, and returns generic
unchanged. generic is written as its name; the function's arguments
begin with the generic's. By the generic:
implement(generic, type) <- valueimplement(generic, type) <- value
generic |
A generic, written as its name. |
type |
An R8 type object. |
value |
Function: The method. |
A generic from generic(), or a trait method such as Fit@fit: an
impl of its trait.
format, str, and dim: an impl of the standard trait Display,
Debug, or Dim; r8_cmp: of PartialOrd, which <, <=, >, and
>= use.
print: an impl of the standard trait Print; print() calls the
function and returns the value invisibly, and format() keeps its own
text. The declaration states this in a message.
Another S3 generic of base R or of an imported package, such as
summary or predict: an S3 method for the qualified class of Type.
The functions through which R8 reads, changes, and compares values
($, [[, @, as.list, $<-, [[<-, [<-, names<-,
length<-, dim<-, levels<-, ==, !=), the comparison and other
operators, S4 generics, and functions that are not generics raise
r8_declaration_error. For r8_convert and r8_converter, the error
names impl(From(source), Type, ...), which declares a conversion.
An impl is declared in the namespace of its generic or of its type.
In a package, r8_rd() documents the method in the generic's Rd file.
generic, unchanged.
op <- options(r8.namespace = "models") Resampler <- new_struct( "Resampler", fields = list(n_resamples = type_integer(min = 1L)) ) implement(format, Resampler) <- function(x, ...) { paste("Resampler,", x$n_resamples, "resamples") } implement(summary, Resampler) <- function(object, ...) { object$n_resamples } r <- Resampler(n_resamples = 10L) format(r) summary(r) options(op)op <- options(r8.namespace = "models") Resampler <- new_struct( "Resampler", fields = list(n_resamples = type_integer(min = 1L)) ) implement(format, Resampler) <- function(x, ...) { paste("Resampler,", x$n_resamples, "resamples") } implement(summary, Resampler) <- function(object, ...) { object$n_resamples } r <- Resampler(n_resamples = 10L) format(r) summary(r) options(op)
TRUE when x is a value of an R8 enum whose variant is variant. In a
rule, is_variant(kernel, "Rbf") compiles to the same test over the
value's JSON form.
is_variant(x, variant)is_variant(x, variant)
x |
An R8 enum value. |
variant |
Character: The variant name. |
Logical: One value.
op <- options(r8.namespace = "demo") Shape <- new_enum("Shape", variants = list(Circle = variant(), Square = variant())) is_variant(Shape@Circle, "Circle") options(op)op <- options(r8.namespace = "demo") Shape <- new_enum("Shape", variants = list(Circle = variant(), Square = variant())) is_variant(Shape@Circle, "Circle") options(op)
A sum type of unit, struct, and newtype variants. An enum of unit variants
is written as the variant name; an enum with another variant as an object
whose tag member names the variant. Kernel@Linear is a unit variant's
value.
new_enum(name, variants = list(), description = "", tag = "type", version = 1L) ## S3 method for class 'r8_enum_type' @(object, name)new_enum(name, variants = list(), description = "", tag = "type", version = 1L) ## S3 method for class 'r8_enum_type' @(object, name)
name |
The variant's name. |
variants |
Named list: The variants, |
description |
Character: What the type is. |
tag |
Character: The member that names the variant in JSON. |
version |
Integer: The type's version, from 1. |
object |
An enum type object. |
new_enum(): the type object, of class r8_enum_type.
Kernel@Linear: the unit variant's value, an R8 value.
op <- options(r8.namespace = "demo") Kernel <- new_enum("Kernel", variants = list( Linear = variant(), Rbf = variant(fields = list(gamma = type_double(exclusive_min = 0))) )) Kernel@Linear options(op)op <- options(r8.namespace = "demo") Kernel <- new_enum("Kernel", variants = list( Linear = variant(), Rbf = variant(fields = list(gamma = type_double(exclusive_min = 0))) )) Kernel@Linear options(op)
A product type: named fields, each with a type and per-field facts, and
rules over them. The type object constructs values: Svm(cost = 2).
Types declared in a package belong to its namespace (the DESCRIPTION
field Config/R8/namespace, or the package name); types declared at the
console belong to the option r8.namespace, "global" by default.
Type@from(x) converts x with the type's From impls.
new_struct( name, fields = list(), description = "", version = 1L, rules = list() ) ## S3 method for class 'r8_struct_type' @(object, name)new_struct( name, fields = list(), description = "", version = 1L, rules = list() ) ## S3 method for class 'r8_struct_type' @(object, name)
name |
The item's name. |
fields |
Named list: The fields, |
description |
Character: What the type is. |
version |
Integer: The type's version, from 1. |
rules |
List: |
object |
A struct type object. |
The type object, of class r8_struct_type.
The item.
op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double()), description = "A point.") options(op)op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double()), description = "A point.") options(op)
A trait declares methods that types implement with impl(). A method is a
generic that dispatches on the type of its first argument, reached as
Trait@method; a package binds and exports it under its name, such as
fit <- Fit@fit. A method named as an S3 generic of the base packages or
of the package's imports, such as summary or format, becomes an S3
method of that generic, and its signature begins with the generic's
arguments.
new_trait(name, methods = list(), description = "", tag = NULL) ## S3 method for class 'r8_trait' @(object, name)new_trait(name, methods = list(), description = "", tag = NULL) ## S3 method for class 'r8_trait' @(object, name)
name |
Character: The trait name. |
methods |
Named list: The methods, |
description |
Character: What the trait is. |
tag |
Optional Character: The member that names an implementor in JSON. |
object |
A trait object. |
The trait object, of class r8_trait.
op <- options(r8.namespace = "demo") Fit <- new_trait("Fit", methods = list(fit = trait_method(function(spec, x, y) NULL))) fit <- Fit@fit options(op)op <- options(r8.namespace = "demo") Fit <- new_trait("Fit", methods = list(fit = trait_method(function(spec, x, y) NULL))) fit <- Fit@fit options(op)
x == y and x != y compare two R8 values with r8_equal(), the
PartialEq standard trait. <, <=, >, and >= use the type's
PartialOrd impl. Other operators raise an error.
## S3 method for class 'r8_value' Ops(e1, e2)## S3 method for class 'r8_value' Ops(e1, e2)
e1, e2
|
R8 values. |
Logical: One value.
Option<T>: the value may be absent, NULL. resolve declares what
absence means.
option(type, resolve = "none", compute = NULL)option(type, resolve = "none", compute = NULL)
type |
An |
resolve |
Character {"none", "computed", "runtime"}: |
compute |
Optional expression: For |
An r8_field_type.
option(type_integer(min = 1L), resolve = "runtime") option(type_double(), resolve = "computed", compute = dose_mg / 1000)option(type_integer(min = 1L), resolve = "runtime") option(type_double(), resolve = "computed", compute = dose_mg / 1000)
Unique string keys in insertion order: a named list in R. Order is part of the value.
ordered_map(type, keys = NULL)ordered_map(type, keys = NULL)
type |
An |
keys |
Optional |
An r8_field_type.
ordered_map(type_double())ordered_map(type_double())
Print a field type
## S3 method for class 'r8_field_type' print(x, ...)## S3 method for class 'r8_field_type' print(x, ...)
x |
An |
... |
Not used. |
x, invisibly.
Print a trait object
## S3 method for class 'r8_trait' print(x, ...)## S3 method for class 'r8_trait' print(x, ...)
x |
A trait object. |
... |
Not used. |
x, invisibly.
Print a type object
## S3 method for class 'r8_type' print(x, ...)## S3 method for class 'r8_type' print(x, ...)
x |
An R8 type object. |
... |
Not used. |
x, invisibly.
Print an R8 value
## S3 method for class 'r8_value' print(x, ...)## S3 method for class 'r8_value' print(x, ...)
x |
An R8 value. |
... |
Not used. |
x, invisibly.
Turns an ordinary R object into a valid input for a struct type and
constructs the value: it removes names and other attributes from scalar
and vector fields, converts a character vector to a factor with declared
levels, POSIXlt to POSIXct, a tibble or data.table to a data.frame,
resets row names, expands an Rle, constructs a nested struct from a
named list, and drops members that are not fields. It reports each change
in one message. Construction itself stays strict: a value r8_conform()
cannot make valid raises the same errors as the type's constructor.
r8_conform(x, type)r8_conform(x, type)
x |
Named list: The fields of a value. |
type |
An R8 struct type object. |
The R8 value.
op <- options(r8.namespace = "demo") Weights <- new_struct("Weights", fields = list(w = vec(type_double(min = 0)))) q <- stats::quantile(c(1, 2, 3)) x <- r8_conform(list(w = q), Weights) options(op)op <- options(r8.namespace = "demo") Weights <- new_struct("Weights", fields = list(w = vec(type_double(min = 0)))) q <- stats::quantile(c(1, 2, 3)) x <- r8_conform(list(w = q), Weights) options(op)
Calls the From(source) impl of type for the class of x, or for its
R8 type when x is an R8 value, and checks that the result is a value of
type.
r8_convert(x, type)r8_convert(x, type)
x |
The value to convert. |
type |
An R8 type object. |
A value of type.
op <- options(r8.namespace = "demo") Pct <- new_struct("Pct", fields = list(p = type_double(min = 0, max = 100))) impl(From("numeric"), Pct, methods = list(from = function(x) Pct(p = x * 100))) r8_convert(0.25, Pct)$p options(op)op <- options(r8.namespace = "demo") Pct <- new_struct("Pct", fields = list(p = type_double(min = 0, max = 100))) impl(From("numeric"), Pct, methods = list(from = function(x) Pct(p = x * 100))) r8_convert(0.25, Pct)$p options(op)
Returns function(x) r8_convert(x, type), which a type's package exports
under a name of its choice, such as as_granges().
r8_converter(type)r8_converter(type)
type |
An R8 type object. |
Function.
op <- options(r8.namespace = "demo") Pct <- new_struct("Pct2", fields = list(p = type_double(min = 0, max = 100))) impl(From("numeric"), Pct, methods = list(from = function(x) Pct(p = x * 100))) as_pct <- r8_converter(Pct) as_pct(0.5)$p options(op)op <- options(r8.namespace = "demo") Pct <- new_struct("Pct2", fields = list(p = type_double(min = 0, max = 100))) impl(From("numeric"), Pct, methods = list(from = function(x) Pct(p = x * 100))) as_pct <- r8_converter(Pct) as_pct(0.5)$p options(op)
Returns the version of the rtemis-r8 Rust crate compiled into R8, which
provenance records alongside the versions of R8 and R.
r8_core_version()r8_core_version()
Character: The version, for example "0.1.0".
r8_core_version()r8_core_version()
The IR document of a type: its namespace and its declaration, as JSON text.
r8_declaration(type)r8_declaration(type)
type |
An R8 type object. |
Character: The IR document.
op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_declaration(Point) options(op)op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_declaration(Point) options(op)
TRUE when both values have the same type and equal fields: their
normalized forms are the same canonical JSON, and their runtime-only
fields are identical(). A provenance record does not enter the
comparison.
r8_equal(x, y)r8_equal(x, y)
x, y
|
R8 values. |
Logical: One value.
op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_equal(Point(x = 1, y = 2), Point(x = 1L, y = 2)) options(op)op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_equal(Point(x = 1, y = 2), Point(x = 1L, y = 2)) options(op)
Reads a document of type: checks "$type" and the versions in
"$types", validates the value, and returns it.
r8_from_json(type, json)r8_from_json(type, json)
type |
An R8 type object. |
json |
Character: The JSON document. |
An R8 value.
op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_from_json(Point, to_json(Point(x = 1, y = 2))) options(op)op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_from_json(Point, to_json(Point(x = 1, y = 2))) options(op)
The SHA-256 of the RFC 8785 canonical JSON of the type's name, its
declaration hash, and the value, written sha256:<hex>. Values that differ
only in member order or in defaults written out hash the same. A matrix,
an array, a sparse matrix, a table, and a vec() of logical, integer,
double, date, or date-time values enter through the digest of their
canonical binary form. A runtime-only field's value stays out of the hash;
its presence enters it. The hash is computed from the R objects in place.
r8_hash(x)r8_hash(x)
x |
An R8 value. |
Character: The hash.
op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_hash(Point(x = 1, y = 2)) options(op)op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) r8_hash(Point(x = 1, y = 2)) options(op)
Returns the function that implement() or impl() declared for type,
for tests and inspection.
r8_method(generic, type)r8_method(generic, type)
generic |
A generic, as |
type |
An R8 type object. |
Function. A generic without a method for type raises
r8_dispatch_error.
op <- options(r8.namespace = "models") GBM <- new_struct("GBM", fields = list(n_trees = type_integer(min = 1L))) describe <- generic("describe", "x") implement(describe, GBM) <- function(x, ...) "Gradient boosting" r8_method(describe, GBM) options(op)op <- options(r8.namespace = "models") GBM <- new_struct("GBM", fields = list(n_trees = type_integer(min = 1L))) describe <- generic("describe", "x") implement(describe, GBM) <- function(x, ...) "Gradient boosting" r8_method(describe, GBM) options(op)
A roxygen2 roclet that writes the Rd files of the rd roclet and adds R8
methods and enum variants to them. A package lists it in place of rd:
Roxygen: list(roclets = c("collate", "namespace", "R8::r8_rd")) in its
DESCRIPTION.
r8_rd()r8_rd()
Each implement(generic, Type) <- function(...) call adds an entry to the
usage section of an Rd file, ## R8 method for struct 'Type' (or enum)
followed by the call with the method's arguments. The entry goes to the Rd
file of the generic when the package declares and documents the generic,
an R8 generic or an S3 generic, and otherwise to the Rd file of the type. A roxygen block above the call
adds its @param entries to that file; a call without a block is found by
scanning R/, and is left out when neither the generic nor the type has an
Rd file in the package. The usage of an enum lists its variants, such as
Method@KFold(k) and Method@Bootstrap.
A roxygen2 roclet, of class roclet_r8_rd.
## Not run: roxygen2::roxygenise(roclets = c("collate", "namespace", "R8::r8_rd")) ## End(Not run)## Not run: roxygen2::roxygenise(roclets = c("collate", "namespace", "R8::r8_rd")) ## End(Not run)
A package's top-level new_struct(), new_enum(), new_trait(), and
impl() calls run when the package is installed, and record themselves in
the package's namespace. r8_register(), called from the package's
.onLoad(), registers them in the session: it checks each declaration
again and makes its types, traits, and impls available. Registering a
package again replaces its declarations.
r8_register(pkgname = NULL)r8_register(pkgname = NULL)
pkgname |
Optional Character: The package; by default, the package
whose code calls |
The number of declarations registered, invisibly.
## Not run: .onLoad <- function(libname, pkgname) { R8::r8_register() } ## End(Not run)## Not run: .onLoad <- function(libname, pkgname) { R8::r8_register() } ## End(Not run)
Fills the absent fields that a type declares with option(T, resolve = ):
a "runtime" field from context, a "computed" field from its
expression over the other fields, in dependency order. The result is a new
value, validated; x is unchanged. A runtime field missing from context
stays absent.
r8_resolve(x, context = list())r8_resolve(x, context = list())
x |
An R8 struct value. |
context |
Named list: Values of runtime fields, by name. |
The resolved R8 value.
op <- options(r8.namespace = "demo") Dose <- new_struct("Dose", fields = list( mg = field(option(type_double(), resolve = "runtime"), unit = "mg"), g = field(option(type_double(), resolve = "computed", compute = mg / 1000), unit = "g") )) r8_resolve(Dose(), context = list(mg = 250))$g options(op)op <- options(r8.namespace = "demo") Dose <- new_struct("Dose", fields = list( mg = field(option(type_double(), resolve = "runtime"), unit = "mg"), g = field(option(type_double(), resolve = "computed", compute = mg / 1000), unit = "g") )) r8_resolve(Dose(), context = list(mg = 250))$g options(op)
Checks a value against its type again, rules included: a value built by
its constructor is valid, and an object reassembled from parts may not
be. With complete = TRUE, a value whose runtime or computed fields are
still absent is an error that names them.
r8_validate(x, complete = FALSE)r8_validate(x, complete = FALSE)
x |
An R8 value. |
complete |
Logical: Require every runtime and computed field to be present. |
x, invisibly.
op <- options(r8.namespace = "demo") Fit <- new_struct("FitSettings", fields = list( mtry = option(type_integer(min = 1L), resolve = "runtime") )) r8_validate(Fit()) try(r8_validate(Fit(), complete = TRUE)) options(op)op <- options(r8.namespace = "demo") Fit <- new_struct("FitSettings", fields = list( mtry = option(type_integer(min = 1L), resolve = "runtime") )) r8_validate(Fit()) try(r8_validate(Fit(), complete = TRUE)) options(op)
x$name and x[["name"]] read a field by its exact name; an unknown name
is an error. x$name <- v and x[["name"]] <- v return a new value,
validated; x is unchanged.
@ reads the associated items of a type, not the fields of a value.
## S3 method for class 'r8_value' x$name ## S3 method for class 'r8_value' x[[i, ...]] ## S3 replacement method for class 'r8_value' x$name <- value ## S3 replacement method for class 'r8_value' x[[i]] <- value ## S3 method for class 'r8_value' @(object, name)## S3 method for class 'r8_value' x$name ## S3 method for class 'r8_value' x[[i, ...]] ## S3 replacement method for class 'r8_value' x$name <- value ## S3 replacement method for class 'r8_value' x[[i]] <- value ## S3 method for class 'r8_value' @(object, name)
x |
An R8 value. |
name |
The name. |
i |
Character: The field name. |
... |
Not used. |
value |
The new field value. |
object |
An R8 value. |
The field's value, or the new R8 value.
Does not return.
names<-, length<-, [<-, dim<-, and levels<- would change a value
without validation, so they abort; [[ with a number aborts, as fields
are read by name.
## S3 replacement method for class 'r8_value' names(x, ...) <- value ## S3 replacement method for class 'r8_value' length(x, ...) <- value ## S3 replacement method for class 'r8_value' x[...] <- value ## S3 replacement method for class 'r8_value' dim(x, ...) <- value ## S3 replacement method for class 'r8_value' levels(x, ...) <- value## S3 replacement method for class 'r8_value' names(x, ...) <- value ## S3 replacement method for class 'r8_value' length(x, ...) <- value ## S3 replacement method for class 'r8_value' x[...] <- value ## S3 replacement method for class 'r8_value' dim(x, ...) <- value ## S3 replacement method for class 'r8_value' levels(x, ...) <- value
x |
An R8 value. |
... |
Not used. |
value |
Not used. |
Does not return.
The default Display and Debug: the type, and each field on its own
line.
## S3 method for class 'r8_value' format(x, ...) ## S3 method for class 'r8_value' str(object, ...)## S3 method for class 'r8_value' format(x, ...) ## S3 method for class 'r8_value' str(object, ...)
x, object
|
An R8 value. |
... |
Not used. |
format(): Character, one element per line. str(): NULL,
invisibly.
A rule states what must hold for a value. The invariant is an R
expression over the type's fields, captured unevaluated: cost <= 100,
kernel$gamma <= 10, is.null(a) || !is.null(b). R's == and != are
strict equality. A rule holds when its when condition is FALSE, or when
a field it reads is absent; is.null() tests presence and is not a read.
Inside all() and any(), .x is the element.
rule(id, invariant, message, when = NULL)rule(id, invariant, message, when = NULL)
id |
Character: The rule's ID, an R8 name such as |
invariant |
Expression: What must hold. |
message |
Character: What a violation means, for the user. |
when |
Optional expression: The condition under which the rule applies. |
An r8_rule.
rule("COST_MAX", cost <= 100, "cost is at most 100.") rule("RBF_COST", cost <= 100, "cost is at most 100 with the Rbf kernel.", when = is_variant(kernel, "Rbf"))rule("COST_MAX", cost <= 100, "cost is at most 100.") rule("RBF_COST", cost <= 100, "cost is at most 100 with the Rbf kernel.", when = is_variant(kernel, "Rbf"))
Traits that R8 declares in its namespace R8, which a type implements
with impl() like any trait:
Display Debug Dim PartialOrd Print r8_cmp(x, y) From(source)Display Debug Dim PartialOrd Print r8_cmp(x, y) From(source)
x, y
|
Values of one R8 type, for |
source |
Character: The class or qualified R8 type converted from. |
Display: format(x, ...), which print() shows for a type without
a Print impl.
Print: print(x, ...), which print() calls before it returns x
invisibly; format() keeps the Display text.
Debug: str(object, ...).
Dim: dim(x); nrow() and ncol() follow.
PartialOrd: cmp(x, y), which returns a negative number, zero, or a
positive number as x sorts before, with, or after y; <, <=, >,
and >= use it, and r8_cmp() calls it.
From(source): from(x), which converts a value of the class or R8
type source to the implementing type; r8_convert(), Type@from(),
and r8_converter() use it.
R8 provides format(), print(), and str() for every value, == and
r8_hash() through r8_equal(), to_json() and r8_from_json(), and a
type whose required fields have defaults is constructed with no
arguments.
A trait object.
op <- options(r8.namespace = "demo") Money <- new_struct("Money", fields = list(cents = type_integer())) impl(Display, Money, methods = list(format = function(x, ...) sprintf("$%.2f", x$cents / 100))) impl(PartialOrd, Money, methods = list(cmp = function(x, y) x$cents - y$cents)) impl(From("numeric"), Money, methods = list( from = function(x) Money(cents = as.integer(round(x * 100))) )) m <- r8_convert(1.5, Money) print(m) m < Money(cents = 200L) options(op)op <- options(r8.namespace = "demo") Money <- new_struct("Money", fields = list(cents = type_integer())) impl(Display, Money, methods = list(format = function(x, ...) sprintf("$%.2f", x$cents / 100))) impl(PartialOrd, Money, methods = list(cmp = function(x, y) x$cents - y$cents)) impl(From("numeric"), Money, methods = list( from = function(x) Money(cents = as.integer(round(x * 100))) )) m <- r8_convert(1.5, Money) print(m) m < Money(cents = 200L) options(op)
The value's document: "$type", "$types" (the version of every type it
contains), then its fields in declaration order.
to_json(x)to_json(x)
x |
An R8 value. |
Character: The JSON document.
op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) to_json(Point(x = 1, y = 2)) options(op)op <- options(r8.namespace = "demo") Point <- new_struct("Point", fields = list(x = type_double(), y = type_double())) to_json(Point(x = 1, y = 2)) options(op)
Declare a trait method
trait_method(fn, description = "", default = NULL, stochastic = FALSE)trait_method(fn, description = "", default = NULL, stochastic = FALSE)
fn |
Function: Its formals are the method's signature; the first formal is the value the method dispatches on. |
description |
Character: What the method does. |
default |
Optional function: A default implementation, used for a type whose impl does not define the method. |
stochastic |
Logical: The method draws random numbers. |
An r8_trait_method.
trait_method(function(spec, x, y) NULL, description = "Trains a model.")trait_method(function(spec, x, y) NULL, description = "Trains a model.")
A dense array of a scalar type, an atomic vector with dim in R.
type_array(type, dim = NULL)type_array(type, dim = NULL)
type |
An |
dim |
Optional Integer: The dimensions. |
An r8_field_type.
type_array(type_integer(), dim = c(2L, 3L, 4L))type_array(type_integer(), dim = c(2L, 3L, 4L))
A string without U+0000, never NA.
type_character(pattern = NULL, values = NULL)type_character(pattern = NULL, values = NULL)
pattern |
Optional Character: A regular expression in Rust |
values |
Optional Character: The admitted values. |
An r8_field_type.
type_character(values = c("gaussian", "binomial"))type_character(values = c("gaussian", "binomial"))
A calendar date from 0000-01-01 to 9999-12-31.
type_date()type_date()
An r8_field_type.
type_date()type_date()
A double. The domain is finite unless finite = FALSE, which admits
Inf, -Inf, and NaN.
type_double( min = NULL, max = NULL, exclusive_min = NULL, exclusive_max = NULL, finite = TRUE, values = NULL )type_double( min = NULL, max = NULL, exclusive_min = NULL, exclusive_max = NULL, finite = TRUE, values = NULL )
min |
Optional Numeric: Smallest admitted value. |
max |
Optional Numeric: Largest admitted value. |
exclusive_min |
Optional Numeric: The value must be above it. |
exclusive_max |
Optional Numeric: The value must be below it. |
finite |
Logical: Restrict the domain to finite values. |
values |
Optional Numeric: The admitted values. |
An r8_field_type.
type_double(exclusive_min = 0)type_double(exclusive_min = 0)
A vector of categorical values.
type_factor(levels = NULL, ordered = FALSE)type_factor(levels = NULL, ordered = FALSE)
levels |
Optional Character: The declared levels. Without them, the levels come from the data. |
ordered |
Logical: An ordered factor. |
An r8_field_type.
type_factor(levels = c("+", "-", "*"))type_factor(levels = c("+", "-", "*"))
An integer from -2147483647 to 2147483647. A double given for an integer field converts when it is a whole number in range.
type_integer( min = NULL, max = NULL, exclusive_min = NULL, exclusive_max = NULL, values = NULL )type_integer( min = NULL, max = NULL, exclusive_min = NULL, exclusive_max = NULL, values = NULL )
min |
Optional Integer: Smallest admitted value. |
max |
Optional Integer: Largest admitted value. |
exclusive_min |
Optional Integer: The value must be above it. |
exclusive_max |
Optional Integer: The value must be below it. |
values |
Optional Integer: The admitted values. |
An r8_field_type.
type_integer(min = 1L)type_integer(min = 1L)
Any JSON value: objects as named lists, arrays as unnamed lists, numbers as doubles.
type_json()type_json()
An r8_field_type.
type_json()type_json()
A logical value, TRUE or FALSE, never NA.
type_logical()type_logical()
An r8_field_type.
type_logical()type_logical()
A dense matrix of a scalar type, an atomic vector with dim in R. Given an
R8 struct type, a matrix whose columns are the struct's fields, all of one
scalar type.
type_matrix(type, nrow = NULL, ncol = NULL)type_matrix(type, nrow = NULL, ncol = NULL)
type |
An |
nrow |
Optional Integer: The number of rows. |
ncol |
Optional Integer: The number of columns. |
An r8_field_type.
type_matrix(option(type_double()), nrow = 2L)type_matrix(option(type_double()), nrow = 2L)
A UTC instant in microseconds, from 1827-04-16T00:06:12.629505Z to 2112-09-17T23:53:47.370495Z, the range a double holds exactly.
type_posixct()type_posixct()
An r8_field_type.
type_posixct()type_posixct()
An R value of a class, held in R only: absent from JSON and from the hash.
A field of this type is declared inside option().
type_r(class)type_r(class)
class |
Character: The R class. |
An r8_field_type.
option(type_r("lm"), resolve = "runtime")option(type_r("lm"), resolve = "runtime")
Bytes, a raw vector in R and canonical padded base64 in JSON.
type_raw()type_raw()
An r8_field_type.
type_raw()type_raw()
A matrix in compressed sparse column form, a dgCMatrix (package Matrix)
in R.
type_sparse_matrix(type = type_double(), nrow = NULL, ncol = NULL)type_sparse_matrix(type = type_double(), nrow = NULL, ncol = NULL)
type |
An |
nrow |
Optional Integer: The number of rows. |
ncol |
Optional Integer: The number of columns. |
An r8_field_type.
type_sparse_matrix()type_sparse_matrix()
A data.frame of equal-length columns, each a scalar type, a factor, or
option() of one, with automatic row names. An open table also accepts
columns its declaration does not name. A table's rules run once per row
and read the row's columns by name. Given an R8 struct type, a table whose
columns are the struct's fields.
type_table(columns = list(), open = FALSE, rules = list())type_table(columns = list(), open = FALSE, rules = list())
columns |
Named list of fields or field types, or an R8 struct type. |
open |
Logical: Accept columns the declaration does not name. |
rules |
List: |
An r8_field_type.
type_table( list(start = type_integer(), width = type_integer(min = 0L)), rules = list(rule("END_FITS", start + width - 1 <= 2147483647, "The end fits in an integer.")) )type_table( list(start = type_integer(), width = type_integer(min = 0L)), rules = list(rule("END_FITS", start + width - 1 <= 2147483647, "The end fits in an integer.")) )
A unit variant has no fields; a struct variant has named fields; a newtype
variant holds one value of a struct, variant(of = GRanges).
variant(fields = list(), description = "", rules = list(), of = NULL)variant(fields = list(), description = "", rules = list(), of = NULL)
fields |
Named list: The fields of a struct variant. |
description |
Character: What the variant is. |
rules |
List: |
of |
Optional R8 struct type: The struct a newtype variant holds. |
An r8_variant.
variant(fields = list( gamma = field(type_double(exclusive_min = 0), description = "Kernel width.") ))variant(fields = list( gamma = field(type_double(exclusive_min = 0), description = "Kernel width.") ))
Vec<T>: an atomic vector for a scalar T, a list otherwise.
vec(type, min_length = NULL, max_length = NULL, unique = FALSE)vec(type, min_length = NULL, max_length = NULL, unique = FALSE)
type |
An |
min_length |
Optional Integer: Fewest elements. |
max_length |
Optional Integer: Most elements. |
unique |
Logical: Elements are distinct. |
An r8_field_type.
vec(type_double(min = 0), min_length = 1L)vec(type_double(min = 0), min_length = 1L)