Qore CsvUtil Module Reference  1.0
 All Classes Namespaces Functions Variables Groups Pages
CsvUtil::CsvFileIterator Class Reference

the CsvFileIterator class allows CSV files to be iterated More...

Inheritance diagram for CsvUtil::CsvFileIterator:

Public Member Functions

 constructor (string path, *hash opts)
 creates the CsvFileIterator with the path of the file to read and optionally an option hash
 
bool next ()
 Moves the current line / record position to the next line / record; returns False if there are no more lines to iterate.
 
any memberGate (string name)
 returns the given column value for the current row
 
any getValue ()
 returns the current record as a hash
 
hash getRecord ()
 returns the current record as a hash
 
list getRecordList ()
 returns the current record as a list
 
string getSeparator ()
 returns the current separator string
 
string getQuote ()
 returns the current quote string
 
*list getHeaders ()
 returns the current column headers or NOTHING if no headers have been detected or saved yet
 

Public Attributes

const Options
 valid options for the object (a hash for quick lookups of valid keys)
 
const Types
 supported type codes (hash for quick lookups)
 
const FieldAttrs = ("type", "format", "timezone", "code")
 supported field description attribute codes
 

Private Member Functions

list parseLine ()
 parses a line in the file and returns a processed list of the fields
 
 setFields ()
 sets field description list
 

Detailed Description

the CsvFileIterator class allows CSV files to be iterated

CsvFileIterator Constructor Option Hash Overview

The CsvFileIterator 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).

CsvFileIterator 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
"timezone" String the timezone to use when parsing dates (will be passed to Qore::TimeZone::constructor())

Option Field Types

CsvFileIterator Option Field Types

Name Description
"int" the value will be unconditionally 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
"number" the value will be unconditionally 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
"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

Option Field Hash

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

CsvFileIterator 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::CsvFileIterator::constructor ( string  path,
*hash  opts 
)

creates the CsvFileIterator with the path of the file to read and optionally an option hash

Parameters
paththe path to the CSV file to read
optsa hash of optional options; see CsvFileIterator Constructor Option Hash Overview for more information
Exceptions
CSVFILEITERATOR-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::CsvFileIterator::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::CsvFileIterator::getQuote ( )

returns the current quote string

Example:
my string $quote = $i.getQuote();
Returns
the current quote string
hash CsvUtil::CsvFileIterator::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::CsvFileIterator::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::CsvFileIterator::getSeparator ( )

returns the current separator string

Example:
my string $sep = $i.getSeparator();
Returns
the current separator string
any CsvUtil::CsvFileIterator::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
Note
the return value is any to match Qore::AbstractIterator::getValue() however this method always returns a Hash
any CsvUtil::CsvFileIterator::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
CSVFILEITERATOR-FIELD-ERRORinvalid or unknown field name given
bool CsvUtil::CsvFileIterator::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.

Example:
foreach my hash $r in (new CsvFileIterator("my_file.csv")) {
printf(" + record: %y\n", $r);
}
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 CsvFileIterator::next() is run on a file (see getHeaders())