read_string(+Stream, +Delimiters, ?Length, ?String)

+Stream

Integer (stream number) or Atom (reserved or user-defined symbolic stream name).

+Delimiters

String or atom.

?Length

Integer or variable.

?String

String or variable.

Description

Two symbolic Delimiters can be specified:

    end_of_line   a newline or carriage-return/newline sequence
    end_of_file   the end of the file/input

If Length is a variable, it is unified with the length of the string String. If Length is an integer, the number of characters read from the input stream Stream is limited by Length.

Fail Conditions

Resatisfiable

Exceptions

(4) instantiation fault

Delimiters is not instantiated.

(5) type error

Delimiters is not a string or atom.

(5) type error

Length is a non-integer number.

(5) type error

String is not a variable or a string.

(6) out of range

Delimiters is an atom but not a valid symbolic delimiter.

(24) number expected

Length is not a variable or number.

(190) end of file reached

End of file was encountered before reading any character.

(192) illegal stream mode

Stream is not an input stream.

(193) illegal stream specification

Stream is an illegal stream specification.

(198) reading past the file end

Trying to read even after the error 190 was raised.

Examples

Success:
      [eclipse]: read_string(input, "123", Length, String).
          abcdef2ghi

      Length = 6
      String = "abcdef"
      yes.
      [eclipse]: read_string(input, " \t", Length, String).
      one two

      Length = 3
      String = "one"
      yes.
      [eclipse]: read_string(input, end_of_line, Length, String).
      abcdefghi

      Length = 9
      String = "abcdefghi"
      yes.
      [eclipse]: read_string(input, end_of_line, 6, String).
      abcdefghi

      String = "abcdef"
      yes.

      [eclipse]: open(file1, read, s).

      yes.
      [eclipse]: system('cat file1').
      abcd

      yes.
      [eclipse]: read_string(s, "", Length, String).

      Length = 5
      String = "abcd\n"           % Read up to end of file
      yes.


% Code example: read lines from a file and return
% a list of strings, each string containing a line

    get_lines(File, Lines) :-
	open(File, read, S),
	get_lines(S, Lines),
	close(S).

    get_lines(S, Lines) :-
	( read_string(S, end_of_line, _, Line) ->
	    Lines = [Line|Ls],
	    get_lines(S, Ls)
	;
	    Lines = []
	).


Fail:
      [eclipse]: open(string(""),read,s), read_string(s,"",L,String).

      no (more) solution.         % EOF - Error 190 - handler fails

Error:
    read_string(Stream, "", Length, String).       (Error 4).
    read_string(stream, Dels, Length, String).     (Error 4).
    read_string("stream", "", Length, String).     (Error 5).
    read_string(stream, 12, Length, String).       (Error 5).
    read_string(stream, "", "abc", String).        (Error 5).
    read_string(stream, "", Length, 12).           (Error 5).
    read_string(stream, stop, Length, String).     (Error 6).
    read_string(output, "", Length, String).       (Error 192).
    read_string(atom, "", Length, String).         (Error 193).

See Also