/ 
Language-MuldisD-0.22.1
/ Language::MuldisD::Core::Functions_Nonscalar

NAME

Language::MuldisD::Core::Functions_Nonscalar - Muldis D general purpose nonscalar functions

VERSION

This document is Language::MuldisD::Core::Functions_Nonscalar version 0.19.1.

PREFACE

This document is part of the Muldis D language specification, whose root document is Language::MuldisD; you should read that root document before you read this one, which provides subservient details. Moreover, you should read the Language::MuldisD::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 Language::MuldisD::Core so that that other document would not be too large.

SYSTEM-DEFINED CORE GENERIC NONSCALAR FUNCTIONS

These functions are applicable to mainly nonscalar types, but are generic in that they typically work with any nonscalar types.

Functions for sys.Core.Tuple.Tuple Having Single Input Tuples

function sys.Core.Tuple.degree result UInt params { topic(Tuple) }

This function results in the degree of its argument (that is, the count of attributes it has).

function sys.Core.Tuple.attr_from_Tuple result ScaTupRel params { topic(Tuple) }

This function results in the scalar or nonscalar value of the sole attribute of its argument. This function will fail if its argument is not of degree 1.

function sys.Core.Tuple.Tuple_from_attr result Tuple params { name(Cat.Name), value(ScaTupRel) }

This function results in the Tuple value which has just one attribute whose name is given by name and whose value is given by value; the attribute's declared type is the same as that of value.

function sys.Core.Tuple.attr result ScaTupRel params { topic(Tuple), name(Cat.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.

function sys.Core.Tuple.update_attr result Tuple params { topic(Tuple), name(Cat.Name), value(ScaTupRel) }

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, or if the declared type of value isn't a subtype of the declared type of the attribute.

function sys.Core.Tuple.multi_update result Tuple params { topic(Tuple), attrs(Tuple) }

This function is like sys.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.Core.Tuple.static_substitution.

function sys.Core.Tuple.substitution_in_default result Tuple params { of(Cat.NameChain), subst(Tuple) }

This function results in the tuple value that is the default value of the tuple data type whose name is given in the of argument, but that zero or more of its attribute values have been substituted by values given in the subst argument. This function is a short-hand for sys.Core.Tuple.multi_update on the result of sys.Core.Universal.default. This function will fail if either default would fail for the same of argument, or if its result isn't a tuple type, or if the heading of subst isn't a subset of the heading of the default. The purpose of this function is to support greater brevity in Muldis D coding such that users can define just part of a desired tuple value and have the remainder filled in from defaults for them; particularly useful with tuples that conceptually have some optional attributes.

function sys.Core.Tuple.rename result Tuple params { topic(Tuple), map(Cat.AttrRenameMap) }

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 before and after attributes of a map tuple representing the old and new 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.

function sys.Core.Tuple.projection result Tuple params { topic(Tuple), attrs(Cat.SetOfName) }

This function results in the projection of its topic argument that has just the subset of attributes of topic which are named in its attrs argument. As a trivial case, this function's result is topic if attrs lists all attributes of topic; or, it is the nullary tuple if attrs is empty. This function will fail if attrs specifies any attribute names that topic doesn't have.

function sys.Core.Tuple.cmpl_projection result Tuple params { topic(Tuple), attrs(Cat.SetOfName) }

This function is the same as projection but that it results in the complementary subset of attributes of topic when given the same arguments.

function sys.Core.Tuple.wrap result Tuple params { topic(Tuple), inner(Cat.SetOfName), outer(Cat.Name) }

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 topic attributes that aren't being wrapped.

function sys.Core.Tuple.cmpl_wrap result Tuple params { topic(Tuple), cmpl_inner(Cat.SetOfName), outer(Cat.Name) }

This function is the same as wrap but that it wraps the complementary subset of attributes of topic to those specified by cmpl_inner.

function sys.Core.Tuple.unwrap result Tuple params { topic(Tuple), outer(Cat.Name) }

This function is the inverse of sys.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} is the same as another topic attribute.

Functions for sys.Core.Tuple.Tuple Having Multiple Input Tuples

function sys.Core.Tuple.product result Tuple params { topic(QuasiSetOfTuple) }

This function is similar to sys.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.

Functions for sys.Core.Relation.Relation Having Single Input Relations

function sys.Core.Relation.degree result UInt params { topic(Relation) }

This function results in the degree of its argument (that is, the count of attributes it has).

function sys.Core.Relation.cardinality result UInt params { topic(Relation) }

This function results in the cardinality of its argument (that is, the count of tuples its body has).

function sys.Core.Relation.is_empty result Bool params { topic(Relation) }

This function results in Bool:true iff its argument has zero tuples, and Bool:false otherwise. Note that if you are using a Maybe to represent a sparse data item, analagously to a SQL nullable context, then testing the Maybe with is_empty is analagous to testing a SQL nullable with is null.

function sys.Core.Relation.is_not_empty result Bool params { topic(Relation) }

This function is exactly the same as sys.Core.Relation.is_empty except that it results in the opposite boolean value when given the same argument. And following the analogy with is_empty, is_not_empty is analagous to SQL's is not null.

function sys.Core.Relation.is_member result Bool params { r(Relation), t(Tuple) }

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 is like sys.Core.Relation.is_subset except that the tuple being looked for doesn't have to be wrapped in a relation. This function will fail if the 2 arguments don't have the same heading.

function sys.Core.Relation.is_not_member result Bool params { r(Relation), t(Tuple) }

This function is exactly the same as sys.Core.Relation.is_member except that it results in the opposite boolean value when given the same arguments.

function sys.Core.Relation.Tuple_from_Relation result Tuple params { topic(Relation) }

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.

function sys.Core.Relation.Relation_from_Tuple result Relation params { topic(Tuple) }

This function results in the Relation value those body has just the one Tuple that is its argument.

function sys.Core.Relation.insertion result Relation params { r(Relation), t(Tuple) }

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.

function sys.Core.Relation.disjoint_insertion result Relation params { r(Relation), t(Tuple) }

This function is exactly the same as sys.Core.Relation.insertion except that it will fail if t already exists in r.

function sys.Core.Relation.deletion result Relation params { r(Relation), t(Tuple) }

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.

function sys.Core.Relation.empty result Relation params { topic(Relation) }

This function results in the empty relation of the same heading of its argument; it has zero tuples.

function sys.Core.Relation.universal result Relation params { topic(Relation) }

This function results in the universal relation of the same heading of its argument; that is, the relation having all the tuples that could ever exist in a relation with that heading. This function will fail if said universal relation is impossible or impractically large to represent, such as when any attributes are of infinite types.

function sys.Core.Relation.power_set result SetOfRelation params { topic(Relation) }

This function results in the power set of its argument. The result is a Set whose sole attribute is Relation-typed (its type is nominally the same as that of the argument) and which has a tuple for every distinct subset of tuples in the argument. The cardinality of the result is equal to 2 raised to the power of the cardinality of the argument (which may easily lead to a very large result, so use this function with care). Note that the N-ary relational union of the power set of some relation is that relation; the N-ary intersection of any power set is the empty relation.

function sys.Core.Relation.negation result Relation params { topic(Relation) }

This function results in the relational negation/not of its argument. The result relation has the same heading as its argument, and its body contains all of the tuples that are in the universal relation of the same heading and that are not in the argument; that is, the result is the relational difference when the argument is subtracted from said universal relation. This function will fail on any argument that sys.Core.Relation.universal would fail on.

function sys.Core.Relation.rename result Relation params { topic(Relation), map(Cat.AttrRenameMap) }

This function is the same as sys.Core.Tuple.rename but that it operates on and results in a Relation rather than a Tuple.

function sys.Core.Relation.projection result Relation params { topic(Relation), attrs(Cat.SetOfName) }

This function is the same as sys.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.

function sys.Core.Relation.cmpl_projection result Relation params { topic(Relation), attrs(Cat.SetOfName) }

This function is the same as sys.Core.Tuple.cmpl_projection but that it operates on and results in a Relation rather than a Tuple.

function sys.Core.Relation.wrap result Relation params { topic(Relation), inner(Cat.SetOfName), outer(Cat.Name) }

This function is the same as sys.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.Core.Tuple.wrap.

function sys.Core.Relation.cmpl_wrap result Relation params { topic(Relation), cmpl_inner(Cat.SetOfName), outer(Cat.Name) }

This function is the same as sys.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.Core.Tuple.cmpl_wrap.

function sys.Core.Relation.unwrap result Relation params { topic(Relation), outer(Cat.Name), inner(Cat.SetOfName) }

This function is the inverse of sys.Core.Relation.wrap as sys.Core.Tuple.unwrap is to sys.Core.Tuple.wrap. But unlike the 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}.

function sys.Core.Relation.group result Relation params { topic(Relation), inner(Cat.SetOfName), outer(Cat.Name) }

This function is similar to sys.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. 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.

function sys.Core.Relation.cmpl_group result Relation params { topic(Relation), group_per(Cat.SetOfName), outer(Cat.Name) }

This function is the same as group but that it groups the complementary subset of attributes of topic to those specified by group_per.

function sys.Core.Relation.ungroup result Relation params { topic(Relation), outer(Cat.Name), inner(Cat.SetOfName) }

This function is the inverse of sys.Core.Relation.group as sys.Core.Relation.unwrap is to sys.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} is the same as another topic attribute.

function sys.Core.Relation.transitive_closure result Relation params { topic(Relation) }

This function results in the transitive closure of its argument. The argument is a binary relation whose attributes are both of the same declared type, and the result is a relation having the same heading and a body which is a superset of the argument's tuples. Assuming that the argument represents all of the node pairs in a directed graph that have an arc between them, and so each argument tuple represents an arc, transitive_closure will determine all of the node pairs in that graph which have a path between them (a recursive operation), so each tuple of the result represents a path. The result is a superset since all arcs are also complete paths. The transitive_closure function is intended to support recursive queries, such as in connection with the "part explosion problem" (the problem of finding all components, at all levels, of some specified part).

function sys.Core.Relation.reduction result Tuple params { topic(Relation), func(Cat.NameChain), assuming(Tuple), identity(Tuple) }

This function is a generic reduction operator that recursively takes each pair of tuples in topic and applies an argument-specified tuple value-resulting function (which is both commutative and associative) to the pair until just one input tuple is left, which is the result. The function to apply is named in the func argument, and that function must have 3 arguments named v1, v2, assuming; the last parameter is curried with the same-named argument of reduction, and the first 2 parameters are the 2 input tuples for an invocation. If topic has zero tuples, then reduction results in the tuple given in identity. Note that identity may be changed to take a function name rather than a value, for consistency with func. This function will fail if the declared headings of identity and topic aren't compatible.

function sys.Core.Relation.maybe_reduction result MaybeOfTuple params { topic(Relation), func(Cat.NameChain), assuming(Tuple) }

This function is exactly the same as sys.Core.Relation.reduction except that it does not take an assuming argument, and it results in a Maybe of what is otherwise the result type, and that result has zero elements if the argument has zero elements.

function sys.Core.Relation.restriction result Relation params { topic(Relation), func(Cat.NameChain), assuming(Tuple) }

This function results in the relational restriction of its topic argument as determined by applying the Bool-resulting function named in its func argument when the latter function is curried by its assuming 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 and assuming as its assuming 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 legitimately known as where. See also the sys.Core.Relation.semijoin function, which is a simpler-syntax alternative for sys.Core.Relation.restriction in its typical usage where restrictions are composed simply of anded or ored tests for attribute value equality.

function sys.Core.Relation.cmpl_restriction result Relation params { topic(Relation), func(Cat.NameChain), assuming(Tuple) }

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.Core.Relation.semidifference function.

function sys.Core.Relation.extension result Relation params { topic(Relation), func(Cat.NameChain), assuming(Tuple) }

This function results in the relational extension of its topic argument as determined by applying the Tuple-resulting function named in its func argument when the latter function is curried by its assuming 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 and assuming as its assuming 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.

function sys.Core.Relation.static_extension result Relation params { topic(Relation), attrs(Tuple) }

This function is a simpler-syntax alternative to both sys.Core.Relation.extension and sys.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.

function sys.Core.Relation.substitution result Relation params { topic(Relation), func(Cat.NameChain), assuming(Tuple) }

This function is similar to extension except that it substitutes values of existing relation attributes rather than adding new attributes. The result relation has the same heading as topic. The result tuple of the function named in func must have a heading that is a subset of the heading of topic; corresponding values resulting from the function named in func will replace the values of the tuples of topic. The result relation has a cardinality that is the same as that of topic, unless the result of any substitutions was redundant tuples, in which case the result has appropriately fewer tuples. As a trivial case, if func is defined to unconditionally result in either the degree-zero tuple or in the same tuple as its own topic argument, then this function results simply in topic; or, if func is defined to have a static result and it replaces all attributes, then this function's result will have just 0..1 tuples.

function sys.Core.Relation.static_substitution result Relation params { topic(Relation), attrs(Tuple) }

This function is a simpler-syntax alternative to sys.Core.Relation.substitution in the typical scenario where every tuple of a relation, given in the topic argument, is updated with identical values for the same attributes; the new attribute values are given in the attrs argument.

function sys.Core.Relation.substitution_in_restriction result Relation params { topic(Relation), restr_func(Cat.NameChain), restr_assuming(Tuple), subst_func(Cat.NameChain), subst_assuming(Tuple) }

This function is like substitution except that it only transforms a subset of the tuples of topic rather than all of them. It is a short-hand for first separating the tuples of topic into 2 groups where those passed by a relational restriction (defined by restr_func and restr_assuming) are then transformed (defined by subst_func and subst_assuming), then the result of the substitution is unioned with the un-transformed group. See also the substitution_in_semijoin function, which is a simpler-syntax alternative for substitution_in_restriction in its typical usage where restrictions are composed simply of anded or ored tests for attribute value equality.

function sys.Core.Relation.static_substitution_in_restriction result Relation params { topic(Relation), restr_func(Cat.NameChain), restr_assuming(Tuple), subst(Tuple) }

This function is to sys.Core.Relation.substitution_in_restriction what sys.Core.Relation.static_substitution is to sys.Core.Relation.substitution. See also the static_substitution_in_semijoin function.

function sys.Core.Relation.map result Relation params { topic(Relation), func(Cat.NameChain), assuming(Tuple) }

This function provides a convenient one-place generalization of per-tuple transformations that otherwise might require the chaining of up to a half-dozen other operators like restriction, extension, and rename. This function results in a relation each of whose tuples is the result of applying, to each of the tuples of its topic argument, the Tuple-resulting function named in its func argument when the latter function is curried by its assuming argument. There is no restriction on what attributes the result tuple of func may have (except that all tuples from func must have compatible headings); this tuple from func would completely replace the original tuple from topic. The result relation has a cardinality that is the same as that of topic, unless the result of func was redundant tuples, in which case the result has appropriately fewer tuples. As a trivial case, if func is defined to unconditionally result in the same tuple as its own topic argument, then this function results simply in topic; or, if func is defined to have a static result, then this function's result will have just 0..1 tuples.

function sys.Core.Relation.summary result Relation params { topic(Relation), group_per(Cat.SetOfName), summ_func(Cat.NameChain), summ_assuming(Tuple) }

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 tuple in the main relation, this function applies the Tuple-resulting function named in its summ_func argument when the latter function is curried by its summ_assuming argument (passed to it as just assuming); the curried function has, rather than the typical 1 topic varying parameter, 2 varying parameters named summarize and per, which are valued with the relation-valued attribute and tuple-valued attribute, respectively. As per a function that map applies, the function named by summ_func effectively takes a whole post-grouping input tuple and results in a whole tuple; the applied function would directly invoke any N-ary / 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 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.

Functions for sys.Core.Relation.Relation Having Multiple Input Relations

function sys.Core.Relation.is_subset result Bool params { look_in(Relation), look_for(Relation) }

This function results in Bool:true iff the set of tuples comprising look_for is a subset of the set of tuples comprising look_in, and Bool:false otherwise. This function will fail if the 2 arguments don't have the same heading.

function sys.Core.Relation.is_not_subset result Bool params { look_in(Relation), look_for(Relation) }

This function is exactly the same as sys.Core.Relation.is_subset except that it results in the opposite boolean value when given the same arguments.

function sys.Core.Relation.is_proper_subset result Bool params { look_in(Relation), look_for(Relation) }

This function is exactly the same as sys.Core.Relation.is_subset except that it results in Bool:false if its 2 arguments are equal.

function sys.Core.Relation.is_not_proper_subset result Bool params { look_in(Relation), look_for(Relation) }

This function is exactly the same as sys.Core.Relation.is_proper_subset except that it results in the opposite boolean value when given the same arguments.

function sys.Core.Relation.union result Relation params { topic(SetOfRelation) }

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 both commutative and associative) 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 union results in the empty relation with the same heading, which is the per-distinct-heading identity value for relational union.

function sys.Core.Relation.disjoint_union result Relation params { topic(SetOfRelation) }

This function is exactly the same as sys.Core.Relation.union except that it will fail if any 2 input values have a tuple in common.

function sys.Core.Relation.exclusion result Relation params { topic(BagOfRelation) }

This function results in the relational exclusion/exclusive-or of the N element values of its argument; it is a reduction operator that recursively takes each pair of input values and relationally excludes (which is both commutative and associative) 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 just an odd number of the input relations. If topic has zero values, then exclusion results in the empty relation with the same heading, which is the per-distinct-heading identity value for relational exclusion. Note that this operation is also legitimately known as symmetric difference.

function sys.Core.Relation.intersection result Relation params { topic(SetOfRelation) }

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 both commutative and associative) 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 intersection results in 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. 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. This function will fail on a topic of zero values if the result type's universal relation is impossible or impractically large to represent, such as when any attributes are of infinite types.

function sys.Core.Relation.difference result Relation params { source(Relation), filter(Relation) }

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 fail if its 2 arguments do not have the same heading. Note that this difference operator is conceptually a special case of semidifference, applicable when the headings of the inputs are the same.

function sys.Core.Relation.semidifference result Relation params { source(Relation), filter(Relation) }

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 legitimately known as antijoin or anti-semijoin.

function sys.Core.Relation.semijoin result Relation params { source(Relation), filter(Relation) }

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 any time that join would fail on the same 2 input relations.

function sys.Core.Relation.join result Relation params { topic(QuasiSetOfRelation) }

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 both commutative and associative) 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 to is a semijoin with the former filtering the latter. This function will fail if any input relations have attributes with common names but different/incompatible declared types. Note that this operation is also legitimately known as natural inner join.

function sys.Core.Relation.product result Relation params { topic(QuasiSetOfRelation) }

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 legitimately known as cartesian/cross join.

function sys.Core.Relation.composition result Relation params { r1(Relation), r2(Relation) }

This function results in the relational composition of its 2 arguments. It 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 only one of the arguments has; that is, the result has all of and just the attributes that were not involved in matching the tuples of the 2 arguments. This function will fail any time that join would fail on the same 2 input relations.

function sys.Core.Relation.quotient result Relation params { dividend(Relation), divisor(Relation) }

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} join B) - A){X}.

function sys.Core.Relation.substitution_in_semijoin result Relation params { topic(Relation), restr(Relation), subst_func(Cat.NameChain), subst_assuming(Tuple) }

This function is like substitution_in_restriction except that the subset of the tuples of topic to be transformed is determined by those matched by a semijoin with restr rather than those that pass a generic relational restriction.

function sys.Core.Relation.static_substitution_in_semijoin result Relation params { topic(Relation), restr(Relation), subst(Tuple) }

This function is to sys.Core.Relation.substitution_in_semijoin what sys.Core.Relation.static_substitution is to sys.Core.Relation.substitution.

function sys.Core.Relation.join_with_group result Relation params { primary(Relation), secondary(Relation), group_attr(Cat.Name) }

This function is a short-hand for first taking a (natural inner) join of its primary and secondary arguments, and then taking a group on all of the attributes that only the secondary argument had, such that the attribute resulting from the group has the name group_attr. The result has 1 tuple for every tuple of primary where at least 1 matching tuple exists in secondary. This function will fail if group_attr is the same name as any source attribute that wasn't grouped. This function is a convenient tool for gathering both parent and child records from a database using a single query while avoiding duplication of the parent record values.

function sys.Core.Relation.outer_join_with_group result Relation params { primary(Relation), secondary(Relation), group_attr(Cat.Name) }

This function is the same as sys.Core.Relation.join_with_group except that it results in a half-outer natural join rather than an inner natural join; every tuple of primary has exactly 1 corresponding tuple in the result, but where there were no matching secondary tuples, the result attribute named by group_attr contains zero tuples rather than 1+.

function sys.Core.Relation.outer_join_with_maybes result Relation params { primary(Relation), secondary(Relation) }

This function results in a plain half-outer natural join of its primary and secondary arguments where all the result attributes that come from just secondary are Maybe-typed; for result tuples from matched source tuples, each secondary attribute value is a Single; for result tuples from non-matched primary tuples, each secondary attribute value is a Nothing. The outer_join_with_maybes function is Muldis D's answer to the SQL LEFT OUTER JOIN where SQL NULL is implicitly used in result rows that were a non-match.

function sys.Core.Relation.outer_join_with_defaults result Relation params { primary(Relation), secondary(Relation) }

This function is the same as sys.Core.Relation.outer_join_with_maybes but that secondary-sourced result attributes are not converted to Maybe; rather, for result tuples from non-matches, the declared types of the secondary attributes are considered, and the default values of those types are used to fill in missing result values.

function sys.Core.Relation.outer_join_with_product result Relation params { primary(Relation), secondary(Relation), filler(Tuple) }

This function is the same as sys.Core.Relation.outer_join_with_defaults but that missing values are provided explicitly from the filler argument, which is a tuple whose heading matches the projection of secondary's attributes that aren't in common with primary, and whose body is the literal values to use for those missing attribute values. This function gets its name in that conceptually the result tuples from non-matches are the result of performing a relational cross-product between the un-matched primary tuples and the single filler tuple. This function could alternately be named outer_join_with_static_extension.

function sys.Core.Relation.outer_join_with_extension result Relation params { primary(Relation), secondary(Relation), exten_func(Cat.NameChain), exten_assuming(Tuple) }

This function is the same as sys.Core.Relation.outer_join_with_product but that the result tuples from non-matches are the result of performing a relational extension on the un-matched primary tuples such that each said result tuple is determined by applying the function named in exten_func to each said primary tuple when the named function is curried using the exten_assuming argument.

Functions for sys.Core.Relation.Set

function sys.Core.Set.is_member result Bool params { set(Set), value(ScaTupRel) }

This function results in Bool:true iff its value argument matches the sole attribute of a tuple of its set argument (that is, iff conceptually value is a member of set), and Bool:false otherwise. This function will fail if the declared type of value isn't a subtype of the declared type of the attribute.

function sys.Core.Set.is_not_member result Bool params { set(Set), value(ScaTupRel) }

This function is exactly the same as sys.Core.Set.is_member except that it results in the opposite boolean value when given the same arguments.

function sys.Core.Set.insertion result Set params { set(Set), value(ScaTupRel) }

This function results in a Set that is the relational union of set and a Set whose sole tuple has the sole attribute value of value; that is, conceptually the result is value inserted into set. As a trivial case, if value already exists in set, then the result is just set.

function sys.Core.Set.disjoint_insertion result Set params { set(Set), value(ScaTupRel) }

This function is exactly the same as sys.Core.Set.insertion except that it will fail if value already exists in set.

function sys.Core.Set.deletion result Set params { set(Set), value(ScaTupRel) }

This function results in a Set that is the relational difference from set of a Set whose sole tuple has the sole attribute value of value; that is, conceptually the result is value deleted from set. As a trivial case, if value already doesn't exist in set, then the result is just set.

function sys.Core.Set.reduction result ScaTupRel params { topic(Set), func(Cat.NameChain), assuming(Tuple), identity(ScaTupRel) }

This function is a generic reduction operator that recursively takes each pair of input values in topic and applies an argument-specified scalar or nonscalar value-resulting function (which is both commutative and associative) to the pair until just one input value is left, which is the result. The function to apply is named in the func argument, and that function must have 3 arguments named v1, v2, assuming; the last parameter is curried with the same-named argument of reduction, and the first 2 parameters are the 2 input scalar or nonscalar values for an invocation. If topic has zero values, then reduction results in the value given in identity. Note that identity may be changed to take a function name rather than a value, for consistency with func. This function will fail if the declared type of identity isn't a subtype of the declared type of the sole attribute of topic.

function sys.Core.Set.maybe_reduction result Maybe params { topic(Set), func(Cat.NameChain), assuming(Tuple) }

This function is exactly the same as sys.Core.Set.reduction except that it does not take an assuming argument, and it results in a Maybe of what is otherwise the result type, and that result has zero elements if the argument has zero elements.

function sys.Core.Set.Set_from_wrap result SetOfTuple params { topic(Relation) }

This function results in a Set whose sole attribute is tuple-typed and the attribute values are all the tuples of topic; is a short-hand for a relational wrap of all attributes of topic such that the new tuple-valued attribute is named value.

function sys.Core.Set.Set_from_attr result Set params { topic(Relation), name(Cat.Name) }

This function results in a Set consisting of all the values of the attribute of topic named by name. It is a short-hand for a unary projection of just the named attribute plus its renaming to value.

Functions for sys.Core.Relation.Maybe

function sys.Core.Maybe.nothing result Nothing params {}

This selector function results in the only zero-tuple Maybe value.

function sys.Core.Maybe.single result Single params { value(ScaTupRel) }

This selector function results in the Maybe value with a single tuple whose value attribute's value is the value argument.

function sys.Core.Maybe.attr result ScaTupRel params { topic(Single) }

This function results in the scalar or nonscalar value of the sole attribute of the sole tuple of its argument, which always exists when the argument is a Single.

function sys.Core.Maybe.attr_or_default result ScaTupRel params { topic(Maybe) }

This function results in the scalar or nonscalar value of the sole attribute of the sole tuple of its argument, if said tuple exists; otherwise, it results in the default value of the declared type of the said attribute.

function sys.Core.Maybe.attr_or_value result ScaTupRel params { topic(Maybe), value(ScaTupRel) }

This function results in the scalar or nonscalar value of the sole attribute of the sole tuple of topic, if said tuple exists; otherwise, it results in value. This function will fail if the declared type of value isn't a subtype of the declared type of the attribute.

Functions for sys.Core.Relation.Seq

function sys.Core.Seq.value result ScaTupRel params { topic(Seq), index(UInt) }

This function results in the scalar or nonscalar value attribute of the tuple of topic whose index attribute is index. This function will fail if no tuple exists in topic with the specified index.

function sys.Core.Seq.update_value result Seq params { topic(Seq), index(UInt), value(ScaTupRel) }

This function results in its topic argument but that the value attribute of the tuple of topic whose index attribute is index has been updated with a new scalar or nonscalar value given by value. This function will fail if no tuple exists in topic with the specified index, or if the declared type of value isn't a subtype of the declared type of the value attribute.

function sys.Core.Seq.insertion result Seq params { topic(Seq), index(UInt), value(ScaTupRel) }

This function results in its topic argument but that a new tuple has been inserted whose index is index and whose value is value; any existing tuples with index values greater than or equal to index had theirs incremented by 1. As a trivial case, if index is equal to zero or is equal to the cardinality of topic, then value has become the new first or last (or only) element, respectively. This function will fail if index is greater than the cardinality of topic, or if the declared type of value isn't a subtype of the declared type of the value attribute.

function sys.Core.Seq.deletion result Seq params { topic(Seq), index(UInt) }

This function results in its topic argument but that a tuple has been deleted whose index is index; any existing tuples with index values greater than or equal to index had theirs decremented by 1. This function will fail if no tuple exists in topic with the specified index.

function sys.Core.Seq.is_element result Bool params { topic(Seq), value(ScaTupRel) }

This function results in Bool:true iff its value argument matches the value attribute of at least one tuple of its topic argument (that is, iff conceptually value is an element of topic), and Bool:false otherwise. This function will fail if the declared type of value isn't a subtype of the declared type of that attribute.

function sys.Core.Seq.is_not_element result Bool params { topic(Seq), value(ScaTupRel) }

This function is exactly the same as sys.Core.Seq.is_element except that it results in the opposite boolean value when given the same arguments.

function sys.Core.Seq.reduction result ScaTupRel params { topic(Seq), func(Cat.NameChain), assuming(Tuple), identity(ScaTupRel) }

This function is the same as sys.Core.Set.reduction, including that input values for the reduction come from the value attribute of topic, except that it works with a Seq rather than a Set. Also, the function named in func is only associative, and not commutative; the arguments to v1 and v2 of func are guaranteed to be consecutive input elements, with the result returning to their place in sequence beween the other input elements.

function sys.Core.Seq.maybe_reduction result Maybe params { topic(Seq), func(Cat.NameChain), assuming(Tuple) }

This function is to sys.Core.Set.maybe_reduction as sys.Core.Seq.reduction is to sys.Core.Set.reduction.

function sys.Core.Seq.catenation result Seq params { topic(SeqOfSeq) }

This function results in the catenation of the N element values of its argument; it is a reduction operator that recursively takes each consecutive pair of input values and catenates (which is associative) them together until just one is left, which is the result. To catenate 2 Seq means to union their tuples after first increasing all the index values of the second one by the cardinality of the first one. If topic has zero values, then catenate results in the empty sequence value, which is the identity value for catenate.

function sys.Core.Seq.repeat result Seq params { topic(Seq), count(UInt) }

This function results in the catenation of count instances of topic.

function sys.Core.Seq.reverse result Seq params { topic(Seq) }

This function results in its argument but that the order of its elements has been reversed. For example, the input { 0=>'a', 1=>'b', 2=>'c', 3=>'d'} results in { 0=>'d', 1=>'c', 2=>'b', 3=>'a' }.

function sys.Core.Seq.is_subseq result Bool params { look_in(Seq), look_for(Seq) }

This function results in Bool:true iff the sequence of values comprising look_for is a sub-sequence of the sequence of values look_in, and Bool:false otherwise. This function will fail if the 2 arguments don't have the same heading.

function sys.Core.Seq.is_not_subseq result Bool params { look_in(Seq), look_for(Seq) }

This function is exactly the same as sys.Core.Seq.is_subseq except that it results in the opposite boolean value when given the same arguments.

Functions for sys.Core.Relation.Bag

function sys.Core.Bag.cardinality result UInt params { topic(Bag) }

This function is like sys.Core.Relation.cardinality but that it accounts for the greater-than-one multiplicity of values in its argument; it results in the sum of the count attribute of its argument.

function sys.Core.Bag.is_member result Bool params { bag(Bag), value(ScaTupRel) }

This function is the same as sys.Core.Set.is_member, including that matching of value is done against the value attribute, except that it works with a Bag rather than a Set.

function sys.Core.Bag.is_not_member result Bool params { bag(Bag), value(ScaTupRel) }

This function is exactly the same as sys.Core.Bag.is_member except that it results in the opposite boolean value when given the same arguments.

function sys.Core.Bag.count result UInt params { bag(Bag), value(ScaTupRel) }

This function results in the multiplicity / count of occurrances of value in bag; if a tuple exists in bag whose value attribute is value, then the result is its count attribute; otherwise the result is zero.

function sys.Core.Bag.insertion result Bag params { bag(Bag), value(ScaTupRel) }

This function is the same as sys.Core.Set.insertion as per is_member but that its result differs depending on whether value already exists in bag; if it does, then no new tuple is added, but the count attribute for the matching tuple is incremented by 1; if it does not, then a new tuple is added where its value is value and its count is 1.

function sys.Core.Bag.deletion result Bag params { bag(Bag), value(ScaTupRel) }

This function is the same as sys.Core.Set.deletion as per is_member but that its result differs depending on what the count for any tuple matching value that already exists in bag is; if the count is greater than 1, then it is decremented by 1; if it is equal to 1, then the tuple whose value is value is deleted.

function sys.Core.Bag.reduction result ScaTupRel params { topic(Bag), func(Cat.NameChain), assuming(Tuple), identity(ScaTupRel) }

This function is the same as sys.Core.Set.reduction, including that input values for the reduction come from the value attribute of topic, except that it works with a Bag rather than a Set; func is invoked extra times, where both its v1 and v2 arguments might be different instances of the same value having >= 2 multiplicity.

function sys.Core.Bag.maybe_reduction result Maybe params { topic(Bag), func(Cat.NameChain), assuming(Tuple) }

This function is to sys.Core.Set.maybe_reduction as sys.Core.Bag.reduction is to sys.Core.Set.reduction.

function sys.Core.Bag.Set_from_Bag result Set params { topic(Bag) }

This function results in the Set that is the projection of the value attribute of its Bag argument.

function sys.Core.Bag.Bag_from_Set result Bag params { topic(Set) }

This function results in the Bag that is the extension of its Set argument with a new count attribute whose value for every tuple is 1.

function sys.Core.Bag.Bag_from_wrap result BagOfTuple params { topic(Relation) }

This function results in a Bag whose value attribute is tuple-typed and that attribute's values are all the tuples of topic; is a short-hand for a relational wrap of all attributes of topic such that the new tuple-valued attribute is named value, and then that result is extended with a count attribute whose value for every tuple is 1.

function sys.Core.Bag.Bag_from_attr result Bag params { topic(Relation), name(Cat.Name) }

This function results in a Bag consisting of all the values of the attribute of topic named by name. It is a short-hand for first doing a relational group on all attributes of topic besides name to produce a new relation-typed attribute, and then extending the result of the group with a new positive integer attribute whose values are the cardinality of the relation-valued attribute's values, and then doing a binary projection of the named attribute and the new integer attribute plus their renaming to value and count respectively.

function sys.Core.Bag.is_subset result Bool params { look_in(Bag), look_for(Bag) }

This function is like sys.Core.Relation.is_subset but that it accounts for the greater-than-one multiplicity of values in its arguments; this function returns Bool:true iff the multiplicity of each look_for value is less than or equal to the multiplicity of its counterpart look_in value.

function sys.Core.Bag.is_not_subset result Bool params { look_in(Bag), look_for(Bag) }

This function is like sys.Core.Relation.is_not_subset as per is_subset.

function sys.Core.Bag.is_proper_subset result Bool params { look_in(Bag), look_for(Bag) }

This function is like sys.Core.Relation.is_proper_subset as per is_subset. TODO: What is its definition?

function sys.Core.Bag.is_not_proper_subset result Bool params { look_in(Bag), look_for(Bag) }

This function is like sys.Core.Relation.is_not_proper_subset as per is_subset. TODO: What is its definition?

function sys.Core.Bag.union result Bag params { topic(SetOfBag) }

This function is like sys.Core.Relation.union but that it just looks at the value attribute of its argument elements when determining what element tuples correspond; then for each tuple in the result, its count attribute value is the maximum of the count attribute values of its corresponding input element tuples.

function sys.Core.Bag.intersection result Bag params { topic(SetOfBag) }

This function is like sys.Core.Relation.intersection as union is like sys.Core.Relation.union; the minimum of count attribute values is used rather than the maximum.

function sys.Core.Bag.difference result Bag params { source(Bag), filter(Bag) }

This function is like sys.Core.Relation.difference as union is like sys.Core.Relation.union; for corresponding input tuples, the result only has a tuple with the same value if the count of the source tuple is greater than the count of the filter tuple, and the count of the result tuple is the difference of those two.

SEE ALSO

Go to Language::MuldisD for the majority of distribution-internal references, and Language::MuldisD::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-2008, Darren Duncan.

See the LICENSE AND COPYRIGHT of Language::MuldisD for details.

ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in Language::MuldisD apply to this file too.