Qore Programming Language Reference Manual  1.7.0
Qore::InputStreamLineIterator Class Reference

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

Inheritance diagram for Qore::InputStreamLineIterator:

Public Member Methods

 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. More...
 
 constructor (Qore::StreamReader sr, *string eol, bool trim=True)
 Creates the InputStreamLineIterator for iterating data from the given StreamReader. More...
 
string getEncoding ()
 Returns the character encoding for the InputStreamLineIterator. More...
 
string getLine ()
 Returns the current line in the data or throws an ITERATOR-ERROR exception if the iterator is invalid. More...
 
StreamReader getStreamReader ()
 Returns the StreamReader object used internally. More...
 
string getValue ()
 Returns the current line in the data or throws an ITERATOR-ERROR exception if the iterator is invalid. More...
 
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. More...
 
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. More...
 
bool valid ()
 Returns True if the iterator is currently pointing at a valid element, False if not. More...
 
- Public Member Methods inherited from Qore::AbstractLineIterator
list< stringgetSplitLine (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. More...
 

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());
}
string printf(string fmt,...)
Outputs the string passed to standard output, using the first argument as a format string; does not e...
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
isthe InputStream to iterate over
encodingcharacter 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
eolthe 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
trimif True the string return values for the lines iterated will be trimmed of the eol bytes
bufsizethe size of the buffer for the internal BufferedStreamReader in bytes; must be a positive integer
Exceptions
STREAM-BUFFER-ERRORan invalid stream buffer size was specified; the buffer size must be a positive integer
ENCODING-CONVERSION-ERRORthis 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
srthe StreamReader used as a source of data to iterate over
eolthe 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
trimif True the string return values for the lines iterated will be trimmed of the eol bytes
Exceptions
ENCODING-CONVERSION-ERRORthis 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 ( )
virtual

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-ERRORthe iterator is not pointing at a valid element
ITERATOR-THREAD-ERRORthis exception is thrown if this method is called from any thread other than the thread that created the object
See also
InputStreamLineIterator::getValue()

Implements Qore::AbstractLineIterator.

◆ 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 ( )
virtual

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-ERRORthe iterator is not pointing at a valid element
ITERATOR-THREAD-ERRORthis exception is thrown if this method is called from any thread other than the thread that created the object
See also
InputStreamLineIterator::getLine()

Implements Qore::AbstractLineIterator.

◆ index()

int Qore::InputStreamLineIterator::index ( )
virtual

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());
}

Implements Qore::AbstractLineIterator.

◆ next()

bool Qore::InputStreamLineIterator::next ( )
virtual

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-ERRORthis exception is thrown if this method is called from any thread other than the thread that created the object

Implements Qore::AbstractLineIterator.

◆ valid()

bool Qore::InputStreamLineIterator::valid ( )
virtual

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

Implements Qore::AbstractLineIterator.