NAME
Muldis::D::Core::Routines - Muldis D general purpose routines
VERSION
This document is Muldis::D::Core::Routines version 0.93.0.
PREFACE
This document is part of the Muldis D language specification, whose root document is Muldis::D; you should read that root document before you read this one, which provides subservient details. Moreover, you should read the Muldis::D::Core document before this current document, as that forms its own tree beneath a root document branch.
DESCRIPTION
This document contains one or more sections that were moved here from Muldis::D::Core so that said other document would not be too large.
SYSTEM-DEFINED GENERIC UNIVERSAL FUNCTIONS
These functions are applicable to values of any data type at all.
sys.std.Core.Universal.is_identical
function sys.std.Core.Universal.is_identical (Bool <-- Universal $topic, Universal $other)
This symmetric function results in Bool:true iff its 2 arguments are exactly the same value, and Bool:false otherwise. This function will warn if, in regards to the declared types of its arguments, none of the following are true: 1. they are both subtypes of a common scalar root type; 2. they are both subtypes of a common complete tuple or relation type, that is they essentially have the same headings; 3. at least one type is a generic (eg-Universal) or incomplete (eg-Relation) type, and it is a supertype of the other. Note that this operation is also known as is equal or =.
sys.std.Core.Universal.is_not_identical
function sys.std.Core.Universal.is_not_identical (Bool <-- Universal $topic, Universal $other)
This symmetric function is exactly the same as sys.std.Core.Universal.is_identical except that it results in the opposite boolean value when given the same arguments. Note that this operation is also known as is not equal or ≠ or !=.
sys.std.Core.Universal.is_value_of_type
function sys.std.Core.Universal.is_value_of_type (Bool <-- Universal $topic, TypeRef $type)
This function results in Bool:true iff the value of its topic argument is a member of the data type whose name is given in the type argument, and Bool:false otherwise. As trivial cases, this function always results in Bool:true if the named type is Universal, and Bool:false if it is Empty. This function will fail if the named type doesn't exist in the virtual machine. Note that this operation is also known as isa.
sys.std.Core.Universal.is_not_value_of_type
function sys.std.Core.Universal.is_not_value_of_type (Bool <-- Universal $topic, TypeRef $type)
This function is exactly the same as sys.std.Core.Universal.is_value_of_type except that it results in the opposite boolean value when given the same arguments. Note that this operation is also known as !isa or not isa.
sys.std.Core.Universal.treated
function sys.std.Core.Universal.treated (Universal <-- Universal $topic, TypeRef $as)
This function results in the value of its topic argument, but that the declared type of the result is the not-Empty data type whose name is given in the as argument. This function will fail if the named type doesn't exist in the virtual machine, or if topic isn't a member of the named type. The purpose of treated is to permit taking values from a context having a more generic declared type, and using them in a context having a more specific declared type; such an action would otherwise be blocked at compile time due to a type-mismatch error; treated causes the type-mismatch validation, and possible failure, to happen at runtime instead, on the actual value rather than declared value. For example, if you are storing an Int value in a Scalar-typed variable, using treated will cause the compiler to let you use that variable as an argument to sys.std.Integer.diff, which it otherwise wouldn't. Note that this operation is also known as as.
sys.std.Core.Universal.default
function sys.std.Core.Universal.default (Universal <-- TypeRef $of)
This function is the externalization of a not-Empty data type's type default named_value function. This function results in the default value of the not-Empty data type whose name is given in the of argument, and the declared type of the result is that same type. This function will fail if the named type doesn't exist in the virtual machine, either at compile or runtime depending whether the type is in the system or user namespace. This function is conceptually implicitly used to provide default values for variables, so they always hold valid values of their declared type. Note that this operation is also known as d.
sys.std.Core.Universal.assertion
function sys.std.Core.Universal.assertion (Universal <-- Bool $is_true, Universal $result)
This function results in the value of its result argument, when its is_true argument is Bool:true. This function will fail if its is_true argument is Bool:false. The purpose of assertion is to perform condition assertions in a pure functional context that may be better done without the overhead of creating a new constrained data type, especially when the assertion is on some fact that is only known after performing calculations from multiple function arguments; this can potentially be done at compile time as per type constraints. Note that this operation is also known as asserting.
SYSTEM-DEFINED GENERIC SCALAR-CONCERNING FUNCTIONS
These functions are applicable to mainly scalar types, but are generic in that they typically work with any scalar types. Note that the terminology used to describe these functions is taking advantage of the fact that a scalar possrep looks just like a tuple. Each possrep and name parameter is optional and each defaults to the empty string if no explicit argument is given to it.
sys.std.Core.Scalar.attr
function sys.std.Core.Scalar.attr (Universal <-- Scalar $topic, Name $possrep?, Name $name?)
This function results in the scalar or nonscalar value of the possrep attribute of topic where the possrep name is given by possrep and the attribute name is given by name. This function will fail if possrep specifies a possrep name that topic doesn't have or name specifies an attribute name that the named possrep of topic doesn't have. Note that this operation is also known as .${}.
sys.std.Core.Scalar.update_attr
function sys.std.Core.Scalar.update_attr (Scalar <-- Scalar $topic, Name $possrep?, Name $name?, Universal $value)
This function results in its topic argument but that its possrep attribute whose possrep name is possrep and whose attribute name is name has been updated with a new scalar or nonscalar value given by value. This function will fail if possrep specifies a possrep name that topic doesn't have or name specifies an attribute name that the named possrep of topic doesn't have, or if value isn't of the declared type of the attribute; this function will otherwise warn if the declared type of value isn't a subtype of the declared type of the attribute.
sys.std.Core.Scalar.multi_update
function sys.std.Core.Scalar.multi_update (Scalar <-- Scalar $topic, Name $possrep?, Tuple $attrs)
This function is like sys.std.Core.Scalar.update_attr except that it handles N scalar possrep attributes at once rather than just 1. The heading of the attrs argument must be a subset of the heading of the topic argument's possrep named by possrep; this function's result is topic with all the possrep attribute values of attrs substituted into it. This function could alternately be named sys.std.Core.Scalar.static_subst.
sys.std.Core.Scalar.projection
function sys.std.Core.Scalar.projection (Tuple <-- Scalar $topic, Name $possrep?, set_of.Name $attr_names)
This function results in the Tuple that is the projection of the possrep (whose name is given in the possrep argument) of its topic argument that has just the subset of attributes of topic which are named in its attr_names argument. As a trivial case, this function's result is the entire named possrep of topic if attr_names lists all attributes of that possrep; or, it is the nullary tuple if attr_names is empty. This function will fail if possrep specifies a possrep name that topic doesn't have or attr_names specifies any attribute names that topic doesn't have. Note that this operation is also known as ${}.
sys.std.Core.Scalar.cmpl_proj
function sys.std.Core.Scalar.cmpl_proj (Tuple <-- Scalar $topic, Name $possrep?, set_of.Name $attr_names)
This function is the same as projection but that it results in the complementary subset of possrep attributes of topic when given the same arguments. Note that this operation is also known as ${!}.
sys.std.Core.Scalar.Tuple_from_Scalar
function sys.std.Core.Scalar.Tuple_from_Scalar (Tuple <-- Scalar $topic, Name $possrep?)
This function results in the Tuple that has all the same attributes of the possrep of topic whose name is given in possrep; in other words, the function results in the externalization of one of a scalar value's possreps. This function will fail if possrep specifies a possrep name that topic doesn't have.
sys.std.Core.Scalar.Scalar_from_Tuple
function sys.std.Core.Scalar.Scalar_from_Tuple (Scalar <-- Tuple $topic, TypeRef $type, Name $possrep?)
This function results in the Scalar value whose scalar root [|sub]type is named by type, which has a possrep whose name matches possrep, and whose complete set of attributes of that named possrep match the attributes of topic. This function can be used to select any scalar value at all that has a possrep.
sys.std.Core.Scalar.order
function sys.std.Core.Scalar.order (Order <-- Scalar $topic, Scalar $other, Tuple $misc_args?, Bool $is_reverse_order?)
This order_determination function is the externalization of a scalar root type's type-default (total) order_determination function. This function results in Order:same iff its topic and other arguments are exactly the same value, and otherwise it results in Order:increase if the value of the other argument is considered to be an increase (as defined by the type) over the value of the topic argument, and otherwise it results in Order:decrease as the reverse of the last condition would be true. This function will fail if its topic and other arguments are not values of a common scalar root type that declares a type-default order_determination function; this function will otherwise warn if the declared types of those arguments are not both subtypes of such a common scalar root type. Note that order_determination functions are considered the only fundamental order-sensitive operators, and all others are defined over them. This function also has a Tuple-typed third parameter, named misc_args, which carries optional customization details for the order-determination algorithm; this permits the function to implement a choice between multiple (typically similar) ordering algorithms rather than just one, which reduces the number of functions needed for supporting that choice; if the algorithm is not customizable, then a tuple argument would be of degree zero. This function also has a Bool-typed fourth parameter, named is_reverse_order; a Bool:false argument means the function's algorithm operates as normal when given any particular 3 other arguments (meaning a sorting operation based on it will place elements in ascending order), while a Bool:true argument means the function's algorithm operates in reverse, so the function results in the reverse Order value it would have otherwise when given the same 3 other arguments (meaning a sorting operation based on it will place elements in descending order). The misc_args and is_reverse_order parameters are optional and default to the zero-attribute tuple and Bool:false, respectively, if no explicit arguments are given to them.
sys.std.Core.Scalar.has_possrep
function sys.std.Core.Scalar.has_possrep (Bool <-- Scalar $topic, Name $possrep?)
This function results in Bool:true iff its topic argument has a possrep whose name is given by possrep; otherwise it results in Bool:false.
sys.std.Core.Scalar.possrep_names
function sys.std.Core.Scalar.possrep_names (set_of.Name <-- Scalar $topic)
This function results in the set of the names of the possreps of its argument.
sys.std.Core.Scalar.degree
function sys.std.Core.Scalar.degree (NNInt <-- Scalar $topic, Name $possrep?)
This function results in the degree of its topic argument's possrep whose name is given by possrep (that is, the count of attributes the possrep has).
sys.std.Core.Scalar.has_attrs
function sys.std.Core.Scalar.has_attrs (Bool <-- Scalar $topic, Name $possrep?, set_of.Name $attr_names)
This function results in Bool:true iff, for every one of the attribute names specified by its attr_names argument, its topic argument's possrep whose name is given by possrep has an attribute with that name; otherwise it results in Bool:false. As a trivial case, this function's result is Bool:true if attr_names is empty.
sys.std.Core.Scalar.attr_names
function sys.std.Core.Scalar.attr_names (set_of.Name <-- Scalar $topic, Name $possrep?)
This function results in the set of the names of the attributes of its topic argument's possrep whose name is given by possrep.
SYSTEM-DEFINED BOOLEAN-CONCERNING FUNCTIONS
These functions implement commonly used boolean logic operations. See also Muldis::D::Ext::Bool for all the other standard boolean logic operators which aren't shown below.
sys.std.Core.Bool.not
function sys.std.Core.Bool.not (Bool <-- Bool $topic)
This function results in the logical not of its argument. This function results in Bool:true iff its argument is Bool:false, and Bool:false otherwise. Note that this operation is also known as negation or ¬ or !.
There also exists conceptually the logical monadic operation called proposition which results simply in its argument; this is the complement operation of negation. Now in practice any value expression that is an invocation of proposition can simply be replaced with its argument, so there is no reason for proposition to exist as an actual function.
sys.std.Core.Bool.and
function sys.std.Core.Bool.and (Bool <-- set_of.Bool $topic?)
This function is a reduction operator that recursively takes each pair of its N input element values and does a logical and (which is commutative, associative, and idempotent) on them until just one is left, which is the function's result. For each pair of input values, the and of that pair is Bool:true iff both input values are Bool:true, and Bool:false otherwise. If topic has zero values, then and results in Bool:true, which is the identity value for logical and. Note that this operation is also known as all or every or conjunction or ∧.
sys.std.Core.Bool.all
function sys.std.Core.Bool.all (Bool <-- set_of.Bool $topic?)
This function is an alias for sys.std.Core.Bool.and. This function results in Bool:true iff all of its input element values are Bool:true (or it has no input values), and Bool:false otherwise (when it has at least one input value that is Bool:false).
sys.std.Core.Bool.or
function sys.std.Core.Bool.or (Bool <-- set_of.Bool $topic?)
This function is a reduction operator that recursively takes each pair of its N input element values and does a logical inclusive-or (which is commutative, associative, and idempotent) on them until just one is left, which is the function's result. For each pair of input values, the or of that pair is Bool:false iff both input values are Bool:false, and Bool:true otherwise. If topic has zero values, then or results in Bool:false, which is the identity value for logical inclusive-or. Note that this operation is also known as any or some or disjunction or ∨.
sys.std.Core.Bool.any
function sys.std.Core.Bool.any (Bool <-- set_of.Bool $topic?)
This function is an alias for sys.std.Core.Bool.or. This function results in Bool:true iff any of its input element values are Bool:true, and Bool:false otherwise (when all of its input values are Bool:false or if it has no input values).
SYSTEM-DEFINED GENERIC TUPLE-CONCERNING FUNCTIONS
These functions are applicable to mainly tuple types, but are generic in that they typically work with any tuple types.
sys.std.Core.Tuple.attr
function sys.std.Core.Tuple.attr (Universal <-- Tuple $topic, Name $name)
This function results in the scalar or nonscalar value of the attribute of topic whose name is given by name. This function will fail if name specifies an attribute name that topic doesn't have. Note that this operation is also known as .%{}.
sys.std.Core.Tuple.update_attr
function sys.std.Core.Tuple.update_attr (Tuple <-- Tuple $topic, Name $name, Universal $value)
This function results in its topic argument but that its attribute whose name is name has been updated with a new scalar or nonscalar value given by value. This function will fail if name specifies an attribute name that topic doesn't have; this function will otherwise warn if the declared type of value isn't a subtype of the declared type of the attribute.
sys.std.Core.Tuple.multi_update
function sys.std.Core.Tuple.multi_update (Tuple <-- Tuple $topic, Tuple $attrs)
This function is like sys.std.Core.Tuple.update_attr except that it handles N tuple attributes at once rather than just 1. The heading of the attrs argument must be a subset of the heading of the topic argument; this function's result is topic with all the attribute values of attrs substituted into it. This function could alternately be named sys.std.Core.Tuple.static_subst.
sys.std.Core.Tuple.rename
function sys.std.Core.Tuple.rename (Tuple <-- Tuple $topic, AttrRenameMap $map)
This function results in a Tuple value that is the same as its topic argument but that some of its attributes have different names. Each tuple of the argument map specifies how to rename one topic attribute, with the after and before attributes of a map tuple representing the new and old names of a topic attribute, respectively. As a trivial case, this function's result is topic if map has no tuples. This function supports renaming attributes to each others' names. This function will fail if map specifies any old names that topic doesn't have, or any new names that are the same as topic attributes that aren't being renamed. Note that this operation is also known as %{<-}.
sys.std.Core.Tuple.projection
function sys.std.Core.Tuple.projection (Tuple <-- Tuple $topic, set_of.Name $attr_names)
This function results in the projection of its topic argument that has just the subset of attributes of topic which are named in its attr_names argument. As a trivial case, this function's result is topic if attr_names lists all attributes of topic; or, it is the nullary tuple if attr_names is empty. This function will fail if attr_names specifies any attribute names that topic doesn't have. Note that this operation is also known as %{}.
sys.std.Core.Tuple.cmpl_proj
function sys.std.Core.Tuple.cmpl_proj (Tuple <-- Tuple $topic, set_of.Name $attr_names)
This function is the same as projection but that it results in the complementary subset of attributes of topic when given the same arguments. Note that this operation is also known as %{!}.
sys.std.Core.Tuple.static_exten
function sys.std.Core.Tuple.static_exten (Tuple <-- Tuple $topic, Tuple $attrs)
This function results in the extension of its topic argument by joining that with its attrs argument; the attribute names of the 2 arguments must be disjoint. See also sys.std.Core.Tuple.product for an N-adic version of this.
sys.std.Core.Tuple.wrap
function sys.std.Core.Tuple.wrap (Tuple <-- Tuple $topic, Name $outer, set_of.Name $inner)
This function results in a Tuple value that is the same as its topic argument but that some of its attributes have been wrapped up into a new Tuple-typed attribute, which exists in place of the original attributes. The inner argument specifies which topic attributes are to be removed and wrapped up, and the outer argument specifies the name of their replacement attribute. As a trivial case, if inner is empty, then the result has all the same attributes as before plus a new tuple-typed attribute of degree zero; or, if inner lists all attributes of topic, then the result has a single attribute whose value is the same as topic. This function supports the new attribute having the same name as an old one being wrapped into it. This function will fail if inner specifies any attribute names that topic doesn't have, or if outer is the same as a topic attribute that isn't being wrapped. Note that this operation is also known as %{%<-}.
sys.std.Core.Tuple.cmpl_wrap
function sys.std.Core.Tuple.cmpl_wrap (Tuple <-- Tuple $topic, Name $outer, set_of.Name $cmpl_inner)
This function is the same as wrap but that it wraps the complementary subset of attributes of topic to those specified by cmpl_inner. Note that this operation is also known as %{%<-!}.
sys.std.Core.Tuple.unwrap
function sys.std.Core.Tuple.unwrap (Tuple <-- Tuple $topic, set_of.Name $inner, Name $outer)
This function is the inverse of sys.std.Core.Tuple.wrap, such that it will unwrap a Tuple-type attribute into its member attributes. This function will fail if outer specifies any attribute name that topic doesn't have, or if an attribute of topic{outer} has the same name as another topic attribute. Now conceptually speaking, the inner parameter is completely superfluous for this Tuple variant of unwrap; however, it is provided anyway so that this function has complete API parity with the Relation variant of unwrap, where inner is necessary in the general case, and so Muldis D code using this function is also forced to be more self-documenting or strongly typed. This function will fail if inner does not match the names of the attributes of topic{outer}. Note that this operation is also known as %{<-%}.
sys.std.Core.Tuple.product
function sys.std.Core.Tuple.product (Tuple <-- set_of.Tuple $topic)
This function is similar to sys.std.Core.Relation.product but that it works with tuples rather than relations. This function is mainly intended for use in connecting tuples that have all disjoint headings, such as for extending one tuple with additional attributes.
sys.std.Core.Tuple.is_member
function sys.std.Core.Tuple.is_member (Bool <-- Tuple $t, Relation $r)
This function is an alias for sys.std.Core.Relation.has_member. This function results in Bool:true iff its t argument matches a tuple of its r argument (that is, iff conceptually t is a member of r), and Bool:false otherwise. Note that this operation is also known as ∈.
sys.std.Core.Tuple.is_not_member
function sys.std.Core.Tuple.is_not_member (Bool <-- Tuple $t, Relation $r)
This function is an alias for sys.std.Core.Relation.has_not_member. This function is exactly the same as sys.std.Core.Tuple.is_member except that it results in the opposite boolean value when given the same arguments. Note that this operation is also known as ¬in;.
SYSTEM-DEFINED GENERIC SINGLE INPUT RELATION FUNCTIONS
These functions are applicable to mainly relation types, but are generic in that they typically work with any relation types.
sys.std.Core.Relation.cardinality
function sys.std.Core.Relation.cardinality (NNInt <-- Relation $topic)
This function results in the cardinality of its argument (that is, the count of tuples its body has). Note that this operation is also known as count or R#.
sys.std.Core.Relation.count
function sys.std.Core.Relation.count (NNInt <-- Relation $topic)
This function is an alias for sys.std.Core.Relation.cardinality.
sys.std.Core.Relation.has_member
function sys.std.Core.Relation.has_member (Bool <-- Relation $r, Tuple $t)
This function results in Bool:true iff its t argument matches a tuple of its r argument (that is, iff conceptually t is a member of r), and Bool:false otherwise. This function will warn if its 2 arguments' common-named attributes have declared types that are incompatible as per is_identical. Note that this operation is also known as ∋.
sys.std.Core.Relation.has_not_member
function sys.std.Core.Relation.has_not_member (Bool <-- Relation $r, Tuple $t)
This function is exactly the same as sys.std.Core.Relation.has_member except that it results in the opposite boolean value when given the same arguments. Note that this operation is also known as ∌.
sys.std.Core.Relation.Tuple_from_Relation
function sys.std.Core.Relation.Tuple_from_Relation (Tuple <-- Relation $topic)
This function results in the Tuple that is the sole member tuple of its argument. This function will fail if its argument does not have exactly one tuple. Note that this operation is also known as t.
sys.std.Core.Relation.Relation_from_Tuple
function sys.std.Core.Relation.Relation_from_Tuple (Relation <-- Tuple $topic)
This function results in the Relation value those body has just the one Tuple that is its argument. Note that this operation is also known as r.
sys.std.Core.Relation.insertion
function sys.std.Core.Relation.insertion (Relation <-- Relation $r, Tuple $t)
This function results in a Relation that is the relational union of r and a relation whose sole tuple is t; that is, conceptually the result is t inserted into r. As a trivial case, if t already exists in r, then the result is just r.
sys.std.Core.Relation.disjoint_ins
function sys.std.Core.Relation.disjoint_ins (Relation <-- Relation $r, Tuple $t)
This function is exactly the same as sys.std.Core.Relation.insertion except that it will fail if t already exists in r.
sys.std.Core.Relation.deletion
function sys.std.Core.Relation.deletion (Relation <-- Relation $r, Tuple $t)
This function results in a Relation that is the relational difference from r of a relation whose sole tuple is t; that is, conceptually the result is t deleted from r. As a trivial case, if t already doesn't exist in r, then the result is just r.
sys.std.Core.Relation.rename
function sys.std.Core.Relation.rename (Relation <-- Relation $topic, AttrRenameMap $map)
This function is the same as sys.std.Core.Tuple.rename but that it operates on and results in a Relation rather than a Tuple. Note that this operation is also known as @{<-}.
sys.std.Core.Relation.projection
function sys.std.Core.Relation.projection (Relation <-- Relation $topic, set_of.Name $attr_names)
This function is the same as sys.std.Core.Tuple.projection but that it operates on and results in a Relation rather than a Tuple. But note that the result relation will have fewer tuples than topic if any topic tuples were non-distinct for just the projected attributes. Note that this operation is also known as @{}.
sys.std.Core.Relation.cmpl_proj
function sys.std.Core.Relation.cmpl_proj (Relation <-- Relation $topic, set_of.Name $attr_names)
This function is the same as sys.std.Core.Tuple.cmpl_proj but that it operates on and results in a Relation rather than a Tuple. Note that this operation is also known as @{!}.
sys.std.Core.Relation.wrap
function sys.std.Core.Relation.wrap (Relation <-- Relation $topic, Name $outer, set_of.Name $inner)
This function is the same as sys.std.Core.Tuple.wrap but that it operates on and results in a Relation rather than a Tuple, where each of its member tuples was transformed as per sys.std.Core.Tuple.wrap. The result relation has the same cardinality as topic. Note that this operation is also known as @{%<-}.
sys.std.Core.Relation.cmpl_wrap
function sys.std.Core.Relation.cmpl_wrap (Relation <-- Relation $topic, Name $outer, set_of.Name $cmpl_inner)
This function is the same as sys.std.Core.Tuple.cmpl_wrap but that it operates on and results in a Relation rather than a Tuple, where each of its member tuples was transformed as per sys.std.Core.Tuple.cmpl_wrap. Note that this operation is also known as @{%<-!}.
sys.std.Core.Relation.unwrap
function sys.std.Core.Relation.unwrap (Relation <-- Relation $topic, set_of.Name $inner, Name $outer)
This function is the inverse of sys.std.Core.Relation.wrap as sys.std.Core.Tuple.unwrap is to sys.std.Core.Tuple.wrap. But unlike the simplest concept of a Tuple variant of unwrap, this current function requires the extra inner argument to prevent ambiguity in the general case where topic might have zero tuples, because in that situation the most-specific-type of topic{outer} would be Empty, and the names of the attributes to add to topic in place of topic{outer} are not known. This function will fail if topic has at least 1 tuple and inner does not match the names of the attributes of topic{outer}. This function will fail with a non-DHRelation valued topic unless, for every tuple of topic, the attribute specified by outer is valued with a tuple of the same degree and heading (attribute names); this failure is because there would be no consistent set of attribute names to extend topic with (a problem that would never happen by definition with a deeply homogeneous relation topic). Note that this operation is also known as @{<-%}.
sys.std.Core.Relation.group
function sys.std.Core.Relation.group (Relation <-- Relation $topic, Name $outer, set_of.Name $inner)
This function is similar to sys.std.Core.Relation.wrap but that the topic attribute-wrapping transformations result in new Relation-typed attributes rather than new Tuple-typed attributes, and moreover multiple topic tuples may be combined into fewer tuples whose new Relation-typed attributes have multiple tuples. This function takes a relation of N tuples and divides the tuples into M groups where all the tuples in a group have the same values in the attributes which aren't being grouped (and distinct values in the attributes that are being grouped); it then results in a new relation of M tuples where the new relation-valued attribute of the result has the tuples of the M groups. A grouped relation contains all of the information in the original relation, but it has less redundancy due to redundant non-grouped attributes now just being represented in one tuple per the multiple tuples whose grouped attributes had them in common. A relation having relation-valued attributes like this is a common way to group so-called child tuples under their parents. As a trivial case, if inner is empty, then the result has all the same tuples and attributes as before plus a new relation-typed attribute of degree zero whose value per tuple is of cardinality one; or, if inner lists all attributes of topic, then the result has a single tuple of a single attribute whose value is the same as topic (except that the result has zero tuples when topic does). This function supports the new attribute having the same name as an old one being grouped into it. This function will fail if inner specifies any attribute names that topic doesn't have, or if outer is the same as topic attributes that aren't being grouped. Note that this operation is also known as nest or @{@<-}.
sys.std.Core.Relation.cmpl_group
function sys.std.Core.Relation.cmpl_group (Relation <-- Relation $topic, Name $outer, set_of.Name $group_per)
This function is the same as group but that it groups the complementary subset of attributes of topic to those specified by group_per. Note that this operation is also known as @{@<-!}.
sys.std.Core.Relation.ungroup
function sys.std.Core.Relation.ungroup (Relation <-- Relation $topic, set_of.Name $inner, Name $outer)
This function is the inverse of sys.std.Core.Relation.group as sys.std.Core.Relation.unwrap is to sys.std.Core.Relation.wrap; it will ungroup a Relation-type attribute into its member attributes and tuples. A relation can be first grouped and then that result ungrouped to produce the original relation, with no data loss. However, the ungroup of a relation on a relation-valued attribute will lose the information in any outer relation tuples whose inner relation value has zero tuples; a group on this result won't bring them back. This function will fail if outer specifies any attribute name that topic doesn't have, or if an attribute of topic{outer} has the same name as another topic attribute. This function will fail with a non-DHRelation valued topic unless, for every tuple of topic, the attribute specified by outer is valued with a relation of the same degree and heading (attribute names); this failure is because there would be no consistent set of attribute names to extend topic with (a problem that would never happen by definition with a deeply homogeneous relation topic). Note that this operation is also known as unnest or @{<-@}.
sys.std.Core.Relation.restriction
function sys.std.Core.Relation.restriction (Relation <-- Relation $topic, ValFiltFuncRef $func)
This function results in the relational restriction of its topic argument as determined by applying the value_filter function named in its func argument. The result relation has the same heading as topic, and its body contains the subset of topic tuples where, for each tuple, the function named by func results in Bool:true when passed the tuple as its topic argument. As a trivial case, if func is defined to unconditionally result in Bool:true, then this function results simply in topic; or, for an unconditional Bool:false, this function results in the empty relation with the same heading. Note that this operation is also known as where. See also the sys.std.Core.Relation.semijoin function, which is a simpler-syntax alternative for sys.std.Core.Relation.restriction in its typical usage where restrictions are composed simply of anded or ored tests for attribute value equality.
sys.std.Core.Relation.restr_and_cmpl
function sys.std.Core.Relation.restr_and_cmpl (Tuple <-- Relation $topic, ValFiltFuncRef $func)
This function performs a 2-way partitioning of all the tuples of topic and results in a binary tuple whose attribute values are each relations that have the same heading as topic and complementary subsets of its tuples; the 2 result attributes have the names pass and fail, and their values are what sys.std.Core.Relation.restriction and sys.std.Core.Relation.cmpl_restr, respectively, would result in when given the same arguments.
sys.std.Core.Relation.cmpl_restr
function sys.std.Core.Relation.cmpl_restr (Relation <-- Relation $topic, ValFiltFuncRef $func)
This function is the same as restriction but that it results in the complementary subset of tuples of topic when given the same arguments. See also the sys.std.Core.Relation.semidiff function.
sys.std.Core.Relation.extension
function sys.std.Core.Relation.extension (Relation <-- Relation $topic, set_of.Name $attr_names, ValMapFuncRef $func)
This function results in the relational extension of its topic argument as determined by applying the Tuple-resulting value_map function named in its func argument. The result relation has a heading that is a superset of that of topic, and its body contains the same number of tuples, with all attribute values of topic retained, and possibly extra present, determined as follows; for each topic tuple, the function named by func results in a second tuple when passed the first tuple as its topic argument; the first and second tuples must have no attribute names in common, and the result tuple is derived by joining (cross-product) the tuples together. As a trivial case, if func is defined to unconditionally result in the degree-zero tuple, then this function results simply in topic. Now, extension requires the extra attr_names argument to prevent ambiguity in the general case where topic might have zero tuples, because in that situation, func would never be invoked, and the names of the attributes to add to topic are not known (we don't generally assume that extension can reverse-engineer func to see what attributes it would have resulted in). This function will fail if topic has at least 1 tuple and the result of func does not have matching attribute names to those named by attr_names.
sys.std.Core.Relation.static_exten
function sys.std.Core.Relation.static_exten (Relation <-- Relation $topic, Tuple $attrs)
This function is a simpler-syntax alternative to both sys.std.Core.Relation.extension and sys.std.Core.Relation.product in the typical scenario of extending a relation, given in the topic argument, such that every tuple has mutually identical values for each of the new attributes; the new attribute names and common values are given in the attrs argument.
sys.std.Core.Relation.summary
function sys.std.Core.Relation.summary (Relation <-- Relation $topic, set_of.Name $group_per, set_of.Name $summ_attr_names, ValMapFuncRef $summ_func)
This function provides a convenient context for using aggregate functions to derive a per-group summary relation, which is its result, from another relation, which is its topic argument. This function first performs a cmpl_group on topic using group_per to specify which attributes get grouped into a new relation-valued attribute and which don't; those that don't instead get wrapped into a tuple-valued attribute. Then, per binary tuple in the main relation, this function applies the Tuple-resulting value_map function named in its summ_func argument; for each post-group main relation tuple, the function named in summ_func results in a second tuple when the first tuple is its topic argument; the topic argument has the 2 attribute names summarize and per, which are valued with the relation-valued attribute and tuple-valued attribute, respectively. As per a function that extension applies, the function named by summ_func effectively takes a whole post-grouping input tuple and results in a partial tuple that would be joined by summary with the per tuple to get the result tuple; the applied function would directly invoke any N-adic/aggregate operators, and extract their inputs from (or calculate) summarize as it sees fit. Note that summary is not intended to be used to summarize an entire topic relation at once (except by chance of it resolving to 1 group); you should instead invoke your summarize-all summ_func directly, or inline it, rather than by way of summary, especially if you want a single-tuple result on an empty topic (which summary) won't do. Now, summary requires the extra summ_attr_names argument to prevent ambiguity in the general case where topic might have zero tuples, because in that situation, summ_func would never be invoked, and the names of the attributes to add to per are not known (we don't generally assume that summary can reverse-engineer summ_func to see what attributes it would have resulted in). This function will fail if topic has at least 1 tuple and the result of summ_func does not have matching attribute names to those named by summ_attr_names.
sys.std.Core.Relation.cardinality_per_group
function sys.std.Core.Relation.cardinality_per_group (Relation <-- Relation $topic, Name $count_attr_name, set_of.Name $group_per)
This function is a convenient shorthand for the common use of summary that is just counting the tuples of each group. This function is like cmpl_group but that the single added attribute, rather than an RVA of the grouped topic attributes, has the cardinality that said RVA would have had. The result's heading consists of the attributes named in group_per plus the attribute named in count_attr_name (a PInt). Note that this operation is also known as @{#@<-!}.
sys.std.Core.Relation.count_per_group
function sys.std.Core.Relation.count_per_group (Relation <-- Relation $topic, Name $count_attr_name, set_of.Name $group_per)
This function is an alias for sys.std.Core.Relation.cardinality_per_group.
SYSTEM-DEFINED GENERIC MULTIPLE INPUT RELATION FUNCTIONS
These functions are applicable to mainly relation types, but are generic in that they typically work with any relation types.
sys.std.Core.Relation.is_subset
function sys.std.Core.Relation.is_subset (Bool <-- Relation $topic, Relation $other)
This function results in Bool:true iff the set of tuples comprising topic is a subset of the set of tuples comprising other, and Bool:false otherwise. This function will warn if the input relations common-named attributes have declared types that are incompatible as per is_identical. Note that this operation is also known as ⊆.
sys.std.Core.Relation.is_not_subset
function sys.std.Core.Relation.is_not_subset (Bool <-- Relation $topic, Relation $other)
This function is exactly the same as sys.std.Core.Relation.is_subset except that it results in the opposite boolean value when given the same arguments. Note that this operation is also known as ⊈.
sys.std.Core.Relation.is_superset
function sys.std.Core.Relation.is_superset (Bool <-- Relation $topic, Relation $other)
This function is an alias for sys.std.Core.Relation.is_subset except that it transposes the topic and other arguments. This function results in Bool:true iff the set of tuples comprising topic is a superset of the set of tuples comprising other, and Bool:false otherwise. Note that this operation is also known as ⊇.
sys.std.Core.Relation.is_not_superset
function sys.std.Core.Relation.is_not_superset (Bool <-- Relation $topic, Relation $other)
This function is an alias for sys.std.Core.Relation.is_not_subset except that it transposes the topic and other arguments. This function is exactly the same as sys.std.Core.Relation.is_superset except that it results in the opposite boolean value when given the same arguments. Note that this operation is also known as ⊉.
sys.std.Core.Relation.union
function sys.std.Core.Relation.union (Relation <-- set_of.Relation $topic)
This function results in the relational union/inclusive-or of the N element values of its argument; it is a reduction operator that recursively takes each pair of input values and relationally unions (which is commutative, associative, and idempotent) them together until just one is left, which is the result. The result relation has the same heading as all of its inputs, and its body contains every tuple that is in any of the input relations. If topic has zero values, then this function will fail. Note that, conceptually union does have an identity value which could be this function's result when topic has zero values, which is the empty relation with the same heading, which is the per-distinct-heading identity value for relational union; however, since a topic with zero values wouldn't know the heading / attribute names for the result relation in question, it seems the best alternative is to require invoking code to work around the limitation somehow, which might mean it will supply the identity value explicitly as an extra topic element. Note that this operation is also known as ∪.
sys.std.Core.Relation.disjoint_union
function sys.std.Core.Relation.disjoint_union (Relation <-- set_of.Relation $topic)
This function is exactly the same as sys.std.Core.Relation.union except that it will fail if any 2 input values have a tuple in common.
sys.std.Core.Relation.intersection
function sys.std.Core.Relation.intersection (Relation <-- set_of.Relation $topic)
This function results in the relational intersection/and of the N element values of its argument; it is a reduction operator that recursively takes each pair of input values and relationally intersects (which is commutative, associative, and idempotent) them together until just one is left, which is the result. The result relation has the same heading as all of its inputs, and its body contains only the tuples that are in every one of the input relations. If topic has zero values, then this function will fail. Note that, conceptually intersection does have an identity value which could be this function's result when topic has zero values, which is the universal relation with the same heading (that is, the relation having all the tuples that could ever exist in a relation with that heading), which is the per-distinct-heading identity value for relational intersection; however, since a topic with zero values wouldn't know the heading / attribute names for the result relation in question (and even if they were, more information on attribute types would be needed to produce said universal relation, and even then it might be infinite or impossibly large), it seems the best alternative is to require invoking code to work around the limitation somehow, which might mean it will supply the identity value explicitly as an extra topic element. Note that this intersection operator is conceptually a special case of join, applicable when the headings of the inputs are the same, and the other will produce the same result as this when given the same inputs, but with the exception that intersection has a different identity value when given zero inputs. Note that this operation is also known as ∩.
sys.std.Core.Relation.diff
function sys.std.Core.Relation.diff (Relation <-- Relation $source, Relation $filter)
This function results in the relational difference when its filter argument is subtracted from its source argument. The result relation has the same heading as both of its arguments, and its body contains only the tuples that are in source and are not in filter. This function will warn if the input relations common-named attributes have declared types that are incompatible as per is_identical. Note that this difference operator is conceptually a special case of semidiff, applicable when the headings of the inputs are the same. Note that this operation is also known as minus or except or ∖.
sys.std.Core.Relation.semidiff
function sys.std.Core.Relation.semidiff (Relation <-- Relation $source, Relation $filter)
This function is the same as semijoin but that it results in the complementary subset of tuples of source when given the same arguments. Note that this operation is also known as antijoin or anti-semijoin or semiminus or !matching or not matching or ⊿.
sys.std.Core.Relation.antijoin
function sys.std.Core.Relation.antijoin (Relation <-- Relation $source, Relation $filter)
This function is an alias for sys.std.Core.Relation.semidiff.
sys.std.Core.Relation.semijoin_and_diff
function sys.std.Core.Relation.semijoin_and_diff (Tuple <-- Relation $source, Relation $filter)
This function performs a 2-way partitioning of all the tuples of source and results in a binary tuple whose attribute values are each relations that have the same heading as source and complementary subsets of its tuples; the 2 result attributes have the names pass and fail, and their values are what sys.std.Core.Relation.semijoin and sys.std.Core.Relation.semidiff, respectively, would result in when given the same arguments.
sys.std.Core.Relation.semijoin
function sys.std.Core.Relation.semijoin (Relation <-- Relation $source, Relation $filter)
This function results in the relational semijoin of its source and filter arguments. The result relation has the same heading as source, and its body contains the subset of source tuples that match those of filter as per join. Note that relational semijoin is conceptually a short-hand for first doing an ordinary relational join between its 2 arguments, and then performing a relational projection on all of the attributes that just source has. This function will fail|warn any time that join would fail|warn on the same 2 input relations. Note that this operation is also known as matching or ⋉.
sys.std.Core.Relation.join
function sys.std.Core.Relation.join (Relation <-- set_of.Relation $topic?)
This function results in the relational join of the N element values of its argument; it is a reduction operator that recursively takes each pair of input values and relationally joins (which is commutative, associative, and idempotent) them together until just one is left, which is the result. The result relation has a heading that is a union of all of the headings of its inputs, and its body is the result of first pairwise-matching every tuple of each input relation with every tuple of each other input relation, then where each member of a tuple pair has attribute names in common, eliminating pairs where the values of those attributes differ and unioning the remaining said tuple pairs, then eliminating any result tuples that duplicate others. If topic has zero values, then join results in the nullary relation with one tuple, which is the identity value for relational join. As a trivial case, if any input relation has zero tuples, then the function's result will too; or, if any input is the nullary relation with one tuple, that input can be ignored (see identity value); or, if any 2 inputs have no attribute names in common, then the join of just those 2 is a cartesian product; or, if any 2 inputs have all attribute names in common, then the join of just those 2 is an intersection; or, if for 2 inputs, one's set of attribute names is a proper subset of another's, then the join of just those two is a semijoin with the former filtering the latter. This function will warn if any input relations have attributes with common names where their declared types are incompatible as per is_identical. Note that this operation is also known as natural inner join or ⋈.
sys.std.Core.Relation.product
function sys.std.Core.Relation.product (Relation <-- set_of.Relation $topic?)
This function results in the relational cartesian/cross product of the N element values of its argument; it is conceptually a special case of join where all input relations have mutually distinct attribute names; unlike join, product will fail if any inputs have attribute names in common. Note that this operation is also known as cartesian/cross join or ×.
sys.std.Core.Relation.quotient
function sys.std.Core.Relation.quotient (Relation <-- Relation $dividend, Relation $divisor)
This function results in the quotient when its dividend argument is divided by its divisor argument using relational division. Speaking informally, say the relations dividend and divisor are called $A and $B, and their attribute sets are respectively named {X,Y} and {Y}, then the result relation has a heading composed of attributes {X} (so the result and divisor headings are both complementary subsets of the dividend heading); the result has all tuples {X} such that a tuple {X,Y} appears in $A for all tuples {Y} appearing in $B; that is, ($A ÷ $B) is shorthand for ($A@{X} ∖ (($A@{X} × $B) ∖ $A)@{X}). Note that this operation is also known as divideby or ÷.
SYSTEM-DEFINED GENERIC CONTROL FLOW FUNCTIONS
sys.std.Core.Control.func_invo
function sys.std.Core.Control.func_invo (Universal <-- FuncRef $function, Tuple $args?)
This function results in the result of invoking the other function named in its function argument with arguments supplied by this function's args argument; each attribute name of args is mapped to a parameter name of the invoked function, and the corresponding attribute value is the corresponding argument for the function invocation. This function will fail if the invoked function has any non-optional parameters such that there aren't any corresponding attributes in args, or if there are any attributes in args that don't have corresponding parameters, or if any attribute values aren't of the declared types of the corresponding parameters. The purpose of func_invo is to support invocation of any function whose name or parameters potentially aren't known until runtime; it forms the foundation of all other system-defined functions that want to invoke a function whose name they take as an argument. The args parameter is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
sys.std.Core.Control.curried_func
function sys.std.Core.Control.curried_func (FuncRef <-- FuncRef $function, Tuple $args)
This function results in a reference to a new anonymous function which is the result of currying the other function named in its function argument with 0..N arguments supplied by this function's args argument; each attribute name of args is mapped to a parameter name of the curried function, and the corresponding attribute value is the corresponding pre-bound parameter of the curried function. This function will fail if there are any attributes in args that don't have corresponding parameters, or if any attribute values aren't of the declared types of the corresponding parameters. A curried function effectively does not have the parameters of the original function that were pre-bound, and attempts to supply arguments to those on the curried function will fail. Note that the result of a curried_func invocation can be used as input to another one, as there is effectively no difference in their kind. The purpose of curried_func is to support the passing of functions as arguments to invocations of other routines where the passed function wants to use runtime-defined information in the context that invoked routine, without having to pass that information separately as additional routine arguments. Or the purpose of curried_func is just to easily support defining functions as simplified versions of others.
SYSTEM-DEFINED GENERIC UNIVERSAL UPDATERS
These update operators are applicable to values of any data type at all.
sys.std.Core.Universal.assign
updater sys.std.Core.Universal.assign (Universal &$target, Universal $v)
This update operator will update the variable supplied as its target argument so that it holds the value supplied as its v argument. This updater will fail if v isn't of the declared type of the variable behind target; this function will otherwise warn if the declared type of v isn't a subtype of the declared type of the variable behind target.
SYSTEM-DEFINED GENERIC TUPLE VARIABLE UPDATERS
Updaters That Rename Attributes
sys.std.Core.Tuple.assign_rename
updater sys.std.Core.Tuple.assign_rename (Tuple &$topic, AttrRenameMap $map)
This update operator is a short-hand for first invoking the sys.std.Core.Tuple.rename function with the same arguments, and then assigning the result of that function to topic. This procedure is analagous to the data-manipulation phase of a SQL RENAME TABLE|VIEW or ALTER TABLE|VIEW RENAME TO statement iff topic is Database-typed; each tuple of map corresponds to a renamed SQL table.
Updaters That Add Attributes
sys.std.Core.Tuple.assign_static_exten
updater sys.std.Core.Tuple.assign_static_exten (Tuple &$topic, Tuple $attrs)
This update operator is a short-hand for first invoking the sys.std.Core.Tuple.static_exten function with the same arguments, and then assigning the result of that function to topic. This procedure is analagous to the data-manipulation phase of a SQL CREATE TABLE|VIEW statement iff both arguments are Database-typed; each relation-typed attribute of attrs corresponds to a created SQL table.
Updaters That Remove Attributes
sys.std.Core.Tuple.assign_projection
updater sys.std.Core.Tuple.assign_projection (Tuple &$topic, set_of.Name $attr_names)
This update operator is a short-hand for first invoking the sys.std.Core.Tuple.projection function with the same arguments, and then assigning the result of that function to topic.
sys.std.Core.Tuple.assign_cmpl_proj
updater sys.std.Core.Tuple.assign_cmpl_proj (Tuple &$topic, set_of.Name $attr_names)
This update operator is a short-hand for first invoking the sys.std.Core.Tuple.cmpl_proj function with the same arguments, and then assigning the result of that function to topic. This procedure is analagous to the data-manipulation phase of a SQL DROP TABLE|VIEW statement iff topic is Database-typed; each relation-typed attribute named by attr_names corresponds to a dropped SQL table.
SYSTEM-DEFINED GENERIC RELATION VARIABLE UPDATERS
Updaters That Add Tuples
sys.std.Core.Relation.assign_insertion
updater sys.std.Core.Relation.assign_insertion (Relation &$r, Tuple $t)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.insertion function with the same arguments, and then assigning the result of that function to r. This updater is analagous to the general case of the single-row SQL "INSERT" statement.
sys.std.Core.Relation.assign_disjoint_ins
updater sys.std.Core.Relation.assign_disjoint_ins (Relation &$r, Tuple $t)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.disjoint_ins function with the same arguments, and then assigning the result of that function to r.
sys.std.Core.Relation.assign_union
updater sys.std.Core.Relation.assign_union (Relation &$topic, Relation $other)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.union function such that it has 2 input relations from assign_union's 2 arguments, and then assigning the result of that function to topic. This updater is analagous to the general case of the multiple-row SQL "INSERT" statement.
sys.std.Core.Relation.assign_disjoint_union
updater sys.std.Core.Relation.assign_disjoint_union (Relation &$topic, Relation $other)
This update operator is to sys.std.Core.Relation.disjoint_union what the function sys.std.Core.Relation.assign_union is to sys.std.Core.Relation.union.
Updaters That Remove Tuples
sys.std.Core.Relation.assign_deletion
updater sys.std.Core.Relation.assign_deletion (Relation &$r, Tuple $t)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.deletion function with the same arguments, and then assigning the result of that function to r.
sys.std.Core.Relation.assign_restriction
updater sys.std.Core.Relation.assign_restriction (Relation &$topic, ValFiltFuncRef $func)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.restriction function with the same arguments, and then assigning the result of that function to topic.
sys.std.Core.Relation.assign_cmpl_restr
updater sys.std.Core.Relation.assign_cmpl_restr (Relation &$topic, ValFiltFuncRef $func)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.cmpl_restr function with the same arguments, and then assigning the result of that function to topic. This updater is analagous to the general case of the SQL "DELETE" statement.
sys.std.Core.Relation.assign_intersection
updater sys.std.Core.Relation.assign_intersection (Relation &$topic, Relation $other)
This update operator is to sys.std.Core.Relation.intersection what the function sys.std.Core.Relation.assign_union is to sys.std.Core.Relation.union.
sys.std.Core.Relation.assign_diff
updater sys.std.Core.Relation.assign_diff (Relation &$source, Relation $filter)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.diff function with the same arguments, and then assigning the result of that function to source.
sys.std.Core.Relation.assign_semidiff
updater sys.std.Core.Relation.assign_semidiff (Relation &$source, Relation $filter)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.semidiff function with the same arguments, and then assigning the result of that function to source. This updater is analagous to the common case of the SQL "DELETE" statement where the criteria is simply a set of and-ed and or-ed value equality tests.
sys.std.Core.Relation.assign_antijoin
updater sys.std.Core.Relation.assign_antijoin (Relation &$source, Relation $filter)
This update operator is an alias for sys.std.Core.Relation.assign_semidiff.
sys.std.Core.Relation.assign_semijoin
updater sys.std.Core.Relation.assign_semijoin (Relation &$source, Relation $filter)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.semijoin function with the same arguments, and then assigning the result of that function to source.
Updaters That Rename Attributes
sys.std.Core.Relation.assign_rename
updater sys.std.Core.Relation.assign_rename (Relation &$topic, AttrRenameMap $map)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.rename function with the same arguments, and then assigning the result of that function to topic. This procedure is analagous to the data-manipulation phase of a SQL ALTER TABLE|VIEW RENAME COLUMN statement; each tuple of map corresponds to a renamed SQL table column.
Updaters That Add Attributes
sys.std.Core.Relation.assign_extension
updater sys.std.Core.Relation.assign_extension (Relation &$topic, set_of.Name $attr_names, ValMapFuncRef $func)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.extension function with the same arguments, and then assigning the result of that function to topic.
sys.std.Core.Relation.assign_static_exten
updater sys.std.Core.Relation.assign_static_exten (Relation &$topic, Tuple $attrs)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.static_exten function with the same arguments, and then assigning the result of that function to topic. This procedure is analagous to the data-manipulation phase of a SQL ALTER TABLE|VIEW ADD COLUMN statement; each attribute of attrs corresponds to an added SQL table column.
Updaters That Remove Attributes
sys.std.Core.Relation.assign_projection
updater sys.std.Core.Relation.assign_projection (Relation &$topic, set_of.Name $attr_names)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.projection function with the same arguments, and then assigning the result of that function to topic.
sys.std.Core.Relation.assign_cmpl_proj
updater sys.std.Core.Relation.assign_cmpl_proj (Relation &$topic, set_of.Name $attr_names)
This update operator is a short-hand for first invoking the sys.std.Core.Relation.cmpl_proj function with the same arguments, and then assigning the result of that function to topic. This procedure is analagous to the data-manipulation phase of a SQL ALTER TABLE|VIEW DROP COLUMN statement; each attribute named by attr_names corresponds to an dropped SQL table column.
SYSTEM-DEFINED GENERIC CONTROL FLOW UPDATERS
sys.std.Core.Control.upd_invo
updater sys.std.Core.Control.upd_invo (UpdRef $updater, Tuple &$upd_args, Tuple $ro_args?)
This update operator has the same purpose and features as sys.std.Core.Control.func_invo but that it invokes an updater rather than a function; there is no result to deal with, and there are both subject-to-update parameters and read-only parameters of the invoked updater to bind to; they are bound with the attributes of this updater's upd_args and ro_args arguments, respectively. The ro_args parameter is optional and defaults as per the args parameter of func_invo; the upd_args parameter is non-optional because an updater must always be invoked with at least one subject-to-update argument.
SYSTEM-DEFINED GENERIC SYSTEM SERVICES FOR STANDARD I/O
These system services are provided so Muldis D can do basic user input/output by itself, using standard input and standard output, like any general purpose programming language, and help satisfy its need to be computationally complete. For now they just work with plain (Unicode) text data, so one can implement a basic command-line program interface, or do basic invoker-setup file piping, as well as display diagnostics to standard error. These routines are not exhaustive, and their details are subject to future revision.
sys.std.Core.STDIO.read_Text
system_service sys.std.Core.STDIO.read_Text (Text &$target, NNInt $len_in_graphs)
This system service routine will attempt to read len_in_graphs characters from standard input as a single Text value, blocking the current in-DBMS process until it finishes, and then update the variable supplied as its target argument so that it holds the read value. The routine will only fetch fewer than the requested number of characters if the input stream is closed first. This routine will throw an exception if any system errors occur.
sys.std.Core.STDIO.read_Text_line
system_service sys.std.Core.STDIO.read_Text_line (Text &$target, Bool $ignore_empty_lines?)
This system service routine is the same as sys.std.Core.STDIO.read_Text except that it will read from standard input until an implementation-defined end-of-line character is read, rather than reading a fixed number of characters; this end-of-line character will not be included in the read Text value. If the ignore_empty_lines argument is Bool:true, then this routine will keep reading lines from standard input until it reads a non-empty line, and then target is only updated to hold that last non-empty line; otherwise, this routine will end as soon as one line is read, even if it is empty.
sys.std.Core.STDIO.write_Text
system_service sys.std.Core.STDIO.write_Text (Text $v)
This system service routine will attempt to write the characters of its v argument to standard output, blocking the current in-DBMS process until it finishes. This routine will throw an exception if any system errors occur.
sys.std.Core.STDIO.write_Text_line
system_service sys.std.Core.STDIO.write_Text_line (Text $v)
This system service routine is the same as sys.std.Core.STDIO.write_Text except that it will additionally write an implementation-defined end-of-line character after writing v.
sys.std.Core.STDIO.prompt_Text_line
system_service sys.std.Core.STDIO.prompt_Text_line (Text &$target, Text $prompt, Bool $ignore_empty_lines? )
This system service routine is a wrapper over first invoking sys.std.Core.STDIO.write_Text with its prompt argument and then invoking sys.std.Core.STDIO.read_Text_line with its target argument. A true ignore_empty_lines argument will result in both of the wrapped routines being invoked repeatedly, not just read_text_line.
sys.std.Core.STDIO.error_Text
system_service sys.std.Core.STDIO.error_Text (Text $v)
This system service routine is the same as sys.std.Core.STDIO.write_Text except that it will write to standard error rather than standard output.
sys.std.Core.STDIO.error_Text_line
system_service sys.std.Core.STDIO.error_Text_line (Text $v)
This system service routine is the same as sys.std.Core.STDIO.write_Text_line except that it will write to standard error rather than standard output.
SYSTEM-DEFINED GENERIC CONTROL FLOW PROCEDURES
These procedures are applicable to use in all kinds of procedures.
sys.std.Core.Control.imp_invo
procedure sys.std.Core.Control.imp_invo (ImpRef $imperative, Tuple &$upd_args?, Tuple $ro_args?)
This procedure is the same as sys.std.Core.Control.upd_invo but that it invokes any kind of imperative routine rather than just an updater, and that upd_args is optional.
sys.std.Core.Control.fail
procedure sys.std.Core.Control.fail (Exception $topic)
This procedure will throw the exception given as its argument; this results in the call stack unwinding, and transaction rollbacks, until it is caught.
sys.std.Core.Control.try_catch
procedure sys.std.Core.Control.try_catch (ImpRef $try, Tuple &$try_upd_args?, Tuple $try_ro_args?, ImpRef $catch?, Tuple &$catch_upd_args?, Tuple $catch_ro_args?)
This procedure invokes the imperative routine named in its try argument with arguments supplied by this procedure's try_upd_args and try_ro_args arguments; each attribute name of try_[upd|ro]_args is mapped to a parameter name of the invoked imperative, and the corresponding attribute value is the corresponding argument for the imperative invocation. If the try routine throws an exception, then any state changes it made roll back (but changes made before that don't), and the call stack unwinds to the try_catch itself; then the imperative routine named by catch is invoked similarly to try was, with corresponding arguments, but with the extra read-only argument topic whose value is an Exception; if the catch routine also throws an exception (such as to say its not handling the thrown one), then that one is not caught and the call stack unwinding plus applicable transaction rollback carries on to the caller of the try_catch. If the try routine succeeds (doesn't throw an exception), then the catch routine is not called. Each of the [try|catch]_[upd|ro]_args parameters is optional and defaults to the zero-attribute tuple if no explicit argument is given to it.
SEE ALSO
Go to Muldis::D for the majority of distribution-internal references, and Muldis::D::SeeAlso for the majority of distribution-external references.
AUTHOR
Darren Duncan (perl@DarrenDuncan.net)
LICENSE AND COPYRIGHT
This file is part of the formal specification of the Muldis D language.
Muldis D is Copyright © 2002-2009, Muldis Data Systems, Inc.
See the LICENSE AND COPYRIGHT of Muldis::D for details.
TRADEMARK POLICY
The TRADEMARK POLICY in Muldis::D applies to this file too.
ACKNOWLEDGEMENTS
The ACKNOWLEDGEMENTS in Muldis::D apply to this file too.