README
¶
strftime
Fast strftime in Go with BCP 47 language tags.
Usage
It is either possible to instanciate an object for a given locale (via strftime.New) or directly call strftime.Format or strftime.EnFormat.
Examples
To simply get a timestamp in English:
fmt.Printf("%s: something happened", strftime.EnFormat(`%c`, time.Now()));
Or get a quick result in French:
fmt.Printf("%s: Quelque chose est arrivé", strftime.Format(language.French, `%c`, time.Now()));
Or display a result in the appropriate language for a web user:
tags, _, _ := language.ParseAcceptLanguage(r.Header.Get("Accept-Language"))
f := strftime.New(tags...)
f.FormatF(w, `%c`, time.Now());
Description
This version of strftime for Go has multiple goals in mind:
- Support for BCP 47 language tags
- Easy to use
- Ability to just return string or write to a io.Writer
- Be as complete as possible in terms of conversion specifications
Pattern support
| pattern | description |
|---|---|
| %A | national representation of the full weekday name |
| %a | national representation of the abbreviated weekday |
| %B | national representation of the full month name |
| %b | national representation of the abbreviated month name |
| %C | (year / 100) as decimal number; single digits are preceded by a zero |
| %c | national representation of time and date |
| %D | equivalent to %m/%d/%y |
| %d | day of the month as a decimal number (01-31) |
| %e | the day of the month as a decimal number (1-31); single digits are preceded by a blank |
| %F | equivalent to %Y-%m-%d |
| %f | Microseconds (6 digits) |
| %G | Year matching the week going by ISO-8601:1988 standards |
| %g | Two digits representation of %G |
| %H | the hour (24-hour clock) as a decimal number (00-23) |
| %h | same as %b |
| %I | the hour (12-hour clock) as a decimal number (01-12) |
| %j | the day of the year as a decimal number (001-366) |
| %k | the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank |
| %l | the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank |
| %M | the minute as a decimal number (00-59) |
| %m | the month as a decimal number (01-12) |
| %n | a newline |
| %p | national representation of either "ante meridiem" (a.m.) or "post meridiem" (p.m.) as appropriate. |
| %P | lower-case version of %p |
| %R | equivalent to %H:%M |
| %r | equivalent to %I:%M:%S %p |
| %S | the second as a decimal number (00-60) |
| %s | Unix Epoch Time timestamp (seconds since January 1st 1970) |
| %T | equivalent to %H:%M:%S |
| %t | a tab |
| %U | the week number of the year (Sunday as the first day of the week) as a decimal number (00-53) |
| %u | the weekday (Monday as the first day of the week) as a decimal number (1-7) |
| %V | the week number of the year (Monday as the first day of the week) as a decimal number (01-53) |
| %v | equivalent to %e-%b-%Y |
| %W | the week number of the year (Monday as the first day of the week) as a decimal number (00-53) |
| %w | the weekday (Sunday as the first day of the week) as a decimal number (0-6) |
| %X | national representation of the time |
| %x | national representation of the date |
| %Y | the year with century as a decimal number |
| %y | the year without century as a decimal number (00-99) |
| %Z | the time zone name |
| %z | the time zone offset from UTC |
| %% | a '%' |
Era modifiers are available. For locales in which there is no era, normal values (without era modifier) are returned.
| pattern | description |
|---|---|
| %Ec | national representation of time and date |
| %EC | name of era the date is in |
| %EX | national representation of the time |
| %Ex | national representation of the date |
| %EY | full era name and year represented in locale |
| %Ey | year as decimal number in era (if any) or same as %y |
Why not Go's Format()?
This is a very good question. Go time package's Format() method has a nice, human friendly method to set the format for a date. Yet, this is unfortunately not appropriate when multiple languages are involved, as each language has its own rules in terms of terms ordering and presentation, and may even use different years.
While maybe less human friendly, strftime() has a long history and most developers will know how it works and what to expect from it.
Performances / other libraries
// On Linux Gentoo 4.14.13-gentoo
// go version go1.11 linux/amd64
$ go test -tags bench -benchmem -bench .
<snip>
BenchmarkCactus-12 1000000 1697 ns/op 216 B/op 7 allocs/op
BenchmarkLeekchan-12 500000 2775 ns/op 1376 B/op 22 allocs/op
BenchmarkTebeka-12 500000 3777 ns/op 288 B/op 21 allocs/op
BenchmarkJehiah-12 1000000 1555 ns/op 256 B/op 17 allocs/op
BenchmarkFastly-12 500000 3774 ns/op 192 B/op 11 allocs/op
BenchmarkLestrrat-12 1000000 1333 ns/op 240 B/op 3 allocs/op
BenchmarkMagicalTux-12 2000000 688 ns/op 240 B/op 3 allocs/op
PASS
ok github.com/MagicalTux/strftime 11.997s
This library is much faster than other libraries for common cases. In case of format pattern re-use, Lestrrat's implementation is still faster (but has no locale awareness).
| Import Path | Score | Note |
|---|---|---|
| github.com/MagicalTux/strftime | 688 ns/op | |
| github.com/lestrrat-go/strftime | 1333 ns/op | Using Format() (NOT cached) |
| github.com/jehiah/go-strftime | 1555 ns/op | |
| github.com/cactus/gostrftime | 1697 ns/op | |
| github.com/leekchan/timeutil | 2775 ns/op | |
| github.com/fastly/go-utils/strftime | 3774 ns/op | cgo version on Linux |
| github.com/tebeka/strftime | 3777 ns/op |
Please note that this benchmark only uses the subset of conversion specifications that are supported by ALL of the libraries compared.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var EnglishFormatter = &Formatter{englishLocale}
EnglishFormatter is pre-initialized English locale formatter.
Functions ¶
Types ¶
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
func New ¶
New creates a new Formatter by matching given language tags against known tags.
One sample use is as follows: t, q, err := language.ParseAcceptLanguage(r.Header.Get("Accept-Language")) f := strftime.New(t...)
func (*Formatter) AppendFormat ¶
AppendFormat is like Format but appends the textual representation to b and returns the extended buffer.
Source Files