interval

Documentation

Overview

Package interval implements an interval tree based on an augmented Left-Leaning Red Black tree.

Index

• Constants
• Variables
• func RangeGroupsOverlap(rg1, rg2 RangeGroup) bool
• type Comparable
  • func (c Comparable) Compare(o Comparable) int
  • func (c Comparable) Equal(o Comparable) bool
• type Interface
• type Node
• type Operation
• type Range
  • func (r Range) Equal(other Range) bool
  • func (r Range) OverlapExclusive(other Range) bool
  • func (r Range) OverlapInclusive(other Range) bool
  • func (r Range) String() string
• type RangeGroup
  • func NewRangeList() RangeGroup
  • func NewRangeTree() RangeGroup
• type RangeGroupIterator
• type Tree
  • func (t *Tree) AdjustRanges()
  • func (t *Tree) Ceil(q Interface) (o Interface, err error)
  • func (t *Tree) Delete(e Interface, fast bool) (err error)
  • func (t *Tree) DeleteMax(fast bool)
  • func (t *Tree) DeleteMin(fast bool)
  • func (t *Tree) Do(fn Operation) bool
  • func (t *Tree) DoMatching(fn Operation, r Range) bool
  • func (t *Tree) DoMatchingReverse(fn Operation, r Range) bool
  • func (t *Tree) DoReverse(fn Operation) bool
  • func (t *Tree) Floor(q Interface) (o Interface, err error)
  • func (t *Tree) Get(r Range) (o []Interface)
  • func (t *Tree) GetWithOverlapper(r Range, overlapper func(Range, Range) bool) (o []Interface)
  • func (t *Tree) Insert(e Interface, fast bool) (err error)
  • func (t *Tree) Iterator() TreeIterator
  • func (t *Tree) Len() int
  • func (t *Tree) Max() Interface
  • func (t *Tree) Min() Interface
• type TreeIterator
  • func (ti *TreeIterator) Next() (i Interface, ok bool)

Constants

const (
	TD234 = iota
	BU23
)

Operation mode of the underlying LLRB tree.

const Mode = BU23

Mode .

Variables

var ErrEmptyRange = errors.New("interval: empty range")

ErrEmptyRange is returned if an interval is used where the start value is equal to the end value.

var ErrInvertedRange = errors.New("interval: inverted range")

ErrInvertedRange is returned if an interval is used where the start value is greater than the end value.

Functions

func RangeGroupsOverlap

func RangeGroupsOverlap(rg1, rg2 RangeGroup) bool

RangeGroupsOverlap determines if two RangeGroups contain any overlapping Ranges or if they are fully disjoint. It does so by iterating over the RangeGroups together and comparing subsequent ranges.

Types

type Comparable

type Comparable []byte

A Comparable is a type that describes the ends of a Range.

func (Comparable) Compare

func (c Comparable) Compare(o Comparable) int

Compare returns a value indicating the sort order relationship between the receiver and the parameter.

Given c = a.Compare(b):

c < 0 if a < b;
c == 0 if a == b; and
c > 0 if a > b.

func (Comparable) Equal

func (c Comparable) Equal(o Comparable) bool

Equal returns a boolean indicating if the given comparables are equal to each other. Note that this has measurably better performance than Compare() == 0, so it should be used when only equality state is needed.

type Interface

type Interface interface {
	Range() Range
	// Returns a unique ID for the element.
	// TODO(nvanbenschoten): Should this be changed to an int64?
	ID() uintptr
}

An Interface is a type that can be inserted into a Tree.

type Node

type Node struct {
	Elem        Interface
	Range       Range
	Left, Right *Node
	Color       llrb.Color
}

A Node represents a node in a Tree.

type Operation

type Operation func(Interface) (done bool)

An Operation is a function that operates on an Interface. If done is returned true, the Operation is indicating that no further work needs to be done and so the Do function should traverse no further.

type Range

type Range struct {
	Start, End Comparable
}

A Range is a type that describes the basic characteristics of an interval.

func (Range) Equal

func (r Range) Equal(other Range) bool

Equal returns whether the two ranges are equal.

func (Range) OverlapExclusive

func (r Range) OverlapExclusive(other Range) bool

OverlapExclusive returns whether the two provided ranges overlap. It defines overlapping as a pair of ranges that share a segment of the keyspace, with the start keys treated as inclusive and the end keys treated as exclusive.

func (Range) OverlapInclusive

func (r Range) OverlapInclusive(other Range) bool

OverlapInclusive returns whether the two provided ranges overlap. It defines overlapping as a pair of ranges that share a segment, with both start and end keys treated as inclusive values.

func (Range) String

func (r Range) String() string

String implements the Stringer interface.

type RangeGroup

type RangeGroup interface {
	// Add will attempt to add the provided Range to the RangeGroup,
	// returning whether the addition increased the range of the group
	// or not.
	Add(Range) bool
	// Sub will attempt to remove the provided Range from the RangeGroup,
	// returning whether the subtraction reduced the range of the group
	// or not.
	Sub(Range) bool
	// Clear clears all ranges from the RangeGroup, resetting it to be
	// used again.
	Clear()
	// Overlaps returns whether the provided Range is partially contained
	// within the group of Ranges in the RangeGroup.
	Overlaps(Range) bool
	// Encloses returns whether the provided Range is fully contained
	// within the group of Ranges in the RangeGroup.
	Encloses(Range) bool
	// ForEach calls the provided function with each Range stored in
	// the group. An error is returned indicating whether the callback
	// function saw an error, whereupon the Range iteration will halt
	// (potentially prematurely) and the error will be returned from ForEach
	// itself. If no error is returned from the callback, the method
	// will visit all Ranges in the group before returning a nil error.
	ForEach(func(Range) error) error
	// Iterator returns an iterator to visit each Range stored in the
	// group, in-order. It is not safe to mutate the RangeGroup while
	// iteration is being performed.
	Iterator() RangeGroupIterator
	// Len returns the number of Ranges currently within the RangeGroup.
	// This will always be equal to or less than the number of ranges added,
	// as ranges that overlap will merge to produce a single larger range.
	Len() int
	fmt.Stringer
}

RangeGroup represents a set of possibly disjointed Ranges. The interface exposes methods to manipulate the group by adding and subtracting Ranges. All methods requiring a Range will panic if the provided range is inverted or empty.

One use case of the interface is to add ranges to the group and observe whether the addition increases the size of the group or not, indicating whether the new range's interval is redundant, or if it is needed for the full composition of the group. Because the RangeGroup builds as more ranges are added, insertion order of the ranges is critical. For instance, if two identical ranges are added, only the first to be added with Add will return true, as it will be the only one to expand the group.

Another use case of the interface is to add and subtract ranges as needed to the group, allowing the internals of the implementation to coalesce and split ranges when needed to factor the group to its minimum number of disjoint ranges.

func NewRangeList

func NewRangeList() RangeGroup

NewRangeList constructs a linked-list backed RangeGroup.

func NewRangeTree

func NewRangeTree() RangeGroup

NewRangeTree constructs an interval tree backed RangeGroup.

type RangeGroupIterator

type RangeGroupIterator interface {
	// Next returns the next Range in the RangeGroup. It returns false
	// if there are no more Ranges.
	Next() (Range, bool)
}

RangeGroupIterator is an iterator that walks in-order over a RangeGroup.

type Tree

type Tree struct {
	Root       *Node                   // root node of the tree.
	Count      int                     // number of elements stored.
	Overlapper func(Range, Range) bool // determines how to define Range overlap.
}

A Tree manages the root node of an interval tree. Public methods are exposed through this type.

func (*Tree) AdjustRanges

func (t *Tree) AdjustRanges()

AdjustRanges fixes range fields for all Nodes in the Tree. This must be called before Get or DoMatching* is used if fast insertion or deletion has been performed.

func (*Tree) Ceil

func (t *Tree) Ceil(q Interface) (o Interface, err error)

Ceil returns the smallest value equal to or greater than the query q according to q.Start.Compare(), with ties broken by comparison of ID() values.

func (*Tree) Delete

func (t *Tree) Delete(e Interface, fast bool) (err error)

Delete deletes the element e if it exists in the Tree.

func (*Tree) DeleteMax

func (t *Tree) DeleteMax(fast bool)

DeleteMax deletes the right-most interval.

func (*Tree) DeleteMin

func (t *Tree) DeleteMin(fast bool)

DeleteMin deletes the left-most interval.

func (*Tree) Do

func (t *Tree) Do(fn Operation) bool

Do performs fn on all intervals stored in the tree. A boolean is returned indicating whether the Do traversal was interrupted by an Operation returning true. If fn alters stored intervals' sort relationships, future tree operation behaviors are undefined.

func (*Tree) DoMatching

func (t *Tree) DoMatching(fn Operation, r Range) bool

DoMatching performs fn on all intervals stored in the tree that match r according to t.Overlapper, with Overlapper() used to guide tree traversal, so DoMatching() will outperform Do() with a called conditional function if the condition is based on sort order, but can not be reliably used if the condition is independent of sort order. A boolean is returned indicating whether the Do traversal was interrupted by an Operation returning true. If fn alters stored intervals' sort relationships, future tree operation behaviors are undefined.

func (*Tree) DoMatchingReverse

func (t *Tree) DoMatchingReverse(fn Operation, r Range) bool

DoMatchingReverse performs fn on all intervals stored in the tree that match r according to t.Overlapper, with Overlapper() used to guide tree traversal, so DoMatching() will outperform Do() with a called conditional function if the condition is based on sort order, but can not be reliably used if the condition is independent of sort order. A boolean is returned indicating whether the Do traversal was interrupted by an Operation returning true. If fn alters stored intervals' sort relationships, future tree operation behaviors are undefined.

func (*Tree) DoReverse

func (t *Tree) DoReverse(fn Operation) bool

DoReverse performs fn on all intervals stored in the tree, but in reverse of sort order. A boolean is returned indicating whether the Do traversal was interrupted by an Operation returning true. If fn alters stored intervals' sort relationships, future tree operation behaviors are undefined.

func (*Tree) Floor

func (t *Tree) Floor(q Interface) (o Interface, err error)

Floor returns the largest value equal to or less than the query q according to q.Start.Compare(), with ties broken by comparison of ID() values.

func (*Tree) Get

func (t *Tree) Get(r Range) (o []Interface)

Get returns a slice of Interfaces that overlap r in the Tree.

func (*Tree) GetWithOverlapper

func (t *Tree) GetWithOverlapper(r Range, overlapper func(Range, Range) bool) (o []Interface)

GetWithOverlapper returns a slice of Interfaces that overlap r in the Tree using the provided overlapper function.

func (*Tree) Insert

func (t *Tree) Insert(e Interface, fast bool) (err error)

Insert inserts the Interface e into the Tree. Insertions may replace existing stored intervals.

func (*Tree) Iterator

func (t *Tree) Iterator() TreeIterator

Iterator creates an iterator to iterate over all intervals stored in the tree, in-order.

func (*Tree) Len

func (t *Tree) Len() int

Len returns the number of intervals stored in the Tree.

func (*Tree) Max

func (t *Tree) Max() Interface

Max returns the right-most interval stored in the tree.

func (*Tree) Min

func (t *Tree) Min() Interface

Min returns the left-most interval stored in the tree.

type TreeIterator

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

TreeIterator iterates over all intervals stored in the Tree, in-order.

func (*TreeIterator) Next

func (ti *TreeIterator) Next() (i Interface, ok bool)

Next moves the iterator to the next Node in the Tree and returns the node's Elem. The method returns false if no Nodes remain in the Tree.