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

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 220 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 379 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

filepath	Path to a file containing CSV data.
delimiter	Character used to separate fields in the data file.

Definition at line 63 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

stream	Input stream containing csv data.
delimiter	Character used to separate fields in the data stream.

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

References NS_LOG_FUNCTION.

◆ ~CsvReader()

ns3::CsvReader::~CsvReader ( )

virtual

Destructor.

Definition at line 81 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 86 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 102 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 110 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

T	The data type of the output variable.

Parameters

[in]	columnIndex	Index of the column to fetch.
[out]	value	Location 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 400 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 147 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 155 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 196 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 204 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 212 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 188 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 163 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 220 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 230 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 263 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 271 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 279 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 255 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 141 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

c	Character to check.

Returns: true if c is the delimiter character, false otherwise.

Definition at line 287 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

begin	Iterator to the first character in the row.
end	Iterator 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 325 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] line String containing delimiter separated data.

Definition at line 295 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 94 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 384 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 383 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 381 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 385 of file csv-reader.h.

◆ m_rowsRead

std::size_t ns3::CsvReader::m_rowsRead

private

Number of lines processed.

Definition at line 382 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 390 of file csv-reader.h.

Referenced by FetchNextRow().

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

src/core/helper/csv-reader.h
src/core/helper/csv-reader.cc

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

File Format

Comments

Quoted Columns

Whitespace

Trailing Delimiter

Differences from RFC 4180

Examples

Member Typedef Documentation

◆ Columns

Constructor & Destructor Documentation

◆ CsvReader() [1/2]

◆ CsvReader() [2/2]

◆ ~CsvReader()

Member Function Documentation

◆ ColumnCount()

◆ Delimiter()

◆ FetchNextRow()

◆ GetValue()

◆ GetValueAs() [1/13]

◆ GetValueAs() [2/13]

◆ GetValueAs() [3/13]

◆ GetValueAs() [4/13]

◆ GetValueAs() [5/13]

◆ GetValueAs() [6/13]

◆ GetValueAs() [7/13]

◆ GetValueAs() [8/13]

◆ GetValueAs() [9/13]

◆ GetValueAs() [10/13]

◆ GetValueAs() [11/13]

◆ GetValueAs() [12/13]

◆ GetValueAs() [13/13]

◆ IsBlankRow()

◆ IsDelimiter()

◆ ParseColumn()

◆ ParseLine()

◆ RowNumber()

Member Data Documentation

◆ m_blankRow

◆ m_columns

◆ m_delimiter

◆ m_fileStream

◆ m_rowsRead

◆ m_stream