README.markdown (3078B)
1 # Humane Units [](https://travis-ci.org/dustin/go-humanize) [](https://godoc.org/github.com/dustin/go-humanize) 2 3 Just a few functions for helping humanize times and sizes. 4 5 `go get` it as `github.com/dustin/go-humanize`, import it as 6 `"github.com/dustin/go-humanize"`, use it as `humanize`. 7 8 See [godoc](https://pkg.go.dev/github.com/dustin/go-humanize) for 9 complete documentation. 10 11 ## Sizes 12 13 This lets you take numbers like `82854982` and convert them to useful 14 strings like, `83 MB` or `79 MiB` (whichever you prefer). 15 16 Example: 17 18 ```go 19 fmt.Printf("That file is %s.", humanize.Bytes(82854982)) // That file is 83 MB. 20 ``` 21 22 ## Times 23 24 This lets you take a `time.Time` and spit it out in relative terms. 25 For example, `12 seconds ago` or `3 days from now`. 26 27 Example: 28 29 ```go 30 fmt.Printf("This was touched %s.", humanize.Time(someTimeInstance)) // This was touched 7 hours ago. 31 ``` 32 33 Thanks to Kyle Lemons for the time implementation from an IRC 34 conversation one day. It's pretty neat. 35 36 ## Ordinals 37 38 From a [mailing list discussion][odisc] where a user wanted to be able 39 to label ordinals. 40 41 0 -> 0th 42 1 -> 1st 43 2 -> 2nd 44 3 -> 3rd 45 4 -> 4th 46 [...] 47 48 Example: 49 50 ```go 51 fmt.Printf("You're my %s best friend.", humanize.Ordinal(193)) // You are my 193rd best friend. 52 ``` 53 54 ## Commas 55 56 Want to shove commas into numbers? Be my guest. 57 58 0 -> 0 59 100 -> 100 60 1000 -> 1,000 61 1000000000 -> 1,000,000,000 62 -100000 -> -100,000 63 64 Example: 65 66 ```go 67 fmt.Printf("You owe $%s.\n", humanize.Comma(6582491)) // You owe $6,582,491. 68 ``` 69 70 ## Ftoa 71 72 Nicer float64 formatter that removes trailing zeros. 73 74 ```go 75 fmt.Printf("%f", 2.24) // 2.240000 76 fmt.Printf("%s", humanize.Ftoa(2.24)) // 2.24 77 fmt.Printf("%f", 2.0) // 2.000000 78 fmt.Printf("%s", humanize.Ftoa(2.0)) // 2 79 ``` 80 81 ## SI notation 82 83 Format numbers with [SI notation][sinotation]. 84 85 Example: 86 87 ```go 88 humanize.SI(0.00000000223, "M") // 2.23 nM 89 ``` 90 91 ## English-specific functions 92 93 The following functions are in the `humanize/english` subpackage. 94 95 ### Plurals 96 97 Simple English pluralization 98 99 ```go 100 english.PluralWord(1, "object", "") // object 101 english.PluralWord(42, "object", "") // objects 102 english.PluralWord(2, "bus", "") // buses 103 english.PluralWord(99, "locus", "loci") // loci 104 105 english.Plural(1, "object", "") // 1 object 106 english.Plural(42, "object", "") // 42 objects 107 english.Plural(2, "bus", "") // 2 buses 108 english.Plural(99, "locus", "loci") // 99 loci 109 ``` 110 111 ### Word series 112 113 Format comma-separated words lists with conjuctions: 114 115 ```go 116 english.WordSeries([]string{"foo"}, "and") // foo 117 english.WordSeries([]string{"foo", "bar"}, "and") // foo and bar 118 english.WordSeries([]string{"foo", "bar", "baz"}, "and") // foo, bar and baz 119 120 english.OxfordWordSeries([]string{"foo", "bar", "baz"}, "and") // foo, bar, and baz 121 ``` 122 123 [odisc]: https://groups.google.com/d/topic/golang-nuts/l8NhI74jl-4/discussion 124 [sinotation]: http://en.wikipedia.org/wiki/Metric_prefix