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

   Reads a string from the stream Stream up to a delimiter or up to a
specified length.



Arguments
   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.

Type
   Character I/O

Description
   A string of characters is read from the input stream Stream up to one
   character which occurs in the delimiter string Delimiters.  This
   character is also consumed, but does not appear in the string which is
   unified with String.


   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

   End of file always acts like a delimiter.


   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.




Modes and Determinism
   read_string(+, +, +, -) is semidet
   read_string(+, +, -, -) is semidet

Fail Conditions
   There is nothing to read, i.e. the stream is at end_of_file

Exceptions
     4 --- Delimiters is not instantiated.
     5 --- Delimiters is not a string or atom.
     5 --- Length is a non-integer number.
     5 --- String is not a variable or a string.
     6 --- Delimiters is an atom but not a valid symbolic delimiter.
    24 --- Length is not a variable or number.
   190 --- End of file was encountered before reading any character.
   192 --- Stream is not an input stream.
   193 --- Stream is an illegal stream specification.
   198 --- 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
   read_string / 3, read_token / 2, read_token / 3, open / 3
