=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.73.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.QScalar
            sys.std.Core.Type.Scalar
                sys.std.Core.Type.Int
                    sys.std.Core.Type.NNInt
                        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

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.

=head1 SYSTEM-DEFINED BLOB-CONCERNING FUNCTIONS

These functions implement commonly used binary string operations.

=head2 sys.std.Blob.catenation

C<< function sys.std.Blob.catenation (Blob <-- array_of.Blob $topic?) >>

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.

=head2 sys.std.Blob.repeat

C<< function sys.std.Blob.repeat (Blob <-- Blob $topic, NNInt $count) >>

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

=head2 sys.std.Blob.length_in_bits

C<< function sys.std.Blob.length_in_bits (NNInt <-- Blob $topic) >>

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

=head2 sys.std.Blob.length_in_octets

C<< function sys.std.Blob.length_in_octets (NNInt <-- OctetBlob $topic) >>

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

=head2 sys.std.Blob.is_substr_bits

C<< function sys.std.Blob.is_substr_bits (Bool <-- Blob $look_in,
Blob $look_for, Bool $fixed_start?, Bool $fixed_end?) >>

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.  Each of the C<fixed_[start|end]> parameters is
optional and defaults to C<Bool:false> if no explicit argument is given to
it.

=head2 sys.std.Blob.is_not_substr_bits

C<< function sys.std.Blob.is_not_substr_bits (Bool <-- Blob $look_in,
Blob $look_for, Bool $fixed_start?, Bool $fixed_end?) >>

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

=head2 sys.std.Blob.is_substr_octets

C<< function sys.std.Blob.is_substr_octets (Bool <-- OctetBlob $look_in,
OctetBlob $look_for, Bool $fixed_start?, Bool $fixed_end?) >>

This function is exactly the same as C<sys.std.Blob.is_substr_bits> except
that its main arguments are C<OctetBlob> and it it only looks for substring
matches on whole-octet boundaries of the C<look_in> bit string.

=head2 sys.std.Blob.is_not_substr_octets

C<< function sys.std.Blob.is_not_substr_octets (Bool <--
OctetBlob $look_in, OctetBlob $look_for, Bool $fixed_start?,
Bool $fixed_end?) >>

This function is to C<is_substr_octets> as C<is_not_substr_bits> is to
C<is_substr_bits>.

=head2 sys.std.Blob.not

C<< function sys.std.Blob.not (Blob <-- Blob $topic) >>

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

=head2 sys.std.Blob.and

C<< function sys.std.Blob.and (Blob <-- set_of.Blob $topic) >>

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 this function
will fail.  Note that, conceptually C<and> I<does> have an identity value
which could be this function's result when C<topic> has zero values, which
is an appropriate-length string of identity/1 valued bits; however, since a
C<topic> with zero values wouldn't know the length in question, it seems
the best alternative is to require invoking code to work around the
limitation somehow, which might mean it will supply the identity value
explicitly as an extra C<topic> element.

=head2 sys.std.Blob.or

C<< function sys.std.Blob.or (Blob <-- set_of.Blob $topic) >>

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
conceptual identity value is composed of zero valued bits.

=head2 sys.std.Blob.xor

C<< function sys.std.Blob.xor (Blob <-- bag_of.Blob $topic) >>

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.

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

=head2 sys.std.Blob.Blob_from_Text

C<< function sys.std.Blob.Blob_from_Text (Blob <-- Text $text,
PInt1_4 $size) >>

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.Blob.Text_from_Blob

C<< function sys.std.Blob.Text_from_Blob (Text <-- Blob $blob,
PInt1_4 $size) >>

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