=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Cast -
Muldis D explicit type-casting operators

=head1 VERSION

This document is Muldis::D::Core::Cast version 0.148.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's purpose is to consolidate all the core Muldis D
type-casting routines that are conceptually monadic functions between 2
core types.  It also declares a few special data types that support them.

I<This documentation is pending.>

=head1 TYPE SUMMARY

Following are all the data types 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.Scalar
            sys.std.Core.Type.DHScalar
                sys.std.Core.Type.Int
                    sys.std.Core.Type.NNInt
                        sys.std.Core.Type.PInt

                            # These are all finite integer types.

                            sys.std.Core.Type.Cast.PInt1_4
                            sys.std.Core.Type.Cast.PInt2_36

I<This documentation is pending.>

=head1 DATA TYPES FOR ENCODING SCALARS AS TEXTS

=head2 sys.std.Core.Type.Cast.PInt1_4

C<PInt1_4> is a proper subtype of
C<PInt> where all member values are between 1 and 4.  Its maximum value is
4.  The cardinality of this type is 4.

=head2 sys.std.Core.Type.Cast.PInt2_36

C<PInt2_36> is a proper subtype of
C<PInt> where all member values are between 2 and 36.  (The significance of
the number 36 is 10 digits plus 26 letters.)  Its default value is 10 (to
correspond to base-10 being the default base for numeric literals in the
STD dialects when no explicit base is given); its minimum and maximum
values are 2 and 36, respectively.  The cardinality of this type is 35.

=head1 FUNCTIONS FOR CASTING BETWEEN TUPLES AND SINGLE-TUPLE RELATIONS

=head2 sys.std.Core.Cast.Tuple_from_Relation

C<< function Tuple_from_Relation (Tuple <-- topic : Relation) {...} >>

This function results in the C<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 C<%>.

=head2 sys.std.Core.Cast.Relation_from_Tuple

C<< function Relation_from_Tuple (Relation <-- topic : Tuple) {...} >>

This function results in the C<Relation> value those body has just the one
C<Tuple> that is its argument.  Note that this operation is also known as
C<@>.

=head1 FUNCTIONS FOR CASTING BETWEEN CANONICAL SETS AND BAGS

=head2 sys.std.Core.Cast.Set_from_Bag

C<< function Set_from_Bag (Set <-- topic : Bag) {...} >>

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

=head2 sys.std.Core.Cast.Bag_from_Set

C<< function Bag_from_Set (Bag <-- topic : Set) {...} >>

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

=head1 FUNCTIONS FOR CASTING BETWEEN INTEGERS AND RATIONALS

These functions convert between C<Rat> values and equal or nearly equal
C<Int> values.

=head2 sys.std.Core.Cast.Int_from_Rat

C<< function Int_from_Rat (Int <-- rat : Rat,
round_meth : RoundMeth) {...} >>

This selector function results in the C<Int> value that is conceptually
equal to or otherwise nearest to its C<rat> argument, where the nearest is
determined by the rounding method specified by the C<round_meth> argument.

=head2 sys.std.Core.Cast.Rat_from_Int

C<< function Rat_from_Int (Rat <-- int : Int) {...} >>

This selector function results in the C<Rat> value that is conceptually
equal to its C<Int> argument.

=head1 FUNCTIONS FOR ENCODING INTEGERS AS TEXTS

These functions convert between C<Int> values and canonically formatted
representations of integers as character strings.

=head2 sys.std.Core.Cast.Int_from_Text

C<< function Int_from_Text (Int <-- text : Text,
radix? : PInt2_36) {...} >>

This selector function results in the C<Int> value that its (not-empty)
C<text> argument maps to when the whole character string is evaluated as a
base-C<radix> integer.  Extending the typical formats of [base-2, base-8,
base-10, base-16], this function supports base-2 through base-36; to get
the latter, the characters 0-9 and A-Z represent values in 0-35.  This
function will fail if C<text> can't be mapped as specified.

=head2 sys.std.Core.Cast.Text_from_Int

C<< function Text_from_Int (Text <-- int : Int, radix? : PInt2_36) {...} >>

This selector function results in the (not-empty) C<Text> value where its
C<int> argument is formatted as a base-C<radix> integer.

=head1 FUNCTIONS FOR ENCODING RATIONALS AS TEXTS

These functions convert between C<Rat> values and canonically formatted
representations of rationals as character strings.

=head2 sys.std.Core.Cast.Rat_from_Text

C<< function Rat_from_Text (Rat <-- text : Text,
radix? : PInt2_36) {...} >>

This selector function results in the C<Rat> value that its (not-empty)
C<text> argument maps to when the whole character string is evaluated as a
base-C<radix> rational.  Extending the typical formats of [base-2, base-8,
base-10, base-16], this function supports base-2 through base-36; to get
the latter, the characters 0-9 and A-Z represent values in 0-35.  This
function will fail if C<text> can't be mapped as specified.

=head2 sys.std.Core.Cast.Text_from_Rat

C<< function Text_from_Rat (Text <-- rat : Rat, radix? : PInt2_36) {...} >>

This selector function results in the (not-empty) C<Text> value where its
C<rat> argument is formatted as a base-C<radix> rational.

=head1 FUNCTIONS FOR ENCODING BLOBS AS TEXTS

These functions convert between C<Blob> values and canonically formatted
representations of binary strings as character strings.

=head2 sys.std.Core.Cast.Blob_from_Text

C<< function Blob_from_Text (Blob <-- text : Text, size : PInt1_4) {...} >>

This selector function results in the C<Blob> value that its C<text>
argument maps to when each input character represents a sequence of 1-4
bits, the number of bits per character being determined by the C<size>
argument; for example, if C<size> is 1, then each input character is a
[0..1] and represents a bit; or, if C<size> is 4, then each input character
is a [0..9A..Fa..f] and represents 4 bits.  This function will fail if
C<text> can't be mapped as specified.

=head2 sys.std.Core.Cast.Text_from_Blob

C<< function Text_from_Blob (Text <-- blob : Blob, size : PInt1_4) {...} >>

This selector function results in the C<Text> value where its argument is
encoded using a character for each sequence of 1-4 bits, the number of bits
per character being determined by the C<size> argument.  This function will
fail if C<blob> doesn't have a length in bits which is a multiple of
C<size>.  Any alpha characters in the result are in uppercase.

=head1 FUNCTIONS FOR ENCODING INTEGERS AS BLOBS

These functions convert between C<Int> values and canonically formatted
representations of integers as binary strings.  I<Conjecture: These may not
actually be useful, and perhaps only operators that take an argument
specifying a fixed-length field size, with big and little endian versions,
would be appropriate instead.  Or maybe both kinds are necessary.>

=head2 sys.std.Core.Cast.Int_from_Blob_S_VBE

C<< function Int_from_Blob_S_VBE (Int <-- blob : Blob) {...} >>

This selector function results in the C<Int> value that its C<blob>
argument maps to when the whole bit string is treated literally as a
variable-length binary (two's complement) signed integer of 1 or more bits
in length.  The first bit is taken as the sign bit, and any other bits
provide greater precision than the -1 thru 0 range.  The bit string is
assumed to be big-endian, since it may not be possible to use little-endian
in situations where the bit length isn't a multiple of 8.

=head2 sys.std.Core.Cast.Blob_S_VBE_from_Int

C<< function Blob_S_VBE_from_Int (Blob <-- int : Int) {...} >>

This selector function results in the C<Blob> value where its C<int>
argument is formatted as a variable-length binary (two's complement) signed
integer of 1 or more bits in length; the smallest number of bits necessary
to store C<int> is used.

=head2 sys.std.Core.Cast.Int_from_Blob_U_VBE

C<< function Int_from_Blob_U_VBE (NNInt <-- blob : Blob) {...} >>

This function is the same as C<sys.std.Core.Cast.Int_from_Blob_S_VBE> but
that it does unsigned integers.

=head2 sys.std.Core.Cast.Blob_U_VBE_from_Int

C<< function Blob_U_VBE_from_Int (NNInt <-- blob : Blob) {...} >>

This function is the same as C<sys.std.Core.Cast.Blob_S_VBE_from_Int> but
that it does unsigned integers.

=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<darren@DarrenDuncan.net>)

=head1 LICENSE AND COPYRIGHT

This file is part of the formal specification of the Muldis D language.

Muldis D is Copyright © 2002-2011, Muldis Data Systems, Inc.

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