Sather Home Page

Section 8.2.3.1:
BINSTR

class BINSTR < $STRING{OCTET,FBINSTR,BINSTR}, $IS_LT{BINSTR}, $STR

Inheritance map $STRING $IS_LT $STR

Formal Types

The type definitions in this class specification fall into two groups :-

  1. The definition of BINSTR itself (including SAME).
  2. The auxiliary vdm type needed to define a generic Sather type used in the feature definitions which follow.
types

SAME = BINSTR ;

BINSTR = seq of OCTET

-- Auxiliary Types

Array_of_Octet = seq of OCTET
NOTE The auxiliary type Array_of_Octet is not the same as the class being specified here - it is a subtype of the generic vdm class Array_of_Elt (which is a 'seq of @elem') which is defined in the generic class ARRAY{ELT}.

This class shall provide immutable semantics for binary (octet) string manipulations. See also the class FBINSTR.

External specifications

The following feature is required to be implemented for this class in accordance with the specification given in $IS_EQ of which $STRING{OCTET,FBINSTR,BINSTR} is a sub-type :-


The following feature is required to be implemented for this class in accordance with the specification given in $IS_LT :-


The following features are required to be implemented for this class in accordance with the specification given in $ELT of which $STRING{OCTET,FBINSTR,BINSTR} is a sub-type :-


The following feature is required to be implemented for this class in accordance with the specification given in $ELT{OCTET} of which $STRING{OCTET,FBINSTR,BINSTR} is a sub-type :-


The following feature is required to be implemented for this class in accordance with the specification given in $HASH of which $STRING{OCTET,FBINSTR,BINSTR} is a sub-type :-


The following features are required to be implemented for this class in accordance with the specifications given by inheritance in $STR of which $STRING{} is a sub-type :-


The following features are required to be implemented for this class in accordance with the specifications given by inheritance in $STRINGS of which $STRING{OCTET,FBINSTR,BINSTR} is a sub-type :-


The following features are required to be implemented for this class in accordance with the specifications given by inheritance in $STRING{OCTET,FBINSTR,BINSTR} :-


create

This first creation routine returns an empty string.

create : SAME
Formal Signature
create() res : SAME
Pre-condition

Since this is a creation routine the pre-condition is vacuously true.

Post-condition
post res = []

This creation routine returns an empty binary string.


create

This version of the creation routine returns a string of the given size all the elements of which are null.

create (
size : CARD
) : SAME
Formal Signature

The name of this routine has been modified from the Sather name, since there is no name overloading in vdm.

create2(size : CARD) res : SAME
Pre-condition

Since this is a creation routine the pre-condition is vacuously true.

Post-condition
post len res = size
and forall idx in set inds res &
res(idx) = OCTET.null

This creation routine returns a binary string of the given size, all of the elements of which are null.


create

This version of the creation routine returns a string of size one containing the single element oct.

create (
oct : OCTET
) : SAME
Formal Signature

The name of this routine has been modified from the Sather name, since there is no name overloading in vdm.

create3(oct : OCTET) res : SAME
Pre-condition

Since this is a creation routine the pre-condition is vacuously true.

Post-condition
post len res = 1
and res(1) = oct

This creation routine returns a binary string of length one containing only the element oct.


create

This final version of creation returns a string of the same size as the argument, filled with its contents.

create (
array : ARRAY{OCTET}
) : SAME
Formal Signature

The name of this routine has been modified from the Sather name, since there is no name overloading in vdm.

create4(array : Array_of_Octet) res : SAME
Pre-condition

Since this is a creation routine the pre-condition is vacuously true.

Post-condition
post len res = Array_of_Octet.size(array)
and forall idx in set inds array &
res(idx) = array(idx)

This creation routine creates a binary string which has the same length as the size of the array argument and has the contents of that array in sequential order of increasing index number.


plus

This is a fourth variant of the plus operation for an object of this class. It is provided as a convenience when manipulating individual HEXET objects. The object returned is the value of self with the argument appended.

plus (
hex : HEXTET
) : SAME
Formal Signature

The name of this routine has been modified from the Sather name, since there is no name overloading in vdm.

plus4(self : SAME, hex : HEXTET) res : SAME
Pre-condition
Since the range of the result is greater than that of self and the second argument is not an optional type then the pre-condition is vacuously true.

Post-condition
post let hexstr = HEXTET.binstr(hex) in
res = self ^ hexstr

This routine returns a new string consisting of the contents of self with the value of hex appended to it.


pad

This feature is provided to pad out the binary string to some specified size with null octets, provided that length is greater than the size of self.

pad (
length : CARD
) : SAME
Formal Signature
pad(self : SAME, length : CARD) res : SAME
Pre-condition
Since the semantics of this operation are defined in such a way that the result is never less than self, the pre-condition is vacuously true.

Post-condition
post ((length <= len self)
and (res = self))
or let nulls : seq of OCTET be st len nulls = length - len self in
(forall idx in set inds nulls &
nulls(idx) = OCTET.null()
and res = self ^ nulls)

This routine returns a new object the contents of which is that of self padded with null octets up to the given length unless self is equal or greater to the length specified when self is returned.


cursor

This feature is provided so that scanning of the buffer may be undertaken - a common activity when 'parsing' input data of some kind.

cursor : BIN_CURSOR
Formal Signature
cursor(self : SAME) res : BIN_CURSOR
Pre-condition

Since the element types are identical and the domain of the argument is of the same size as that of the result, the pre-condition is vacuously true.

Post-condition
post BIN_CURSOR.buffer(res) = self
and BIN_CURSOR.loc(res) = 0

This routine returns a new cursor object, the buffer of which contains the contents of self and the cursor index is set to 0.


fbinstr

This routine creates a new 'fast' binary string which has mutable semantics - and is provided for use when speed of execution is important.

fbinstr : FBINSTR
Formal Signature
fbinstr(self : SAME) res : FBINSTR
Pre-condition

Since the domain of self and the range of the result are the same, the pre-condition is vacuously true.

Post-condition
post let fstr : seq of OCTET be st fstr = res in
fstr = self
and FBINSTR.loc(res) = len self

This routine creates and returns a mutable version of self with the same contents as self and the next insertion location pointer set to a value equal to the size of self.


sized

This routine is included for the common case where a relatively short binary string is to be placed in a stream of octets (eg in a file) in order that subsequent retrieval will be able to determine the length of the string when 'reading' (see also the get_sized feature of the BIN_CURSOR class). It returns a copy of self preceded by a length octet.

sized : SAME
Formal Signature
sized(self : SAME) res : SAME
Pre-condition
pre len self <= OCTET.Octet_Max()
Post-condition
post let size = len self in res = [OCTET.create(size)] ^ self

This routine returns a binary string with the contents of self preceded by an octet with the bit-pattern equivalent to the number which is the count of octets in self.


text_str

This routine produces a textual representation, using the given repertoire and encoding, of the contents of self as a space separated list of hexadecimal numbers representing each octet in the string. There is neither prefix nor suffix of any kind.

text_str (
lib : LIBCHARS
) : STR
Formal Signature
text_str(self : SAME, lib : LIBCHARS) res : STR
Pre-condition

Since the result range is at least the size of the domain of self then the pre-condition is vacuously true.

Post-condition
post forall idx in set inds self &
let res_idx = (idx - 1) * 3 + 1 in
let substr : seq of CHAR = res(res_idx, ..., (res_idx + 2) in
(substr(1, ..., 2) = OCTET.str(self(idx),lib))
and ((idx = len self)

or (substr(3) = LIBCHARS.Space(lib))

This routine returns a text string representation of the contents of self as a sequence of space separated hexadecimal octet representations, using the given repertoire and encoding.


text_str

This second version of this routine produces, using the default encoding and repertoire, a textual representation of the contents of self as a space separated list of hexadecimal numbers representing each octet in the string. There is neither prefix nor suffix of any kind.

text_str : STR
Formal Signature

The name of this routine has been modified from the Sather name, since there is no name overloading in vdm.

text_str2(self : SAME) res : STR
Pre-condition

Since the result range is at least the size of the domain of self then the pre-condition is vacuously true.

Post-condition
post forall idx in set inds self &
let res_idx = (idx - 1) * 3 + 1 in
let substr : seq of CHAR = res(res_idx, ..., (res_idx + 2) in
(substr(1, ..., 2) = OCTET.str(self(idx),LIBCHARS.default()))
and ((idx = len self)

or (substr(3) = LIBCHARS.Space(LIBCHARS.default()))

This routine returns a text string representation of the contents of self as a sequence of space separated hexadecimal octet representations, using the default repertoire and encoding.


Language Index Library Index Binary Index
Comments or enquiries should be made to Keith Hopper.
Page last modified: Wednesday, 22 November 2000.
Produced with Amaya