rampart

README

go-rampart

Go port of the Haskell Rampart library by Taylor Fausak.

This package provides types and functions for defining intervals and determining how they relate to each other. This can be useful to determine if an event happened during a certain time frame, or if two time frames overlap (and if so, how exactly they overlap).

Install

go get github.com/francesconi/go-rampart

Examples

Ordered types

Any type that supports the operators < <= >= >.

a := rampart.NewInterval(2, 3)
b := rampart.NewInterval(3, 7)
rel := a.Relate(b)
// rel: RelationMeets

Any other type

NewIntervalFunc accepts any type as long as a comparison function is provided. The comparison function should return values as follows:

cmp(t1, t2) < 0 if t1 < t2
cmp(t1, t2) > 0 if t1 > t2
cmp(t1, t2) == 0 if t1 == t2

time.Time

func compareTimes(t1, t2 time.Time) int {
    return int(t1.Sub(t2))
}

a := rampart.NewIntervalFunc(
    time.Date(2022, time.April, 1, 0, 0, 0, 0, time.UTC),
    time.Date(2022, time.April, 8, 0, 0, 0, 0, time.UTC),
    compareTimes,
)
b := rampart.NewIntervalFunc(
    time.Date(2022, time.April, 6, 0, 0, 0, 0, time.UTC),
    time.Date(2022, time.April, 15, 0, 0, 0, 0, time.UTC),
    compareTimes,
)
rel := a.Relate(b)
// rel: RelationOverlaps

Documentation

Index

• type Interval
  • func NewInterval[T constraints.Ordered](x, y T) Interval[T]
  • func NewIntervalFunc[T any](x, y T, cmp func(T, T) int) Interval[T]
  • func (i Interval[T]) Greater() T
  • func (i Interval[T]) IsEmpty() bool
  • func (i Interval[T]) IsNonEmpty() bool
  • func (i Interval[T]) Lesser() T
  • func (x Interval[T]) Relate(y Interval[T]) Relation
• type Relation
  • func (r Relation) Invert() Relation

Types

type Interval

type Interval[T any] struct {
	// contains filtered or unexported fields
}

Interval represents two values, the lesser and the greater. Both must be of the same type.

func NewInterval

func NewInterval[T constraints.Ordered](x, y T) Interval[T]

NewInterval returns an Interval that uses the natural ordering of T for comparison.

func NewIntervalFunc

func NewIntervalFunc[T any](x, y T, cmp func(T, T) int) Interval[T]

NewIntervalFunc returns an Interval out of x and y so that the Interval can be sorted on construction by the given comparison function.

The comparison function should return values as follows:

cmp(t1, t2) < 0 if t1 < t2
cmp(t1, t2) > 0 if t1 > t2
cmp(t1, t2) == 0 if t1 == t2

For example, to compare time.Time instances,

NewIntervalFunc(t1, t2, func(t1, t2 time.Time) int { return int(t1.Sub(t2)) })

func (Interval[T]) Greater

func (i Interval[T]) Greater() T

Greater returns the greater value from an Interval.

func (Interval[T]) IsEmpty

func (i Interval[T]) IsEmpty() bool

IsEmpty returns true if the given Interval is empty, false otherwise. An Interval is empty if its lesser equals its greater.

func (Interval[T]) IsNonEmpty

func (i Interval[T]) IsNonEmpty() bool

IsNonEmpty returns true if the given Interval is non-empty, false otherwise. An Interval is non-empty if its lesser is not equal to its greater.

func (Interval[T]) Lesser

func (i Interval[T]) Lesser() T

Lesser returns the lesser value from an Interval.

func (Interval[T]) Relate

func (x Interval[T]) Relate(y Interval[T]) Relation

Relates tells you how Interval x relates to Interval y. Consult the Relation documentation for an explanation of all the possible results.

type Relation

type Relation int

Relation represents how two Intervals relate to each other.

const (
	RelationUnknown Relation = iota

	/*
		Interval x is before Interval y.

		    +---+
		    | x |
		    +---+
		          +---+
		          | y |
		          +---+
	*/
	RelationBefore

	/*
		Interval x meets Interval y.

		    +---+
		    | x |
		    +---+
		        +---+
		        | y |
		        +---+
	*/
	RelationMeets

	/*
		Interval x overlaps Interval y.

		    +---+
		    | x |
		    +---+
		      +---+
		      | y |
		      +---+
	*/
	RelationOverlaps

	/*
		Interval x is finished by Interval y.

		    +-----+
		    |  x  |
		    +-----+
		      +---+
		      | y |
		      +---+
	*/
	RelationFinishedBy

	/*
		Interval x contains Interval y.

		    +-------+
		    |   x   |
		    +-------+
		      +---+
		      | y |
		      +---+
	*/
	RelationContains

	/*
		Interval x starts Interval y.

		    +---+
		    | x |
		    +---+
		    +-----+
		    |  y  |
		    +-----+
	*/
	RelationStarts

	/*
		Interval x is equal to Interval y.

		    +---+
		    | x |
		    +---+
		    +---+
		    | y |
		    +---+
	*/
	RelationEqual

	/*
		Interval x is started by Interval y.

		    +-----+
		    |  x  |
		    +-----+
		    +---+
		    | y |
		    +---+
	*/
	RelationStartedBy

	/*
		Interval x is during Interval y.

		      +---+
		      | x |
		      +---+
		    +-------+
		    |   y   |
		    +-------+
	*/
	RelationDuring

	/*
		Interval x finishes Interval y.

		      +---+
		      | x |
		      +---+
		    +-----+
		    |  y  |
		    +-----+
	*/
	RelationFinishes

	/*
		Interval x is overlapped by Interval y.

		      +---+
		      | x |
		      +---+
		    +---+
		    | y |
		    +---+
	*/
	RelationOverlappedBy

	/*
		Interval x is met by Interval y.

		        +---+
		        | x |
		        +---+
		    +---+
		    | y |
		    +---+
	*/
	RelationMetBy

	/*
		Interval x is after Interval y.

		          +---+
		          | x |
		          +---+
		    +---+
		    | y |
		    +---+
	*/
	RelationAfter
)

func (Relation) Invert

func (r Relation) Invert() Relation

Inverts a Relation. Every Relation has an inverse.