rapidcsv

Rapidcsv

Rapidcsv is an easy-to-use C++ CSV parser library. It supports C++11 (and later), is header-only and comes with a basic test suite.

The library was featured in the book C++20 for Programmers.

Example Usage

Here is a simple example reading a CSV file and getting 'Close' column as a vector of floats.

colhdr.csv content:

Open,High,Low,Close,Volume,Adj Close
64.529999,64.800003,64.139999,64.620003,21705200,64.620003
64.419998,64.730003,64.190002,64.620003,20235200,64.620003
64.330002,64.389999,64.050003,64.360001,19259700,64.360001
64.610001,64.949997,64.449997,64.489998,19384900,64.489998
64.470001,64.690002,64.300003,64.620003,21234600,64.620003

ex001.cpp content:

…

cpp rapidcsv::Document doc("file.csv", rapidcsv::LabelParams(), rapidcsv::SeparatorParams(), rapidcsv::ConverterParams(true));

Check if a Column Exists
------------------------
Rapidcsv provides the methods GetColumnNames() and GetRowNames() to retrieve
the column and row names. To check whether a particular column name exists
one can for example do:

```cpp
rapidcsv::Document doc("file.csv");
std::vector columnNames = doc.GetColumnNames();
bool columnExists =
  (std::find(columnNames.begin(), columnNames.end(), "A") != columnNames.end());

Handling Quoted Cells

By default rapidcsv automatically dequotes quoted cells (i.e. removes the encapsulating " characters from "example quoted cell"). This functionality may be disabled by passing pAutoQuote = false in SeparatorParams, example:

rapidcsv::Document doc("file.csv", rapidcsv::LabelParams(),
                       rapidcsv::SeparatorParams(',' /* pSeparator */,
                                                 false /* pTrim */,
                                                 rapidcsv::sPlatformHasCR /* pHasCR */,
                                                 false /* pQuotedLinebreaks */,
                                                 false /* pAutoQuote */));

Skipping Empty and Comment Lines

Rapidcsv reads all lines by default, but may be called to ignore comment lines starting with a specific character, example:

rapidcsv::Document doc("file.csv", rapidcsv::LabelParams(), rapidcsv::SeparatorParams(),
                       rapidcsv::ConverterParams(),
                       rapidcsv::LineReaderParams(true /* pSkipCommentLines */,
                                                  '#' /* pCommentPrefix */));

Using LineReaderParams it is also possible to skip empty lines, example:

rapidcsv::Document doc("file.csv", rapidcsv::LabelParams(), rapidcsv::SeparatorParams(),
                       rapidcsv::ConverterParams(),
                       rapidcsv::LineReaderParams(false /* pSkipCommentLines */,
                                                  '#' /* pCommentPrefix */,
                                                  true /* pSkipEmptyLines */));

UTF-16 and UTF-8

Rapidcsv's preferred encoding for non-ASCII text is UTF-8. UTF-16 LE and UTF-16 BE can also be read and written, using the byte order mark of a loaded file to automatically detect its encoding. Documents loaded as UTF-16 are converted to UTF-8 internally, and converted back to their original UTF-16 encoding when saved.

Limiting Maximum Document Size

Rapidcsv does not limit the amount of data read by default. As each parsed cell has some memory overhead, malformed input may expand to much more memory than the size of the input data. Applications reading untrusted input may define RAPIDCSV_MAX_COUNT before including rapidcsv.h, in order to set an upper limit for the number of rows or columns read and throw exception std::out_of_range when exceeded.

CMake

Rapidcsv may be included in a CMake project using various methods:

• Add Subdirectory: Example Project / CMakeLists.txt
• Fetch Content: Example Project / CMakeLists.txt
• Find Package: Example Project / CMakeLists.txt

Locale Independent Parsing

Rapidcsv uses locale-dependent conversion functions when parsing float values by default. It is possible to configure rapidcsv to use locale independent parsing by setting mNumericLocale in ConverterParams, see for example tests/test087.cpp

API Documentation

The following classes makes up the Rapidcsv interface:

• class rapidcsv::Document
• class rapidcsv::LabelParams
• class rapidcsv::SeparatorParams
• class rapidcsv::ConverterParams
• class rapidcsv::LineReaderParams
• class rapidcsv::no_converter
• class rapidcsv::Converter

Technical Details

Rapidcsv uses cmake for its tests. Commands to build and execute the test suite:

mkdir -p build && cd build && cmake -DRAPIDCSV_BUILD_TESTS=ON .. && make && ctest -C unit --output-on-failure && ctest -C perf --verbose ; cd -

Rapidcsv uses doxygenmd to generate its Markdown API documentation:

doxygenmd src doc

Rapidcsv uses Uncrustify to ensure consistent code formatting:

uncrustify -c uncrustify.cfg --no-backup src/rapidcsv.h

Alternatives

There are many CSV parsers for C++, for example:

• Fast C++ CSV Parser
• Vince's CSV Parser

License

Rapidcsv is distributed under the BSD 3-Clause license. See LICENSE file.

Contributions

Bugs, PRs, etc are welcome on the GitHub project page https://github.com/d99kris/rapidcsv

Keywords

c++, c++11, csv parser, comma separated values, single header library.