Kea  2.3.5-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. More...
 
 CSVRow (const std::string &text, const char separator=',')
 Constructor, parses a single row of the CSV file. More...
 
template<typename T >
void append (const T value)
 Appends the value as a new column. More...
 
size_t getValuesCount () const
 Returns number of values in a CSV row. More...
 
bool operator!= (const CSVRow &other) const
 Unequality operator. More...
 
bool operator== (const CSVRow &other) const
 Equality operator. More...
 
void parse (const std::string &line)
 Parse the CSV file row. More...
 
template<typename T >
readAndConvertAt (const size_t at) const
 Retrieves a value from the internal container. More...
 
std::string readAt (const size_t at) const
 Retrieves a value from the internal container. More...
 
std::string readAtEscaped (const size_t at) const
 Retrieves a value from the internal container, free of escaped characters. More...
 
std::string render () const
 Creates a text representation of the CSV file row. More...
 
void trim (const size_t count)
 Trims a given number of elements from the end of a row. More...
 
void writeAt (const size_t at, const char *value)
 Replaces the value at specified index. More...
 
void writeAt (const size_t at, const std::string &value)
 Replaces the value at specified index. More...
 
template<typename T >
void writeAt (const size_t at, const T value)
 Replaces the value at specified index. More...
 
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. More...
 

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. More...
 
static std::string unescapeCharacters (const std::string &escaped_str)
 Returns a copy of a string with special characters unescaped. More...
 

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 51 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
colsNumber of values in the row.
separatorCharacter used as a separator between values in the text representation of the row.

Definition at line 19 of file csv_file.cc.

◆ 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
textText representation of the CSV row.
separatorCharacter 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
valueValue to be written.
Template Parameters
TType of the value being written.

Definition at line 220 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_strstring which may contain characters that require escaping.
characterslist 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

@return A copy of the original string with special characters escaped.  

Definition at line 435 of file csv_file.cc.

Referenced by writeAtEscaped().

◆ getValuesCount()

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

◆ 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
otherObject to compare to.

Definition at line 267 of file csv_file.h.

References isc::util::operator<<(), 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
otherObject to compare to.

Definition at line 257 of file csv_file.h.

References 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
lineString 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
atIndex 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
Ttype of the value to convert to.
Returns
Converted value.
Exceptions
CSVFileErrorif the index is out of range or if the boost::bad_lexical_cast is thrown by the boost::lexical_cast.

Definition at line 156 of file csv_file.h.

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

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

+ 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
atIndex 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
CSVFileErrorif 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::dhcp::CSVLeaseFile6::next(), isc::dhcp::CSVLeaseFile4::next(), isc::util::CSVFile::open(), readAtEscaped(), isc::util::VersionedCSVFile::validateHeader(), and isc::util::CSVFile::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
atIndex 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
CSVFileErrorif 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().

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

+ 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
countnumber of elements to trim
Exceptions
CSVFileErrorif 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_strstring which may contain escaped characters.
Returns
A string free of escaped characters

Definition at line 479 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
atIndex of the value to be replaced.
valueValue to be written given as string.
Exceptions
CSVFileErrorif index is out of range.

Definition at line 84 of file csv_file.cc.

Referenced by isc::dhcp::CSVLeaseFile4::append(), isc::util::CSVFile::recreate(), 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
atIndex of the value to be replaced.
valueValue to be written given as string.
Exceptions
CSVFileErrorif index is out of range.

Definition at line 198 of file csv_file.h.

◆ 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
atIndex of the value to be replaced.
valueValue to be written - typically a number.
Template Parameters
TType of the value being written.
Exceptions
CSVFileErrorif index is out of range.

Definition at line 240 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
atIndex of the value to be replaced.
valueValue to be written given as string.
Exceptions
CSVFileErrorif index is out of range.

Definition at line 90 of file csv_file.cc.

References escapeCharacters(), and writeAt().

Referenced by isc::dhcp::CSVLeaseFile4::append().

+ Here is the call graph for this function:

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