README.md

Spaniel

Time span handling for Go

Spaniel contains functionality for timespan handling, specifically for merging overlapping timespans and finding the intersections between multiple timespans. It lets you specify the type of interval you want to use (open, closed), and provide handlers for when you want to add more functionality when merging/intersecting.

Install

This package is "go-gettable", just do:

go get github.com/senseyeio/spaniel

Basics

Spaniel operates on lists of timespans, where a timespan is represented as the interval between a start and end time. It has a built-in minimal timespan representation for convenience, or you can use your own type, so long as it implements the timespan.Span interface.

To import spaniel and create a new list of timespans:

package main

import (
	"fmt"
	timespan "github.com/senseyeio/spaniel"
	"time"
)

func main() {
	// Times at half-hourly intervals
	var t1 = time.Date(2018, 1, 30, 0, 0, 0, 0, time.UTC)
	var t2 = time.Date(2018, 1, 30, 0, 30, 0, 0, time.UTC)
	var t3 = time.Date(2018, 1, 30, 1, 0, 0, 0, time.UTC)
	var t4 = time.Date(2018, 1, 30, 1, 30, 0, 0, time.UTC)

	input := timespan.Spans{
		timespan.New(t1, t3),
		timespan.New(t2, t4),
	}
	fmt.Println(input)
}

You can then use the Union function to merge the timestamps:

union := input.Union()
fmt.Println(union[0].Start(), "->", union[0].End()) // 2018-01-30 00:00:00 +0000 UTC -> 2018-01-30 01:30:00 +0000 UTC

Or the Intersection function to find the overlaps:

intersection := input.Intersection()
fmt.Println(intersection[0].Start(), "->", intersection[0].End()) // 2018-01-30 00:30:00 +0000 UTC -> 2018-01-30 01:00:00 +0000 UTC

Types

timespan.New sets the span to be [) by default - i.e. including the left-most point, excluding the right-most. In other words, [1,2,3) and [3,4,5) do not overlap, but are contiguous. Instants are [] by default (they contain a single time).

If you would like to override these types, you can use NewWithTypes:

openSpan := timespan.NewWithTypes(t1, t3, timespan.Open, timespan.Open)

You can see a more involved example of types in examples/types/types.go

Handlers

If you need to use a more complex object, you can call UnionWithHandler and IntersectionWithHandler. There is an example of this in examples/handlers/handlers.go.

More Examples

All of the above examples are available in the examples folder.