=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Types -
Muldis D general purpose data types

=head1 VERSION

This document is Muldis::D::Core::Types version 0.25.0.

=head1 PREFACE

This document is part of the Muldis D language specification, whose root
document is L<Muldis::D>; you should read that root document before
you read this one, which provides subservient details.  Moreover, you
should read the L<Muldis::D::Core> document before this current
document, as that forms its own tree beneath a root document branch.

=head1 DESCRIPTION

This document contains one or more sections that were moved here from
L<Muldis::D::Core> so that that other document would not be too
large.

=head1 TYPE SUMMARY

Following are all the data types and data type factories described in this
document, arranged in a type graph according to their proper sub|supertype
relationships:

    sys.std.Core.Type.Universal

        sys.std.Core.Type.Empty

        sys.std.Core.Type.Scalar

            # The following are all regular ordered scalar types.

            sys.std.Core.Type.Bool
            sys.std.Core.Type.Int
                sys.std.Core.Type.UInt
                    sys.std.Core.Type.PInt
            sys.std.Core.Type.Blob
            sys.std.Core.Type.Text

        # The following are mostly nonscalar type factories.

        sys.std.Core.Type.Tuple
            sys.std.Core.Type.TupleD0
            sys.std.Core.Type.Database

        sys.std.Core.Type.Relation
            sys.std.Core.Type.RelationD0
            sys.std.Core.Type.Set
                sys.std.Core.Type.Maybe
                    sys.std.Core.Type.Nothing
                    sys.std.Core.Type.Single
            sys.std.Core.Type.Array
            sys.std.Core.Type.Bag

        # The following is filler, to group possible user-def types.

        sys.std.Core.Type.QuasiScalar
            sys.std.Core.Type.QuasiScalarDVPT

        # The following are mostly quasi-nonscalar type factories.

        sys.std.Core.Type.QuasiTuple
            sys.std.Core.Type.QuasiTupleD0

        sys.std.Core.Type.QuasiRelation
            sys.std.Core.Type.QuasiRelationD0
            sys.std.Core.Type.QuasiSet
                sys.std.Core.Type.QuasiMaybe
                    sys.std.Core.Type.QuasiNothing
                    sys.std.Core.Type.QuasiSingle
            sys.std.Core.Type.QuasiArray
            sys.std.Core.Type.QuasiBag

        # The following are all remnant types.

        sys.std.Core.Type.Remnant
            sys.std.Core.Type.ScaTupRel

Note that C<sys.std.Core.Type.Empty> is a proper subtype of all of the
other types in this graph, but every other type has only one immediate
supertype shown, and hence the graph of them is a simple hierarchy.

=head1 SYSTEM-DEFINED CORE MAXIMAL AND MINIMAL DATA TYPES

These core data types are special and are the only Muldis D types that are
neither scalar nor nonscalar nor quasi-nonscalar types.  They are all
system-defined and it is impossible for users to define more types of this
nature.

=head2 sys.std.Core.Type.Universal

The C<Universal> type is the maximal type of the entire Muldis D type
system, and contains every value that can possibly exist.  Every other type
is implicitly a proper subtype of C<Universal>, and C<Universal> is
implicitly a union type over all other types.  Its default value is
C<Bool:false>.  The cardinality of this type is infinity.

=head2 sys.std.Core.Type.Empty

The C<Empty> type is the minimal type of the entire Muldis D type system,
and is the only type that contains exactly zero values.  Every other type
is implicitly a proper supertype of C<Empty> and C<Empty> is implicitly an
intersection type over all other types.  It has no default value.  The
cardinality of this type is zero.

=head1 SYSTEM-DEFINED CORE SCALAR DATA TYPES

These core scalar data types are the most fundamental Muldis D types.  Each
one has zero possreps, and hence has no named components that can be
referenced.  Plain Text Muldis D provides a specific syntax per type to
select a value of one of these types, which does not look like a routine
invocation, but rather like a scalar literal in a typical programming
language; details of that syntax are not given here, but in
L<Muldis::D::Dialect::PTMD_Tiny>.  Hosted Data Muldis D as hosted in
another language will essentially use literals of corresponding host
language types, whatever they use for eg booleans and integers and
character strings, but tagged with extra meta-data if the host language is
more weakly typed or lacks one-to-one type correspondence; see
L<Muldis::D::Dialect::HDMD_Perl_Tiny> for a Perl-based example.  These
types, except for C<Scalar>, are all ordered.

=head2 sys.std.Core.Type.Scalar

The C<Scalar> type is the maximal type of all Muldis D scalar types, and
contains every scalar value that can possibly exist.  Every other scalar
type is implicitly a proper subtype of C<Scalar>, and C<Scalar> is
implicitly a union type over all other scalar types.  Its default value is
C<Bool:false>.  The cardinality of this type is infinity.

=head2 sys.std.Core.Type.Bool

A C<Bool> is a scalar enumeration consisting of the 2 values C<Bool:false>
and C<Bool:true>.  It represents a truth value, and is the result type of
any C<is_identical> or C<is_not_identical> routine; it is the only
essential general-purpose scalar data type of a B<D> language.  Its default
and minimum value is C<Bool:false>; its maximum value is C<Bool:true>.  The
cardinality of this type is 2.  The C<Bool> type has a default ordering
algorithm; C<Bool:false> is ordered before C<Bool:true>.

=head2 sys.std.Core.Type.Int

An C<Int> is a single exact integral number of any magnitude.  Its default
value is zero; its minimum and maximum values are conceptually infinities
and practically impossible.  The cardinality of this type is infinity; to
define a most-generalized finite C<Int> subtype, you must specify the 2
integer end-points of the inclusive range that all its values are in.  The
C<Int> type has a default ordering algorithm; for 2 distinct C<Int> values,
the value closer to negative infinity is ordered before the value closer to
positive infinity.

=head2 sys.std.Core.Type.UInt

A C<UInt> (unsigned / non-negative integer) is a proper subtype of C<Int>
where all member values are greater than or equal to zero.  Its minimum
value is zero.

=head2 sys.std.Core.Type.PInt

A C<PInt> (positive integer) is a proper subtype of C<UInt> where all
member values are greater than zero.  Its default and minimum value is 1.

=head2 sys.std.Core.Type.Blob

A C<Blob> is an undifferentiated string of bits.  Its default and minimum
value is the empty string; its maximum value is an infinite-length string
and practically impossible.  The cardinality of this type is infinity; to
define a most-generalized finite C<Blob> subtype, you must specify a
maximum length in bits that the subtype's strings are.  The C<Blob> type
has a default ordering algorithm; for 2 distinct C<Blob> values, their
order is determined as follows:  1.  Eliminate any identical leading
sub-strings from both bit strings as those alone would make the strings
compare as same (if the remainder of both strings was the empty string,
then the strings are identical).  2.  Iff the remainder of just one string
is the empty string, then that string is ordered before the non-empty one.
3.  Compare the first bit of each of the string remainders; the one with
the 0-valued first bit is ordered before the one with the 1-valued first
bit.

=head2 sys.std.Core.Type.Text

A C<Text> is a string of characters.  Its default and minimum value is the
empty string; its maximum value is an infinite-length string and
practically impossible.  Note that there is only one system-defined
character repertoire for C<Text> types, which is the newest Unicode
repertoire (5.0.0).  The cardinality of this type is infinity; to define a
most-generalized finite C<Text> subtype, you must specify a maximum length
in characters (that is, eg, in NFC graphemes) that the subtype's strings
are.  The C<Text> type has a default ordering algorithm; for 2 distinct
C<Text> values, their order is determined as per C<Blob> but that
characters are being compared rather than bits; more specifically, the
standard Unicode Collation Algorithm (UCA) is used by default, assuming it
is totally ordered.  I<TODO: Support customization parameters for default
text sorting, or fix to make totally ordered if it isn't yet.>

=head1 SYSTEM-DEFINED CORE NONSCALAR PARAMETERIZED DATA TYPES

These are only called nonscalar data types in a loose sense, because by
themselves they are incomplete type definitions.  Actual nonscalar data
type definitions are derived from these by supplying the balance of the
type definitions, such as what their attributes are and/or what their
attribute types are.  Associated with these incomplete type definitions are
a set of system-defined routines that can be applied to values of any
actual nonscalar types derived from them; such are called I<generic
nonscalar operators>.  In the Muldis D type system, these incomplete
nonscalar types are defined as union types over all actual types derived
from them, and are proper supertypes of said.

Some actual nonscalar data types are system-defined, for use in defining
the Muldis D system catalog / meta-model (see further below in the current
document), and some others are system-defined for convenience since they
are the types of many core operators (see further below in the current
document), but all other actual nonscalar data types are user-defined.
Users can also define their own incomplete nonscalar data types that are
tuple or relation types.

As exceptions to the above 2 paragraphs, the C<Nothing> type and the 2
C<D0> types are actually complete types, despite being listed here.

=head2 sys.std.Core.Type.Tuple

The C<Tuple> type is the maximal type of all Muldis D tuple (nonscalar)
types, and contains every tuple value that could possibly exist.  A
C<Tuple> is an unordered heterogeneous collection of 0..N named attributes
(the count of attributes being its I<degree>), where all attribute names
are mutually distinct, and each attribute may be of distinct types; the
mapping of a tuple's attribute names and their declared data types is
called the tuple's I<heading>.  Its default value is the sole value of the
sole tuple data type that has zero attributes.  The cardinality of a
I<complete> C<Tuple> type (if it has no type constraints other than those
of its constituent attribute types) is equal to the product of the N-ary
multiplication where there is an input to that multiplication for each
attribute of the tuple and the value of the input is the cardinality of the
declared type of the attribute; for a C<Tuple> subtype to be finite, all of
its attribute types must be.

=head2 sys.std.Core.Type.TupleD0

A C<TupleD0> is a proper subtype of C<Tuple> that has zero attributes; its
cardinality is 1, and its only value is also the default value of C<Tuple>.

=head2 sys.std.Core.Type.Database

A C<Database> is a proper subtype of C<Tuple> where all of its attributes
are each of relation types or of database types (the leaves of this
recursion are all relation types); it is otherwise the same.  The 4
system-defined user-data variables named C<(fed|dep|sdp|pkg).data> are all
of "just" the C<Database> type, or are of its proper subtypes.  It is also
trivially a proper supertype of C<TupleD0>.

=head2 sys.std.Core.Type.Relation

The C<Relation> type is the maximal type of all Muldis D relation
(nonscalar) types, and contains every relation value that could possibly
exist.  A C<Relation> is analogous to a set of 0..N tuples where all tuples
have the same heading (the degrees match and all attribute names and
corresponding declared data types match), but that a C<Relation> data type
still has its own corresponding heading (attribute names and declared data
types) even when it consists of zero tuples.  Its default value is the
zero-tuple value of the sole relation data type that has zero attributes.
The cardinality of a I<complete> C<Relation> type (if it has no type
constraints other than those of its constituent attribute types) is equal
to 2 raised to the power of the cardinality of the I<complete> C<Tuple>
type with the same heading.  A relation data type can also have (unique)
keys each defined over a subset of its attributes, which constrain its set
of values relative to there being no explicit keys, but having the keys
won't turn an infinite relation type into a finite one.

=head2 sys.std.Core.Type.RelationD0

A C<RelationD0> is a proper subtype of C<Relation> that has 0 attributes;
its cardinality is 2, and its default value is the same as that of
C<Relation>.

=head2 sys.std.Core.Type.Set

A C<Set> is a proper subtype of C<Relation> that has 1 attribute, and its
name is C<value>; it can be of any declared type.  A C<Set> subtype is
normally used by any system-defined N-ary operators where the order of
their argument elements or result is not significant, and that duplicate
values are not significant.  Its default value has zero tuples.  Note that,
for any given I<complete> C<Set> subtype, C<Foo>, where its C<value>
attribute has a declared type of C<Bar>, the type C<Foo> can be considered
the I<power set> of the type C<Bar>.

=head2 sys.std.Core.Type.Maybe

A C<Maybe> is a proper subtype of C<Set> that may have at most one element;
that is, it is a unary C<Relation> with a nullary key.  Operators that work
specifically with C<Maybe> subtypes can provide a syntactic shorthand for
working with sparse data; so Muldis D has something which is conceptually
close to SQL's nullable types without actually having 3-valued logic; it
would probably be convenient for code that round-trips SQL by way of Muldis
D to use the C<Maybe> type.  Its default value has zero tuples.

=head2 sys.std.Core.Type.Nothing

A C<Nothing> is a proper subtype of C<Maybe> that has exactly zero
elements; its cardinality is 1 and its only value is its default.  The
single C<Nothing> value, which is a relation with zero tuples and a single
attribute named C<value>, is Muldis D's answer to the SQL NULL and is
intended to be used for the same purposes; that is, a special marker for
missing or inapplicable information, that does not typically equal any
normal/scalar value; however, in Muldis D, C<Nothing> I<is a value>, and it
I<is> equal to itself.

=head2 sys.std.Core.Type.Single

A C<Single> is a proper subtype of C<Maybe> that has exactly 1 element.
Its default value's only tuple's only attribute has the value
C<Bool:false>.  The C<Single> type is complementary to the C<Nothing> type
under C<Maybe>; C<Nothing> consists of exactly 1 of C<Maybe>'s values, and
C<Single> consists of all of C<Maybe>'s other values.  Subtypes of
C<Single> are also used to implement data-carrying database objects that
are conceptually scalars rather than relations; for example, the current
state of a sequence generator might typically be one.

=head2 sys.std.Core.Type.Array

An C<Array> is a proper subtype of C<Relation> that has 2 attributes, and
their names are C<index> and C<value>, where C<index> is a unary key and
its declared type is a C<UInt> subtype (C<value> can be non-unique and of
any declared type).  An C<Array> is considered dense, and all C<index>
values in one are numbered consecutively from 0 to 1 less than the count of
tuples, like array indices in typical programming languages.  An C<Array>
subtype is normally used by any system-defined N-ary operators where the
order of their argument elements or result is significant (and duplicate
values are significant); specifically, C<index> defines an explicit
ordering for C<value>.  Its default value has zero tuples.

=head2 sys.std.Core.Type.Bag

A C<Bag> (or I<multiset>) is a proper subtype of C<Relation> that has 2
attributes, and their names are C<value> and C<count>, where C<value> is a
unary key (that can have any declared type) and C<count> is a C<PInt>
subtype.  A C<Bag> subtype is normally used by any system-defined N-ary
operators where the order of their argument elements or result is not
significant, but that duplicate values are significant; specifically,
C<count> defines an explicit count of occurrences for C<value>, also known
as that value's I<multiplicity>.  Its default value has zero tuples.

=head1 SYSTEM-DEFINED CORE QUASI-SCALAR DATA TYPES

There are no system-defined normal quasi-scalar types; the only reason the
following exist is to provide a maximal type of any user-defined ones that
may come to exist.

=over

=item C<sys.std.Core.Type.QuasiScalar>

The C<QuasiScalar> type is the maximal type of all Muldis D quasi-scalar
types, and contains every quasi-scalar value that can possibly exist.  Its
default value is C<QuasiScalarDVPT:default>.  The cardinality of this type
is infinity.

=item C<sys.std.Core.Type.QuasiScalarDVPT>

A C<QuasiScalarDVPT> is an enumeration consisting of the 1 value
C<QuasiScalarDVPT:default>, which is also its default value.  The only
reason it exists is to provide a default value for the QuasiScalar union
type.  The cardinality of this type is 1.

=back

=head1 SYSTEM-DEFINED CORE QUASI-NONSCALAR PARAMETERIZED DATA TYPES

These quasi-nonscalar incomplete data type definitions correspond to their
similarly-named (differing only by the C<Quasi>) nonscalar data types, and
their use is intended to be limited to the few situations where the
corresponding nonscalar data types can't be used.  It should be noted in
particular that there is no "QuasiDatabase" type, since all normal data or
catalog databases should be composed of normal relations only; but all of
the other nonscalar incomplete types have counterparts here.

=head2 sys.std.Core.Type.QuasiTuple

A C<QuasiTuple> is like a C<Tuple> but that the declared types of its
attributes can be anything at all.  Its cardinality is infinite.

=head2 sys.std.Core.Type.QuasiTupleD0

A C<QuasiTupleD0> is a proper subtype of C<QuasiTuple> in the
corresponding manner to C<TupleD0> being a proper subtype of C<Tuple>.
Its cardinality is 1.

=head2 sys.std.Core.Type.QuasiRelation

A C<QuasiRelation> is like a C<Relation> but that the declared types of its
attributes can be anything at all.  Its cardinality is infinite.

=head2 sys.std.Core.Type.QuasiRelationD0

A C<QuasiRelationD0> is a proper subtype of C<QuasiRelation> in the
corresponding manner to C<RelationD0> being a proper subtype of
C<Relation>.  Its cardinality is 2.

=head2 sys.std.Core.Type.QuasiSet

A C<QuasiSet> is a proper subtype of C<QuasiRelation> in the corresponding
manner to C<Set> being a proper subtype of C<Relation>.  Its cardinality is
infinite.

=head2 sys.std.Core.Type.QuasiMaybe

A C<QuasiMaybe> is a proper subtype of C<QuasiSet> in the corresponding
manner to C<Maybe> being a proper subtype of C<Set>.  Its cardinality is
infinite.

=head2 sys.std.Core.Type.QuasiNothing

A C<QuasiNothing> is a proper subtype of C<QuasiMaybe> in the corresponding
manner to C<Nothing> being a proper subtype of C<Maybe>.  Its cardinality
is 1.

=head2 sys.std.Core.Type.QuasiSingle

A C<QuasiSingle> is a proper subtype of C<QuasiMaybe> in the corresponding
manner to C<Single> being a proper subtype of C<Maybe>.  Its cardinality is
infinite.

=head2 sys.std.Core.Type.QuasiArray

A C<QuasiArray> is a proper subtype of C<QuasiRelation> in the
corresponding manner to C<Array> being a proper subtype of C<Relation>.
Its cardinality is infinite.

=head2 sys.std.Core.Type.QuasiBag

A C<QuasiBag> is a proper subtype of C<QuasiRelation> in the corresponding
manner to C<Bag> being a proper subtype of C<Relation>.  Its cardinality is
infinite.

=head1 SYSTEM-DEFINED REMNANT TYPES

These core data types are mainly for use with the definitions of some
polymorphic operators whose range of possibly acceptable values may be
mutually incompatible, and they aren't appropriate to group into other type
categories or namespaces.

=head2 sys.std.Core.Type.Remnant

The C<Remnant> type is a partially redundant maximal type of all Muldis D
remnant types.  Its default value is C<Bool:false> by way of its
C<ScaTupRel> subtype.  The cardinality of this type is infinity.

=head2 sys.std.Core.Type.ScaTupRel

The C<ScaTupRel> type is a union type over C<Scalar>, C<Tuple> and
C<Relation>; it is mainly useful in describing the possible range of types
of attributes of scalar possreps or tuples or relations.  Its default value
is C<Bool:false>.

=head1 SEE ALSO

Go to L<Muldis::D> for the majority of distribution-internal
references, and L<Muldis::D::SeeAlso> for the majority of
distribution-external references.

=head1 AUTHOR

Darren Duncan (C<perl@DarrenDuncan.net>)

=head1 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 L<Muldis::D> for details.

=head1 TRADEMARK POLICY

The TRADEMARK POLICY in L<Muldis::D> applies to this file too.

=head1 ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in L<Muldis::D> apply to this file too.

=cut