/ 
Muldis-D-0.58.0
River stage zero No dependents
/ Muldis::D::Ext::Blob

NAME

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

VERSION

This document is Muldis::D::Ext::Blob version 0.58.0.

PREFACE

This document is part of the Muldis D language specification, whose root document is Muldis::D; you should read that root document before you read this one, which provides subservient details.

DESCRIPTION

Muldis D has a mandatory core set of system-defined (eternally available) entities, which is referred to as the Muldis D core or the 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 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 Blob document describes the system-defined 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 Muldis::D::Core.

This documentation is pending.

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

This documentation is pending.

SYSTEM-DEFINED BLOB-CONCERNING DATA TYPES

sys.std.Blob.Type.PInt1_4

This is an enumeration data type. PInt1_4 is a proper subtype of PInt where all member values are between 1 and 4. Its maximum value is 4. The cardinality of this type is 4.

SYSTEM-DEFINED BLOB-CONCERNING FUNCTIONS

These functions implement commonly used binary string operations.

function sys.std.Blob.catenation result Blob params { topic(array_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 topic has zero values, then catenate results in the empty string value, which is the identity value for catenate.

function sys.std.Blob.repeat result Blob params { topic(Blob), count(NNInt) }

This function results in the catenation of count instances of topic.

function sys.std.Blob.length_in_bits result NNInt params { topic(Blob) }

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

function sys.std.Blob.length_in_octets result NNInt params { topic(OctetBlob) }

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

function sys.std.Blob.is_substr_bits result Bool params { look_in(Blob), look_for(Blob), fixed_start(Bool)?, fixed_end(Bool)? }

This function results in Bool:true iff its look_for argument is a substring of its look_in argument as per the optional fixed_start and fixed_end constraints, and Bool:false otherwise. If fixed_start or fixed_end are Bool:true, then look_for must occur right at the start or end, respectively, of look_in in order for contains to results in Bool:true; if either flag is Bool:false, its additional constraint doesn't apply. Each of the fixed_(start|end) parameters is optional and defaults to Bool:false if no explicit argument is given to it.

function sys.std.Blob.is_not_substr_bits result Bool params { look_in(Blob), look_for(Blob), fixed_start(Bool)?, fixed_end(Bool)? }

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

function sys.std.Blob.is_substr_octets result Bool params { look_in(OctetBlob), look_for(OctetBlob), fixed_start(Bool)?, fixed_end(Bool)? }

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

function sys.std.Blob.is_not_substr_octets result Bool params { look_in(OctetBlob), look_for(OctetBlob), fixed_start(Bool)?, fixed_end(Bool)? }

This function is to is_substr_octets as is_not_substr_bits is to is_substr_bits.

function sys.std.Blob.not result Blob params { topic(Blob) }

This function results in the bitwise not of its argument.

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 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, Blob subtype) definition, and that is also the length in bits of the function's result. If topic has zero values, then this function will fail. Note that, conceptually and does have an identity value which could be this function's result when topic has zero values, which is an appropriate-length string of identity/1 valued bits; however, since a 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 topic element.

function sys.std.Blob.or result Blob params { topic(set_of.Blob) }

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

function sys.std.Blob.xor result Blob params { topic(bag_of.Blob) }

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

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

function sys.std.Blob.Blob_from_Text result Blob params { text(Text), size(PInt1_4) }

This selector function results in the Blob value that its 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 size argument; for example, if size is 1, then each input character is a [0-1] and represents a bit; or, if size is 4, then each input character is a [0-9A-F] and represents 4 bits. This function will fail if text can't be mapped as specified.

function sys.std.Blob.Text_from_Blob result Text params { blob(Blob), size(PInt1_4) }

This selector function results in the 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 size argument. This function will fail if blob doesn't have a length in bits which is a multiple of size.

SEE ALSO

Go to Muldis::D for the majority of distribution-internal references, and Muldis::D::SeeAlso for the majority of distribution-external references.

AUTHOR

Darren Duncan (perl@DarrenDuncan.net)

LICENSE AND COPYRIGHT

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

Muldis D is Copyright © 2002-2009, Darren Duncan.

See the LICENSE AND COPYRIGHT of Muldis::D for details.

TRADEMARK POLICY

The TRADEMARK POLICY in Muldis::D applies to this file too.

ACKNOWLEDGEMENTS

The ACKNOWLEDGEMENTS in Muldis::D apply to this file too.