| Qore Programming Language Reference Manual 2.2.0

Loading...
Searching...
No Matches
Public Member Functions | List of all members
Qore::InputStreamLineIterator Class Reference

This class defines a line iterator for input streams. More...

`#include <QC_InputStreamLineIterator.dox.h>`

Inheritance diagram for Qore::InputStreamLineIterator:
[legend]

## Public Member Functions
| constructor (Qore::InputStream is, *string encoding, *string eol, bool trim=True, int bufsize=DefaultStreamBufferSize)
| Creates a buffered InputStreamLineIterator object for iterating over the given `InputStream`.
| constructor (Qore::StreamReader sr, *string eol, bool trim=True)
| Creates the InputStreamLineIterator for iterating data from the given `StreamReader`.
string | getEncoding ()
| Returns the character encoding for the InputStreamLineIterator.
string | getLine ()
| Returns the current line in the data or throws an `ITERATOR-ERROR` exception if the iterator is invalid.
StreamReader | getStreamReader ()
| Returns the StreamReader object used internally.
string | getValue ()
| Returns the current line in the data or throws an `ITERATOR-ERROR` exception if the iterator is invalid.
int | index ()
| Returns the current iterator line number in the data (the first line is line 1) or 0 if not pointing at a valid element.
bool | next ()
| Moves the current position to the next line in the data; returns False if there are no more lines to read; if the iterator is not pointing at a valid element before this call, the iterator will be positioned to the beginning of the data.
bool | valid ()
| Returns True if the iterator is currently pointing at a valid element, False if not.
Public Member Functions inherited from Qore::AbstractLineIterator
abstract string | getLine ()
| Returns the current line in the data or throws an `INVALID-ITERATOR` exception if the iterator is invalid.
list< string > | getSplitLine (string sep, string quote, string eol="\n", bool trim_unquoted=False)
| Returns the current line and splits the string into a list of components based on a separator string and a quote character.
abstract string | getValue ()
| Returns the current line in the data or throws an `INVALID-ITERATOR` exception if the iterator is invalid.
abstract int | index ()
| Returns the current iterator line number (the first line is line 1) or 0 if not pointing at a valid element.
abstract bool | next ()
| Moves the current position to the next line; returns False if there are no more lines to read.
abstract bool | valid ()
| Returns True if the iterator is currently pointing at a valid element, False if not.
Public Member Functions inherited from Qore::AbstractIterator
abstract auto | getValue ()
| returns the current value
abstract bool | next ()
| Moves the current position to the next element; returns False if there are no more elements.
abstract bool | valid ()
| returns True if the iterator is currently pointing at a valid element, False if not

## Detailed Description

This class defines a line iterator for input streams.

Since
  Qore 0.8.13

Example: InputStreamLineIterator basic usage
  FileInputStream fis("log.txt");
  InputStreamLineIterator it(fis, "\n");
  while (it.next()) {
  printf("line %d = %n\n", it.index(), it.getLine());
  }

See also
  Qore::DataLineIterator
  Qore::FileLineIterator

## Member Function Documentation

## ◆ constructor() [1/2]

Qore::InputStreamLineIterator::constructor | ( | Qore::InputStream | is,
|  | *string | encoding,
|  | *string | eol,
|  | bool | trim = True,
|  | int | bufsize = DefaultStreamBufferSize )

Creates a buffered InputStreamLineIterator object for iterating over the given `InputStream`.

Parameters

  is | the `InputStream` to iterate over
  encoding | character encoding of the data from input stream; if not ASCII-compatible, all data will be converted to UTF-8; if not present, the default character encoding is assumed
  eol | the optional end of line character(s) to use to detect lines in the data; if this string is not passed, then if the character-encoding is ASCII-compatible, the end of line character(s) are detected automatically from `"\n"`, `"\r"`, or `"\r\n"`; if the stream uses a non-ASCII-compatible character encoding, then `"\n"` is assumed
  trim | if True the string return values for the lines iterated will be trimmed of the eol bytes
  bufsize | the size of the buffer for the internal BufferedStreamReader in bytes; must be a positive integer

Exceptions

  STREAM-BUFFER-ERROR | an invalid stream buffer size was specified; the buffer size must be a positive integer
  ENCODING-CONVERSION-ERROR | this exception could be thrown if the eol argument has a different character encoding from the data's and an error occurs during encoding conversion

Note
  this variant of the InputStreamLineIterator::constructor creates a BufferedStreamReader to read the input data

## ◆ constructor() [2/2]

Qore::InputStreamLineIterator::constructor | ( | Qore::StreamReader | sr,
|  | *string | eol,
|  | bool | trim = True )

Creates the InputStreamLineIterator for iterating data from the given `StreamReader`.

Parameters

  sr | the `StreamReader` used as a source of data to iterate over
  eol | the optional end of line character(s) to use to detect lines in the data; if this string is not passed, then if the character-encoding is ASCII-compatible, the end of line character(s) are detected automatically from `"\n"`, `"\r"`, or `"\r\n"`; if the stream uses a non-ASCII-compatible character encoding, then `"\n"` is assumed
  trim | if True the string return values for the lines iterated will be trimmed of the eol bytes

Exceptions

  ENCODING-CONVERSION-ERROR | this exception could be thrown if the eol argument has a different character encoding from the data's and an error occurs during encoding conversion

## ◆ getEncoding()

string Qore::InputStreamLineIterator::getEncoding | ( |  | ) |

Returns the character encoding for the InputStreamLineIterator.

Code Flags:
  CONSTANT

Example:
  string encoding = i.getEncoding();

Returns
  the character encoding for the InputStreamLineIterator

## ◆ getLine()

string Qore::InputStreamLineIterator::getLine | ( |  | ) |

Returns the current line in the data or throws an `ITERATOR-ERROR` exception if the iterator is invalid.

Returns
  the current line in the data or throws an `ITERATOR-ERROR` exception if the iterator is invalid

Code Flags:
  RET_VALUE_ONLY

Example:
  while (i.next()) {
  printf("+ %y\n", i.getLine());
  }

Exceptions

  ITERATOR-ERROR | the iterator is not pointing at a valid element
  ITERATOR-THREAD-ERROR | this exception is thrown if this method is called from any thread other than the thread that created the object

See also
  InputStreamLineIterator::getValue()

## ◆ getStreamReader()

StreamReader Qore::InputStreamLineIterator::getStreamReader | ( |  | ) |

Returns the StreamReader object used internally.

Example:
  StreamReader sr = i.getStreamReader();

Returns
  the StreamReader object used internally

## ◆ getValue()

string Qore::InputStreamLineIterator::getValue | ( |  | ) |

Returns the current line in the data or throws an `ITERATOR-ERROR` exception if the iterator is invalid.

Returns
  the current line in the data or throws an `ITERATOR-ERROR` exception if the iterator is invalid

Code Flags:
  RET_VALUE_ONLY

Example:
  while (i.next()) {
  printf("+ %y\n", i.getValue());
  }

Exceptions

  ITERATOR-ERROR | the iterator is not pointing at a valid element
  ITERATOR-THREAD-ERROR | this exception is thrown if this method is called from any thread other than the thread that created the object

See also
  InputStreamLineIterator::getLine()

## ◆ index()

int Qore::InputStreamLineIterator::index | ( |  | ) |

Returns the current iterator line number in the data (the first line is line 1) or 0 if not pointing at a valid element.

Returns
  the current iterator line number in the data (the first line is line 1) or 0 if not pointing at a valid element

Code Flags:
  CONSTANT

Example:
  while (i.next()) {
  printf("+ %d: %y\n", i.index(), i.getValue());
  }

## ◆ next()

bool Qore::InputStreamLineIterator::next | ( |  | ) |

Moves the current position to the next line in the data; returns False if there are no more lines to read; if the iterator is not pointing at a valid element before this call, the iterator will be positioned to the beginning of the data.

The iterator object should not be used after this method returns False.

Returns
  False if there are no more lines in the data (in which case the iterator object is invalid and should not be used); True if successful (meaning that the iterator object is valid)

Example:
  while (i.next()) {
  printf("line: %y\n", i.getValue());
  }

Exceptions

  ITERATOR-THREAD-ERROR | this exception is thrown if this method is called from any thread other than the thread that created the object

## ◆ valid()

bool Qore::InputStreamLineIterator::valid | ( |  | ) |

Returns True if the iterator is currently pointing at a valid element, False if not.

Returns
  True if the iterator is currently pointing at a valid element, False if not

Code Flags:
  CONSTANT

Example:
  if (i.valid())
  printf("current value: %y\n", i.getValue());