Qore CsvUtil Module Reference  1.2
 All Classes Namespaces Functions Variables Groups Pages
CsvUtil::CsvAbstractIterator Class Referenceabstract

the CsvAbstractIterator class is an abstract base class that allows abstract CSV data to be iterated More...

Inheritance diagram for CsvUtil::CsvAbstractIterator:

Public Member Functions

 constructor (*hash opts)
 creates the CsvAbstractIterator with an option hash More...
 
private *string getDataName ()
 Returns the name of the input data.
 
*list getHeaders ()
 returns the current column headers or NOTHING if no headers have been detected or saved yet More...
 
abstract private string getLineValueImpl ()
 Returns the current line.
 
string getQuote ()
 returns the current quote string More...
 
hash getRecord ()
 returns the current record as a hash More...
 
list getRecordList ()
 returns the current record as a list More...
 
string getSeparator ()
 returns the current separator string More...
 
hash getValue ()
 returns the current record as a hash More...
 
int index ()
 returns the row index being iterated, which does not necessarily correspond to the line number when there are header rows and blank lines are skipped More...
 
int lineNumber ()
 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...
 
abstract private int lineNumberImpl ()
 Returns the current line number.
 
any memberGate (string name)
 returns the given column value for the current row More...
 
bool next ()
 Moves the current line / record position to the next line / record; returns False if there are no more lines to iterate. More...
 
abstract private bool nextLineImpl ()
 Moves the current line / record position to the next line / record; returns False if there are no more lines to iterate.
 
private list parseLine ()
 parses a line in the file and returns a processed list of the fields
 

Private Attributes

const Options
 valid options for the object (a hash for quick lookups of valid keys)
 

Additional Inherited Members

- Private Member Functions inherited from CsvHelper
private setFields ()
 sets field description list
 

Detailed Description

the CsvAbstractIterator class is an abstract base class that allows abstract CSV data to be iterated

CsvAbstractIterator Constructor Option Hash Overview

The CsvAbstractIterator class constructor takes an optional hash with possible keys given in the following table. Note that key names are case-sensitive, and data types are soft (conversions are made when possible).

CsvAbstractIterator Options

Option Data Type Description
"encoding" String the character encoding for the file (and for tagging string data read); if the value of this key is not a string then it will be ignored
"separator" String the string separating the fields in the file (default: ",")
"quote" String the field quote character (default: '"')
"eol" String the end of line character(s) (default: auto-detect); if the value of this key is not a string then it will be ignored
"ignore-empty" Boolean if True (the default) then empty lines will be ignored; this option is processed with parse_boolean()
"ignore-whitespace" Boolean if True (the default) then leading and trailing whitespace will be stripped from non-quoted fields; this option is processed with parse_boolean()
"header-names" Boolean if True then the object will parse the header names from the first header row, in this case "header-lines" must be > 0
"header-lines" Integer the number of headers lines in the file (must be > 0 if "header-names" is True)
"headers" List of strings list of header / column names for the data iterated; if this is present, then "header-names" must be False
"verify-columns" Boolean if True (the default is False) then if a line is parsed with a different column count than other lines, a CSVFILEITERATOR-DATA-ERROR exception is thrown
"fields" Hash the keys are column names (or numbers in case column names are not used) and the values are either strings (one of Option Field Types giving the data type for the field) or a Option Field Hash describing the field; also sets headers; if this is present, then "header-names" must be False
"timezone" String the timezone to use when parsing dates (will be passed to Qore::TimeZone::constructor())

Option Field Types

CsvAbstractIterator Option Field Types

Name Description
"int" the value will be unconditionally converted to an integer using the Qore::int() function
"*int" the value will be converted to NOTHING if empty, otherwise it will be converted to an integer using the Qore::int() function
"float" the value will be unconditionally converted to a floating-point value using the Qore::float() function
"*float" the value will be converted to NOTHING if empty, otherwise it will be converted to a floating-point value using the Qore::float() function
"number" the value will be unconditionally converted to an arbitrary-precision number value using the Qore::number() function
"*number" the value will be converted to NOTHING if empty, otherwise it will be converted to an arbitrary-precision number value using the Qore::number() function
"string" (the default) the value remains a string; no transformation is done on the input data
"*string" the value will be converted to NOTHING if empty, otherwise, it remains a string
"date" in this case dates are parsed directly with the Qore::date() function (and therefore are tagged automatically with the current time zone); to specify another date format, use the hash format documented below
"*date" the value will be converted to NOTHING if empty, otherwise dates are parsed directly with the Qore::date() function (and therefore are tagged automatically with the current time zone); to specify another date format, use the hash format documented below

Option Field Hash

See here for an example of using the hash field description in the constructor().

CsvAbstractIterator Option Field Hash

Key Value Description
"type" one of the option type values giving the field type
"format" used only with the "date" type; this is a date/time format mask for parsing dates
"timezone" used only with the "date" type; this value is passed to Qore::TimeZone::constructor() and the resulting timezone is used to parse the date (this value overrides any default time zone for the object; use only in the rare case that date/time values from different time zones are present in different columns of the same file)
"code" this is a Closures or Call References that takes a single argument of the value (after formatting with any optional "type" formats) and returns the value that will be output for the field

Member Function Documentation

CsvUtil::CsvAbstractIterator::constructor ( *hash  opts)

creates the CsvAbstractIterator with an option hash

Parameters
optsa hash of optional options; see CsvAbstractIterator Constructor Option Hash Overview for more information
Exceptions
CSVABSTRACTITERATOR-ERRORinvalid or unknown option; invalid data type for option; "header-names" is True and "header-lines" is 0 or "headers" is also present; unknown field type
*list CsvUtil::CsvAbstractIterator::getHeaders ( )

returns the current column headers or NOTHING if no headers have been detected or saved yet

Example:
Note
if headers are not saved against the object in the constructor(), then they are written to the object after the first call to next()
string CsvUtil::CsvAbstractIterator::getQuote ( )

returns the current quote string

Example:
my string $quote = $i.getQuote();
Returns
the current quote string
hash CsvUtil::CsvAbstractIterator::getRecord ( )

returns the current record as a hash

Example:
my hash $h = $i.getRecord();
Exceptions
INVALID-ITERATORthis error is thrown if the iterator is invalid; make sure that the next() method returns True before calling this method
Returns
the current record as a hash
list CsvUtil::CsvAbstractIterator::getRecordList ( )

returns the current record as a list

Example:
my list $l = $i.getRecordList();
Exceptions
INVALID-ITERATORthis error is thrown if the iterator is invalid; make sure that the next() method returns True before calling this method
Returns
the current record as a list
string CsvUtil::CsvAbstractIterator::getSeparator ( )

returns the current separator string

Example:
my string $sep = $i.getSeparator();
Returns
the current separator string
hash CsvUtil::CsvAbstractIterator::getValue ( )

returns the current record as a hash

Example:
my hash $h = $i.getValue();
Returns
the current record as a hash
Exceptions
INVALID-ITERATORthis error is thrown if the iterator is invalid; make sure that the next() method returns True before calling this method
int CsvUtil::CsvAbstractIterator::index ( )

returns the row index being iterated, which does not necessarily correspond to the line number when there are header rows and blank lines are skipped

Example:
my int $index = $i.index();
Returns
the row index being iterated, which does not necessarily correspond to the line number when there are header rows and blank lines are skipped
See Also
lineNumber()
Since
CsvUtil 1.1
int CsvUtil::CsvAbstractIterator::lineNumber ( )

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

Example:
while ($i.next()) {
printf("+ line %d: %y\n", $i.lineNumber(), $i.getValue());
}
Returns
returns the current iterator line number in the file (the first line is line 1) or 0 if not pointing at a valid element
Note
equivalent to Qore::FileLineIterator::index()
See Also
index()
Since
CsvUtil 1.1
any CsvUtil::CsvAbstractIterator::memberGate ( string  name)

returns the given column value for the current row

Parameters
namethe name of the field (header name) in record
Returns
the value of the given header for the current record
Exceptions
INVALID-ITERATORthis error is thrown if the iterator is invalid; make sure that the next() method returns True before calling this method
CSVABSTRACTITERATOR-FIELD-ERRORinvalid or unknown field name given
bool CsvUtil::CsvAbstractIterator::next ( )

Moves the current line / record position to the next line / record; returns False if there are no more lines to iterate.

This method will return True again after it returns False once if the file being iterated has data that can be iterated, otherwise it will always return False. The iterator object should not be used to retrieve a value after this method returns False.

Returns
False if there are no lines / records to iterate (in which case the iterator object is invalid and should not be used); True if successful (meaning that the iterator object is valid)
Note
that if headers are not given as an option to the constructor, then they are detected and set the first time CsvAbstractIterator::next() is run on a file (see getHeaders())