| # Section 8.10.3.7: BIN_FILE_CURSOR |

###### class BIN_FILE_CURSOR < $FILE_CURSORS

#### Formal Types

types
SAME = BIN_FILE_CURSOR ;

This class implements a model of a cursor (and associated buffer) into a binary file.

#### External specifications

The following routines are required to be implemented for this class in accordance with the specifications given in the abstract class $FILE_CURSORS :-

- position : CARD
- position(at : CARD) : SAME
- forward(cnt : CARD) : SAME
- skip(cnt : CARD) : SAME
- backward(cnt : CARD) : SAME
- size : CARD
- readable : BOOL
- writable : BOOL
- at_end : BOOL
- error : BOOL
- error_message : STR
- clear

#### get

This is the single 'input' feature associated with the cursor, it allows for arbitrary reading of octets from the current position, updating that position as reading continues.

get | (
| count : CARD
| ) : FBINSTR

##### Formal Signature

get(self : SAME, count : CARD) res : [FBINSTR]

##### Pre-condition

pre readable(self)
and (count > 0)

##### Post-condition

post (at_end
and res = nil)
or (FBINSTR.size(result) = count)

This routine returns the next count items in the file in a binary string buffer. If there is insufficient data in the file then void is returned.

#### plus

This first variant of plus places the value of the single octet item at the current position in the file buffer.

plus | (
| item : OCTET
| )

##### Formal Signature

plus1(self : SAME, item : OCTET)

##### Pre-condition

pre writable(self)

##### Post-condition

post (position(self) = (position(self)~ + 1))

This feature sets the value of item into the current file position in the file buffer associated with this cursor.

#### plus

This second variant of plus places the value of the single octet item at the current position in the file buffer and then returns the cursor.

plus | (
| item : OCTET
| ) : SAME

##### Formal Signature

plus2(self : SAME, item : OCTET) res : SAME

##### Pre-condition

pre writable(self)

##### Post-condition

post (position(self) = (position(self)~ + 1))
and res = self

This feature makes the value of the current file position equal to item and moves the cursor forward by one.

#### plus

This is the first of the two features which are provided to send a binary string of data to the file associated with this cursor, extending the length of the file as needed.

plus | (
| entity : BINSTR
| )

##### Formal Signature

plus3(self : SAME, entity : BINSTR)

##### Pre-condition

pre writable(self)
and (BINSTR.size(entity) > 0)

##### Post-condition

post (position(self) = (position(self)~ + BINSTR.size(entity)))

This feature appends the given item at the current position in the file buffer. The cursor position is moved forward by the size of the binary string. This action may or may not involve writing to the underlying file.

#### plus

This is the second feature provided to send a binary string of data to the file associated with this cursor, extending the length of the file as needed. This one returns the cursor itself.

plus | (
| entity : BINSTR
| ) : SAME

##### Formal Signature

plus4(self : SAME, entity : BINSTR) res : SAME

##### Pre-condition

pre writable(self)
and (BINSTR.size(entity) > 0)

##### Post-condition

post (position(self) = (position(self)~ + BINSTR.size(entity)))
and res = self

This feature sets the file contents for the number of octets in the binary string to be the values of the binary string. The cursor position is moved forward by that number of octets. The cursor itself is then returned.

#### flush

This feature ensures that any buffer contents which has not been written to the file has been written, synchronising the program with the file store.

flush

##### Formal Signature

flush(self : SAME)

##### Pre-condition

This is vacuously true.

##### Post-condition

Any output which has been sent to the file since either it was opened or the most recent previous call of this routine, will be forced out to synchronise the file with the program.

This routine flushes the cursor buffer to the file, ensuring that file and program are synchronised.

| Language Index |  | Library Index |  | Input/Output Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Monday, 17 July 2000. |