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.92.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.Scalar
sys.std.Core.Type.DHScalar
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_4This 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.
sys.std.Blob.catenation
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 topic has zero values, then catenate results in the empty string value, which is the identity value for catenate. Note that this operation is also known as B~.
sys.std.Blob.replication
function sys.std.Blob.replication (Blob <-- Blob $topic, NNInt $count)
This function results in the catenation of count instances of topic. Note that this operation is also known as Bx.
sys.std.Blob.len_in_bits
function sys.std.Blob.len_in_bits (NNInt <-- Blob $topic)
This function results in the length of its argument in bits.
sys.std.Blob.len_in_octets
function sys.std.Blob.len_in_octets (NNInt <-- OctetBlob $topic)
This function results in the length of its argument in octets.
sys.std.Blob.has_substr_bits
function sys.std.Blob.has_substr_bits (Bool <-- Blob $look_in, Blob $look_for, Bool $fixed_start?, Bool $fixed_end?)
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.
sys.std.Blob.has_not_substr_bits
function sys.std.Blob.has_not_substr_bits (Bool <-- Blob $look_in, Blob $look_for, Bool $fixed_start?, Bool $fixed_end?)
This function is exactly the same as sys.std.Blob.has_substr_bits except that it results in the opposite boolean value when given the same arguments.
sys.std.Blob.has_substr_octets
function sys.std.Blob.has_substr_octets (Bool <-- OctetBlob $look_in, OctetBlob $look_for, Bool $fixed_start?, Bool $fixed_end?)
This function is exactly the same as sys.std.Blob.has_substr_bits except that its main arguments are OctetBlob and it only looks for substring matches on whole-octet boundaries of the look_in bit string.
sys.std.Blob.has_not_substr_octets
function sys.std.Blob.has_not_substr_octets (Bool <-- OctetBlob $look_in, OctetBlob $look_for, Bool $fixed_start?, Bool $fixed_end?)
This function is to has_substr_octets as has_not_substr_bits is to has_substr_bits.
sys.std.Blob.not
function sys.std.Blob.not (Blob <-- Blob $topic)
This function results in the bitwise not of its argument.
sys.std.Blob.and
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 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, 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.
sys.std.Blob.or
function sys.std.Blob.or (Blob <-- set_of.Blob $topic)
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.
sys.std.Blob.xor
function sys.std.Blob.xor (Blob <-- bag_of.Blob $topic)
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.
sys.std.Blob.Blob_from_Text
function sys.std.Blob.Blob_from_Text (Blob <-- Text $text, PInt1_4 $size)
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.
sys.std.Blob.Text_from_Blob
function sys.std.Blob.Text_from_Blob (Text <-- Blob $blob, PInt1_4 $size)
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, Muldis Data Systems, Inc.
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.