Loading...
Searching...
No Matches
Qore::FileLineIterator Class Reference

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

`#include <QC_FileLineIterator.dox.h>`

Inheritance diagram for Qore::FileLineIterator:
[legend]

## Public Member Functions

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