# 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
- position : CARD
- size : CARD
- 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 and has a potentially infinite range, the post-condition 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 (len entity > 0)

##### Post-condition

post res = nil
or (let head : seq of OCTET be st len head = position(self~) in
let tail : seq of OCTET be st head ^ tail = self~ in
(update(self)
and (res = head ^ entity ^ tail((len tail - len entity), ..., (len tail))))
or (res = self~ ^ entity)

This feature either inserts (if update is true) or 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(self)

##### Post-condition

post res = nil
or (let head : seq of OCTET be st len head = position(self~) in
let tail : seq of OCTET be st head ^ tail = self~ in
(update(self)
and (res = head ^ [entity] ^ tail((len tail - 1), ..., (len tail))))
or (res = self~ ^ [entity])

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 res = 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, 17 November 2000. |