A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ns3::CsvReader Class Reference

Provides functions for parsing and extracting data from Comma Separated Value (CSV) formatted text files. More...

#include "csv-reader.h"

+ Collaboration diagram for ns3::CsvReader:

Public Member Functions

 CsvReader (const std::string &filepath, char delimiter=',')
 Constructor.
 
 CsvReader (std::istream &stream, char delimiter=',')
 Constructor.
 
virtual ~CsvReader ()
 Destructor.
 
std::size_t ColumnCount () const
 Returns the number of columns in the csv data.
 
char Delimiter () const
 Returns the delimiter character specified during object construction.
 
bool FetchNextRow ()
 Reads one line from the input until a new line is encountered.
 
template<class T >
bool GetValue (std::size_t columnIndex, T &value) const
 Attempt to convert from the string data in the specified column to the specified data type.
 
bool IsBlankRow () const
 Check if the current row is blank.
 
std::size_t RowNumber () const
 The number of lines that have been read.
 

Private Types

typedef std::vector< std::string > Columns
 Container of CSV data.
 

Private Member Functions

bool IsDelimiter (char c) const
 Returns true if the supplied character matches the delimiter.
 
std::tuple< std::string, std::string::const_iterator > ParseColumn (std::string::const_iterator begin, std::string::const_iterator end)
 Extracts the data for one column in a csv row.
 
void ParseLine (const std::string &line)
 Scans the string and splits it into individual columns based on the delimiter.
 
bool GetValueAs (std::string input, double &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, float &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, signed char &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, short &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, int &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, long &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, long long &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, std::string &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, unsigned char &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, unsigned short &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, unsigned int &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, unsigned long &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 
bool GetValueAs (std::string input, unsigned long long &value) const
 Attempt to convert from the string data stored at the specified column index into the specified type.
 

Private Attributes

bool m_blankRow
 Line contains no data (blank line or comment only).
 
Columns m_columns
 Fields extracted from the current line.
 
char m_delimiter
 Character used to separate fields.
 
std::ifstream m_fileStream
 File stream containing the data.
 
std::size_t m_rowsRead
 Number of lines processed.
 
std::istream * m_stream
 Pointer to the input stream containing the data.
 

Detailed Description

Provides functions for parsing and extracting data from Comma Separated Value (CSV) formatted text files.

This parser is somewhat more relaxed than RFC 4180; see below for a list of the differences. In particular it is possible to set the delimiting character at construction, enabling parsing of tab-delimited streams or other formats with delimiters.

Note
Excel may generate "CSV" files with either ',' or ';' delimiter depending on the locale: if ',' is the decimal mark then ';' is the list separator and used to read/write "CSV" files.

To use this facility, construct a CsvReader from either a file path or std::istream, then FetchNextRow(), and finally GetValue() to extract specific values from the row.

For example:

CsvReader csv (filePath);
while (csv.FetchNextRow ())
{
// Ignore blank lines
if (csv.IsBlankRow ())
{
continue;
}
// Expecting three values
double x, y, z;
bool ok = csv.GetValue (0, x);
ok |= csv.GetValue (1, y);
ok |= csv.GetValue (2, z);
if (!ok)
{
// Handle error, then
continue;
}
// Do something with values
} // while FetchNextRow
Provides functions for parsing and extracting data from Comma Separated Value (CSV) formatted text fi...
Definition: csv-reader.h:232

As another example, supposing we need a vector from each row, the middle of the previous example would become:

std::vector<double> v (n);
bool ok = true;
for (std::size_t i = 0; i < v.size (); ++i)
{
ok |= csv.GetValue (i, v[i]);
}
if (!ok) ...

File Format

This parser implements RFC 4180, but with several restrictions removed; see below for differences. All the formatting features described next are illustrated in the examples which which follow.

Comments

The hash character (#) is used to indicate the start of a comment. Comments are not parsed by the reader. Comments are treated as either an empty column or part of an existing column depending on where the comment is located. Comments that are found at the end of a line containing data are ignored.

1,2 # This comment ignored, leaving two data columns

Lines that contain a comment and no data are treated as rows with a single empty column, meaning that ColumnCount will return 1 and GetValue() will return an empty string.

# This row treated as a single empty column, returning an empty string.
"" # So is this

IsBlankRow() will return true in either of these cases.

Quoted Columns

Columns with string data which contain the delimiter character or the hash character can be wrapped in double quotes to prevent CsvReader from treating them as special characters.

3,string without delimiter,"String with comma ',' delimiter"

Double quotes can be escaped by doubling up the quotes inside a quoted field. See example 6 below for a demonstration.

Whitespace

Leading and trailing whitespace are ignored by the reader and are not stored in the column data.

4,5 , 6     # Columns contain '4', '5', '6'

If leading or trailing whitespace are important for a column, wrap the column in double quotes as discussed above.

7,"8 "," 9" # Columns contain '7', '8 ', ' 9'

Trailing Delimiter

Trailing delimiters are ignored; they do not result in an empty column.

Differences from RFC 4180

Section 2.1

  • Line break can be LF or CRLF

Section 2.3

  • Non-parsed lines are allowed anywhere, not just as a header.
  • Lines do not all have to contain the same number fields.

Section 2.4

  • Characters other than comma can be used to separate fields.
  • Lines do not all have to contain the same number fields.
  • Leading/trailing spaces are stripped from the field unless the whitespace is wrapped in double quotes.
  • A trailing delimiter on a line is not an error.

Section 2.6

  • Quoted fields cannot contain line breaks

Examples

Example 1: Basic
# Column 1: Product
# Column 2: Price
widget, 12.5
Example 2: Comment at end of line
# Column 1: Product
# Column 2: Price
broken widget, 12.5 # this widget is broken
Example 3: Delimiter in double quotes
# Column 1: Product
# Column 2: Price
# Column 3: Count
# Column 4: Date
widget, 12.5, 100, "November 6, 2018"
# Example 4: Hash character in double quotes
# Column 1: Key
# Column 2: Value
# Column 3: Description
count, 5, "# of widgets currently in stock"
Example 5: Extra whitespace
# Column 1: Key
# Column 2: Value
# Column 3: Description
count , 5 ,"# of widgets in stock"
Example 6: Escaped quotes
# Column 1: Key
# Column 2: Description
# The value returned for Column 2 will be: String with "embedded" quotes
foo, "String with ""embedded"" quotes"

Definition at line 231 of file csv-reader.h.

Member Typedef Documentation

◆ Columns

typedef std::vector<std::string> ns3::CsvReader::Columns
private

Container of CSV data.

Each entry represents one field in a row of data. The fields are stored in the same order that they are encountered in the CSV data.

Definition at line 390 of file csv-reader.h.

Constructor & Destructor Documentation

◆ CsvReader() [1/2]

ns3::CsvReader::CsvReader ( const std::string &  filepath,
char  delimiter = ',' 
)

Constructor.

Opens the file specified in the filepath argument and reads data from it.

Parameters
filepathPath to a file containing CSV data.
delimiterCharacter used to separate fields in the data file.

Definition at line 74 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ CsvReader() [2/2]

ns3::CsvReader::CsvReader ( std::istream &  stream,
char  delimiter = ',' 
)

Constructor.

Reads csv data from the supplied input stream.

Parameters
streamInput stream containing csv data.
delimiterCharacter used to separate fields in the data stream.

Definition at line 83 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ ~CsvReader()

ns3::CsvReader::~CsvReader ( )
virtual

Destructor.

Definition at line 92 of file csv-reader.cc.

Member Function Documentation

◆ ColumnCount()

std::size_t ns3::CsvReader::ColumnCount ( ) const

Returns the number of columns in the csv data.

Returns
Number of columns

Definition at line 97 of file csv-reader.cc.

References m_columns, and NS_LOG_FUNCTION.

Referenced by ns3::ListPositionAllocator::Add(), and GetValue().

+ Here is the caller graph for this function:

◆ Delimiter()

char ns3::CsvReader::Delimiter ( ) const

Returns the delimiter character specified during object construction.

Returns
Character used as the column separator.

Definition at line 113 of file csv-reader.cc.

References m_delimiter, and NS_LOG_FUNCTION.

◆ FetchNextRow()

bool ns3::CsvReader::FetchNextRow ( )

Reads one line from the input until a new line is encountered.

The read data is stored in a cache which is accessed by the GetValue functions to extract fields from the data.

Returns
true if a line was read successfully or false if the read failed or reached the end of the file.

Definition at line 121 of file csv-reader.cc.

References m_rowsRead, m_stream, NS_LOG_ERROR, NS_LOG_FUNCTION, NS_LOG_LOGIC, and ParseLine().

Referenced by ns3::ListPositionAllocator::Add().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetValue()

template<class T >
bool ns3::CsvReader::GetValue ( std::size_t  columnIndex,
T &  value 
) const

Attempt to convert from the string data in the specified column to the specified data type.

Template Parameters
TThe data type of the output variable.
Parameters
[in]columnIndexIndex of the column to fetch.
[out]valueLocation where the converted data will be stored.
Returns
true if the specified column has data and the data was converted to the specified data type.

Definition at line 411 of file csv-reader.h.

References ColumnCount(), GetValueAs(), and m_columns.

Referenced by ns3::ListPositionAllocator::Add().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ GetValueAs() [1/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
double value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 158 of file csv-reader.cc.

References NS_LOG_FUNCTION.

Referenced by GetValue().

+ Here is the caller graph for this function:

◆ GetValueAs() [2/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
float &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 166 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [3/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
int &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 207 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [4/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
long &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 215 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [5/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
long long &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 223 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [6/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
short &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 199 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [7/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
signed char &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 174 of file csv-reader.cc.

References NS_LOG_DEBUG, and NS_LOG_FUNCTION.

◆ GetValueAs() [8/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
std::string &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 231 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [9/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
unsigned char &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 241 of file csv-reader.cc.

References NS_LOG_DEBUG, and NS_LOG_FUNCTION.

◆ GetValueAs() [10/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
unsigned int &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 274 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [11/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
unsigned long &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 282 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [12/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
unsigned long long &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 290 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ GetValueAs() [13/13]

bool ns3::CsvReader::GetValueAs ( std::string  input,
unsigned short &  value 
) const
private

Attempt to convert from the string data stored at the specified column index into the specified type.

Parameters
input[in] String value to be converted.
value[out] Location where the converted value will be stored.
Returns
true if the column exists and the conversion succeeded, false otherwise.

Definition at line 266 of file csv-reader.cc.

References NS_LOG_FUNCTION.

◆ IsBlankRow()

bool ns3::CsvReader::IsBlankRow ( ) const

Check if the current row is blank.

A blank row can consist of any combination of

  • Whitespace
  • Comment
  • Quoted empty string ""
Returns
true if the input row is a blank line.

Definition at line 152 of file csv-reader.cc.

References m_blankRow.

◆ IsDelimiter()

bool ns3::CsvReader::IsDelimiter ( char  c) const
private

Returns true if the supplied character matches the delimiter.

Parameters
cCharacter to check.
Returns
true if c is the delimiter character, false otherwise.

Definition at line 298 of file csv-reader.cc.

References m_delimiter, and NS_LOG_FUNCTION.

Referenced by ParseColumn().

+ Here is the caller graph for this function:

◆ ParseColumn()

std::tuple< std::string, std::string::const_iterator > ns3::CsvReader::ParseColumn ( std::string::const_iterator  begin,
std::string::const_iterator  end 
)
private

Extracts the data for one column in a csv row.

Parameters
beginIterator to the first character in the row.
endIterator to the last character in the row.
Returns
A tuple containing the content of the column and an iterator pointing to the position in the row where the column ended.

Definition at line 336 of file csv-reader.cc.

References END, IsDelimiter(), NS_LOG_DEBUG, and NS_LOG_FUNCTION.

Referenced by ParseLine().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ ParseLine()

void ns3::CsvReader::ParseLine ( const std::string &  line)
private

Scans the string and splits it into individual columns based on the delimiter.

Parameters
[in]lineString containing delimiter separated data.

Definition at line 306 of file csv-reader.cc.

References m_blankRow, m_columns, NS_LOG_DEBUG, NS_LOG_FUNCTION, NS_LOG_LOGIC, and ParseColumn().

Referenced by FetchNextRow().

+ Here is the call graph for this function:
+ Here is the caller graph for this function:

◆ RowNumber()

std::size_t ns3::CsvReader::RowNumber ( ) const

The number of lines that have been read.

Returns
The number of lines that have been read.

Definition at line 105 of file csv-reader.cc.

References m_rowsRead, and NS_LOG_FUNCTION.

Referenced by ns3::ListPositionAllocator::Add().

+ Here is the caller graph for this function:

Member Data Documentation

◆ m_blankRow

bool ns3::CsvReader::m_blankRow
private

Line contains no data (blank line or comment only).

Definition at line 395 of file csv-reader.h.

Referenced by IsBlankRow(), and ParseLine().

◆ m_columns

Columns ns3::CsvReader::m_columns
private

Fields extracted from the current line.

Definition at line 394 of file csv-reader.h.

Referenced by ColumnCount(), GetValue(), and ParseLine().

◆ m_delimiter

char ns3::CsvReader::m_delimiter
private

Character used to separate fields.

Definition at line 392 of file csv-reader.h.

Referenced by Delimiter(), and IsDelimiter().

◆ m_fileStream

std::ifstream ns3::CsvReader::m_fileStream
private

File stream containing the data.

Definition at line 396 of file csv-reader.h.

◆ m_rowsRead

std::size_t ns3::CsvReader::m_rowsRead
private

Number of lines processed.

Definition at line 393 of file csv-reader.h.

Referenced by FetchNextRow(), and RowNumber().

◆ m_stream

std::istream* ns3::CsvReader::m_stream
private

Pointer to the input stream containing the data.

Definition at line 401 of file csv-reader.h.

Referenced by FetchNextRow().


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