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
BenchmarkKarpelesLab-12 2000000 688 ns/op 240 B/op 3 allocs/op
PASS
ok github.com/KarpelesLab/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/KarpelesLab/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
¶
Overview ¶
Package strftime implements C-like strftime functionality with locale support.
Package strftime implements C-like strftime functionality.
Package strftime provides locale-aware time formatting.
Package strftime implements C-like strftime functionality with locale support.
Package strftime implements C-like strftime functionality with locale support.
Package strftime implements C-like strftime functionality with locale support.
Package strftime implements C-like strftime format functionality with multiple locale support. It provides formatting of time.Time instances into strings using format specifiers similar to those used in C's strftime function. Supports various locales including English, Japanese, Chinese, and many European languages.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var EnglishFormatter = &Formatter{englishLocale}
EnglishFormatter is a pre-initialized English locale formatter. It can be used directly without calling New() for English locale formatting.
Functions ¶
func EnFormat ¶
EnFormat formats time t using format f with English locale. This is a convenience function that uses the pre-initialized EnglishFormatter.
Parameters:
- f: Format string with strftime-compatible format specifiers
- t: Time value to format
Returns: Formatted time string in English locale
func EnFormatF ¶
EnFormatF formats time t using format f in English locale and outputs it to the provided io.Writer. This is a more efficient alternative to EnFormat when the output is to be written directly.
Parameters:
- o: io.Writer to write the formatted output to
- f: Format string with strftime-compatible format specifiers
- t: Time value to format
Returns: Error if writing to the io.Writer fails
func Format ¶
Format is a shortcut to format a date in a given locale easily. Best performance is achieved by using language constants such as language.AmericanEnglish or language.French.
Parameters:
- l: Language tag to determine the locale for formatting
- f: Format string with strftime-compatible format specifiers
- t: Time value to format
Returns: Formatted time string according to the specified locale and format
Types ¶
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
Formatter represents a time formatter with specific locale settings. It handles the formatting of time values according to the specified locale.
func New ¶
New creates a new Formatter by matching given language tags against known tags. If multiple language tags are provided, the best matching locale will be selected.
One sample use is as follows:
t, q, err := language.ParseAcceptLanguage(r.Header.Get("Accept-Language"))
f := strftime.New(t...)
Parameters:
- l: One or more language tags to match against known locales
Returns: A new Formatter instance configured for the best matching locale
func (*Formatter) AppendFormat ¶
AppendFormat is like Format but appends the textual representation to b and returns the extended buffer. This is more efficient when building strings as it avoids unnecessary allocations.
Parameters:
- b: Byte slice to append the formatted time to
- f: Format string with strftime-compatible format specifiers
- t: Time value to format
Returns: The extended byte slice containing the original content followed by the formatted time
func (*Formatter) Format ¶
Format formats time using provided format, and returns a string. Uses the locale associated with this Formatter.
Parameters:
- f: Format string with strftime-compatible format specifiers
- t: Time value to format
Returns: Formatted time string according to this Formatter's locale
func (*Formatter) FormatF ¶
FormatF formats time using provided format, and outputs it to the provided io.Writer. This is more efficient than Format when the output is to be written directly.
Parameters:
- o: io.Writer to write the formatted output to
- f: Format string with strftime-compatible format specifiers
- t: Time value to format
Returns: Error if writing to the io.Writer fails
Source Files