| # Section 8.10.3.2: IN |

###### class IN < $IN_DEVICE

#### Formal Types

types
SAME = IN ;

This class implements a connection to the standard operating system input channel -- for input only!

#### External specifications

The following routine is required to be implemented for this class in accordance with the specification given in $IN_DEVICE :-

- input_possible : BOOL

Since the input channel is uni-directional only for input, this will vacuously return true for this class.

#### create

This feature produces a new connection to the program environment standard input channel for use in retrieving text from that channel.

create | : SAME

##### Formal Signature

create() res : SAME

##### Pre-condition

This is vacuously true for creation without arguments.

##### Post-condition

The result, not being an optional object is the newly created connection and the post-condition is true.

This creation creates a new connection to the program environment standard input channel for retrieving text data.

#### get_code

This feature returns a single character encoding in the repertoire for the environment in which the program is running. This may therefore be either a code representing an entire character or one representing part of a character (see the notes for the REPERTOIRE class).

get_code | : CHAR_CODE

##### Formal Signature

get_code(self : SAME) res : CHAR_CODE

##### Pre-condition

Since the parameter is not optional this pre-condition is vacuously true.

##### Post-condition

The value returned is the next encoding consisting of the number of octets which form a single character encoding in the program environment - or if there is no such encoding the bit-pattern with all bits set - which is never a valid encoding (see the notes for the UNICODE class).

This feature retrieves a single character encoding from the standard input channel. An encoding is defined to be the bit-pattern formed by the number of octets (Left-most first) needed to form a correct code in the repertoire of the environment in which the program is executing. Note that the encoding itself need not be in that code - it merely occupies that number of bits. Should the operation fail then invalid is returned (this is not a valid character encoding - see the standard ISO/IEC 10646-1:2000 for the detailed specification.

#### get_ch

This feature returns a character in the repertoire and encoding specified in the environment in which the program is executing. The bit-pattern is expected to be valid in that repertoire. The result if it is not valid is undefined.

get_ch | : CHAR

##### Formal Signature

get_ch(self : SAME) res : CHAR

##### Pre-condition

Since the parameter is not optional the pre-condition is vacuously true.

##### Post-condition

Provided that the operation succeeds then the character value is returned, otherwise an invalid character.

This feature retrieves a single character from the standard input channel. Should the operation fail then an invalid 'character' is returned (ie it is not in the repertoire of the environment in which the program is executing - see notes in the REPERTOIRE class.

#### get_str

This feature, the first of two overloaded features, requires the external repertoire and encoding to be in the form described by the lib argument. It then retrieves characters up to and including the next line mark found from the standard input channel. The string returned (which may be empty) has had the end of line mark removed.

get_str | (
| lib : LIBCHARS
| ) : STR

##### Formal Signature

get_str1(self : SAME, lib : LIBCHARS) res : STR

##### Pre-condition

Since neither of the arguments is optional, the pre-condition is vacuously true.

##### Post-condition

post (STR.size(res) = 0)
or not exists ch : CHAR in set dom res & ch in set dom lib.Line_Mark

Providing that the retrieval actions do not fail then this feature returns a string containing a sequence of text characters from the standard input channel up to but not including the next end of line indicator (which has, however, been removed from the input stream). If failure has occurred then the cheracters obtained (if any) are returned and the state of the input stream is undefined.

#### get_str

This feature is the second returning a string, this one uses the program environment repertoire and encoding rather than a specified one. It retrieves characters up to the next line mark found from the standard input channel. The end of line mark is, however, removed.

get_str | : STR

##### Formal Signature

get_str2(self : SAME) res : STR

##### Pre-condition

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

##### Post-condition

post (STR.size(res) = 0)
or not exists ch : CHAR in set dom res & ch in set dom LIBCHARS.default.Line_Mark

Providing that the retrieval actions do not fail then this feature returns a string containing a sequence of text characters from the standard input channel up to but not including the next end of line indicator which is determined from the default repertoire and encoding. The end of line mark has been removed from the stream. If failure has occurred then the characters obtained so far (which could be none!)are returned and the state of the input stream is undefined.

#### get_line

This feature, the first of another pair of overloaded features, requires the external repertoire and encoding to be in the form described by the lib argument. It then retrieves characters up to and including the next line mark found from the standard input channel. The end of line mark is stripped off the buffer used, which is then returned.

get_line | (
| lib : LIBCHARS
| ) : FSTR

##### Formal Signature

get_line1(self : SAME, lib : LIBCHARS) res : FSTR

##### Pre-condition

Since neither of the arguments is optional, the pre-condition is vacuously true.

##### Post-condition

Note that a buffer is always returned by this feature - but it may be empty.

post FSTR.size(res) = 0
or not exists ch : CHAR in set dom res & ch in set dom lib.Line_Mark

Providing that the retrieval actions do not fail then this feature returns a string buffer containing a sequence of text characters from the standard input channel up to but not including the next end of line indicator. If failure has occurred then the characters read (if any) are returned in the buffer.

#### get_line

This feature, the second returning a string buffer, uses the program environment repertoire and encoding. It retrieves characters up to the next line mark found from the standard input channel.

get_line | : FSTR

##### Formal Signature

get_line2(self : SAME) res : FSTR

##### Pre-condition

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

##### Post-condition

post (STR.size(res) = 0)
or not exists ch : CHAR in set dom res & ch in set dom LIBCHARS.default.Line_Mark

Providing that the retrieval actions do not fail then this feature returns a new object containing a sequence of text characters from the standard input channel up to but not including the next end of line indicator which is determined from the default repertoire and encoding. If failure has occurred then those characters which have been retrieved (which may be none) are returned in the buffer and the state of the input stream is undefined.

#### append_line

This feature appends the next line of text to the given buffer. It requires the external repertoire and encoding to be in the form described by the lib argument. It then retrieves characters, appending them to the buffer, up to and including the next line mark found from the standard input channel. The end of line mark is stripped off the buffer, which is then returned.

get_line | (
| lib : LIBCHARS
| ) : FSTR

##### Formal Signature

append_line(self : SAME, str : FSTR) res : FSTR

##### Pre-condition

Since neither of the arguments is optional, the pre-condition is vacuously true.

##### Post-condition

Note that a buffer is always returned by this feature - but it may only have the initial contents. This feature can not guarantee that the initial buffer is free from line marks - as indicated in the formal condition below.

post FSTR.size(res) = FSTR.size(str)
or let loc_buffer be st res = str ++ loc_buffer in
not exists ch : CHAR in set dom loc_buffer & ch in set dom lib.Line_Mark

Providing that the retrieval actions do not fail then this feature returns the string buffer which has had appended to it a sequence of text characters from the standard input channel up to but not including the next end of line indicator. If failure has occurred then the contents of the buffer returned consist of the initial string to which has been appended all of those characters retrived up to the instant of failure.

#### error

This feature provides a facility for a program to detect if an input error has occurred.

error | : BOOL

##### Formal Signature

error(self : SAME) res : BOOL

##### Pre-condition

Since this feature is a predicate the pre-condition is vacuously true.

##### Post-condition

The value returned indicates the current error state of the channel connection.

This predicate returns true if and only if an error has been detected since object creation or the most recent use of the clear feature.

#### clear

This feature resets the error state of the connection.

clear

##### Formal Signature

clear(self : SAME)

##### Pre-condition

This is vacuously true.

##### Post-condition

post not error

This routine resets the state of the connection to be error-free.

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

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