[commons-csv] 04/04: Document that the list of header names will not contain null names.

[aherbert]

This is an automated email from the ASF dual-hosted git repository.

aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-csv.git

commit 12a2ff42d3c39cf3a33cb07bb57ede81656a02a4
Author: aherbert <aherb...@apache.org>
AuthorDate: Tue Jan 21 13:00:00 2020 +0000

    Document that the list of header names will not contain null names.
    
    Added a test to demonstrate missing null headers from the list.
---
 src/main/java/org/apache/commons/csv/CSVParser.java     | 11 +++++++++++
 src/test/java/org/apache/commons/csv/CSVParserTest.java | 14 ++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/src/main/java/org/apache/commons/csv/CSVParser.java 
b/src/main/java/org/apache/commons/csv/CSVParser.java
index 3803d96..c189dc4 100644
--- a/src/main/java/org/apache/commons/csv/CSVParser.java
+++ b/src/main/java/org/apache/commons/csv/CSVParser.java
@@ -555,6 +555,11 @@ public final class CSVParser implements 
Iterable<CSVRecord>, Closeable {
      * <p>
      * The map keys are column names. The map values are 0-based indices.
      * </p>
+     * <p>
+     * Note: The map can only provide a one-to-one mapping when the format did 
not
+     * contain null or duplicate column names.
+     * </p>
+     *
      * @return a copy of the header map.
      */
     public Map<String, Integer> getHeaderMap() {
@@ -577,8 +582,14 @@ public final class CSVParser implements 
Iterable<CSVRecord>, Closeable {
 
     /**
      * Returns a read-only list of header names that iterates in column order.
+     * <p>
+     * Note: The list provides strings that can be used as keys in the header 
map.
+     * The list will not contain null column names if they were present in the 
input
+     * format.
+     * </p>
      *
      * @return read-only list of header names that iterates in column order.
+     * @see #getHeaderMap()
      * @since 1.7
      */
     public List<String> getHeaderNames() {
diff --git a/src/test/java/org/apache/commons/csv/CSVParserTest.java 
b/src/test/java/org/apache/commons/csv/CSVParserTest.java
index 6b0dfc3..582652f 100644
--- a/src/test/java/org/apache/commons/csv/CSVParserTest.java
+++ b/src/test/java/org/apache/commons/csv/CSVParserTest.java
@@ -725,6 +725,20 @@ public class CSVParserTest {
     }
 
     @Test
+    public void testHeadersWithNullColumnName() throws IOException {
+        final Reader in = new 
StringReader("header1,null,header3\n1,2,3\n4,5,6");
+        final Iterator<CSVRecord> records = CSVFormat.DEFAULT
+            .withHeader()
+            .withNullString("null")
+            .withAllowMissingColumnNames()
+            .parse(in).iterator();
+        final CSVRecord record = records.next();
+        // Expect the null header to be missing
+        assertEquals(Arrays.asList("header1", "header3"), 
record.getParser().getHeaderNames());
+        assertEquals(2, record.getParser().getHeaderMap().size());
+    }
+
+    @Test
     public void testIgnoreCaseHeaderMapping() throws Exception {
         final Reader reader = new StringReader("1,2,3");
         final Iterator<CSVRecord> records = 
CSVFormat.DEFAULT.withHeader("One", "TWO", "three").withIgnoreHeaderCase()