Add facetCount

Author: osvik

README.md

@@ -369,6 +369,20 @@ counts, wasRead := x.ValueCounts("Country")
 
 The original csv is not modified. `wasRead` is false if the csv is empty or the field name does not exist; in that case a copy of the csv is returned.
 
+`FacetCount` returns a map that counts how many times each string appears in a column (data cells only, the header cell is never counted). Case does not matter by default: `Foo`, `foo` and `FOO` are counted together under the lower-case key `foo`:
+
+```go
+counts, wasRead := x.FacetCount("Country")
+```
+
+`wasRead` is false if the csv is empty, the field name is empty, or the field name does not exist; in that case an empty map is returned. A csv with only the header row returns an empty map and true.
+
+`FacetCountCaseSensitive` is the same but case matters: `Foo`, `foo` and `FOO` are counted as separate entries:
+
+```go
+counts, wasRead = x.FacetCountCaseSensitive("Country")
+```
+
 ### Group by
 
 `GroupBy` collapses the data rows into one output row per group, where a group is all the data rows whose key fields have the same values. The output header row is the key field names followed by the `As` name of each aggregation; each output data row is the key values followed by one cell per aggregation. Groups appear in order of first occurrence:

distinct.go

@@ -1,6 +1,9 @@
 package simplecsv
 
-import "strconv"
+import (
+	"strconv"
+	"strings"
+)
 
 // Distinct returns the distinct values of the data cells of the column
 // with the header name field, in order of first appearance. The header
@@ -55,3 +58,47 @@ func (s SimpleCsv) ValueCounts(field string) (SimpleCsv, bool) {
 	}
 	return newCsv, true
 }
+
+// facetCount returns a map that counts how many times each string appears in
+// the data cells of the column with the header name field. If caseSensitive
+// is false, case does not matter: values that only differ in case are
+// counted together under their lower-case key. If it is true, they are
+// separate entries. The header cell in row 0 is never counted. It returns
+// an empty map and false if the csv is empty, the field name is empty, or
+// the field name does not exist. A csv with only the header row returns an
+// empty map and true.
+func (s SimpleCsv) facetCount(field string, caseSensitive bool) (map[string]int, bool) {
+	if field == "" {
+		return map[string]int{}, false
+	}
+	columnPosition := s.GetHeaderPosition(field)
+	if columnPosition == -1 {
+		return map[string]int{}, false
+	}
+	counts := make(map[string]int)
+	for i := 1; i < len(s); i++ {
+		value := s[i][columnPosition]
+		if !caseSensitive {
+			value = strings.ToLower(value)
+		}
+		counts[value]++
+	}
+	return counts, true
+}
+
+// FacetCount returns a map that counts how many times each string appears
+// in the data cells of the column with the header name field. The header
+// cell in row 0 is never counted. Case does not matter by default: Foo,
+// foo and FOO are counted together under the lower-case key "foo". If the
+// csv is empty, the field name is empty, or the field name does not exist,
+// it returns an empty map and false. A csv with only the header row
+// returns an empty map and true.
+func (s SimpleCsv) FacetCount(field string) (map[string]int, bool) {
+	return s.facetCount(field, false)
+}
+
+// FacetCountCaseSensitive is like FacetCount but case matters: Foo, foo
+// and FOO are counted as separate entries.
+func (s SimpleCsv) FacetCountCaseSensitive(field string) (map[string]int, bool) {
+	return s.facetCount(field, true)
+}

distinct_test.go

@@ -261,3 +261,205 @@ func TestDistinctValueCountsDoNotMutateSource(t *testing.T) {
 		t.Errorf("mutating failed ValueCounts result changed source: %v", s)
 	}
 }
+
+func TestSimpleCsv_FacetCount(t *testing.T) {
+	tests := []struct {
+		name  string
+		s     SimpleCsv
+		field string
+		want  map[string]int
+		want1 bool
+	}{
+		{
+			name: "FacetCountIgnoresCaseByDefault",
+			s: SimpleCsv{
+				{"Country", "City"},
+				{"PT", "Lisbon"},
+				{"pt", "Porto"},
+				{"PT", "Braga"},
+				{"ES", "Madrid"},
+			},
+			field: "Country",
+			want:  map[string]int{"pt": 3, "es": 1},
+			want1: true,
+		},
+		{
+			name: "FacetCountGroupsOnlyCaseVariants",
+			s: SimpleCsv{
+				{"Code"},
+				{"Foo"},
+				{"foo"},
+				{"FOO"},
+			},
+			field: "Code",
+			want:  map[string]int{"foo": 3},
+			want1: true,
+		},
+		{
+			name: "FacetCountKeepsEmptyValues",
+			s: SimpleCsv{
+				{"Code"},
+				{""},
+				{"x"},
+				{""},
+			},
+			field: "Code",
+			want:  map[string]int{"": 2, "x": 1},
+			want1: true,
+		},
+		{
+			name: "FacetCountHeaderCellNotIncluded",
+			s: SimpleCsv{
+				{"Country"},
+				{"Country"},
+				{"PT"},
+				{"country"},
+			},
+			field: "Country",
+			want:  map[string]int{"country": 2, "pt": 1},
+			want1: true,
+		},
+		{
+			name: "FacetCountHeaderOnly",
+			want: map[string]int{},
+			s: SimpleCsv{
+				{"Country", "City"},
+			},
+			field: "Country",
+			want1: true,
+		},
+		{
+			name:  "FacetCountEmpty",
+			want:  map[string]int{},
+			s:     SimpleCsv{},
+			field: "Country",
+			want1: false,
+		},
+		{
+			name: "FacetCountMissingField",
+			want: map[string]int{},
+			s: SimpleCsv{
+				{"Country", "City"},
+				{"PT", "Lisbon"},
+			},
+			field: "Book",
+			want1: false,
+		},
+		{
+			name: "FacetCountEmptyFieldName",
+			want: map[string]int{},
+			s: SimpleCsv{
+				{"Country", "City"},
+				{"PT", "Lisbon"},
+			},
+			field: "",
+			want1: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, got1 := tt.s.FacetCount(tt.field)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("SimpleCsv.FacetCount() got = %v, want %v", got, tt.want)
+			}
+			if got1 != tt.want1 {
+				t.Errorf("SimpleCsv.FacetCount() got1 = %v, want %v", got1, tt.want1)
+			}
+		})
+	}
+}
+
+func TestSimpleCsv_FacetCountCaseSensitive(t *testing.T) {
+	tests := []struct {
+		name  string
+		s     SimpleCsv
+		field string
+		want  map[string]int
+		want1 bool
+	}{
+		{
+			name: "FacetCountCaseSensitiveSeparatesCase",
+			s: SimpleCsv{
+				{"Country", "City"},
+				{"PT", "Lisbon"},
+				{"pt", "Porto"},
+				{"PT", "Braga"},
+				{"ES", "Madrid"},
+			},
+			field: "Country",
+			want:  map[string]int{"PT": 2, "pt": 1, "ES": 1},
+			want1: true,
+		},
+		{
+			name: "FacetCountCaseSensitiveKeepsEmptyValues",
+			s: SimpleCsv{
+				{"Code"},
+				{""},
+				{"x"},
+				{""},
+			},
+			field: "Code",
+			want:  map[string]int{"": 2, "x": 1},
+			want1: true,
+		},
+		{
+			name: "FacetCountCaseSensitiveHeaderCellNotIncluded",
+			s: SimpleCsv{
+				{"Country"},
+				{"Country"},
+				{"PT"},
+				{"country"},
+			},
+			field: "Country",
+			want:  map[string]int{"Country": 1, "PT": 1, "country": 1},
+			want1: true,
+		},
+		{
+			name: "FacetCountCaseSensitiveHeaderOnly",
+			want: map[string]int{},
+			s: SimpleCsv{
+				{"Country", "City"},
+			},
+			field: "Country",
+			want1: true,
+		},
+		{
+			name:  "FacetCountCaseSensitiveEmpty",
+			want:  map[string]int{},
+			s:     SimpleCsv{},
+			field: "Country",
+			want1: false,
+		},
+		{
+			name: "FacetCountCaseSensitiveMissingField",
+			want: map[string]int{},
+			s: SimpleCsv{
+				{"Country", "City"},
+				{"PT", "Lisbon"},
+			},
+			field: "Book",
+			want1: false,
+		},
+		{
+			name: "FacetCountCaseSensitiveEmptyFieldName",
+			want: map[string]int{},
+			s: SimpleCsv{
+				{"Country", "City"},
+				{"PT", "Lisbon"},
+			},
+			field: "",
+			want1: false,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, got1 := tt.s.FacetCountCaseSensitive(tt.field)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("SimpleCsv.FacetCountCaseSensitive() got = %v, want %v", got, tt.want)
+			}
+			if got1 != tt.want1 {
+				t.Errorf("SimpleCsv.FacetCountCaseSensitive() got1 = %v, want %v", got1, tt.want1)
+			}
+		})
+	}
+}

doc.go

@@ -331,6 +331,22 @@ The header cell is never counted and the original csv is not modified:
 `wasRead` is false if the csv is empty or the field name does not exist; in
 that case a copy of the csv is returned.
 
+`FacetCount` returns a map that counts how many times each string appears in
+the data cells of a column. The header cell is never counted. Case does not
+matter by default: `Foo`, `foo` and `FOO` are counted together under the
+lower-case key `foo`:
+
+    counts, wasRead := x.FacetCount("Country")
+
+`wasRead` is false if the csv is empty, the field name is empty, or the
+field name does not exist; in that case an empty map is returned. A csv
+with only the header row returns an empty map and true.
+
+`FacetCountCaseSensitive` is the same but case matters: `Foo`, `foo` and
+`FOO` are counted as separate entries:
+
+    counts, wasRead = x.FacetCountCaseSensitive("Country")
+
 * GROUP BY *
 
 `GroupBy` collapses the data rows into one output row per group, where a

docs/api.md

@@ -114,6 +114,8 @@ description: A practical map of simplecsv APIs grouped by the job they solve.
             <li><code>UniqueByFields</code></li>
             <li><code>Distinct</code></li>
             <li><code>ValueCounts</code></li>
+            <li><code>FacetCount</code></li>
+            <li><code>FacetCountCaseSensitive</code></li>
             <li><code>SortByField</code></li>
             <li><code>SortByFields</code></li>
           </ul>

docs/concepts.md

@@ -95,6 +95,7 @@ row 2: 102, Ben,  paused
           <ul>
             <li><code>Distinct</code></li>
             <li><code>ValueCounts</code></li>
+            <li><code>FacetCount</code></li>
             <li><code>GetColumnByField</code></li>
             <li><code>EachDataRow</code></li>
           </ul>

docs/recipes/summarize.md

@@ -118,6 +118,20 @@ counts, ok := orders.ValueCounts("status")
 if !ok {
     log.Fatal("status field not found")
 }
+{% endhighlight %}
+
+      <p>Use <code>FacetCount</code> when you need the counts as a map, e.g. for
+      facet navigation. It is case-insensitive by default; use
+      <code>FacetCountCaseSensitive</code> when case matters:</p>
+
+{% highlight go %}
+facet, ok := orders.FacetCount("status")
+if !ok {
+    log.Fatal("status field not found")
+}
+for status, n := range facet {
+    fmt.Println(status, n)
+}
 {% endhighlight %}
 
       <h2 id="stable-report-order">Control report order</h2>