| # Section 8.10.3.5: BIN_FILE |

###### class BIN_FILE < $FILES

#### Formal Types

types
SAME = BIN_FILE ;

This class implements a model of 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 $FILES :-

- open_for_read(name : STR) : BIN_FILE
- open_for_write(name : STR) : BIN_FILE
- open_at_end(name : STR) : BIN_FILE
- open_for_update(name : STR) : BIN_FILE
- open_at_end_for_update(name : STR) : BIN_FILE
- create_for_write(name : STR) : BIN_FILE
- create_for_update(name : STR) : BIN_FILE
- create_temp : BIN_FILE
- is_open : BOOL
- readable : BOOL
- writable : BOOL
- append : BOOL
- update : BOOL
- close
- error : BOOL
- error_message : STR
- clear

#### cursor

This feature creates a file cursor object which provides a facility for handling very large files where a computer system has not enought memory available.

cursor | (
| size : CARD
| ) : BIN_FILE_CURSOR

##### Formal Signature

cursor(self : SAME, size : CARD) res : BIN_FILE_CURSOR

##### Pre-condition

pre is_open(self)
and (size mod 4) = 0

##### Post-condition

Since the return value is not an optional type this is vacuously true.

This routine creates and returns a file buffer cursor object associated with self.

#### plus

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

plus | (
| entity : BINSTR
| ) : SAME

##### Formal Signature

plus1(self : SAME, entity : BINSTR) res : [SAME]

##### Pre-condition

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

##### Post-condition

post res = nil
or (update(self)
and (size(self) >= BINSTR.size(entity)))
or (size(self) = (size(self)~ + BINSTR.size(entity)))

This feature appends the given item to the file channel to which self is a connection, returning self if successful, otherwise returning void.

#### plus

This is the variant of plus which places the value of the single octet item at the current position in the file, extending the file size if needed.

plus | (
| item : OCTET
| ) : SAME

##### Formal Signature

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

##### Pre-condition

pre writable

##### Post-condition

post res = nil
or (update(self)
and (size(self) >= 1))
or (size(self) = (size(self)~ + 1))

This feature appends the given octet to the file channel to which self is a connection, returning self if successful, otherwise returning void.

#### buffer

This is the sole direct input feature from a binary file, returning a buffer containing the entire contents of the file.

buffer | : FBINSTR

##### Formal Signature

buffer(self : SAME) res : [FBINSTR]

##### Pre-condition

pre readable(self)

##### Post-condition

post (FBINSTR.size(res) = size(self))

This feature returns a buffer containing the entire contents of the file (which could be empty) provided that it was possible to set the environment next-location-to-read point at the beginning of the file, otherwise void.

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

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