Add case-insensitive column lookup

vincentlaucsb · vincentlaucsb · commit 3c5be3d98169 · 2026-04-07T20:48:48.000-07:00
diff --git a/README.md b/README.md
@@ -273,7 +273,7 @@ CSVReader sstream_reader(my_csv, format);
 ```
 
 ### Indexing by Column Names
-Retrieving values using a column name string is a cheap, constant time operation.
+Retrieving values using a column name string is a cheap, constant time operation with `EXACT` matching; with `CASE_INSENSITIVE`, the key is normalized before lookup.
 
 ```cpp
 # include "csv.hpp"
@@ -282,7 +282,12 @@ using namespace csv;
 
 ...
 
-CSVReader reader("very_big_file.csv");
+// Optional: pass in a format to customize lookup behavior
+// Defaults to EXACT matching
+CSVFormat format;
+format.column_names_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+
+CSVReader reader("very_big_file.csv", format);
 double sum = 0;
 
 for (auto& row: reader) {
diff --git a/include/csv.hpp b/include/csv.hpp
@@ -1,5 +1,5 @@
 /*
-CSV for C++, version 3.0.0
+CSV for C++, version 3.1.0
 https://github.com/vincentlaucsb/csv-parser
 
 MIT License
diff --git a/include/internal/col_names.cpp b/include/internal/col_names.cpp
@@ -1,3 +1,5 @@
+#include <algorithm>
+#include <cctype>
 #include "col_names.hpp"
 
 namespace csv {
@@ -8,20 +10,44 @@ namespace csv {
 
         CSV_INLINE void ColNames::set_col_names(const std::vector<std::string>& cnames) {
             this->col_names = cnames;
+            this->col_pos.clear();
 
             for (size_t i = 0; i < cnames.size(); i++) {
-                this->col_pos[cnames[i]] = i;
+                if (this->_policy == csv::ColumnNamePolicy::CASE_INSENSITIVE) {
+                    // For case-insensitive lookup, cache a lowercase version
+                    // of the column name in the map
+                    std::string lower(cnames[i]);
+                    std::transform(lower.begin(), lower.end(), lower.begin(),
+                        [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+                    this->col_pos[lower] = i;
+                } else {
+                    this->col_pos[cnames[i]] = i;
+                }
             }
         }
 
         CSV_INLINE int ColNames::index_of(csv::string_view col_name) const {
+            if (this->_policy == csv::ColumnNamePolicy::CASE_INSENSITIVE) {
+                std::string lower(col_name);
+                std::transform(lower.begin(), lower.end(), lower.begin(),
+                    [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+                auto pos = this->col_pos.find(lower);
+                if (pos != this->col_pos.end())
+                    return (int)pos->second;
+                return CSV_NOT_FOUND;
+            }
+
             auto pos = this->col_pos.find(col_name.data());
             if (pos != this->col_pos.end())
                 return (int)pos->second;
 
             return CSV_NOT_FOUND;
         }
 
+        CSV_INLINE void ColNames::set_policy(csv::ColumnNamePolicy policy) {
+            this->_policy = policy;
+        }
+
         CSV_INLINE size_t ColNames::size() const noexcept {
             return this->col_names.size();
         }
diff --git a/include/internal/col_names.hpp b/include/internal/col_names.hpp
@@ -6,6 +6,7 @@
 #include <vector>
 
 #include "common.hpp"
+#include "csv_format.hpp"
 
 namespace csv {
     namespace internals {
@@ -30,6 +31,11 @@ namespace csv {
             void set_col_names(const std::vector<std::string>&);
             int index_of(csv::string_view) const;
 
+            /** Sets the column name lookup policy.
+             *  Must be called before set_col_names() for CI policy to take effect.
+             */
+            void set_policy(csv::ColumnNamePolicy policy);
+
             bool empty() const noexcept { return this->col_names.empty(); }
             size_t size() const noexcept;
 
@@ -39,6 +45,7 @@ namespace csv {
         private:
             std::vector<std::string> col_names;
             std::unordered_map<std::string, size_t> col_pos;
+            csv::ColumnNamePolicy _policy = csv::ColumnNamePolicy::EXACT;
         };
     }
 }
diff --git a/include/internal/csv_format.hpp b/include/internal/csv_format.hpp
@@ -24,6 +24,12 @@ namespace csv {
         KEEP   = 1
     };
 
+    /** Determines how column name lookups are performed */
+    enum class ColumnNamePolicy {
+        EXACT = 0,            /**< Case-sensitive match (default) */
+        CASE_INSENSITIVE = 1  /**< Case-insensitive match */
+    };
+
     /** Stores the inferred format of a CSV file. */
     struct CSVGuessResult {
         char delim;
@@ -104,6 +110,17 @@ namespace csv {
             return *this;
         }
 
+        /** Sets the column name lookup policy.
+         *
+         *  @param[in] policy  Use ColumnNamePolicy::CASE_INSENSITIVE to allow
+         *                     case-insensitive column lookups via CSVRow::operator[]
+         *                     and CSVReader::index_of().
+         */
+        CONSTEXPR_14 CSVFormat& column_names_policy(ColumnNamePolicy policy) {
+            this->_column_name_policy = policy;
+            return *this;
+        }
+
         /** Sets the chunk size used when reading the CSV
          *
          *  @param[in] size Chunk size in bytes (minimum: 10MB = ITERATION_CHUNK_SIZE)
@@ -131,6 +148,7 @@ namespace csv {
         std::vector<char> get_possible_delims() const { return this->possible_delimiters; }
         std::vector<char> get_trim_chars() const { return this->trim_chars; }
         CONSTEXPR VariableColumnPolicy get_variable_column_policy() const { return this->variable_column_policy; }
+        CONSTEXPR ColumnNamePolicy get_column_name_policy() const { return this->_column_name_policy; }
         CONSTEXPR size_t get_chunk_size() const { return this->_chunk_size; }
         #endif
         
@@ -176,6 +194,9 @@ namespace csv {
         /**< Allow variable length columns? */
         VariableColumnPolicy variable_column_policy = VariableColumnPolicy::IGNORE_ROW;
 
+        /**< Column name lookup policy */
+        ColumnNamePolicy _column_name_policy = ColumnNamePolicy::EXACT;
+
         /**< Chunk size for reading; passed to CSVReader at construction time */
         size_t _chunk_size = internals::ITERATION_CHUNK_SIZE;
     };
diff --git a/include/internal/csv_reader.cpp b/include/internal/csv_reader.cpp
@@ -225,11 +225,7 @@ namespace csv {
      *         csv::CSV_NOT_FOUND otherwise.
      */
     CSV_INLINE int CSVReader::index_of(csv::string_view col_name) const {
-        auto _col_names = this->get_col_names();
-        for (size_t i = 0; i < _col_names.size(); i++)
-            if (_col_names[i] == col_name) return (int)i;
-
-        return CSV_NOT_FOUND;
+        return this->col_names->index_of(col_name);
     }
 
     CSV_INLINE void CSVReader::trim_header() {
@@ -252,6 +248,7 @@ namespace csv {
      */
     CSV_INLINE void CSVReader::set_col_names(const std::vector<std::string>& names)
     {
+        this->col_names->set_policy(this->_format.get_column_name_policy());
         this->col_names->set_col_names(names);
         this->n_cols = names.size();
     }
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
@@ -23,6 +23,7 @@ target_sources(csv_test
     PRIVATE
         ${CSV_INCLUDE_DIR}/csv.hpp
         main.cpp
+        test_col_names.cpp
         test_csv_delimiter.cpp
         test_csv_field.cpp
         test_csv_field_array.cpp
diff --git a/tests/test_col_names.cpp b/tests/test_col_names.cpp
@@ -0,0 +1,197 @@
+/** @file
+ *  Unit tests for csv::internals::ColNames
+ */
+
+#include <catch2/catch_all.hpp>
+#include "internal/col_names.hpp"
+
+using namespace csv;
+using namespace csv::internals;
+
+// ============================================================
+// Default (exact / case-sensitive) policy
+// ============================================================
+
+TEST_CASE("ColNames - empty on construction", "[col_names]") {
+    ColNames cn;
+    REQUIRE(cn.empty());
+    REQUIRE(cn.size() == 0);
+}
+
+TEST_CASE("ColNames - set and get column names", "[col_names]") {
+    ColNames cn;
+    cn.set_col_names({"A", "B", "C"});
+
+    REQUIRE(cn.size() == 3);
+    REQUIRE_FALSE(cn.empty());
+
+    auto names = cn.get_col_names();
+    REQUIRE(names.size() == 3);
+    REQUIRE(names[0] == "A");
+    REQUIRE(names[1] == "B");
+    REQUIRE(names[2] == "C");
+}
+
+TEST_CASE("ColNames - constructor with names", "[col_names]") {
+    ColNames cn({"X", "Y", "Z"});
+    REQUIRE(cn.size() == 3);
+    REQUIRE(cn.get_col_names() == std::vector<std::string>{"X", "Y", "Z"});
+}
+
+TEST_CASE("ColNames - index_of (exact policy)", "[col_names]") {
+    ColNames cn({"Name", "Age", "City"});
+
+    REQUIRE(cn.index_of("Name") == 0);
+    REQUIRE(cn.index_of("Age")  == 1);
+    REQUIRE(cn.index_of("City") == 2);
+}
+
+TEST_CASE("ColNames - index_of returns CSV_NOT_FOUND for missing column (exact)", "[col_names]") {
+    ColNames cn({"Name", "Age"});
+
+    REQUIRE(cn.index_of("missing") == CSV_NOT_FOUND);
+    REQUIRE(cn.index_of("")        == CSV_NOT_FOUND);
+}
+
+TEST_CASE("ColNames - exact policy is case-sensitive", "[col_names]") {
+    ColNames cn({"Name", "Age"});
+
+    // Different case must not match under EXACT policy
+    REQUIRE(cn.index_of("name") == CSV_NOT_FOUND);
+    REQUIRE(cn.index_of("NAME") == CSV_NOT_FOUND);
+    REQUIRE(cn.index_of("AGE")  == CSV_NOT_FOUND);
+}
+
+TEST_CASE("ColNames - operator[] by index", "[col_names]") {
+    ColNames cn({"First", "Second", "Third"});
+
+    REQUIRE(cn[0] == "First");
+    REQUIRE(cn[1] == "Second");
+    REQUIRE(cn[2] == "Third");
+}
+
+TEST_CASE("ColNames - operator[] throws on out-of-bounds", "[col_names]") {
+    ColNames cn({"A", "B"});
+    REQUIRE_THROWS_AS(cn[2], std::out_of_range);
+    REQUIRE_THROWS_AS(cn[100], std::out_of_range);
+}
+
+TEST_CASE("ColNames - operator[] throws on empty ColNames", "[col_names]") {
+    ColNames cn;
+    REQUIRE_THROWS_AS(cn[0], std::out_of_range);
+}
+
+TEST_CASE("ColNames - set_col_names replaces existing names", "[col_names]") {
+    ColNames cn({"Old1", "Old2"});
+    cn.set_col_names({"New1", "New2", "New3"});
+
+    REQUIRE(cn.size() == 3);
+    REQUIRE(cn.index_of("New1")  == 0);
+    REQUIRE(cn.index_of("Old1")  == CSV_NOT_FOUND);
+}
+
+// ============================================================
+// Case-insensitive policy
+// ============================================================
+
+TEST_CASE("ColNames - case-insensitive index_of: lowercase query", "[col_names][case_insensitive]") {
+    ColNames cn;
+    cn.set_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+    cn.set_col_names({"Name", "Age", "City"});
+
+    REQUIRE(cn.index_of("name") == 0);
+    REQUIRE(cn.index_of("age")  == 1);
+    REQUIRE(cn.index_of("city") == 2);
+}
+
+TEST_CASE("ColNames - case-insensitive index_of: uppercase query", "[col_names][case_insensitive]") {
+    ColNames cn;
+    cn.set_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+    cn.set_col_names({"Name", "Age", "City"});
+
+    REQUIRE(cn.index_of("NAME") == 0);
+    REQUIRE(cn.index_of("AGE")  == 1);
+    REQUIRE(cn.index_of("CITY") == 2);
+}
+
+TEST_CASE("ColNames - case-insensitive index_of: exact query still works", "[col_names][case_insensitive]") {
+    ColNames cn;
+    cn.set_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+    cn.set_col_names({"Name", "Age", "City"});
+
+    REQUIRE(cn.index_of("Name") == 0);
+    REQUIRE(cn.index_of("Age")  == 1);
+    REQUIRE(cn.index_of("City") == 2);
+}
+
+TEST_CASE("ColNames - case-insensitive missing column returns CSV_NOT_FOUND", "[col_names][case_insensitive]") {
+    ColNames cn;
+    cn.set_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+    cn.set_col_names({"Name", "Age"});
+
+    REQUIRE(cn.index_of("missing") == CSV_NOT_FOUND);
+    REQUIRE(cn.index_of("")        == CSV_NOT_FOUND);
+}
+
+TEST_CASE("ColNames - case-insensitive get_col_names preserves original casing", "[col_names][case_insensitive]") {
+    // The stored names should be in their original form even under CI policy.
+    // The lowercase transform is internal to the lookup map only.
+    ColNames cn;
+    cn.set_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+    cn.set_col_names({"ReportDt", "Unit", "Power"});
+
+    auto names = cn.get_col_names();
+    REQUIRE(names[0] == "ReportDt");
+    REQUIRE(names[1] == "Unit");
+    REQUIRE(names[2] == "Power");
+}
+
+TEST_CASE("ColNames - case-insensitive operator[] preserves original casing", "[col_names][case_insensitive]") {
+    ColNames cn;
+    cn.set_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+    cn.set_col_names({"ReportDt", "Unit"});
+
+    REQUIRE(cn[0] == "ReportDt");
+    REQUIRE(cn[1] == "Unit");
+}
+
+TEST_CASE("ColNames - policy must be set before set_col_names to take effect", "[col_names][case_insensitive]") {
+    // set_col_names called BEFORE set_policy: map is built with exact keys,
+    // so CI lookup will not work.
+    ColNames cn({"Name", "Age"});  // policy is EXACT at this point
+    cn.set_policy(ColumnNamePolicy::CASE_INSENSITIVE);
+
+    // The map was built with exact keys so lowercase query won't find anything.
+    REQUIRE(cn.index_of("name") == CSV_NOT_FOUND);
+
+    // After rebuilding the map, CI works.
+    cn.set_col_names(cn.get_col_names());
+    REQUIRE(cn.index_of("name") == 0);
+}
+
+// ============================================================
+// Edge cases
+// ============================================================
+
+TEST_CASE("ColNames - empty column name list", "[col_names][edge_cases]") {
+    ColNames cn;
+    cn.set_col_names({});
+
+    REQUIRE(cn.empty());
+    REQUIRE(cn.size() == 0);
+    REQUIRE(cn.index_of("anything") == CSV_NOT_FOUND);
+}
+
+TEST_CASE("ColNames - column name that is an empty string", "[col_names][edge_cases]") {
+    ColNames cn({"", "B", "C"});
+    REQUIRE(cn.index_of("") == 0);
+    REQUIRE(cn.index_of("B") == 1);
+}
+
+TEST_CASE("ColNames - duplicate column names: last index wins", "[col_names][edge_cases]") {
+    // When header has duplicate names the last occurrence wins in the hash map.
+    // This documents current behavior rather than prescribing it.
+    ColNames cn({"dup", "other", "dup"});
+    REQUIRE(cn.index_of("dup") == 2);
+    REQUIRE(cn.index_of("other") == 1);
+}

Original file line number	Diff line number	Diff line change
`@@ -225,11 +225,7 @@ namespace csv {`
`225`	`225`	`* csv::CSV_NOT_FOUND otherwise.`
`226`	`226`	`*/`
`227`	`227`	`CSV_INLINE int CSVReader::index_of(csv::string_view col_name) const {`
`228`		`- auto _col_names = this->get_col_names();`
`229`		`- for (size_t i = 0; i < _col_names.size(); i++)`
`230`		`- if (_col_names[i] == col_name) return (int)i;`
`231`		`-`
`232`		`- return CSV_NOT_FOUND;`
	`228`	`+ return this->col_names->index_of(col_name);`
`233`	`229`	`}`
`234`	`230`
`235`	`231`	`CSV_INLINE void CSVReader::trim_header() {`
`@@ -252,6 +248,7 @@ namespace csv {`
`252`	`248`	`*/`
`253`	`249`	`CSV_INLINE void CSVReader::set_col_names(const std::vector<std::string>& names)`
`254`	`250`	`{`
	`251`	`+ this->col_names->set_policy(this->_format.get_column_name_policy());`
`255`	`252`	`this->col_names->set_col_names(names);`
`256`	`253`	`this->n_cols = names.size();`
`257`	`254`	`}`