=pod

=encoding utf8

=head1 NAME

Muldis::D::Ext::Blob -
Muldis D extension for bit string data types and operators

=head1 VERSION

This document is Muldis::D::Ext::Blob version 0.24.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.

=head1 DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available)
entities, which is referred to as the I<Muldis D core> or the I<core>; they
are the minimal entities that all Muldis D implementations need to provide;
they are mutually self-describing and are used to bootstrap the language;
any entities outside the core, called I<Muldis D extensions>, are
non-mandatory and are defined in terms of the core or each other, but the
reverse isn't true.

This current C<Blob> document describes the system-defined I<Muldis D Blob
Extension>, which consists of undifferentiated bit string data types and
operators, essentially all the generic ones that a typical programming
language should have, but for the bare minimum needed for bootstrapping
Muldis D, which are defined in the language core instead.

This current document does not describe the polymorphic operators that all
types, or some types including core types, have defined over them; said
operators are defined once for all types in L<Muldis::D::Core>.

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 (but that
a few of them just reappear from the core set to provide a similar context,
and aren't re-described here):

    sys.std.Core.Type.Universal

        sys.std.Core.Type.Empty

        sys.std.Core.Type.Scalar
            sys.std.Core.Type.Int
                sys.std.Core.Type.UInt
                    sys.std.Core.Type.PInt

                        # These are all integer types.

                        sys.std.Blob.Type.PInt1_4

I<This documentation is pending.>

=head1 SYSTEM-DEFINED BLOB-CONCERNING DATA TYPES

=head2 sys.std.Blob.Type.PInt1_4

A 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.

=head1 SYSTEM-DEFINED BLOB-CONCERNING FUNCTIONS

These functions implement commonly used binary string operations.

=over

=item C<function sys.std.Blob.catenation result Blob params {
topic(seq_of.Blob) }>

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.  If C<topic> has zero
values, then C<catenate> results in the empty string value, which is the
identity value for catenate.

=item C<function sys.std.Blob.repeat result Blob params { topic(Blob),
count(UInt) }>

This function results in the catenation of C<count> instances of C<topic>.

=item C<function sys.std.Blob.length_in_bits result UInt params {
topic(Blob) }>

This function results in the length of its argument in bits.

=item C<function sys.std.Blob.is_substr result Bool params { look_in(Blob),
look_for(Blob), fixed_start(Bool), fixed_end(Bool) }>

This function results in C<Bool:true> iff its C<look_for> argument is a
substring of its C<look_in> argument as per the optional C<fixed_start> and
C<fixed_end> constraints, and C<Bool:false> otherwise.  If C<fixed_start>
or C<fixed_end> are C<Bool:true>, then C<look_for> must occur right at the
start or end, respectively, of C<look_in> in order for C<contains> to
results in C<Bool:true>; if either flag is C<Bool:false>, its additional
constraint doesn't apply.

=item C<function sys.std.Blob.is_not_substr result Bool params {
look_in(Blob), look_for(Blob), fixed_start(Bool), fixed_end(Bool) }>

This function is exactly the same as C<sys.std.Blob.is_substr> except that
it results in the opposite boolean value when given the same arguments.

=item C<function sys.std.Blob.not result Blob params { topic(Blob) }>

This function results in the bitwise I<not> of its argument.

=item C<function sys.std.Blob.and result Blob params { topic(set_of.Blob)
}>

This function is a reduction operator that recursively takes each pair of
its N input element values and does a bitwise I<and> (which is both
commutative and associative) on them until just one is left, which is the
function's result.  This function's argument values must all be of the same
length in bits, that length being part of the argument's declared type
(that is, C<Blob> subtype) definition, and that is also the length in bits
of the function's result.  If C<topic> has zero values, then C<and> will
result in an appropriate-length string of identity/1 valued bits.

=item C<function sys.std.Blob.or result Blob params { topic(set_of.Blob) }>

This function is the same as C<sys.std.Blob.and> but that it recursively
does a bitwise inclusive-or rather than a bitwise I<and>, and its identity
value is composed of zero valued bits.

=item C<function sys.std.Blob.xor result Blob params { topic(bag_of.Blob)
}>

This function is the same as C<sys.std.Blob.or> but that it recursively
does a bitwise exclusive-or rather than a bitwise inclusive-or.

=back

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

=over

=item C<function sys.std.Blob.Blob_from_Text result Blob params {
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.

=item C<function sys.std.Blob.Text_from_Blob result Text params {
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>.

=back

=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