timefmt

README

timefmt-go

Efficient time formatting library (strftime, strptime) for Golang

This is a Go language package for formatting and parsing date time strings.

package main

import (
	"fmt"
	"log"

	"github.com/itchyny/timefmt-go"
)

func main() {
	t, err := timefmt.Parse("2020/07/24 09:07:29", "%Y/%m/%d %H:%M:%S")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(t) // 2020-07-24 09:07:29 +0000 UTC

	str := timefmt.Format(t, "%Y/%m/%d %H:%M:%S")
	fmt.Println(str) // 2020/07/24 09:07:29

	str = timefmt.Format(t, "%a, %d %b %Y %T %z")
	fmt.Println(str) // Fri, 24 Jul 2020 09:07:29 +0000
}

Please refer to man 3 strftime and man 3 strptime for formatters. As an extension, %f directive is supported for zero-padded microseconds, which originates from Python. Note that E and O modifier characters are not supported.

Comparison to other libraries

• This library
  • provides both formatting and parsing functions in pure Go language,
  • depends only on the Go standard libraries not to grow up dependency.
• Format (strftime) implements glibc extensions including
  • width specifier like %6Y %10B %4Z (limited to 1024 bytes),
  • omitting padding modifier like %-y-%-m-%-d,
  • space padding modifier like %_y-%_m-%_d,
  • upper case modifier like %^a %^b,
  • swapping case modifier like %#Z,
  • time zone offset modifier like %:z %::z %:::z,
  • and its performance is very good.
• AppendFormat is provided for reducing allocations.
• Parse (strptime) allows to parse
  • composed directives like %F %T,
  • century years like %C %y,
  • week directives like %W %a and %G-W%V-%u.
• ParseInLocation is provided for configuring the default location.

Bug Tracker

Report bug at Issues・itchyny/timefmt-go - GitHub.

Author

itchyny (https://github.com/itchyny)

License

This software is released under the MIT License, see LICENSE.

Documentation

Overview

Package timefmt provides functions for formatting and parsing date time strings.

Index

• func AppendFormat(buf []byte, t time.Time, format string) []byte
• func Format(t time.Time, format string) string
• func Parse(source, format string) (t time.Time, err error)
• func ParseInLocation(source, format string, loc *time.Location) (t time.Time, err error)

Examples

• AppendFormat
• Format
• Parse
• ParseInLocation

Functions

func AppendFormat

func AppendFormat(buf []byte, t time.Time, format string) []byte

AppendFormat appends formatted time string to the buffer.

Example

t := time.Date(2020, time.July, 24, 9, 7, 29, 0, time.UTC)
buf := make([]byte, 0, 64)
buf = append(buf, '(')
buf = timefmt.AppendFormat(buf, t, "%Y-%m-%d %H:%M:%S")
buf = append(buf, ')')
fmt.Println(string(buf))

Output:

(2020-07-24 09:07:29)

func Format

func Format(t time.Time, format string) string

Format time to string using the format.

Example

t := time.Date(2020, time.July, 24, 9, 7, 29, 0, time.UTC)
str := timefmt.Format(t, "%Y-%m-%d %H:%M:%S")
fmt.Println(str)

Output:

2020-07-24 09:07:29

func Parse

func Parse(source, format string) (t time.Time, err error)

Parse time string using the format.

Example

str := "2020-07-24 09:07:29"
t, err := timefmt.Parse(str, "%Y-%m-%d %H:%M:%S")
if err != nil {
	log.Fatal(err)
}
fmt.Println(t)

Output:

2020-07-24 09:07:29 +0000 UTC

func ParseInLocation

func ParseInLocation(source, format string, loc *time.Location) (t time.Time, err error)

ParseInLocation parses time string with the default location. The location is also used to parse the time zone name (%Z).

Example

loc := time.FixedZone("JST", 9*60*60)
str := "2020-07-24 09:07:29"
t, err := timefmt.ParseInLocation(str, "%Y-%m-%d %H:%M:%S", loc)
if err != nil {
	log.Fatal(err)
}
fmt.Println(t)

Output:

2020-07-24 09:07:29 +0900 JST