timestring

README

go-timestring

go-timestring is a Go package that provides human-readable formatters for time.Duration. It offers different ways to represent durations, suitable for various display needs, such as long, verbose formats or short, abbreviated ones.

Installation

go get github.com/na4ma4/go-timestring

Usage

The package provides several pre-configured formatters. You can use them directly or customize them with options.

Formatters

LongProcess

The LongProcess formatter is designed for displaying durations in a full, human-readable format, similar to how one might describe uptime for a server or a long-running process.

Default Behavior:

• Displays time units in their full names (e.g., "days", "hours", "minutes", "seconds").
• Includes spaces between values, unit names, and different time unit parts.
• For durations less than a second, it will show "0 seconds" by default.

Example:

package main

import (
	"fmt"
	"time"
	"github.com/na4ma4/go-timestring"
)

func main() {
	duration1, _ := time.ParseDuration("49h15m30s100ms")
	fmt.Println(timestring.LongProcess.String(duration1))
	// Output: 2 days 1 hour 15 minutes 30 seconds

	duration2 := 500 * time.Millisecond
	fmt.Println(timestring.LongProcess.String(duration2))
	// Output: 0 seconds
}

ShortProcess and Absolute (New)

The ShortProcess formatter provides a concise, abbreviated representation of durations. It's suitable for contexts where space is limited, but a clear representation of the duration is still needed.

Default Behavior:

• Uses abbreviated unit names (e.g., "d", "h", "m", "s", "ms").
• Omits time units that have a zero value.
• Includes spaces between different time unit parts (e.g., "1d 2h").
• For a zero duration or durations that round down to zero for all its units (e.g. <1ms), it displays "0s".

The Absolute formatter provides an absolute, precise and concise abbreviated representation of durations. It's suitable where sub-ms times are required.

Example:

package main

import (
	"fmt"
	"time"
	"github.com/na4ma4/go-timestring"
)

func main() {
	duration1, _ := time.ParseDuration("49h15m30s100ms") // 2 days, 1 hour, 15 minutes, 30 seconds, 100 milliseconds
	fmt.Println(timestring.ShortProcess.String(duration1))
	// Output: 2d 1h 15m 30s 100ms

	duration2 := 2*time.Hour + 30*time.Minute
	fmt.Println(timestring.ShortProcess.String(duration2))
	// Output: 2h 30m

	duration3 := 5 * time.Second
	fmt.Println(timestring.ShortProcess.String(duration3))
	// Output: 5s

	duration4 := 500 * time.Millisecond
	fmt.Println(timestring.ShortProcess.String(duration4))
	// Output: 500ms

	duration5 := time.Duration(0)
	fmt.Println(timestring.ShortProcess.String(duration5))
	// Output: 0s

	duration6 := 100 * time.Nanosecond
	fmt.Println(timestring.ShortProcess.String(duration6))
	// Output: 0s
	fmt.Println(timestring.Absolute.String(duration6))
	// Output: 100ns
}

Customization Options

Both formatters implement the Formatter interface, which includes an Option() method. This method allows for customization of the output string.

Available options:

• timestring.NoSpaces: Removes spaces between unit parts (e.g., "1d2h3m" instead of "1d 2h 3m").
• timestring.NoUnitSpaces: Removes spaces between the numeric value and its unit name (e.g., "1day" instead of "1 day"). Note: For abbreviated formats like ShortProcess or LongProcess with Abbreviated option, this has no visible effect as "1d" already has no space.
• timestring.Abbreviated: (Mainly for LongProcess) Uses abbreviated unit names (e.g., "d", "h", "m", "s"). ShortProcess is always abbreviated.
• timestring.ShowMSOnSeconds: (For LongProcess) Displays milliseconds when the duration is less than 60 seconds.

Option Usage Example:

package main

import (
	"fmt"
	"time"
	"github.com/na4ma4/go-timestring"
)

func main() {
	duration, _ := time.ParseDuration("25h30m") // 1 day, 1 hour, 30 minutes

	// LongProcess with NoSpaces and Abbreviated
	formattedLong := timestring.LongProcess.Option(
		timestring.NoSpaces,
		timestring.Abbreviated,
	).String(duration)
	fmt.Println(formattedLong) // Output: 1d1h30m

	// ShortProcess with NoSpaces
	formattedShort := timestring.ShortProcess.Option(
		timestring.NoSpaces,
	).String(duration)
	fmt.Println(formattedShort) // Output: 1d1h30m
}

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

(The internal structure of LongProcessFormatter was recently refactored for clarity and maintainability, without altering its public API.)

Documentation

Overview

Package timestring provides some helper functions for displaying time in a human readable way.

Index

• type AbsoluteFormatter
  • func (s AbsoluteFormatter) Option(opts ...FormatterOption) Formatter
  • func (s AbsoluteFormatter) String(td time.Duration) string
• type Duration
  • func TimeDurationToDuration(td time.Duration) Duration
• type Formatter
• type FormatterOption
• type LongProcessFormatter
  • func (a LongProcessFormatter) Option(opts ...FormatterOption) Formatter
  • func (a LongProcessFormatter) String(td time.Duration) string
• type ShortProcessFormatter
  • func (s ShortProcessFormatter) Option(opts ...FormatterOption) Formatter
  • func (s ShortProcessFormatter) String(td time.Duration) string

Examples

• AbsoluteFormatter.String

Types

type AbsoluteFormatter

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

AbsoluteFormatter is a Absolute Formatter. It provides a concise and precise representation of time.Duration, always using abbreviated units and omitting zero-value units.

func (AbsoluteFormatter) Option

func (s AbsoluteFormatter) Option(opts ...FormatterOption) Formatter

Option returns a Absolute Formatter with the applied options. For AbsoluteFormatter, Abbreviated is always true. ShowMSOnSeconds is not applicable.

func (AbsoluteFormatter) String

func (s AbsoluteFormatter) String(td time.Duration) string

String returns a human readable string using the Absolute Formatter. It always uses abbreviated units and omits zero-value units.

Example: "1d 2h 3m 4s", "2h 3m", "4s", "0s".

Example

ExampleAbsoluteFormatter_String demonstrates the usage of AbsoluteFormatter's String method.

package main

import (
	"fmt"
	"time"

	"github.com/na4ma4/go-timestring"
)

func main() {
	d, _ := time.ParseDuration("49h15m30s")
	fmt.Println(timestring.Absolute.String(d))
}

Output:
2d 1h 15m 30s

type Duration

type Duration struct {
	Days         int64
	Hours        int64
	Minutes      int64
	Seconds      int64
	Milliseconds int64
	Microseconds int64
	Nanoseconds  int64
}

Duration contains the absolute number of each field with all fields adding up to the total duration, so Hours is only the amount of hours to be displayed, unlike (time.Duration).Hours().

func TimeDurationToDuration

func TimeDurationToDuration(td time.Duration) Duration

TimeDurationToDuration converts a time.Duration to the timestring.Duration for easier display of durations.

type Formatter

type Formatter interface {
	Option(...FormatterOption) Formatter
	String(time.Duration) string
}

Formatter is the interface that any timestring formatter should match.

var Absolute Formatter = AbsoluteFormatter{/* contains filtered or unexported fields */}

Absolute is the ready-to-use Absolute Formatter.

var LongProcess Formatter = LongProcessFormatter{}

LongProcess is the ready-to-use Long Process Formatter.

var ShortProcess Formatter = ShortProcessFormatter{/* contains filtered or unexported fields */}

ShortProcess is the ready-to-use Short Process Formatter.

type FormatterOption

type FormatterOption uint

FormatterOption is a list of options that can be applied to the standard formatters.

const (
	// NoSpaces is a FormatterOption that tells the formatter to ignore spaces between values.
	NoSpaces FormatterOption = iota

	// NoUnitSpaces is a FormatterOption that tells the formatter to ignore spaces betwee values and
	// units.
	NoUnitSpaces

	// Abbreviated  is a FormatterOption that tells the formatter to abbreviate the units
	// (eg. "d" instead of "days").
	Abbreviated

	// ShowMSOnSeconds is a FormatterOption that tells the formatter to show milliseconds when
	// the value is less than a minute (59 seconds or less).
	ShowMSOnSeconds
)

type LongProcessFormatter

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

LongProcessFormatter is a Long Process Formatter.

It is a formatter that handles processes that would be considered long running, like displaying the uptime of a server or service.

func (LongProcessFormatter) Option

func (a LongProcessFormatter) Option(opts ...FormatterOption) Formatter

Option returns a Long Process Formatter with the applied options.

func (LongProcessFormatter) String

func (a LongProcessFormatter) String(td time.Duration) string

String returns a human readable string using the Long Process Formatter. It formats the duration into days, hours, minutes, seconds, and milliseconds, with options for abbreviated output, no spaces, and showing milliseconds on seconds.

type ShortProcessFormatter

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

ShortProcessFormatter is a Short Process Formatter. It provides a concise representation of time.Duration, always using abbreviated units and omitting zero-value units.

func (ShortProcessFormatter) Option

func (s ShortProcessFormatter) Option(opts ...FormatterOption) Formatter

Option returns a Short Process Formatter with the applied options. For ShortProcessFormatter, Abbreviated is always true. ShowMSOnSeconds is not applicable.

func (ShortProcessFormatter) String

func (s ShortProcessFormatter) String(td time.Duration) string

String returns a human readable string using the Short Process Formatter. It always uses abbreviated units and omits zero-value units.

Example: "1d 2h 3m 4s", "2h 3m", "4s", "0s".