vendor/github.com/lestrrat-go/strftime/README.md

   1 # strftime
   2
   3 Fast strftime for Go
   4
   5 [![Build Status](https://travis-ci.org/lestrrat-go/strftime.png?branch=master)](https://travis-ci.org/lestrrat-go/strftime)
   6
   7 [![GoDoc](https://godoc.org/github.com/lestrrat-go/strftime?status.svg)](https://godoc.org/github.com/lestrrat-go/strftime)
   8
   9 # SYNOPSIS
  10
  11 ```go
  12 f := strftime.New(`.... pattern ...`)
  13 if err := f.Format(buf, time.Now()); err != nil {
  14     log.Println(err.Error())
  15 }
  16 ```
  17
  18 # DESCRIPTION
  19
  20 The goals for this library are
  21
  22 * Optimized for the same pattern being called repeatedly
  23 * Be flexible about destination to write the results out
  24 * Be as complete as possible in terms of conversion specifications
  25
  26 # API
  27
  28 ## Format(string, time.Time) (string, error)
  29
  30 Takes the pattern and the time, and formats it. This function is a utility function that recompiles the pattern every time the function is called. If you know beforehand that you will be formatting the same pattern multiple times, consider using `New` to create a `Strftime` object and reuse it.
  31
  32 ## New(string) (\*Strftime, error)
  33
  34 Takes the pattern and creates a new `Strftime` object.
  35
  36 ## obj.Pattern() string
  37
  38 Returns the pattern string used to create this `Strftime` object
  39
  40 ## obj.Format(io.Writer, time.Time) error
  41
  42 Formats the time according to the pre-compiled pattern, and writes the result to the specified `io.Writer`
  43
  44 ## obj.FormatString(time.Time) string
  45
  46 Formats the time according to the pre-compiled pattern, and returns the result string.
  47
  48 # SUPPORTED CONVERSION SPECIFICATIONS
  49
  50 | pattern | description |
  51 |:--------|:------------|
  52 | %A      | national representation of the full weekday name |
  53 | %a      | national representation of the abbreviated weekday |
  54 | %B      | national representation of the full month name |
  55 | %b      | national representation of the abbreviated month name |
  56 | %C      | (year / 100) as decimal number; single digits are preceded by a zero |
  57 | %c      | national representation of time and date |
  58 | %D      | equivalent to %m/%d/%y |
  59 | %d      | day of the month as a decimal number (01-31) |
  60 | %e      | the day of the month as a decimal number (1-31); single digits are preceded by a blank |
  61 | %F      | equivalent to %Y-%m-%d |
  62 | %H      | the hour (24-hour clock) as a decimal number (00-23) |
  63 | %h      | same as %b |
  64 | %I      | the hour (12-hour clock) as a decimal number (01-12) |
  65 | %j      | the day of the year as a decimal number (001-366) |
  66 | %k      | the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank |
  67 | %l      | the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank |
  68 | %M      | the minute as a decimal number (00-59) |
  69 | %m      | the month as a decimal number (01-12) |
  70 | %n      | a newline |
  71 | %p      | national representation of either "ante meridiem" (a.m.)  or "post meridiem" (p.m.)  as appropriate. |
  72 | %R      | equivalent to %H:%M |
  73 | %r      | equivalent to %I:%M:%S %p |
  74 | %S      | the second as a decimal number (00-60) |
  75 | %T      | equivalent to %H:%M:%S |
  76 | %t      | a tab |
  77 | %U      | the week number of the year (Sunday as the first day of the week) as a decimal number (00-53) |
  78 | %u      | the weekday (Monday as the first day of the week) as a decimal number (1-7) |
  79 | %V      | the week number of the year (Monday as the first day of the week) as a decimal number (01-53) |
  80 | %v      | equivalent to %e-%b-%Y |
  81 | %W      | the week number of the year (Monday as the first day of the week) as a decimal number (00-53) |
  82 | %w      | the weekday (Sunday as the first day of the week) as a decimal number (0-6) |
  83 | %X      | national representation of the time |
  84 | %x      | national representation of the date |
  85 | %Y      | the year with century as a decimal number |
  86 | %y      | the year without century as a decimal number (00-99) |
  87 | %Z      | the time zone name |
  88 | %z      | the time zone offset from UTC |
  89 | %%      | a '%' |
  90
  91 # PERFORMANCE / OTHER LIBRARIES
  92
  93 The following benchmarks were run separately because some libraries were using cgo on specific platforms (notabley, the fastly version)
  94
  95 ```
  96 // On my OS X 10.11.6, 2.9 GHz Intel Core i5, 16GB memory.
  97 // go version go1.8rc1 darwin/amd64
  98 hummingbird% go test -tags bench -benchmem -bench .
  99 <snip>
 100 BenchmarkTebeka-4                     300000          4469 ns/op         288 B/op         21 allocs/op
 101 BenchmarkJehiah-4                    1000000          1931 ns/op         256 B/op         17 allocs/op
 102 BenchmarkFastly-4                    2000000           724 ns/op          80 B/op          5 allocs/op
 103 BenchmarkLestrrat-4                  1000000          1572 ns/op         240 B/op          3 allocs/op
 104 BenchmarkLestrratCachedString-4      3000000           548 ns/op         128 B/op          2 allocs/op
 105 BenchmarkLestrratCachedWriter-4       500000          2519 ns/op         192 B/op          3 allocs/op
 106 PASS
 107 ok      github.com/lestrrat-go/strftime 22.900s
 108 ```
 109
 110 ```
 111 // On a host on Google Cloud Platform, machine-type: n1-standard-4 (vCPU x 4, memory: 15GB)
 112 // Linux <snip> 3.16.0-4-amd64 #1 SMP Debian 3.16.36-1+deb8u2 (2016-10-19) x86_64 GNU/Linux
 113 // go version go1.8rc1 linux/amd64
 114 hummingbird% go test -tags bench -benchmem -bench .
 115 <snip>
 116 BenchmarkTebeka-4                     500000          3904 ns/op         288 B/op         21 allocs/op
 117 BenchmarkJehiah-4                    1000000          1665 ns/op         256 B/op         17 allocs/op
 118 BenchmarkFastly-4                    1000000          2134 ns/op         192 B/op         13 allocs/op
 119 BenchmarkLestrrat-4                  1000000          1327 ns/op         240 B/op          3 allocs/op
 120 BenchmarkLestrratCachedString-4      3000000           498 ns/op         128 B/op          2 allocs/op
 121 BenchmarkLestrratCachedWriter-4      1000000          3390 ns/op         192 B/op          3 allocs/op
 122 PASS
 123 ok      github.com/lestrrat-go/strftime 44.854s
 124 ```
 125
 126 This library is much faster than other libraries *IF* you can reuse the format pattern.
 127
 128 Here's the annotated list from the benchmark results. You can clearly see that (re)using a `Strftime` object
 129 and producing a string is the fastest. Writing to an `io.Writer` seems a bit sluggish, but since
 130 the one producing the string is doing almost exactly the same thing, we believe this is purely the overhead of
 131 writing to an `io.Writer`
 132
 133 | Import Path                         | Score   | Note                            |
 134 |:------------------------------------|--------:|:--------------------------------|
 135 | github.com/lestrrat-go/strftime     | 3000000 | Using `FormatString()` (cached) |
 136 | github.com/fastly/go-utils/strftime | 2000000 | Pure go version on OS X         |
 137 | github.com/lestrrat-go/strftime     | 1000000 | Using `Format()` (NOT cached)   |
 138 | github.com/jehiah/go-strftime       | 1000000 |                                 |
 139 | github.com/fastly/go-utils/strftime | 1000000 | cgo version on Linux            |
 140 | github.com/lestrrat-go/strftime     | 500000  | Using `Format()` (cached)       |
 141 | github.com/tebeka/strftime          | 300000  |                                 |
 142
 143 However, depending on your pattern, this speed may vary. If you find a particular pattern that seems sluggish,
 144 please send in patches or tests.
 145
 146 Please also note that this benchmark only uses the subset of conversion specifications that are supported by *ALL* of the libraries compared.
 147
 148 Somethings to consider when making performance comparisons in the future:
 149
 150 * Can it write to io.Writer?
 151 * Which `%specification` does it handle?