get_byte/2

get_byte(@stream_or_alias, ?in_byte) [ISO]

This built-in clause reads a single byte from the stream, the stream is altered. The input stream must be a binary stream that was opened for reading. If Byte is a variable or an in_byte (a byte or the number -1) then:

If the stream position is neither end-of-stream or past-end-of-stream then let Byte be the next byte to be read from the input stream, the stream position is advanced one byte. If the byte read and Byte are unifiable then get_byte/2 succeeds else fails.
If the stream position is end-of-stream then sets the stream position to past-end-of-stream, if the number -1 and Byte are unifiable then get_byte/2 succeeds else fails.
If the stream position is past-end-of-stream and the stream property is eof_action(error) then a permission_error exception is thrown. If the stream has the property eof_action(reset) then the stream position is reset so that input can be read from it again, else if the stream has the property eof_action(eof_code) then if the number -1 and Byte are unifiable then get_byte/2 succeeds else fails.

Example
get_byte(user_in, A).	Assume there is an input stream called user_in and it has contents: 120, 66, 67, ... A is assigned the value 120 and the stream is left as: 66, 67, ...
get_byte(user_in, 117).	Assume there is an input stream called user_in and it has contents: 120, 66, 67, ... get_byte/2 fails, and a byte was removed from the stream, the stream is left as: 66, 67, ...

Exceptions
Byte is neither a variable nor an in_byte	a type_error(in_byte, Byte) is thrown
stream_or_alias is a variable	an instantiation_error exception is thrown
stream_or_alias is neither a variable nor a stream term nor an alias	a domain_error(stream_or_alias, Stream) exception is thrown, the variable Stream is assigned the incorrect stream_or_alias term
stream_or_alias is not associated with an open stream	an existence_error(stream, Stream) exception is thrown
stream_or_alias is an output stream	a permission_error(input, stream, Stream) exception is thrown
stream_or_alias is a text stream	a permission_error(input, text_stream, InputStream) is thrown, the variable InputStream is assigned the stream which was used as the input stream
current input stream has properties end_of_stream(past) and eof_action(error)	a permission_error(input, past_end_of_stream, InputStream) exception is thrown

info@trinc-prolog.com