tuesday

README

Tuesday: Ruby-Compatible Strftime for Go

Tuesday formats Go time.Time values with Ruby-compatible strftime format strings. It supports padding and case flags, field widths, fractional seconds, epoch time, and colon-delimited timezone offsets.

Tuesday was developed for use by Liquid and Gojekyll.

Install

go get github.com/osteele/tuesday@latest

Usage

package main

import (
	"fmt"
	"time"

	"github.com/osteele/tuesday"
)

func main() {
	value := time.Date(2026, 8, 11, 15, 4, 5, 123456789, time.UTC)
	formatted, err := tuesday.Strftime("%Y-%m-%d %H:%M:%S.%3N %:z", value)
	if err != nil {
		panic(err)
	}
	fmt.Println(formatted)
}

Output:

2026-08-11 15:04:05.123 +00:00

Compile formats that are used repeatedly. A compiled formatter is immutable and safe for concurrent use:

formatter, err := tuesday.Compile("%a, %b %d, %Y")
if err != nil {
	panic(err)
}
formatted := formatter.Format(value)

Compatibility

Tuesday targets the formatting behavior of Ruby 3.4 Time#strftime. Its differential test matrix also uses DateTime#strftime for %Q, which Ruby Time does not implement.

• Month and weekday names use Go's English names, corresponding to Ruby's C locale. Locale-specific names are not supported; E and O modifiers use the corresponding unmodified conversion.
• %Z uses the name attached to the Go time.Location. A numeric offset alone does not imply a timezone abbreviation.
• Unsupported directives are copied to the result unchanged.
• Supported field widths greater than 1 MiB return an error to prevent excessive allocation.
• %Q, %N, %L, %:z, %::z, and %:::z follow the corresponding Ruby DateTime, fractional-second, and timezone conventions.

The Ruby differential test is skipped when Ruby is unavailable. The checked-in Go tests remain sufficient to run the package test suite without Ruby.

Development

go test ./...
go test -fuzz=FuzzStrftime
go test -bench=. -benchmem

References

• Ruby 3.4 Time
• Ruby 3.4 DateTime

License

MIT License

Documentation

Overview

Package tuesday implements strftime formatting compatible with Ruby 3.4.

Index

• func Strftime(format string, t time.Time) (string, error)
• type Formatter
  • func Compile(format string) (*Formatter, error)
  • func (f *Formatter) Format(t time.Time) string

Examples

• Formatter.Format
• Strftime (Flags)
• Strftime (Timezone)

Functions

func Strftime

func Strftime(format string, t time.Time) (string, error)

Strftime formats t according to a Ruby-compatible strftime format. Unsupported directives are retained as literal text. Strftime returns an error if a supported directive requests a field width greater than 1 MiB.

Example (Flags)

t, _ := time.Parse(time.RFC822, "10 Jul 17 18:45 EDT")
s, _ := Strftime("%B %^B %m %_m %-m %6Y", t)
fmt.Println(s)

Output:
July JULY 07  7 7 002017

Example (Timezone)

t, _ := time.Parse(time.RFC822, "10 Jul 17 18:45 EDT")
s, _ := Strftime("%Z %z %:z %::z", t)
fmt.Println(s)

Output:
EDT -0400 -04:00 -04:00:00

Types

type Formatter

type Formatter struct {
	// contains filtered or unexported fields
}

Formatter is an immutable, reusable compiled strftime format. A Formatter is safe for concurrent use by multiple goroutines.

func Compile

func Compile(format string) (*Formatter, error)

Compile parses a strftime format for repeated use. Unsupported directives are retained as literal text. Compile returns an error when a supported directive requests a field width large enough to risk excessive allocation.

func (*Formatter) Format

func (f *Formatter) Format(t time.Time) string

Format formats t using the compiled format.

Example

formatter, _ := Compile("%a, %b %d, %Y")
value := time.Date(2026, 8, 11, 15, 4, 5, 0, time.UTC)
fmt.Println(formatter.Format(value))

Output:
Tue, Aug 11, 2026