Qore CsvUtil Module Reference 1.1

- Main Page
- Related Pages
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Private Member Functions | Private Attributes | List of all members
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 More...
*list | getHeaders ()
| returns the current column headers or NOTHING if no headers have been detected or saved yet More...
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...
any | 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...
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...

## Private Member Functions
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)

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

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

int CsvUtil::CsvFileIterator::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::CsvFileIterator::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::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())