trn

README

Time Ranges

Package trn introduces a Range type with useful methods to perform complex operations over time ranges.

Install and update

go get -u github.com/cappuccinotm/trn

Usage

rng := trn.New(time.Now(), 3 * time.Hour, trn.In(time.UTC))

betweenRng := trn.Between(time.Now(), time.Now().Add(3 * time.Hour), trn.In(time.UTC))

For more examples see test file.

Todo

• Make UTC and opts tests work in UTC location

Methods

• func New(start time.Time, duration time.Duration, opts ...Option) Range

  Creates a new Range with start at the given time and with the given duration.

• func Between(start, end time.Time, opts ...Option) (Range, error)

  Creates a new Range within the given time range. Between uses the location of the start time for the range. Returns ErrStartAfterEnd if the start time is later than the end.

• func (r Range) Stratify(duration time.Duration, interval time.Duration) ([]Range, error)

  Slices the range into smaller ones with fixed duration and fixed interval between their starts. In case if the last interval doesn't fit into the given duration, Stratify won't return it. Returns ErrZeroDurationInterval if the provided duration or interval is less or equal to zero.

Illustration

• func (r Range) Split(duration time.Duration, interval time.Duration) ([]Range, error)

  Slices the range into smaller ones with fixed duration and fixed interval between the end of the one range and start of next range. In case if the last interval doesn't fit into the given duration, Split won't return it. Returns ErrZeroDurationInterval if the provided duration is less or equal to zero.

Illustration

• func (r Range) Truncate(bounds Range) Range

  Cuts the start and the end of the range to fit the given bounds.

Illustration

• MergeOverlappingRanges(ranges []Range) []Range

Illustration

• func (r Range) Flip(ranges []Range) []Range

  Flips the given ranges within the given period (r).

  The boundaries of the given ranges are considered to be inclusive, which means that the flipped ranges will start or end at the exact nanosecond where the boundary from the input starts or ends.

  Note: for the sake of safety, ranges are being merged before flip to ensure the correct working of method.

Illustration

• func Intersection(ranges []Range) Range

  Returns the range, which is common for all the given ranges.

Illustration

There are some other non-algorithmic methods, which you can see in the reference.

Details

String method formats the range in format [start time, end time], where the times are formatted with the next template:

const defaultRangeFmt = "2006-01-02 15:04:05.999999999 -0700 MST"

Status

The code was extracted from existing project and still under development. Until v1.x released the API may change.

Documentation

Overview

Package trn provides structures and methods to perform complex operations over time ranges.

Index

• Constants
• type Error
  • func (e Error) Error() string
• type Option
  • func In(loc *time.Location) Option
• type Range
  • func Between(start, end time.Time, opts ...Option) (Range, error)
  • func Intersection(ranges []Range) Range
  • func MergeOverlappingRanges(ranges []Range) []Range
  • func MustRange(r Range, err error) Range
  • func MustRanges(r []Range, err error) []Range
  • func New(start time.Time, duration time.Duration, opts ...Option) Range
  • func (r Range) Contains(other Range) bool
  • func (r Range) Duration() time.Duration
  • func (r Range) Empty() bool
  • func (r Range) End() time.Time
  • func (r Range) Flip(ranges []Range) []Range
  • func (r Range) Format(layout string) string
  • func (r Range) GoString() string
  • func (r Range) In(loc *time.Location) Range
  • func (r Range) Split(duration time.Duration, interval time.Duration) ([]Range, error)
  • func (r Range) Start() time.Time
  • func (r Range) Stratify(duration time.Duration, interval time.Duration) ([]Range, error)
  • func (r Range) String() string
  • func (r Range) Truncate(bounds Range) Range
  • func (r Range) UTC() Range

Constants

const (
	ErrStartAfterEnd        = Error("trn: start time is later than the end")
	ErrZeroDurationInterval = Error("trn: cannot split with zero duration or interval")
)

package errors

Types

type Error

type Error string

Error describes any error appeared in this package.

func (Error) Error

func (e Error) Error() string

Error returns string representation of the error.

type Option

type Option func(r *Range)

Option is an adapter over date ranges.

func In

func In(loc *time.Location) Option

In sets the time range in the given location.

type Range

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

Range represents time slot with its own start and end time boundaries

func Between

func Between(start, end time.Time, opts ...Option) (Range, error)

Between returns the new Range in the given time bounds. Range will use the location of the start timestamp. Returns ErrStartAfterEnd if the start time is later than the end.

func Intersection

func Intersection(ranges []Range) Range

Intersection returns the date range, which is common for all the given ranges.

func MergeOverlappingRanges

func MergeOverlappingRanges(ranges []Range) []Range

MergeOverlappingRanges looks in the ranges slice, seeks for overlapping ranges and merges such ranges into the one range.

func MustRange

func MustRange(r Range, err error) Range

MustRange is a helper that accepts the result of function, that returns a single range and panics, if err is returned.

func MustRanges

func MustRanges(r []Range, err error) []Range

MustRanges is a helper that accepts the result of function, that returns ranges and panics, if err is returned.

func New

func New(start time.Time, duration time.Duration, opts ...Option) Range

New makes a new Range with start at the given time and with the given duration.

func (Range) Contains

func (r Range) Contains(other Range) bool

Contains returns true if the other date range is within this date range.

func (Range) Duration

func (r Range) Duration() time.Duration

Duration returns the duration of the date range.

func (Range) Empty

func (r Range) Empty() bool

Empty returns true if the date range is empty.

func (Range) End

func (r Range) End() time.Time

End returns the end time of the date range.

func (Range) Flip

func (r Range) Flip(ranges []Range) []Range

Flip within the given period.

The boundaries of the given ranges are considered to be inclusive, means that the flipped ranges will start or end at the exact nanosecond where the boundary from the input starts or ends.

func (Range) Format

func (r Range) Format(layout string) string

Format returns the string representation of the time range with the given format.

func (Range) GoString

func (r Range) GoString() string

GoString implements fmt.GoStringer and formats r to be printed in Go source code.

func (Range) In

func (r Range) In(loc *time.Location) Range

In returns the date range with boundaries in the provided location's time zone.

func (Range) Split

func (r Range) Split(duration time.Duration, interval time.Duration) ([]Range, error)

Split the date range into smaller ranges, with fixed duration and with the given interval between the *end* of the one range and *start* of next range. In case if the last interval doesn't fit into the given duration, MustSplit won't return it. Returns ErrZeroDurationInterval if the provided duration is less or equal zero.

func (Range) Start

func (r Range) Start() time.Time

Start returns the start time of the date range.

func (Range) Stratify

func (r Range) Stratify(duration time.Duration, interval time.Duration) ([]Range, error)

Stratify the date range into smaller ranges, with fixed duration and with the given interval between the *starts* of the resulting ranges. In case if the last interval doesn't fit into the given duration, MustStratify won't return it. Returns ErrZeroDurationInterval if the provided duration or interval is less or equal to zero.

func (Range) String

func (r Range) String() string

String implements fmt.Stringer to print and log Range properly

func (Range) Truncate

func (r Range) Truncate(bounds Range) Range

Truncate returns the date range bounded to the *bounds*, i.e. it cuts the start and the end of *r* to fit into the *bounds*.

func (Range) UTC

func (r Range) UTC() Range

UTC returns the date range with boundaries in UTC.