Kea: isc::util::CSVRow Class Reference

| Kea 3.2.0-git

isc::util::CSVRow Class Reference

Represents a single row of the CSV file. More...

`#include <csv_file.h>`

## Public Member Functions
| CSVRow (const size_t cols=0, const char separator=',')
| Constructor, creates the raw to be used for output.
| CSVRow (const std::string &text, const char separator=',')
| Constructor, parses a single row of the CSV file.
template<typename T>
void | append (const T value)
| Appends the value as a new column.
size_t | getValuesCount () const
| Returns number of values in a CSV row.
bool | operator!= (const CSVRow &other) const
| Unequality operator.
bool | operator== (const CSVRow &other) const
| Equality operator.
void | parse (const std::string &line)
| Parse the CSV file row.
template<typename T>
T | readAndConvertAt (const size_t at) const
| Retrieves a value from the internal container.
std::string | readAt (const size_t at) const
| Retrieves a value from the internal container.
std::string | readAtEscaped (const size_t at) const
| Retrieves a value from the internal container, free of escaped characters.
std::string | render () const
| Creates a text representation of the CSV file row.
void | trim (const size_t count)
| Trims a given number of elements from the end of a row.
void | writeAt (const size_t at, const char *value)
| Replaces the value at specified index.
void | writeAt (const size_t at, const std::string &value)
| Replaces the value at specified index.
template<typename T>
void | writeAt (const size_t at, const T value)
| Replaces the value at specified index.
void | writeAtEscaped (const size_t at, const std::string &value)
| Replaces the value at the specified index with a value that has had special characters escaped.

## Static Public Member Functions
static std::string | escapeCharacters (const std::string &orig_str, const std::string &characters)
| Returns a copy of a string with special characters escaped.
static std::string | unescapeCharacters (const std::string &escaped_str)
| Returns a copy of a string with special characters unescaped.

## Detailed Description

Represents a single row of the CSV file.

The object of this type can create the string holding a collection of the comma separated values, representing a row of the CSV file. It allows the selection of any character as a separator for the values. The default separator is the comma symbol.

The `CSVRow` object can be constructed in two different ways. The first option is that the caller creates an object holding empty values and then adds values one by one. Note that it is possible to either add a string or a number. The number is converted to the appropriate text representation. When all the values are added, the text representation of the row can be obtained by calling `CSVRow::render` function or output stream operator.

The `CSVRow` object can be also constructed by parsing a row of a CSV file. In this case, the separator has to be known in advance and passed to the class constructor. The constructor will call the `CSVRow::parse` function internally to tokenize the CSV row and create the collection of values. The class accessors can be then used to retrieve individual values.

This class is meant to be used by the `CSVFile` class to manipulate individual rows of the CSV file.

Definition at line 59 of file csv_file.h.

## Constructor & Destructor Documentation

## ◆ CSVRow() [1/2]

isc::util::CSVRow::CSVRow | ( | const size_t | cols = 0,
|  | const char | separator = ',' )

Constructor, creates the raw to be used for output.

Creates CSV row with empty values. The values should be later set using the `CSVRow::writeAt` functions. When the `CSVRow::render` is called, the text representation of the row will be created using a separator character specified as an argument of this constructor.

This constructor is exception-free.

Parameters

  cols | Number of values in the row.
  separator | Character used as a separator between values in the text representation of the row.

Definition at line 19 of file csv_file.cc.

Referenced by operator!=(), and operator==().

## ◆ CSVRow() [2/2]

isc::util::CSVRow::CSVRow | ( | const std::string & | text,
|  | const char | separator = ',' )

Constructor, parses a single row of the CSV file.

This constructor should be used to parse a single row of the CSV file. The separator being used for the particular row needs to be known in advance and specified as an argument of the constructor if other than the default separator is used in the row being parsed. An example string to be parsed by this function looks as follows: "foo,bar,foo-bar".

This constructor is exception-free.

Parameters

  text | Text representation of the CSV row.
  separator | Character being used as a separator in a parsed file.

Definition at line 23 of file csv_file.cc.

References parse().

Here is the call graph for this function:

## Member Function Documentation

## ◆ append()

template<typename T>

void isc::util::CSVRow::append | ( | const T | value | ) |
| inline

Appends the value as a new column.

Parameters

  value | Value to be written.

Template Parameters

  T | Type of the value being written.

Definition at line 228 of file csv_file.h.

References isc_throw.

Referenced by isc::util::VersionedCSVFile::next().

## ◆ escapeCharacters()

std::string isc::util::CSVRow::escapeCharacters | ( | const std::string & | orig_str,
|  | const std::string & | characters )
| static

Returns a copy of a string with special characters escaped.

Parameters

  orig_str | string which may contain characters that require escaping.
  characters | list of characters which require escaping.

The escaped characters will use the following format:

    /// &#x{xx}
    ///

where {xx} is the two digit hexadecimal ASCII value of the character escaped. A comma, for example is:

&#x2c

Returns
  A copy of the original string with special characters escaped.

Definition at line 449 of file csv_file.cc.

Referenced by writeAtEscaped().

## ◆ getValuesCount()

size_t isc::util::CSVRow::getValuesCount | ( |  | ) | const
| inline

Returns number of values in a CSV row.

Definition at line 93 of file csv_file.h.

Referenced by isc::util::CSVFile::append(), isc::util::VersionedCSVFile::columnCountError(), isc::util::VersionedCSVFile::next(), isc::util::CSVFile::open(), isc::util::CSVFile::validate(), isc::util::CSVFile::validateHeader(), and isc::util::VersionedCSVFile::validateHeader().

## ◆ operator!=()

bool isc::util::CSVRow::operator!= | ( | const CSVRow & | other | ) | const
| inline

Unequality operator.

Two CSV rows are unequal when their string representation is unequal. This includes the order of fields, separator etc.

Parameters

  other | Object to compare to.

Definition at line 275 of file csv_file.h.

References CSVRow(), and render().

Here is the call graph for this function:

## ◆ operator==()

bool isc::util::CSVRow::operator== | ( | const CSVRow & | other | ) | const
| inline

Equality operator.

Two CSV rows are equal when their string representation is equal. This includes the order of fields, separator etc.

Parameters

  other | Object to compare to.

Definition at line 265 of file csv_file.h.

References CSVRow(), and render().

Here is the call graph for this function:

## ◆ parse()

void isc::util::CSVRow::parse | ( | const std::string & | line | ) |

Parse the CSV file row.

This function parses a string containing CSV values and assigns them to the `values_` private container. These values can be retrieved from the container by calling `CSVRow::readAt` function.

This function is exception-free.

Parameters

  line | String holding a row of comma separated values.

Definition at line 30 of file csv_file.cc.

Referenced by CSVRow(), and isc::util::CSVFile::next().

## ◆ readAndConvertAt()

template<typename T>

T isc::util::CSVRow::readAndConvertAt | ( | const size_t | at | ) | const
| inline

Retrieves a value from the internal container.

This method is reads a value from the internal container and converts this value to the type specified as a template parameter. Internally it uses `boost::lexical_cast`.

Parameters

  at | Index of the value in the container. The values are indexed from 0, where 0 corresponds to the left-most value in the CSV file row.

Template Parameters

  T | type of the value to convert to.

Returns
  Converted value.

Exceptions

  CSVFileError | if the index is out of range or if the `boost::bad_lexical_cast` is thrown by the `boost::lexical_cast`.

Definition at line 164 of file csv_file.h.

References isc_throw, readAt(), and isc::Exception::what().

Referenced by isc::radius::RadiusAccounting::loadFromFile().

Here is the call graph for this function:

## ◆ readAt()

std::string isc::util::CSVRow::readAt | ( | const size_t | at | ) | const

Retrieves a value from the internal container.

Parameters

  at | Index of the value in the container. The values are indexed from 0, where 0 corresponds to the left-most value in the CSV file row.

Returns
  Value at specified index in the text form.

Exceptions

  CSVFileError | if the index is out of range. The number of elements being held by the container can be obtained using `CSVRow::getValuesCount`.

Definition at line 60 of file csv_file.cc.

Referenced by isc::radius::RadiusAccounting::loadFromFile(), isc::util::CSVFile::open(), readAndConvertAt(), readAtEscaped(), isc::util::CSVFile::validateHeader(), and isc::util::VersionedCSVFile::validateHeader().

## ◆ readAtEscaped()

std::string isc::util::CSVRow::readAtEscaped | ( | const size_t | at | ) | const

Retrieves a value from the internal container, free of escaped characters.

Returns a copy of the internal container value at the given index which has had all escaped characters replaced with their unescaped values. Escaped characters embedded using the following format:

This function fetches the value at the given index and passes it into CSVRow::unescapeCharacters which replaces any escaped special characters with their unescaped form.

Parameters

  at | Index of the value in the container. The values are indexed from 0, where 0 corresponds to the left-most value in the CSV file row.

Returns
  Value at specified index in the text form.

Exceptions

  CSVFileError | if the index is out of range. The number of elements being held by the container can be obtained using `CSVRow::getValuesCount`.

Definition at line 66 of file csv_file.cc.

References readAt(), and unescapeCharacters().

Here is the call graph for this function:

## ◆ render()

std::string isc::util::CSVRow::render | ( |  | ) | const

Creates a text representation of the CSV file row.

This function iterates over all values currently held in the internal `values_` container and appends them to a string. The values are separated using the separator character specified in the constructor.

This function is exception free.

Returns
  Text representation of the CSV file row.

Definition at line 71 of file csv_file.cc.

Referenced by isc::util::CSVFile::append(), operator!=(), isc::util::operator<<(), and operator==().

## ◆ trim()

void isc::util::CSVRow::trim | ( | const size_t | count | ) |

Trims a given number of elements from the end of a row.

Parameters

  count | number of elements to trim

Exceptions

  CSVFileError | if the number to trim is larger than then the number of elements

Definition at line 95 of file csv_file.cc.

Referenced by isc::util::VersionedCSVFile::next().

## ◆ unescapeCharacters()

std::string isc::util::CSVRow::unescapeCharacters | ( | const std::string & | escaped_str | ) |
| static

Returns a copy of a string with special characters unescaped.

This function reverses the escaping of characters done by `CSVRow::escapeCharacters`.

Parameters

  escaped_str | string which may contain escaped characters.

Returns
  A string free of escaped characters

Definition at line 493 of file csv_file.cc.

Referenced by readAtEscaped().

## ◆ writeAt() [1/3]

void isc::util::CSVRow::writeAt | ( | const size_t | at,
|  | const char * | value )

Replaces the value at specified index.

This function is used to set values to be rendered using `CSVRow::render` function.

Parameters

  at | Index of the value to be replaced.
  value | Value to be written given as string.

Exceptions

  CSVFileError | if index is out of range.

Definition at line 84 of file csv_file.cc.

Referenced by isc::dhcp::CSVLeaseFile4::append(), isc::dhcp::CSVLeaseFile6::append(), isc::radius::RadiusAccounting::eraseCreateTimestamp(), isc::radius::RadiusAccounting::getCreateTimestamp(), isc::util::CSVFile::recreate(), isc::radius::RadiusAccounting::storeToFile(), writeAt(), and writeAtEscaped().

## ◆ writeAt() [2/3]

void isc::util::CSVRow::writeAt | ( | const size_t | at,
|  | const std::string & | value )
| inline

Replaces the value at specified index.

This function is used to set values to be rendered using `CSVRow::render` function.

Parameters

  at | Index of the value to be replaced.
  value | Value to be written given as string.

Exceptions

  CSVFileError | if index is out of range.

Definition at line 206 of file csv_file.h.

References writeAt().

Here is the call graph for this function:

## ◆ writeAt() [3/3]

template<typename T>

void isc::util::CSVRow::writeAt | ( | const size_t | at,
|  | const T | value )
| inline

Replaces the value at specified index.

This function is used to set values to be rendered using `CSVRow::render` function.

Parameters

  at | Index of the value to be replaced.
  value | Value to be written - typically a number.

Template Parameters

  T | Type of the value being written.

Exceptions

  CSVFileError | if index is out of range.

Definition at line 248 of file csv_file.h.

References isc_throw.

## ◆ writeAtEscaped()

void isc::util::CSVRow::writeAtEscaped | ( | const size_t | at,
|  | const std::string & | value )

Replaces the value at the specified index with a value that has had special characters escaped.

This function first calls `CSVRow::escapeCharacters` to replace special characters with their escaped form. It then sets the value to be rendered using `CSVRow::render` function.

Parameters

  at | Index of the value to be replaced.
  value | Value to be written given as string.

Exceptions

  CSVFileError | if index is out of range.

Definition at line 90 of file csv_file.cc.

References escapeCharacters(), and writeAt().

Referenced by isc::dhcp::CSVLeaseFile4::append(), and isc::dhcp::CSVLeaseFile6::append().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

- csv_file.h
- csv_file.cc