README.md
1# go-strftime
2
3strftime for Go
4
5[](https://travis-ci.org/lestrrat/go-strftime)
6
7[](https://godoc.org/github.com/lestrrat/go-strftime)
8
9# SYNOPSIS
10
11```go
12f := strftime.New(`.... pattern ...`)
13if err := f.Format(buf, time.Now()); err != nil {
14 log.Println(err.Error())
15}
16```
17
18# DESCRIPTION
19
20The 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
30Takes 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
34Takes the pattern and creates a new `Strftime` object.
35
36## obj.Pattern() string
37
38Returns the pattern string used to create this `Strftime` object
39
40## obj.Format(io.Writer, time.Time) error
41
42Formats 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
46Formats 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
93The 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
98hummingbird% go test -tags bench -benchmem -bench .
99<snip>
100BenchmarkTebeka-4 300000 4469 ns/op 288 B/op 21 allocs/op
101BenchmarkJehiah-4 1000000 1931 ns/op 256 B/op 17 allocs/op
102BenchmarkFastly-4 2000000 724 ns/op 80 B/op 5 allocs/op
103BenchmarkLestrrat-4 1000000 1572 ns/op 240 B/op 3 allocs/op
104BenchmarkLestrratCachedString-4 3000000 548 ns/op 128 B/op 2 allocs/op
105BenchmarkLestrratCachedWriter-4 500000 2519 ns/op 192 B/op 3 allocs/op
106PASS
107ok 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
114hummingbird% go test -tags bench -benchmem -bench .
115<snip>
116BenchmarkTebeka-4 500000 3904 ns/op 288 B/op 21 allocs/op
117BenchmarkJehiah-4 1000000 1665 ns/op 256 B/op 17 allocs/op
118BenchmarkFastly-4 1000000 2134 ns/op 192 B/op 13 allocs/op
119BenchmarkLestrrat-4 1000000 1327 ns/op 240 B/op 3 allocs/op
120BenchmarkLestrratCachedString-4 3000000 498 ns/op 128 B/op 2 allocs/op
121BenchmarkLestrratCachedWriter-4 1000000 3390 ns/op 192 B/op 3 allocs/op
122PASS
123ok github.com/lestrrat/go-strftime 44.854s
124```
125
126This library is much faster than other libraries *IF* you can reuse the format pattern.
127
128Here's the annotated list from the benchmark results. You can clearly see that (re)using a `Strftime` object
129and producing a string is the fastest. Writing to an `io.Writer` seems a bit sluggish, but since
130the one producing the string is doing almost exactly the same thing, we believe this is purely the overhead of
131writing 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
143However, depending on your pattern, this speed may vary. If you find a particular pattern that seems sluggish,
144please send in patches or tests.
145
146Please also note that this benchmark only uses the subset of conversion specifications that are supported by *ALL* of the libraries compared.
147
148Somethings to consider when making performance comparisons in the future:
149
150* Can it write to io.Writer?
151* Which `%specification` does it handle?
152
){kind=link}
){kind=link}