| # Section 8.10.3.6: TEXT_FILE |

###### class TEXT_FILE < $FILES

#### Formal Types

types
SAME = TEXT_FILE ;

This class implements a model of a file which contains text in any possible character encoding and repertoire.

#### 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) : TEXT_FILE
- open_for_write(name : STR) : TEXT_FILE
- open_at_end(name : STR) : TEXT_FILE
- open_for_update(name : STR) : TEXT_FILE
- open_at_end_for_update(name : STR) : TEXT_FILE
- create_for_write(name : STR) : TEXT_FILE
- create_for_update(name : STR) : TEXT_FILE
- create_temp : TEXT_FILE
- is_open : BOOL
- readable : BOOL
- writable : BOOL
- append : BOOL
- update : BOOL
- close
- error : BOOL
- error_message : STR
- clear

#### cursor

This feature is the first variant of text file cursor creation, creating a cursor object which provides a facility for handling very large files of text in the given repertoire and encoding (where a computer system has not enough memory available for the entire file contents).

cursor | (
| size : CARD,
| lib : LIBCHARS
| ) : TEXT_FILE_CURSOR

##### Formal Signature

cursor(self : SAME, size : CARD, lib : LIBCHARS) res : TEXT_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 for text in the given repertoire and encoding.

#### cursor

This feature is the second variant which creates a text file cursor object for text in the program environment repertoire and encoding which provides a facility for handling very large files of text where a computer system has not enough memory available.

cursor | (
| size : CARD
| ) : TEXT_FILE_CURSOR

##### Formal Signature

cursor(self : SAME, size : CARD) res : TEXT_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 for text in the program environment repertoire and encoding.

#### plus

This is the first of two features which are provided to send text data (of any repertoire and encoding) to a file, extending the length of the file as needed.

plus | (
| item : $STR
| )

##### Formal Signature

plus1(self : SAME, item : multi)

##### Pre-condition

The state component given below is taken from the definition of the abstract class $STR, repeated here for convenience.

state
multi : $STR
inv multi_types ==
forall obj in set multi_types & sub_type($STR,obj)
pre writable(self)
and (multi.item(size) > 0)

##### Post-condition

Note the use of inequality in this post-condition. This arises since a text string item may have one or more storage 'spaces' per character. The size feature returns the size in characters since storage is only really of concern during import and export of data.

post res = nil
or (update(self)
and (size(self) >= multi.size(item)))
or (size(self) >= (size(self)~ + multi.size(item)))

This feature appends the given item to the text file channel to which self is a connection.

#### plus

This variant of plus sends the given item to the text file and then returns self if successful. otherwise void.

plus | (
| item : $STR
| ) : SAME

##### Formal Signature

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

##### Pre-condition

The state component given below is taken from the definition of the abstract class $STR, repeated here for convenience.

state
multi : $STR
inv multi_types ==
forall obj in set multi_types & sub_type($STR,obj)
pre writable
and (multi.item(size) > 0)

##### Post-condition

Note the use of inequality in this post-condition. This arises since a text string item may have one or more storage 'spaces' per character. The size feature returns the size in characters since storage is only really of concern during import and export of data.

post res = nil
or (update(self)
and (size(self) >= multi.size(item)))
or (size(self) >= (size(self)~ + multi.size(item)))

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

#### fstr

This feature is the first of a pair which retrieve the contents of the given file into a buffer which is returned.

fstr | (
| lib : LIBCHARS
| ) : FSTR

##### Formal Signature

str(self : SAME, lib : LIBCHARS) res : [FSTR]

##### Pre-condition

pre readable(self)

##### Post-condition

Note the use of inequality in this post-condition. This arises since a text string item may have one or more storage 'spaces' per character. The size feature returns the size in characters since storage is only really of concern during import and export of data.

post (FSTR.size(res) <= size(self))

This feature returns a buffer containing the entire contents of the text 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. The text string is in the given encoding and repertoire.

#### fstr

This feature retrieves the contents of the given file, considering it to be in the program environment repertoire and encoding, into a buffer which is returned.

fstr | : FSTR

##### Formal Signature

fstr2(self : SAME) res : [FSTR]

##### Pre-condition

pre readable(self)

##### Post-condition

Note the use of inequality in this post-condition. This arises since a text string item may have one or more storage 'spaces' per character. The size feature returns the size in characters since storage is only really of concern during import and export of data.

post (FSTR.size(res) <= size(self))

This feature returns a buffer containing the entire contents of the text 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. The text string is in the program environment encoding and repertoire.

#### frunes

This feature is the first of a pair of rune text retrieval features. The entire contents of the given file is transferred to a buffer which is organised to contain a sequence of runes (see notes in the class RUNE definition). The buffer itself is returned.

frunes | (
| lib : LIBCHARS
| ) : FRUNES

##### Formal Signature

frunes(self : SAME, lib : LIBCHARS) res : [FRUNES]

##### Pre-condition

pre readable(self)

##### Post-condition

Note the inequality in this condition. This arises since an individual rune may occupy any 'size' space from 1 to 24 octets!

post (FSTR.size(res) >= size(self))

This feature returns a buffer containing the entire contents of the text 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. The rune string is composed on the basis that it is in the given encoding and repertoire.

#### frunes

This feature retrieves the contents of the given file, considering it to be in the program environment repertoire and encoding, into a buffer which is returned.

frunes | : FRUNES

##### Formal Signature

frunes2(self : SAME) res : [FSTR]

##### Pre-condition

pre readable(self)

##### Post-condition

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

This feature returns a buffer containing the entire contents of the text 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. The rune string is composed assuming that the data is in the program environment encoding and repertoire.

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

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