timeline

Documentation

Overview

Package timeline defines the basic types of a timeline.

Index

• Variables
• func Bound(tl TL) (first, last time.Time, exists bool)
• func Empty(tl TL) bool
• func Equal(a, b TL) bool
• func EqualExplain(a, b TL) (bool, string)
• type AddTL
• type Ater
• type BoundTL
• type EmptyTL
• type FilterTL
• type MatchFunc
• type RemoveTL
• type SliceTL
• type TL
  • func Filter(tl TL, matches MatchFunc) TL
  • func FromSlice(s []Ater) TL
  • func Slice(tl TL, from, to time.Time) TL
  • func Zero() TL
• type WriteTL

Examples

• AddTL
• RemoveTL

Variables

var MaxTime = time.Unix(1<<63-1-unixToInternal, 999999999)

MaxTime is the largest time after MinTime where durations don't overflow.

var MinTime = time.Time{}

MinTime is a sensible time for which timeline operations make sense. Timelines compare times to order them, these values prevent overflows during these operations.

Functions

func Bound

func Bound(tl TL) (first, last time.Time, exists bool)

Bound returns the first and last event time of tl, if they exist.

If tl implements BoundTl, Bound calls tl.Bound. Otherwise Bound attempts to find the first and last events by calling Previous and Next using MinTime and MaxTime.

func Empty

func Empty(tl TL) bool

Empty returns true if there are no events in the timeline.

If tl implements EmptyTL, Empty calls tl.Empty. Otherwise Empty uses Bound to check for existence.

func Equal

func Equal(a, b TL) bool

Equal compares two TLs for equality.

func EqualExplain

func EqualExplain(a, b TL) (bool, string)

EqualExplain compares two TLs for equality, returning a reason if they aren't equal.

Types

type AddTL

type AddTL interface {
	TL
	// Add adds the given entries to this TL at the time specified by t.
	Add(t time.Time, entries ...interface{})
}

AddTL is a TL with an Add method.

Add does not have a fallback mechanism, so no Add utility function exists for this feature. To add to a TL, explicitly cast the TL to an AddTL and call Add directly.

Example

tl := writableTL()
if wtl, ok := tl.(AddTL); ok {
	wtl.Add(time.Now(), entries...)
}

type Ater

type Ater interface {
	// At returns the time this object is at.
	At() time.Time
}

Ater provides the At method for converting to a Time.

type BoundTL

type BoundTL interface {
	TL
	// Bound returns the first and last event time, if they exist.
	Bound() (first, last time.Time, exists bool)
}

BoundTL is a TL with a Bound method.

type EmptyTL

type EmptyTL interface {
	TL
	// Empty return true if there are no event in the timeline.
	Empty() bool
}

EmptyTL is a TL with an Empty method.

type FilterTL

type FilterTL interface {
	Filter(matches MatchFunc) TL
}

FilterTL is a TL with a Filter method.

type MatchFunc

type MatchFunc func(t time.Time, e interface{}) bool

MatchFunc returns true if the element at time t should be included in the result.

type RemoveTL

type RemoveTL interface {
	TL
	// Remove removes the entries from the TL at the time specified by t.
	Remove(t time.Time, entries ...interface{})
}

RemoveTL is a TL with a Remove method.

Remove does not have a fallback mechanism, so no Remove utility function exists for this feature. To remove from a TL, explicitly cast the TL to a RemoveTL and call Remove directly.

Example

tl := writableTL()
if wtl, ok := tl.(RemoveTL); ok {
	wtl.Remove(time.Unix(1000, 0), entries...)
}

type SliceTL

type SliceTL interface {
	TL
	// Slice returns a TL containing only events >=from and <to.
	Slice(from, to time.Time) TL
}

SliceTL is a TL with a Slice method.

type TL

type TL interface {
	// At returns all the events at the specific time.
	At(t time.Time) []interface{}

	// Previous returns the newest time with events < t on this TL.
	Previous(t time.Time) (previous time.Time, exists bool)
	// Next returns the oldest time with events > t on this TL.
	Next(t time.Time) (next time.Time, exists bool)
}

TL implements an ordered set of events, a timeline.

func Filter

func Filter(tl TL, matches MatchFunc) TL

Filter returns a TL that only includes entries where MatchFunc returns true.

If tl is a FilterTL, Filter returns tl.Filter. Otherwise Filter returns a new TL that acts as if no entries exist that MatchFunc returns false for.

func FromSlice

func FromSlice(s []Ater) TL

FromSlice creates a TL using a []Ater. This will sort s in place by the results of calling s[i].At().

func Slice

func Slice(tl TL, from, to time.Time) TL

Slice returns a TL containing only tl events >=from and <to.

If tl implements SliceTL, Slice calls tl.Slice. Otherwise Slice creates a new TL that excludes events outside the range.

func Zero

func Zero() TL

Zero returns an empty TL. The returned TL will be nil.

type WriteTL

type WriteTL interface {
	AddTL
	RemoveTL
}

WriteTL is the interface that groups AddTL and RemoveTL