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:
[legend]

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

  path | the path to the CSV file to read
  opts | a hash of optional options; see CsvFileIterator Constructor Option Hash Overview for more information

Exceptions

  CSVFILEITERATOR-ERROR | invalid 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-ITERATOR | this 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-ITERATOR | this 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-ITERATOR | this 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

  name | the name of the field (header name) in record

Returns
  the value of the given header for the current record

Exceptions

  INVALID-ITERATOR | this error is thrown if the iterator is invalid; make sure that the next() method returns True before calling this method
  CSVFILEITERATOR-FIELD-ERROR | invalid 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())