=pod

=encoding utf8

=head1 NAME

Muldis::D::Core::Blob -
Muldis D bit string operators

=head1 VERSION

This document is Muldis::D::Core::Blob 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 describes essentially all of the core Muldis D operators that
are specific to the core data type C<Blob>, essentially all the generic
ones that a typical programming language should have.

I<This documentation is pending.>

=head1 FUNCTIONS IMPLEMENTING VIRTUAL ORDERED FUNCTIONS

=head2 sys.std.Core.Blob.order

C<< function order (Order <-- topic : Blob,
other : Blob, misc_args? : Tuple, is_reverse_order? : Bool)
implements sys.std.Core.Ordered.order {...} >>

This is a (total) C<order-determination> function specific to C<Blob>.  Its
only valid C<misc_args> argument is C<Tuple:D0>.

=head1 FUNCTIONS IMPLEMENTING VIRTUAL STRINGY FUNCTIONS

=head2 sys.std.Core.Blob.catenation

C<< function catenation (Blob <--
topic? : array_of.Blob) implements sys.std.Core.Stringy.catenation {...} >>

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<catenation> results in the empty string value, which is the
identity value for catenation.

=head2 sys.std.Core.Blob.replication

C<< function replication (Blob <-- topic : Blob,
count : NNInt) implements sys.std.Core.Stringy.replication {...} >>

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

=head1 GENERIC FUNCTIONS FOR BLOBS

These functions implement commonly used binary string operations.

=head2 sys.std.Core.Blob.len_in_bits

C<< function len_in_bits (NNInt <-- topic : Blob) {...} >>

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

=head2 sys.std.Core.Blob.len_in_octets

C<< function len_in_octets (NNInt <-- topic : OctetBlob) {...} >>

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

=head2 sys.std.Core.Blob.has_substr_bits

C<< function has_substr_bits (Bool <-- 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.  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.Core.Blob.has_not_substr_bits

C<< function has_not_substr_bits (Bool <-- look_in : Blob,
look_for : Blob, fixed_start? : Bool, fixed_end? : Bool) {...} >>

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

=head2 sys.std.Core.Blob.has_substr_octets

C<< function has_substr_octets (Bool <-- look_in : OctetBlob,
look_for : OctetBlob, fixed_start? : Bool, fixed_end? : Bool) {...} >>

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

=head2 sys.std.Core.Blob.has_not_substr_octets

C<< function has_not_substr_octets (Bool <-- look_in : OctetBlob,
look_for : OctetBlob, fixed_start? : Bool, fixed_end? : Bool) {...} >>

This function is to C<has_substr_octets> as C<has_not_substr_bits> is to
C<has_substr_bits>.

=head2 sys.std.Core.Blob.not

C<< function not (Blob <-- topic : Blob) {...} >>

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

=head2 sys.std.Core.Blob.and

C<< function and (Blob <-- 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 commutative,
associative, and idempotent) 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.Core.Blob.or

C<< function or (Blob <-- topic : set_of.Blob) {...} >>

This function is the same as C<sys.std.Core.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.Core.Blob.xor

C<< function xor (Blob <-- topic : bag_of.Blob) {...} >>

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

=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