[ Character I/O | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

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

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

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

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) 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

read_string / 3, read_token / 2, read_token / 3, open / 3