Updated documentation (also LeBron to the Lakers 🏀)

README.md

@@ -19,8 +19,10 @@ In additon to being easy on your computer's hardware, this library is also easy
  * Ability to manually set the delimiter and quoting character of the parser
 
 ### Well Tested
+In addition to using modern C++ features to build a memory safe parser while still performing well, this parser has a extensive test suite.
+
+## Building [(latest stable version)](https://github.com/vincentlaucsb/csv-parser/releases)
 
-## Building
 All of this library's essentials are located under `src/`, with no dependencies aside from the STL. This is a C++17 library developed using Microsoft Visual Studio and compatible with g++ and clang. The CMakeList and Makefile contain instructions for building the main library, some sample programs, and the test suite.
 
 **GCC/Clang Compiler Flags**: `-pthread -O3 -std=c++17`
@@ -40,9 +42,10 @@ target_link_libraries(<your program> csv)
 ```
 
 ## Features & Examples
-### Reading a Large File
+### Reading a Large File (with Iterators)
 With this library, you can easily stream over a large file without reading its entirety into memory.
 
+**C++ Style**
 ```cpp
 # include "csv_parser.hpp"
 
@@ -51,18 +54,44 @@ using namespace csv;
 ...
 
 CSVReader reader("very_big_file.csv");
-std::vector<std::string> row;
+double sum = 0;
+
+for (CSVRow& row: reader) { // Input iterator
+    for (CSVField& field: row) {
+        // For efficiency, get<>() produces a string_view
+        std::cout << field.get<>() << ...
+    }
+
+    /* Sum up wages
+     * Notes:
+     *  - Indexing can be done by position (size_t) or column name
+     *  - Invalid positions/column names will throw runtime errors
+     */
+    sum += field["Total Salary"].get<double>();
+}
 
+...
+```
+
+**Old-Fashioned C Style Loop**
+```cpp
+...
+
+CSVReader reader("very_big_file.csv");
+CSVRow row;
+ 
 while (reader.read_row(row)) {
     // Do stuff with row here
 }
 
+...
 ```
 
-### Indexing Rows by Column Name and Type Conversions
-If your CSV has lots of numeric values, you can also have this parser automatically convert them to the proper data type.
-For efficiency, numeric values are lazily converted, and the indexing feature is implemented by having all rows
-share a pointer to the original set of column names.
+
+### Type Conversions
+If your CSV has lots of numeric values, you can also have this parser (lazily)
+convert them to the proper data type. Type checking is performed on conversions
+to prevent undefined behavior.
 
 ```cpp
 # include "csv_parser.hpp"
@@ -72,15 +101,12 @@ using namespace csv;
 ...
 
 CSVReader reader("very_big_file.csv");
-std::vector<CSVField> row;
 
-while (reader.read_row(row)) {
-    if (row["timestamp"].is_int())
+for (auto& row: reader) {
+    if (row["timestamp"].is_int()) {
         row["timestamp"].get<int>();
-    
-    // get<>() returns a std::string_view of the original field
-    for (size_t i = 0; i < row.size(); i++) {
-        std::cout << row[i].get<>() << ...
+
+        // ..
     }
 }
 
@@ -103,9 +129,8 @@ CSVFormat format = {
 };
 
 CSVReader reader("wierd_csv_dialect.csv", {}, format);
-vector<CSVField> row;
 
-while (reader.read_row(row)) {
+for (auto& row: reader) {
     // Do stuff with rows here
 }
 

docs/annotated.html

@@ -92,8 +92,10 @@
 <tr id="row_0_1_" class="even"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVField.html" target="_self">CSVField</a></td><td class="desc">Data type representing individual CSV values. CSVFields can be obtained by using <a class="el" href="classcsv_1_1CSVRow.html#ad523d2b544bc7dab0a121891e5062d2c" title="Return a CSVField object corrsponding to the nth value in the row. ">CSVRow::operator[]</a> </td></tr>
 <tr id="row_0_2_"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structcsv_1_1CSVFileInfo.html" target="_self">CSVFileInfo</a></td><td class="desc"></td></tr>
 <tr id="row_0_3_" class="even"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="structcsv_1_1CSVFormat.html" target="_self">CSVFormat</a></td><td class="desc">Stores information about how to parse a CSV file </td></tr>
-<tr id="row_0_4_"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVReader.html" target="_self">CSVReader</a></td><td class="desc">Main class for parsing CSVs from files and in-memory sources </td></tr>
-<tr id="row_0_5_" class="even"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVRow.html" target="_self">CSVRow</a></td><td class="desc">Data structure for representing CSV rows </td></tr>
+<tr id="row_0_4_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_0_4_" class="arrow" onclick="toggleFolder('0_4_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVReader.html" target="_self">CSVReader</a></td><td class="desc">Main class for parsing CSVs from files and in-memory sources </td></tr>
+<tr id="row_0_4_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVReader_1_1iterator.html" target="_self">iterator</a></td><td class="desc">An input iterator capable of handling large files. Created by <a class="el" href="classcsv_1_1CSVReader.html#ac2b664c3ba18ac36076c1a1891bd1cf2" title="Return an iterator to the first row in the reader. ">CSVReader::begin()</a> and <a class="el" href="classcsv_1_1CSVReader.html#a13a1161c1512e23a6be6f8b7f0ead6eb" title="A placeholder for the imaginary past the end row in a CSV. Attempting to deference this will lead to ...">CSVReader::end()</a> </td></tr>
+<tr id="row_0_5_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_0_5_" class="arrow" onclick="toggleFolder('0_5_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVRow.html" target="_self">CSVRow</a></td><td class="desc">Data structure for representing CSV rows </td></tr>
+<tr id="row_0_5_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVRow_1_1iterator.html" target="_self">iterator</a></td><td class="desc">A random access iterator over the contents of a CSV row. Each iterator points to a <a class="el" href="classcsv_1_1CSVField.html" title="Data type representing individual CSV values. CSVFields can be obtained by using CSVRow::operator[]. ">CSVField</a> </td></tr>
 <tr id="row_0_6_"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1CSVStat.html" target="_self">CSVStat</a></td><td class="desc">Class for calculating statistics from CSV files and in-memory sources </td></tr>
 <tr id="row_0_7_" class="even"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="classcsv_1_1DelimWriter.html" target="_self">DelimWriter</a></td><td class="desc">Class for writing delimiter separated values files </td></tr>
 </table>

docs/classcsv_1_1CSVField-members.html

@@ -94,10 +94,9 @@
   <tr bgcolor="#f0f0f0"><td class="entry"><b>is_null</b>() (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"><span class="mlabel">inline</span></td></tr>
   <tr bgcolor="#f0f0f0" class="even"><td class="entry"><b>is_num</b>() (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"><span class="mlabel">inline</span></td></tr>
   <tr bgcolor="#f0f0f0"><td class="entry"><b>is_str</b>() (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"><span class="mlabel">inline</span></td></tr>
-  <tr bgcolor="#f0f0f0" class="even"><td class="entry"><b>operator==</b>(const std::string &amp;) const (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"></td></tr>
-  <tr bgcolor="#f0f0f0"><td class="entry"><b>sv</b> (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"></td></tr>
+  <tr bgcolor="#f0f0f0" class="even"><td class="entry"><b>operator==</b>(std::string_view other) const (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"></td></tr>
+  <tr bgcolor="#f0f0f0"><td class="entry"><b>operator==</b>(const long double &amp;other) (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"></td></tr>
   <tr class="even"><td class="entry"><a class="el" href="classcsv_1_1CSVField.html#aee31987c4c62c8ef7a89b475bd089618">type</a>()</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"></td></tr>
-  <tr bgcolor="#f0f0f0"><td class="entry"><b>value</b> (defined in <a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a>)</td><td class="entry"><a class="el" href="classcsv_1_1CSVField.html">csv::CSVField</a></td><td class="entry"></td></tr>
 </table></div><!-- contents -->
 </div><!-- doc-content -->
 <!-- start footer part -->

docs/classcsv_1_1CSVField.html

@@ -81,7 +81,6 @@
 <div class="header">
   <div class="summary">
 <a href="#pub-methods">Public Member Functions</a> &#124;
-<a href="#pub-attribs">Public Attributes</a> &#124;
 <a href="classcsv_1_1CSVField-members.html">List of all members</a>  </div>
   <div class="headertitle">
 <div class="title">csv::CSVField Class Reference</div>  </div>
@@ -98,12 +97,15 @@
 <tr class="memitem:af2522aba384653dd198540ad668a9ab0"><td class="memItemLeft" align="right" valign="top"><a id="af2522aba384653dd198540ad668a9ab0"></a>
 &#160;</td><td class="memItemRight" valign="bottom"><b>CSVField</b> (std::string_view _sv)</td></tr>
 <tr class="separator:af2522aba384653dd198540ad668a9ab0"><td class="memSeparator" colspan="2">&#160;</td></tr>
-<tr class="memitem:ad0efc38057c54ae4a67742972235a88a"><td class="memItemLeft" align="right" valign="top"><a id="ad0efc38057c54ae4a67742972235a88a"></a>
-bool&#160;</td><td class="memItemRight" valign="bottom"><b>operator==</b> (const std::string &amp;) const</td></tr>
-<tr class="separator:ad0efc38057c54ae4a67742972235a88a"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a67ff24172c5ac52417bbc36697511644"><td class="memTemplParams" colspan="2">template&lt;typename T  = std::string_view&gt; </td></tr>
 <tr class="memitem:a67ff24172c5ac52417bbc36697511644"><td class="memTemplItemLeft" align="right" valign="top">T&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classcsv_1_1CSVField.html#a67ff24172c5ac52417bbc36697511644">get</a> ()</td></tr>
 <tr class="separator:a67ff24172c5ac52417bbc36697511644"><td class="memSeparator" colspan="2">&#160;</td></tr>
+<tr class="memitem:a18cf4ba59439652c4d283248e2464c29"><td class="memItemLeft" align="right" valign="top"><a id="a18cf4ba59439652c4d283248e2464c29"></a>
+bool&#160;</td><td class="memItemRight" valign="bottom"><b>operator==</b> (std::string_view other) const</td></tr>
+<tr class="separator:a18cf4ba59439652c4d283248e2464c29"><td class="memSeparator" colspan="2">&#160;</td></tr>
+<tr class="memitem:a02c2efa7c701c534e97220e5405ef9d6"><td class="memItemLeft" align="right" valign="top"><a id="a02c2efa7c701c534e97220e5405ef9d6"></a>
+bool&#160;</td><td class="memItemRight" valign="bottom"><b>operator==</b> (const long double &amp;other)</td></tr>
+<tr class="separator:a02c2efa7c701c534e97220e5405ef9d6"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:aee31987c4c62c8ef7a89b475bd089618"><td class="memItemLeft" align="right" valign="top"><a class="el" href="namespacecsv.html#a1a3911f2387412df696be542923ef62d">DataType</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classcsv_1_1CSVField.html#aee31987c4c62c8ef7a89b475bd089618">type</a> ()</td></tr>
 <tr class="memdesc:aee31987c4c62c8ef7a89b475bd089618"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return the type number of the stored value in accordance with the DataType enum.  <a href="#aee31987c4c62c8ef7a89b475bd089618">More...</a><br /></td></tr>
 <tr class="separator:aee31987c4c62c8ef7a89b475bd089618"><td class="memSeparator" colspan="2">&#160;</td></tr>
@@ -126,20 +128,11 @@
 template&lt;&gt; </td></tr>
 <tr class="memitem:a2f8e1cc269190283c8a668f5273df99d"><td class="memTemplItemLeft" align="right" valign="top">long double&#160;</td><td class="memTemplItemRight" valign="bottom"><b>get</b> ()</td></tr>
 <tr class="separator:a2f8e1cc269190283c8a668f5273df99d"><td class="memSeparator" colspan="2">&#160;</td></tr>
-</table><table class="memberdecls">
-<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-attribs"></a>
-Public Attributes</h2></td></tr>
-<tr class="memitem:a040a17d1ec3bdea212797539181b179a"><td class="memItemLeft" align="right" valign="top"><a id="a040a17d1ec3bdea212797539181b179a"></a>
-long double&#160;</td><td class="memItemRight" valign="bottom"><b>value</b> = 0</td></tr>
-<tr class="separator:a040a17d1ec3bdea212797539181b179a"><td class="memSeparator" colspan="2">&#160;</td></tr>
-<tr class="memitem:aea55bc32d073faf378173e8cdd961210"><td class="memItemLeft" align="right" valign="top"><a id="aea55bc32d073faf378173e8cdd961210"></a>
-std::string_view&#160;</td><td class="memItemRight" valign="bottom"><b>sv</b></td></tr>
-<tr class="separator:aea55bc32d073faf378173e8cdd961210"><td class="memSeparator" colspan="2">&#160;</td></tr>
 </table>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 <div class="textblock"><p>Data type representing individual CSV values. CSVFields can be obtained by using <a class="el" href="classcsv_1_1CSVRow.html#ad523d2b544bc7dab0a121891e5062d2c" title="Return a CSVField object corrsponding to the nth value in the row. ">CSVRow::operator[]</a>. </p>
 
-<p class="definition">Definition at line <a class="el" href="csv__row_8hpp_source.html#l00037">37</a> of file <a class="el" href="csv__row_8hpp_source.html">csv_row.hpp</a>.</p>
+<p class="definition">Definition at line <a class="el" href="csv__row_8hpp_source.html#l00038">38</a> of file <a class="el" href="csv__row_8hpp_source.html">csv_row.hpp</a>.</p>
 </div><h2 class="groupheader">Member Function Documentation</h2>
 <a id="a67ff24172c5ac52417bbc36697511644"></a>
 <h2 class="memtitle"><span class="permalink"><a href="#a67ff24172c5ac52417bbc36697511644">&#9670;&nbsp;</a></span>get()</h2>
@@ -174,9 +167,8 @@ <h2 class="memtitle"><span class="permalink"><a href="#a67ff24172c5ac52417bbc366
 <li>double</li>
 <li>long double </li>
 </ul>
-<p>Get numeric values </p>
 
-<p class="definition">Definition at line <a class="el" href="csv__row_8hpp_source.html#l00057">57</a> of file <a class="el" href="csv__row_8hpp_source.html">csv_row.hpp</a>.</p>
+<p class="definition">Definition at line <a class="el" href="csv__row_8hpp_source.html#l00055">55</a> of file <a class="el" href="csv__row_8hpp_source.html">csv_row.hpp</a>.</p>
 
 </div>
 </div>
@@ -198,7 +190,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#aee31987c4c62c8ef7a89b475
 <p>Return the type number of the stored value in accordance with the DataType enum. </p>
 <p>&lt; </p>
 
-<p class="definition">Definition at line <a class="el" href="csv__row_8cpp_source.html#l00110">110</a> of file <a class="el" href="csv__row_8cpp_source.html">csv_row.cpp</a>.</p>
+<p class="definition">Definition at line <a class="el" href="csv__row_8cpp_source.html#l00107">107</a> of file <a class="el" href="csv__row_8cpp_source.html">csv_row.cpp</a>.</p>
 
 </div>
 </div>

docs/classcsv_1_1CSVField.js

@@ -8,8 +8,7 @@ var classcsv_1_1CSVField =
     [ "is_null", "classcsv_1_1CSVField.html#a855f05d296b992f5d6bb0bbfb94bf792", null ],
     [ "is_num", "classcsv_1_1CSVField.html#aa0a899b3c0b597512506183edfb4ad62", null ],
     [ "is_str", "classcsv_1_1CSVField.html#aa515c7eba5f76bd73e6f448d1069c6af", null ],
-    [ "operator==", "classcsv_1_1CSVField.html#ad0efc38057c54ae4a67742972235a88a", null ],
-    [ "type", "classcsv_1_1CSVField.html#aee31987c4c62c8ef7a89b475bd089618", null ],
-    [ "sv", "classcsv_1_1CSVField.html#aea55bc32d073faf378173e8cdd961210", null ],
-    [ "value", "classcsv_1_1CSVField.html#a040a17d1ec3bdea212797539181b179a", null ]
+    [ "operator==", "classcsv_1_1CSVField.html#a18cf4ba59439652c4d283248e2464c29", null ],
+    [ "operator==", "classcsv_1_1CSVField.html#a02c2efa7c701c534e97220e5405ef9d6", null ],
+    [ "type", "classcsv_1_1CSVField.html#aee31987c4c62c8ef7a89b475bd089618", null ]
 ];