Adds package humanize/english for English-word manipulations.
Includes:
- Plural and PluralWord to form simple plurals.
- WordSeries and OxfordWordSeries to form comma-separated
lists (e.g., "foo, bar and baz").
Fixes: #57
diff --git a/README.markdown b/README.markdown
index f69d3c8..91b4ae5 100644
--- a/README.markdown
+++ b/README.markdown
@@ -88,5 +88,37 @@
humanize.SI(0.00000000223, "M") // 2.23 nM
```
+## English-specific functions
+
+The following functions are in the `humanize/english` subpackage.
+
+### Plurals
+
+Simple English pluralization
+
+```go
+english.PluralWord(1, "object", "") // object
+english.PluralWord(42, "object", "") // objects
+english.PluralWord(2, "bus", "") // buses
+english.PluralWord(99, "locus", "loci") // loci
+
+english.Plural(1, "object", "") // 1 object
+english.Plural(42, "object", "") // 42 objects
+english.Plural(2, "bus", "") // 2 buses
+english.Plural(99, "locus", "loci") // 99 loci
+```
+
+### Word series
+
+Format comma-separated words lists with conjuctions:
+
+```go
+english.WordSeries([]string{"foo"}, "and") // foo
+english.WordSeries([]string{"foo", "bar"}, "and") // foo and bar
+english.WordSeries([]string{"foo", "bar", "baz"}, "and") // foo, bar and baz
+
+english.OxfordWordSeries([]string{"foo", "bar", "baz"}, "and") // foo, bar, and baz
+```
+
[odisc]: https://groups.google.com/d/topic/golang-nuts/l8NhI74jl-4/discussion
[sinotation]: http://en.wikipedia.org/wiki/Metric_prefix
diff --git a/english/words.go b/english/words.go
new file mode 100644
index 0000000..26e9918
--- /dev/null
+++ b/english/words.go
@@ -0,0 +1,96 @@
+// Package english provides utilities to generate more user-friendly English output.
+package english
+
+import (
+ "fmt"
+ "strings"
+)
+
+// These are included because they are common technical terms.
+var specialPlurals = map[string]string{
+ "index": "indices",
+ "matrix": "matrices",
+ "vertex": "vertices",
+}
+
+var sibilantEndings = []string{"s", "sh", "tch", "x"}
+
+var isVowel = map[byte]bool{
+ 'A': true, 'E': true, 'I': true, 'O': true, 'U': true,
+ 'a': true, 'e': true, 'i': true, 'o': true, 'u': true,
+}
+
+// PluralWord builds the plural form of an English word.
+// The simple English rules of regular pluralization will be used
+// if the plural form is an empty string (i.e. not explicitly given).
+// The special cases are not guaranteed to work for strings outside ASCII.
+func PluralWord(quantity int, singular, plural string) string {
+ if quantity == 1 {
+ return singular
+ }
+ if plural != "" {
+ return plural
+ }
+ if plural = specialPlurals[singular]; plural != "" {
+ return plural
+ }
+
+ // We need to guess what the English plural might be. Keep this
+ // function simple! It doesn't need to know about every possiblity;
+ // only regular rules and the most common special cases.
+ //
+ // Reference: http://en.wikipedia.org/wiki/English_plural
+
+ for _, ending := range sibilantEndings {
+ if strings.HasSuffix(singular, ending) {
+ return singular + "es"
+ }
+ }
+ l := len(singular)
+ if l >= 2 && singular[l-1] == 'o' && !isVowel[singular[l-2]] {
+ return singular + "es"
+ }
+ if l >= 2 && singular[l-1] == 'y' && !isVowel[singular[l-2]] {
+ return singular[:l-1] + "ies"
+ }
+
+ return singular + "s"
+}
+
+// Plural formats an integer and a string into a single pluralized string.
+// The simple English rules of regular pluralization will be used
+// if the plural form is an empty string (i.e. not explicitly given).
+func Plural(quantity int, singular, plural string) string {
+ return fmt.Sprintf("%d %s", quantity, PluralWord(quantity, singular, plural))
+}
+
+// WordSeries converts a list of words into a word series in English.
+// It returns a string containing all the given words separated by commas,
+// the coordinating conjunction, and a serial comma, as appropriate.
+func WordSeries(words []string, conjunction string) string {
+ switch len(words) {
+ case 0:
+ return ""
+ case 1:
+ return words[0]
+ default:
+ return fmt.Sprintf("%s %s %s", strings.Join(words[:len(words)-1], ", "), conjunction, words[len(words)-1])
+ }
+}
+
+// OxfordWordSeries converts a list of words into a word series in English,
+// using an Oxford comma (https://en.wikipedia.org/wiki/Serial_comma). It
+// returns a string containing all the given words separated by commas, the
+// coordinating conjunction, and a serial comma, as appropriate.
+func OxfordWordSeries(words []string, conjunction string) string {
+ switch len(words) {
+ case 0:
+ return ""
+ case 1:
+ return words[0]
+ case 2:
+ return strings.Join(words, fmt.Sprintf(" %s ", conjunction))
+ default:
+ return fmt.Sprintf("%s, %s %s", strings.Join(words[:len(words)-1], ", "), conjunction, words[len(words)-1])
+ }
+}
diff --git a/english/words_test.go b/english/words_test.go
new file mode 100644
index 0000000..3c1d7be
--- /dev/null
+++ b/english/words_test.go
@@ -0,0 +1,94 @@
+package english
+
+import (
+ "testing"
+)
+
+func TestPluralWord(t *testing.T) {
+ tests := []struct {
+ n int
+ singular, plural string
+ want string
+ }{
+ {0, "object", "", "objects"},
+ {1, "object", "", "object"},
+ {-1, "object", "", "objects"},
+ {42, "object", "", "objects"},
+ {2, "vax", "vaxen", "vaxen"},
+
+ // special cases
+ {2, "index", "", "indices"},
+
+ // ending in a sibilant sound
+ {2, "bus", "", "buses"},
+ {2, "bush", "", "bushes"},
+ {2, "watch", "", "watches"},
+ {2, "box", "", "boxes"},
+
+ // ending with 'o' preceded by a consonant
+ {2, "hero", "", "heroes"},
+
+ // ending with 'y' preceded by a consonant
+ {2, "lady", "", "ladies"},
+ {2, "day", "", "days"},
+ }
+ for _, tt := range tests {
+ if got := PluralWord(tt.n, tt.singular, tt.plural); got != tt.want {
+ t.Errorf("PluralWord(%d, %q, %q)=%q; want: %q", tt.n, tt.singular, tt.plural, got, tt.want)
+ }
+ }
+}
+
+func TestPlural(t *testing.T) {
+ tests := []struct {
+ n int
+ singular, plural string
+ want string
+ }{
+ {1, "object", "", "1 object"},
+ {42, "object", "", "42 objects"},
+ }
+ for _, tt := range tests {
+ if got := Plural(tt.n, tt.singular, tt.plural); got != tt.want {
+ t.Errorf("Plural(%d, %q, %q)=%q; want: %q", tt.n, tt.singular, tt.plural, got, tt.want)
+ }
+ }
+}
+
+func TestWordSeries(t *testing.T) {
+ tests := []struct {
+ words []string
+ conjunction string
+ want string
+ }{
+ {[]string{}, "and", ""},
+ {[]string{"foo"}, "and", "foo"},
+ {[]string{"foo", "bar"}, "and", "foo and bar"},
+ {[]string{"foo", "bar", "baz"}, "and", "foo, bar and baz"},
+ {[]string{"foo", "bar", "baz"}, "or", "foo, bar or baz"},
+ }
+ for _, tt := range tests {
+ if got := WordSeries(tt.words, tt.conjunction); got != tt.want {
+ t.Errorf("WordSeries(%q, %q)=%q; want: %q", tt.words, tt.conjunction, got, tt.want)
+ }
+ }
+}
+
+func TestOxfordWordSeries(t *testing.T) {
+ tests := []struct {
+ words []string
+ conjunction string
+ want string
+ }{
+ {[]string{}, "and", ""},
+ {[]string{"foo"}, "and", "foo"},
+ {[]string{"foo", "bar"}, "and", "foo and bar"},
+ {[]string{"foo", "bar", "baz"}, "and", "foo, bar, and baz"},
+ {[]string{"foo", "bar", "baz"}, "or", "foo, bar, or baz"},
+ }
+ for _, tt := range tests {
+ if got := OxfordWordSeries(tt.words, tt.conjunction); got != tt.want {
+ t.Errorf("OxfordWordSeries(%q, %q)=%q; want: %q", tt.words, tt.conjunction, got, tt.want)
+ }
+ }
+}
