epok

README

epok

epok is a set of tools for dealing with time in Go.

Documentation

Overview

Package epok provides a set of tools dealing with time.

Index

• type Converter
• type Frequency
  • func (freq Frequency) String() string
• type Range
  • func RangeFrom(start, stop, step int) Range
• type Rule
• type Rules
• type Ticks
  • func (t Ticks) Ticks(min, max float64) []plot.Tick
• type UTCUnixTimeConverter
  • func (UTCUnixTimeConverter) FromTime(t time.Time) float64
  • func (UTCUnixTimeConverter) ToTime(v float64) time.Time

Examples

• Ticks (YearlyPlot)
• Ticks (YearlyPlotAutoTicks)

Types

type Converter

type Converter interface {
	FromTime(t time.Time) float64
	ToTime(v float64) time.Time
}

Converter converts values back and forth between float64 and time.Time.

type Frequency

type Frequency byte

Frequency describes the ticks frequency of a time axis.

const (
	Yearly Frequency
	Monthly
	Weekly
	Daily
	Hourly
	Minutely
	Secondly
	Microsecondly
)

func (Frequency) String

func (freq Frequency) String() string

type Range

type Range struct {
	Start int
	Stop  int
	Step  int
}

Range describes a logical range [start, stop).

func RangeFrom

func RangeFrom(start, stop, step int) Range

RangeFrom creates a new range [start, stop), with the provided step.

type Rule

type Rule struct {
	Freq  Frequency
	Range Range
}

type Rules

type Rules struct {
	Major Rule
	Minor Rule

	MinTicks int // minimum number of ticks
	MaxTicks int // maximum number of ticks
}

type Ticks

type Ticks struct {
	// Ruler describes how minor and major ticks should be generated.
	Ruler Rules

	// Format is the textual representation of the time value.
	// If empty, time.RFC3339 will be used
	Format string

	// Converter converts back and forth between float64 and time.Time.
	// If nil, UTCUnixTimeConverter is used.
	Converter Converter
}

Ticks is suitable for axes representing time values.

Example (YearlyPlot)

package main

import (
	"image/color"
	"log"
	"time"

	"git.sr.ht/~sbinet/epok"
	"gonum.org/v1/plot"
	"gonum.org/v1/plot/plotter"
	"gonum.org/v1/plot/vg"
	"gonum.org/v1/plot/vg/draw"
)

func main() {
	cnv := epok.UTCUnixTimeConverter{}

	p := plot.New()
	p.Title.Text = "Time series"
	p.Y.Label.Text = "Goroutines"

	p.Y.Min = 0
	p.Y.Max = 4
	p.X.AutoRescale = true
	p.X.Tick.Marker = epok.Ticks{
		Ruler: epok.Rules{
			Major: epok.Rule{
				Freq:  epok.Yearly,
				Range: epok.Range{Step: 5},
			},
		},
		Format:    "2006-01-02\n15:04:05",
		Converter: cnv,
	}

	xysFrom := func(vs ...float64) plotter.XYs {
		o := make(plotter.XYs, len(vs))
		for i := range o {
			o[i].X = vs[i]
			o[i].Y = float64(i + 1)
		}
		return o
	}
	data := xysFrom(
		cnv.FromTime(parse("2010-02-03 01:02:03")),
		cnv.FromTime(parse("2015-02-03 04:05:06")),
		cnv.FromTime(parse("2020-02-03 07:08:09")),
	)

	line, pnts, err := plotter.NewLinePoints(data)
	if err != nil {
		log.Fatalf("could not create plotter: %+v", err)
	}

	line.Color = color.RGBA{B: 255, A: 255}
	pnts.Shape = draw.CircleGlyph{}
	pnts.Color = color.RGBA{R: 255, A: 255}

	p.Add(line, pnts, plotter.NewGrid())

	err = p.Save(20*vg.Centimeter, 10*vg.Centimeter, "testdata/yearly.png")
	if err != nil {
		log.Fatalf("could not save plot: %+v", err)
	}
}

func parse(vs ...string) time.Time {
	format := "2006-01-02 15:04:05"
	if len(vs) > 1 {
		format = vs[1]
	}
	t, err := time.Parse(format, vs[0])
	if err != nil {
		panic(err)
	}
	return t
}

Example (YearlyPlotAutoTicks)

package main

import (
	"image/color"
	"log"
	"time"

	"git.sr.ht/~sbinet/epok"
	"gonum.org/v1/plot"
	"gonum.org/v1/plot/plotter"
	"gonum.org/v1/plot/vg"
	"gonum.org/v1/plot/vg/draw"
)

func main() {
	cnv := epok.UTCUnixTimeConverter{}

	p := plot.New()
	p.Title.Text = "Time series"
	p.Y.Label.Text = "Goroutines"

	p.Y.Min = 0
	p.Y.Max = 5
	p.X.AutoRescale = true
	p.X.Tick.Marker = epok.Ticks{
		Format:    "2006-01-02\n15:04:05",
		Converter: cnv,
	}

	xysFrom := func(vs ...float64) plotter.XYs {
		o := make(plotter.XYs, len(vs))
		for i := range o {
			o[i].X = vs[i]
			o[i].Y = float64(i + 1)
		}
		return o
	}
	data := xysFrom(
		cnv.FromTime(parse("2010-02-03 01:02:03")),
		cnv.FromTime(parse("2015-02-03 04:05:06")),
		cnv.FromTime(parse("2020-02-03 07:08:09")),
		cnv.FromTime(parse("2025-02-03 10:11:12")),
	)

	line, pnts, err := plotter.NewLinePoints(data)
	if err != nil {
		log.Fatalf("could not create plotter: %+v", err)
	}

	line.Color = color.RGBA{B: 255, A: 255}
	pnts.Shape = draw.CircleGlyph{}
	pnts.Color = color.RGBA{R: 255, A: 255}

	p.Add(line, pnts, plotter.NewGrid())

	err = p.Save(20*vg.Centimeter, 10*vg.Centimeter, "testdata/yearly_autoticks.png")
	if err != nil {
		log.Fatalf("could not save plot: %+v", err)
	}
}

func parse(vs ...string) time.Time {
	format := "2006-01-02 15:04:05"
	if len(vs) > 1 {
		format = vs[1]
	}
	t, err := time.Parse(format, vs[0])
	if err != nil {
		panic(err)
	}
	return t
}

func (Ticks) Ticks

func (t Ticks) Ticks(min, max float64) []plot.Tick

Ticks returns gonum/plot ticks in a specified range.

type UTCUnixTimeConverter

type UTCUnixTimeConverter struct{}

UTCUnixTimeConverter converts time values in UTC, with nanosecond precision.

func (UTCUnixTimeConverter) FromTime

func (UTCUnixTimeConverter) FromTime(t time.Time) float64

func (UTCUnixTimeConverter) ToTime

func (UTCUnixTimeConverter) ToTime(v float64) time.Time