# Section 8.2.3.1:
BINSTR

###### class BINSTR < $STRING{OCTET,FBINSTR,BINSTR}, $IS_LT{BINSTR}, $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 :-

- is_eq(other : SAME) : BOOL

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

- is_lt(other : SAME) : BOOL

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

- size : CARD
- elt! : $OB

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

- elt! : OCTET

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

- hash : CARD

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

- str(lib : LIBCHARS) : STR
- str : STR

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

- array_ptr : REFERENCE
- head(cnt : CARD) : SAME
- tail(cnt : CARD) : SAME
- substring(start : CARD, cnt : CARD) : SAME

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

- acopy(val : SAME)
- copy : SAME
- aget(index : CARD) : OCTET
- plus(elem : OCTET) : SAME
- plus(str : SAME) : SAME
- plus(fstr : FBINSTR) : SAME
- is_empty : BOOL
- is_prefix(other : SAME) : BOOL
- count(elem : OCTET) : CARD
- search(elem : OCTET) : CARD
- search(elem : OCTET, start : CARD) : CARD
- search(str : SAME) : CARD
- search(str : SAME, start : CARD) : CARD
- search_backwards(elem : OCTET) : CARD
- search_backwards(elem : OCTET, start : CARD) : CARD
- mismatch(str : SAME) : CARD
- substring(start : CARD) : SAME
- contains(elem : OCTET) : BOOL
- reverse : SAME
- elt!(once start : CARD) : OCTET
- elt!(once start : CARD, once cnt : CARD) : OCTET
- ind! : CARD
- chunk!(size : CARD) : SAME
- chunk!(once start : CARD, size : CARD) : SAME

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