Sather Home Page

Section 8.2.3.3:
BIN_CURSOR

class BIN_CURSOR < $CURSOR{OCTET,BINSTR}

Inheritance map

$CURSOR

Formal Types

types

SAME = BIN_CURSOR ;
BIN_CURSOR = token

This class models a pointer referring to the successive elements of a binary string. Since the elements of the buffer are purely bit-patterns, no semantics other than equality are provided for them.


External specifications

The following four reader routines are required to be implemented in accordance with the specifications given in the class $CURSOR{OCTET,BINSTR} from which this class inherits :-


The following features are required to be implemented for this class in accordance with the specifications given in $CURSOR{OCTET,BINSTR} from which this class inherits :-


create

This routine creates a new string cursor associated with the string argument, ready to scan from the beginning. There is no error condition and the default skip element is a space character.

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

Since the argument is not optional, the pre-condition is vacuously true.

Post-condition
post buffer = str
      and index(res) = 0
      and is_done(res) = (index(res) >= len str)
      and not has_ind(res)

This routine creates and initialises a new cursor to have the buffer given as parameter and to be ready to scan from the beginning, having a space character as skip element.


get_sized

This feature is provided for the common case where an object is a known number of octets for storage - less than the value OCTET::Octet_Max. The remainder of the buffer is treated as such a variable sized chunk in which the first octet specifies the size of the chunk to be returned.

get_sized : BINSTR
Formal Signature
get_sized(self : SAME) res : BINSTR
Pre-condition
pre not is_done(self)
      and remaining(self) > CARD.create(item(self)) 
Post-condition
post let loc_last = CARD.create(item(self~)) in
      res = buffer(index~ + 1, ..., index~ + loc_last)

This feature presumes that the current item is a single octet containing a binary number which must be strictly less than the number of remaining octets in the buffer. The next item is scanned past and the number of octets which equals that number are returned, the cursor having moved.


is_bool

This predicate returns true if and only if the next item in the buffer is a valid truth value, otherwise false.

is_bool : BOOL
Formal Signature
is_bool(self : SAME) res : BOOL
Pre-condition

Since this feature is a predicate and the argument is not optional, this pre-condition is vacuously true. If there are no octets remaining to be scanned this is identical to the next value not being a truth value.

Post-condition

Since this feature is a predicate the post-condition is also vacuously true!

This feature is a predicate which returns true if and only if the next octet in the buffer (if any) is a boolean value.


is_card

This predicate returns true if and only if the next item in the buffer is a cardinal number. Since any number of remaining octets may form a cardinal number this only returns false if there are no more remaining octets to be scanned.

is_card : BOOL
Formal Signature
is_card(self : SAME) res : BOOL
Pre-condition

Since this feature is a predicate and the argument is not optional, this pre-condition is vacuously true. If there are no octets remaining to be scanned this is identical to the next value not being a numeric value.

Post-condition

Since this feature is a predicate the post-condition is also vacuously true!

This feature is a predicate which returns true if and only if the next octet in the buffer (if any) is a number. This is equivalent to stating that there is at least one more unscanned element.


is_field

This predicate returns true if and only if the next item in the buffer is a number. Since any number of remaining octets may form a number this only returns false if there are no more remaining octets to be scanned.

is_field : BOOL
Formal Signature
is_field(self : SAME) res : BOOL
Pre-condition

Since this feature is a predicate and the argument is not optional, this pre-condition is vacuously true. If there are no octets remaining to be scanned this is identical to the next value not being a numeric value.

Post-condition

Since this feature is a predicate the post-condition is also vacuously true!

This feature is a predicate which returns true if and only if the next octet in the buffer (if any) is a number. This is equivalent to stating that there is at least one more unscanned element.


is_int

This predicate returns true if and only if the next item in the buffer is a number. Since any number of remaining octets may form a number this only returns false if there are no more remaining octets to be scanned.

is_int : BOOL
Formal Signature
is_int(self : SAME) res : BOOL
Pre-condition

Since this feature is a predicate and the argument is not optional, this pre-condition is vacuously true. If there are no octets remaining to be scanned this is identical to the next value not being a numeric value.

Post-condition

Since this feature is a predicate the post-condition is also vacuously true!

This feature is a predicate which returns true if and only if the next octet in the buffer (if any) is a number. This is equivalent to stating that there is at least one more unscanned element.


is_int

This predicate returns true if and only if the next item in the buffer is a number. Since any number of remaining octets may form a number this only returns false if there are no more remaining octets to be scanned.

is_int : BOOL
Formal Signature
is_int(self : SAME) res : BOOL
Pre-condition

Since this feature is a predicate and the argument is not optional, this pre-condition is vacuously true. If there are no octets remaining to be scanned this is identical to the next value not being a numeric value.

Post-condition

Since this feature is a predicate the post-condition is also vacuously true!

This feature is a predicate which returns true if and only if the next octet in the buffer (if any) is a number. This is equivalent to stating that there is at least one more unscanned element.


is_flt

This predicate returns true if and only if the next item in the buffer is an approximate number.

is_flt : BOOL
Formal Signature
is_flt(self : SAME) res : BOOL
Pre-condition

Since this feature is a predicate and the argument is not optional, this pre-condition is vacuously true.

Post-condition

Since this feature is a predicate the post-condition is also vacuously true!

This feature is a predicate which returns true if and only if there are sufficient octets unscanned in the buffer from which a floating point number could be created, otherwise false.


is_fltd

This predicate returns true if and only if the next item in the buffer is an approximate number.

is_fltd : BOOL
Formal Signature
is_fltd(self : SAME) res : BOOL
Pre-condition

Since this feature is a predicate and the argument is not optional, this pre-condition is vacuously true.

Post-condition

Since this feature is a predicate the post-condition is also vacuously true!

This feature is a predicate which returns true if and only if there are sufficient octets unscanned in the buffer from which an extended floating point number could be created, otherwise false.


card

The cursor scan expects that there is at least one octet to convert into a cardinal number value

card : CARD
Formal Signature
card(self : SAME) res : CARD
Pre-condition
pre not is_done(self)
Post-condition
post let loc_rem : nat = remaining(self~),
         loc_left : nat = remaining(self) in
      ((loc_left <= NUM_BITS.Octets)
         and is_done(self))
      or loc_left + NUM_BITS.Octets_per_Card = loc_rem
      and (res < CARD.maxval)
         and (res in set dom nat)

This routine returns the cardinal number represented by the sequence of decimal digit characters starting at the current cursor position. If there is no such number then CARD::nil is returned and the cursor has not been moved.


field

Provided that there is at least one octet remaining in the buffer a field value is returned.

field : FIELD
Formal Signature
field(self : SAME) res : FIELD
Pre-condition
pre not is_done(self)
Post-condition
post (let loc_rem : nat = remaining(self~),
         loc_left : nat = remaining(self) in
      ((loc_left <= NUM_BITS.Octets)
         and is_done(self))
      or loc_left + NUM_BITS.Octets_per_Card = loc_rem)
      and (res < FIELD.maxval)
         and (res in set dom nat)

This routine returns the field value obtained from one or more octets which have been scanned past on exit.


int

The cursor scan expects that the character at the current position is a valid decimal digit character and scans forward as many characters as necessary to obtain the numeric value, leaving the cursor positioned at the next following character. If the first character is not a valid digit or if the value cannot be represented in the executing computer system then nil is returned and the cursor remains in its initial position.

int : INT
Formal Signature
int(self : SAME) res : INT
Pre-condition
pre not is_done(self)
Post-condition
post (let loc_rem : nat = remaining(self~),
         loc_left : nat = remaining(self) in
      ((loc_left <= NUM_BITS.Octets)
         and is_done(self))
      or loc_left + NUM_BITS.Octets_per_Card = loc_rem)
      and (res < INT.maxval)
         and (res >= INT.minval)
         and (res in set dom int)

This routine returns the integer number represented by the sequence of decimal digit characters (with an optional initial minus sign) starting at the current cursor position. If the character at the current position is not a decimal digit then INT::nil is returned and the cursor has not been moved.


flt

The cursor scans the next four octets in the buffer and converts them to a floating point number value.

flt : FLT
Formal Signature
flt(self : SAME) res : FLT
Pre-condition
pre not is_done(self)
Post-condition
post (let loc_rem : nat = remaining(self~),
         loc_left : nat = remaining(self),
         loc_size = len FLT.binstr(FLT.create(0.0)) in
            ((loc_left <= loc_size)
               and (loc_rem = loc_left)
               and res = FLT.nil)
            or loc_left + loc_size = loc_rem)
            and (res < FLT.maxval)
               and (res >= FLT.minval)
               and (res in set dom real)

Provided that there are at least four octets remaining to be scanned, the floating point value corresponding to them is returned, otherwise FLT::nil.


fltd

There must be as many octets remaining to be scanned and converted into a floating point number or nil is returned.

Formal Signature
fltd(self : SAME) res : FLTD
Pre-condition
pre not is_done(self)
Post-condition
post (let loc_rem : nat = remaining(self~),
         loc_left : nat = remaining(self),
         loc_size = len FLTD.binstr(FLTD.create(0.0)) in
            ((loc_left <= loc_size)
               and (loc_rem = loc_left)
               and res = FLTD.nil)
            or loc_left + loc_size = loc_rem)
            and (res < FLTD.maxval)
               and (res >= FLTD.minval)
               and (res in set dom real)

Provided that there remain at least eight octets to be scanned (see the IEEE 754 standard), this routine returns the floating point number obtained by scanning them, otherwise FLTD::nil is returned and the cursor has not been moved.


bool

The cursor scan expects that the octet at the current position corresponds to the single element string either BOOL.binstr(true)(1) or BOOL.binstr(false)(1), otherwise false is returned and the cursor has not been moved.

Formal Signature
bool(self : SAME) res : BOOL
Pre-condition
pre not is_done(self)
Post-condition
post let loc_true = BOOL.binstr(true)(1),
         loc_false = BOOL.binstr(false)(1),
         loc_rem = remaining(self~),
         loc_left = remaining(self) in
      (((res = loc_true)
            (or res = loc_false))
         and (loc_left + 1 = loc_rem))
      or ((res = loc_false)
         and (loc_left = loc_rem))

This test that the next item in the buffer is a representation of the value true or of the value false, returning the value found. If neither value was found, false is returned and the cursor has not been moved.


Language Index Library Index Binary Index
Comments or enquiries should be made to Keith Hopper.
Page last modified: Thursday, 29 March 2001.
Produced with Amaya