=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.101.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.Empty

        sys.std.Core.Type.Scalar
            sys.std.Core.Type.DHScalar
                sys.std.Core.Type.Cat.OVLScalar
                    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

This is an enumeration data type.  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

This is an enumeration data type.  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 and minimum value
is 2.  Its maximum value is 36.  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 sys.std.Core.Cast.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<t>.

=head2 sys.std.Core.Cast.Relation_from_Tuple

C<< function sys.std.Core.Cast.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<r>.

=head1 FUNCTIONS FOR CASTING BETWEEN CANONICAL SETS AND BAGS

=head2 sys.std.Core.Cast.Set_from_Bag

C<< function sys.std.Core.Cast.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 sys.std.Core.Cast.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 sys.std.Core.Cast.Int_from_Rat (Int <-- $rat : Rat,
$round_meth : RatRoundMeth) >>

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 sys.std.Core.Cast.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 sys.std.Core.Cast.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 sys.std.Core.Cast.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 sys.std.Core.Cast.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 sys.std.Core.Cast.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 sys.std.Core.Cast.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-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 sys.std.Core.Cast.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>.

=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 sys.std.Core.Cast.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 sys.std.Core.Cast.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 sys.std.Core.Cast.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 sys.std.Core.Cast.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-2009, 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
