Qore::FileLineIterator Class Reference

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

#include <QC_FileLineIterator.dox.h>

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< StatInfo >	hstat ()
	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...
Public Member Methods 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. More...
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. More...
abstract string	getValue ()
	Returns the current line in the data or throws an INVALID-ITERATOR exception if the iterator is invalid. More...
abstract int	index ()
	Returns the current iterator line number (the first line is line 1) or 0 if not pointing at a valid element. More...
abstract bool	next ()
	Moves the current position to the next line; returns False if there are no more lines to read. More...
abstract bool	valid ()
	Returns True if the iterator is currently pointing at a valid element, False if not. More...
abstract auto	getValue ()
	returns the current value More...
abstract bool	next ()
	Moves the current position to the next element; returns False if there are no more elements. More...
abstract 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

path	the path to open for reading
encoding	character 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
eol	the 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
trim	if True the string return values for the lines iterated will be trimmed of the eol bytes
nonblocking_open	if True, then the O_NONBLOCK flag will be set in the call to open() (2)

Exceptions

ENCODING-CONVERSION-ERROR	this 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-EXPRESSION	FileLineIterator::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-EXPRESSION

FileLineIterator::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-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

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

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

this 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-ERROR

this 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.