github.com/bingoohuang/gg@v0.0.0-20240325092523-45da7dee9335/pkg/man/README.md (about)

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