Fix poorly organized iterator test suite

Author: vincentlaucsb

README.md

@@ -147,6 +147,17 @@ However, `std::ifstream` may also be used as well as in-memory sources via `std:
 **Note**: Currently CSV guessing only works for memory-mapped files. The CSV dialect
 must be manually defined for other sources.
 
+**Note on Iterator Type**: `CSVReader::iterator` is an **input iterator**, not a forward iterator.
+This design enables streaming large CSV files without loading them entirely into memory.
+While some algorithms requiring forward iterators (e.g., `std::max_element`) may work in practice,
+only input iterator algorithms are guaranteed to work reliably. If you need guaranteed forward-iterator
+or random-access support, collect rows into a container first:
+```cpp
+std::vector<CSVRow> rows;
+for (auto& row : reader) rows.push_back(row);
+// Now use std::max_element or other forward-iterator algorithms reliably
+```
+
 ```cpp
 CSVFormat format;
 // custom formatting options go here

tests/test_csv_iterator.cpp

@@ -108,27 +108,32 @@ TEST_CASE("Basic CSVReader Iterator Test", "[read_ints_iter]") {
 
 //! [CSVReader Iterator 2]
 TEST_CASE("CSVReader Iterator + std::max_elem", "[iter_max_elem]") {
-    // The first is such that each value in the ith row is the number i
-    // There are 100 rows
-    // The second file is a database of California state employee salaries
-    CSVReader r1("./tests/data/fake_data/ints.csv"),
-        r2("./tests/data/real_data/2015_StateDepartment.csv");
-
-    // Find largest number
-    auto int_finder = [](CSVRow& left, CSVRow& right) {
-        return (left["A"].get<int>() < right["A"].get<int>());
-    };
+    SECTION("Find Max Element with std::max_element") {
+        // The first is such that each value in the ith row is the number i
+        // There are 100 rows
+        CSVReader r1("./tests/data/fake_data/ints.csv");
+
+        // Find largest number
+        auto int_finder = [](CSVRow& left, CSVRow& right) {
+            return (left["A"].get<int>() < right["A"].get<int>());
+        };
+
+        auto max_int = std::max_element(r1.begin(), r1.end(), int_finder);
+        REQUIRE((*max_int)["A"] == 100);
+    }
 
-    auto max_int = std::max_element(r1.begin(), r2.end(), int_finder);
+    SECTION ("Find Max Element with std::max_element - Large File") {
+        // The second file is a database of California state employee salaries
+        CSVReader r2("./tests/data/real_data/2015_StateDepartment.csv");
+        
+        // Find highest salary
+        auto wage_finder = [](CSVRow& left, CSVRow& right) {
+            return (left["Total Wages"].get<double>() < right["Total Wages"].get<double>());
+        };
 
-    // Find highest salary
-    auto wage_finder = [](CSVRow& left, CSVRow& right) {
-        return (left["Total Wages"].get<double>() < right["Total Wages"].get<double>());
-    };
+        auto max_wage = std::max_element(r2.begin(), r2.end(), wage_finder);
 
-    auto max_wage = std::max_element(r2.begin(), r2.end(), wage_finder);
-
-    REQUIRE((*max_int)["A"] == 100);
-    REQUIRE((*max_wage)["Total Wages"] == "812064.87");
+        REQUIRE((*max_wage)["Total Wages"] == "812064.87");
+    }
 }
 //! [CSVReader Iterator 2]