Qore Programming Language Reference Manual  0.9.4.5
Qore::FileLineIterator Class Reference

This class defines a line iterator for text files. More...

Inheritance diagram for Qore::FileLineIterator:

Public Member Methods

 constructor (string path, *string encoding, *string eol, bool trim=True, *bool nonblocking_open)
 Opens the given file for reading with the given options and creates the FileLineIterator object. More...
 
 copy ()
 Creates a new FileLineIterator object, based on the same object being iterated in the original object (the original file is reopened) More...
 
string getEncoding ()
 Returns the character encoding for the FileLineIterator. More...
 
string getFileName ()
 Returns the file path/name used to open the file. More...
 
string getLine ()
 Returns the current line in the file or throws an ITERATOR-ERROR exception if the iterator is invalid. More...
 
string getValue ()
 Returns the current line in the file or throws an ITERATOR-ERROR exception if the iterator is invalid. More...
 
hash< StatInfohstat ()
 Returns StatInfo hash of hstat() of the underlying file. More...
 
int index ()
 Returns the current iterator line number in the file (the first line is line 1) or 0 if not pointing at a valid element. More...
 
bool isTty ()
 Returns True if the FileLineIterator is connected to a terminal device, False if not. More...
 
bool next ()
 Moves the current position to the next line in the file; 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 file. More...
 
 reset ()
 Reset the iterator instance to its initial state. More...
 
list< auto > stat ()
 Returns Stat List of stat() of the underlying file. 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 text files.

Since
Qore 0.8.6
Restrictions:
Qore::PO_NO_FILESYSTEM
Example: FileLineIterator basic usage
file content:
a2ps-4.13-1332.1.x86_64
a2ps-devel-4.13-1332.1.x86_64
aaa_base-11.3-7.2.x86_64
...
FileLineIterator it("/export/home/pvanek/ren.list");
while (it.next()) {
printf("%s:%d = %n\n", it.getFileName(), it.index(), it.getValue());
}
/export/home/pvanek/ren.list:1 = "a2ps-4.13-1332.1.x86_64"
/export/home/pvanek/ren.list:2 = "a2ps-devel-4.13-1332.1.x86_64"
/export/home/pvanek/ren.list:3 = "aaa_base-11.3-7.2.x86_64"
...
/export/home/pvanek/ren.list:2155 = "zypper-1.4.5-1.10.x86_64"
See also
Qore::InputStreamLineIterator
Qore::DataLineIterator

Member Function Documentation

◆ constructor()

Qore::FileLineIterator::constructor ( string  path,
*string  encoding,
*string  eol,
bool  trim = True,
*bool  nonblocking_open 
)

Opens the given file for reading with the given options and creates the FileLineIterator object.

Parameters
paththe path to open for reading
encodingcharacter encoding of the data in the file; 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 file; 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" (the last one is only automatically detected when not connected to a terminal device in order to keep the I/O from stalling); 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 FileLineIterator's character encoding
trimif True the string return values for the lines iterated will be trimmed of the eol bytes
nonblocking_openif True, then the O_NONBLOCK flag will be set in the call to open() (2)
Exceptions
ENCODING-CONVERSION-ERRORthis exception could be thrown if the eol argument has a different character encoding from the File's and an error occurs during encoding conversion
ILLEGAL-EXPRESSIONFileLineIterator::constructor() cannot be called with a TTY target when %no-terminal-io is set
Since
Qore 0.9.3 added the nonblocking_open flag

◆ copy()

Qore::FileLineIterator::copy ( )

Creates a new FileLineIterator object, based on the same object being iterated in the original object (the original file is reopened)

Example:
FileLineIterator ni = i.copy();
Exceptions
ILLEGAL-EXPRESSIONFileLineIterator::constructor() cannot be called with a TTY target when %no-terminal-io is set

◆ getEncoding()

string Qore::FileLineIterator::getEncoding ( )

Returns the character encoding for the FileLineIterator.

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

◆ getFileName()

string Qore::FileLineIterator::getFileName ( )

Returns the file path/name used to open the file.

Code Flags:
CONSTANT
Example:
string fn = f.getFileName();
Returns
the file path/name used to open the file

◆ getLine()

string Qore::FileLineIterator::getLine ( )
virtual

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

Returns
the current line in the file 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
FileLineIterator::getValue()

Implements Qore::AbstractLineIterator.

◆ getValue()

string Qore::FileLineIterator::getValue ( )
virtual

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

Returns
the current line in the file 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
FileLineIterator::getLine()

Implements Qore::AbstractLineIterator.

◆ hstat()

hash<StatInfo> Qore::FileLineIterator::hstat ( )

Returns StatInfo hash of hstat() of the underlying file.

If any errors occur, a FILE-HSTAT-ERROR exception is thrown

Code Flags:
CONSTANT
Example:
hash<StatInfo> h = f.hstat();
Returns
StatInfo hash of hstat() of the underlying file
Since
Qore 0.8.12

◆ index()

int Qore::FileLineIterator::index ( )
virtual

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

Returns
the current iterator line number in the file (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.

◆ isTty()

bool Qore::FileLineIterator::isTty ( )

Returns True if the FileLineIterator is connected to a terminal device, False if not.

Returns
True if the FileLineIterator is connected to a terminal device, False if not
Code Flags:
CONSTANT
Example:
bool b = i.isTty();

◆ next()

bool Qore::FileLineIterator::next ( )
virtual

Moves the current position to the next line in the file; 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 file.

This method will return True again after it returns False once if file 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 file (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::FileLineIterator::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

◆ stat()

list<auto> Qore::FileLineIterator::stat ( )

Returns Stat List of stat() of the underlying file.

If any errors occur, a FILE-HSTAT-ERROR exception is thrown

Code Flags:
CONSTANT
Example:
list<auto> l = f.stat();
Returns
Stat List of stat() of the underlying file
Since
Qore 0.8.12

◆ valid()

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