Qore Programming Language Reference Manual  0.9.1
Qore::DataLineIterator Class Reference

This class defines a line iterator for string data. More...

Inheritance diagram for Qore::DataLineIterator:

Public Member Methods

 constructor (string str, *string eol, bool trim=True)
 creates the DataLineIterator based on the string given More...
 
 copy ()
 Creates a new DataLineIterator object, based on the same object being iterated in the original object. More...
 
string getEncoding ()
 Returns the character encoding for the DataLineIterator. More...
 
string getLine ()
 returns the current line in the data or throws an ITERATOR-ERROR exception if the iterator is invalid 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...
 
 reset ()
 Reset the iterator instance to its initial state. More...
 
bool valid ()
 returns True if the iterator is currently pointing at a valid element, False if not More...
 

Detailed Description

This class defines a line iterator for string data.

Since
Qore 0.8.12
Example: DataLineIterator basic usage
string str = "a2ps-4.13-1332.1.x86_64
a2ps-devel-4.13-1332.1.x86_64
aaa_base-11.3-7.2.x86_64";
DataLineIterator it(str);
while (it.next()) {
printf("line %d = %n\n", it.index(), it.getValue());
}
line 1 = "a2ps-4.13-1332.1.x86_64"
line 2 = "a2ps-devel-4.13-1332.1.x86_64"
line 3 = "aaa_base-11.3-7.2.x86_64"
See also
Qore::InputStreamLineIterator
Qore::FileLineIterator

Member Function Documentation

◆ constructor()

Qore::DataLineIterator::constructor ( string  str,
*string  eol,
bool  trim = True 
)

creates the DataLineIterator based on the string given

Parameters
strthe string to iterate over; note that if this string is in a non-ascii-compatible character encoding, it will be converted to UTF-8 for processing in the constructor and the UTF-8 version of the string will be used for iterating in this object
eolthe optional end of line character(s) to use to detect lines in the data; if this string is not passed, then the end of line character(s) are detected automatically, and can be either "\n", "\r", or "\r\n"; if this string is passed and has a different character encoding from this object's (as determined by the encoding parameter), then it will be converted to the DataLineIterator's character encoding
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

◆ copy()

Qore::DataLineIterator::copy ( )

Creates a new DataLineIterator object, based on the same object being iterated in the original object.

Example:
DataLineIterator ni = i.copy();

◆ getEncoding()

string Qore::DataLineIterator::getEncoding ( )

Returns the character encoding for the DataLineIterator.

Code Flags:
CONSTANT
Example:
string encoding = f.getEncoding();
Returns
the character encoding for the DataLineIterator

◆ getLine()

string Qore::DataLineIterator::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
DataLineIterator::getValue()

Implements Qore::AbstractLineIterator.

◆ getValue()

string Qore::DataLineIterator::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
DataLineIterator::getLine()

Implements Qore::AbstractLineIterator.

◆ index()

int Qore::DataLineIterator::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::DataLineIterator::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.

This method will return True again after it returns False once if data is not empty, otherwise it will always return False 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.

◆ reset()

Qore::DataLineIterator::reset ( )

Reset the iterator instance to its initial state.

Reset the iterator instance to its initial state

Example
i.reset();
Exceptions
ITERATOR-THREAD-ERRORthis exception is thrown if this method is called from any thread other than the thread that created the object

◆ valid()

bool Qore::DataLineIterator::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.