timerange

README

go-timerange

This is a Go package to handle a time range.

See https://pkg.go.dev/github.com/int128/go-timerange for details.

Getting Started

To install this package,

go get github.com/int128/go-timerange

Here is an example.

package example

import (
	"fmt"
	"time"

	"github.com/int128/go-timerange"
)

func CheckIfAvailable(desiredTime time.Time) {
	availableRange := timerange.New(
		time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
		time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
	)
	if timerange.In(desiredTime, availableRange) {
		fmt.Printf("The reservation at %s is available.", desiredTime)
	}
}

Documentation

Overview

Package timerange provides simple types to handle a time range.

Index

• func In(t time.Time, r TimeRange) bool
• type SplitIterator
• type TimeRange
  • func From(start time.Time, duration time.Duration) TimeRange
  • func Intersect(a, b TimeRange) TimeRange
  • func New(start, end time.Time) TimeRange
  • func Until(end time.Time, duration time.Duration) TimeRange
  • func (r TimeRange) After(t time.Time) bool
  • func (r TimeRange) Before(t time.Time) bool
  • func (r TimeRange) Contains(t time.Time) bool
  • func (r TimeRange) Duration() time.Duration
  • func (r TimeRange) End() time.Time
  • func (r TimeRange) Equal(x TimeRange) bool
  • func (r TimeRange) Extend(d time.Duration) TimeRange
  • func (r TimeRange) ExtendDate(years, months, days int) TimeRange
  • func (r TimeRange) IsZero() bool
  • func (r TimeRange) Shift(d time.Duration) TimeRange
  • func (r TimeRange) ShiftDate(years, months, days int) TimeRange
  • func (r TimeRange) Split(span time.Duration) []time.Time
  • func (r TimeRange) SplitIterator(span time.Duration) SplitIterator
  • func (r TimeRange) Start() time.Time
  • func (r TimeRange) String() string

Examples

• From
• In
• New
• TimeRange.Contains
• TimeRange.Extend
• TimeRange.ExtendDate
• TimeRange.Shift
• TimeRange.ShiftDate
• TimeRange.Split
• TimeRange.SplitIterator
• TimeRange.String
• Until

Functions

func In

func In(t time.Time, r TimeRange) bool

In returns true if the time is within the range. This is a synonym of TimeRange.Contains().

Example

desiredTime := time.Date(2006, 1, 2, 15, 6, 0, 0, time.UTC)
availableRange := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
if timerange.In(desiredTime, availableRange) {
	fmt.Printf("The reservation at %s is available.", desiredTime)
}

Output:

The reservation at 2006-01-02 15:06:00 +0000 UTC is available.

Types

type SplitIterator

type SplitIterator interface {
	// HasNext returns true if the next time is within the range.
	HasNext() bool

	// Next returns the next time.
	// It the next time is not in the range, this returns a zero value.
	Next() time.Time
}

SplitIterator is an iterator to retrieve time points within a range.

type TimeRange

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

TimeRange represents an immutable range of time with timezone. The range includes start time and end time, i.e., [start, end]. Start time must be earlier than end time.

func From

func From(start time.Time, duration time.Duration) TimeRange

From returns a TimeRange with start time and duration. The duration must be positive.

Example

start := time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC)
r := timerange.From(start, 15*time.Minute)
fmt.Print(r)

Output:

[2006-01-02T15:04:05Z, 2006-01-02T15:19:05Z]

func Intersect

func Intersect(a, b TimeRange) TimeRange

Intersect returns the intersection of given ranges. If the intersection is empty, this returns a zero value.

func New

func New(start, end time.Time) TimeRange

New returns a TimeRange with start time and end time. It must be start <= end. If start > end, this returns a zero value.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
fmt.Print(r)

Output:

[2006-01-02T15:04:05Z, 2006-01-02T15:07:05Z]

func Until

func Until(end time.Time, duration time.Duration) TimeRange

Until returns a TimeRange with end time and duration. The duration must be positive.

Example

end := time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC)
r := timerange.Until(end, 15*time.Minute)
fmt.Print(r)

Output:

[2006-01-02T14:49:05Z, 2006-01-02T15:04:05Z]

func (TimeRange) After

func (r TimeRange) After(t time.Time) bool

After returns true if this range is later than the time.

func (TimeRange) Before

func (r TimeRange) Before(t time.Time) bool

Before returns true if this range is earlier than the time.

func (TimeRange) Contains

func (r TimeRange) Contains(t time.Time) bool

Contains returns true if the time is within this range.

Example

desiredTime := time.Date(2006, 1, 2, 15, 6, 0, 0, time.UTC)
availableRange := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
if availableRange.Contains(desiredTime) {
	fmt.Printf("The reservation at %s is available.", desiredTime)
}

Output:

The reservation at 2006-01-02 15:06:00 +0000 UTC is available.

func (TimeRange) Duration

func (r TimeRange) Duration() time.Duration

Duration returns the duration between start time and end time.

func (TimeRange) End

func (r TimeRange) End() time.Time

End returns the end time.

func (TimeRange) Equal

func (r TimeRange) Equal(x TimeRange) bool

Equal returns true if this range is equivalent to one.

func (TimeRange) Extend

func (r TimeRange) Extend(d time.Duration) TimeRange

Extend returns an extended TimeRange for the duration. If the duration is positive, this returns the longer range. If the duration is negative, this returns the shorter range.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
fmt.Print(r.Extend(15 * time.Minute))

Output:

[2006-01-02T15:04:05Z, 2006-01-02T15:22:05Z]

func (TimeRange) ExtendDate

func (r TimeRange) ExtendDate(years, months, days int) TimeRange

ExtendDate returns an extended TimeRange for the duration in days. If the duration is positive, this returns the longer range. If the duration is negative, this returns the shorter range.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
fmt.Print(r.ExtendDate(0, 0, 1))

Output:

[2006-01-02T15:04:05Z, 2006-01-03T15:07:05Z]

func (TimeRange) IsZero

func (r TimeRange) IsZero() bool

IsZero returns true if both start time and end time are zero value.

func (TimeRange) Shift

func (r TimeRange) Shift(d time.Duration) TimeRange

Shift returns a TimeRange moved by the duration. If the duration is positive, this returns the later range. If the duration is negative, this returns the earlier range.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
fmt.Print(r.Shift(15 * time.Minute))

Output:

[2006-01-02T15:19:05Z, 2006-01-02T15:22:05Z]

func (TimeRange) ShiftDate

func (r TimeRange) ShiftDate(years, months, days int) TimeRange

ShiftDate returns a TimeRange moved by the duration in days. If the duration is positive, this returns the later range. If the duration is negative, this returns the earlier range.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
fmt.Print(r.ShiftDate(0, 0, -1))

Output:

[2006-01-01T15:04:05Z, 2006-01-01T15:07:05Z]

func (TimeRange) Split

func (r TimeRange) Split(span time.Duration) []time.Time

Split returns an array of time points within this range. If the span is longer than this range, this returns only start time.

If the result array is too long, consider using SplitIterator() instead.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
for _, t := range r.Split(1 * time.Minute) {
	fmt.Println(t)
}

Output:

2006-01-02 15:04:05 +0000 UTC
2006-01-02 15:05:05 +0000 UTC
2006-01-02 15:06:05 +0000 UTC
2006-01-02 15:07:05 +0000 UTC

func (TimeRange) SplitIterator

func (r TimeRange) SplitIterator(span time.Duration) SplitIterator

SplitIterator returns an iterator for time points within this range. If the span is longer than this range, this returns only start time.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
iter := r.SplitIterator(1 * time.Minute)
for iter.HasNext() {
	fmt.Println(iter.Next())
}

Output:

2006-01-02 15:04:05 +0000 UTC
2006-01-02 15:05:05 +0000 UTC
2006-01-02 15:06:05 +0000 UTC
2006-01-02 15:07:05 +0000 UTC

func (TimeRange) Start

func (r TimeRange) Start() time.Time

Start returns the start time.

func (TimeRange) String

func (r TimeRange) String() string

String returns a string representation of this range in RFC3339.

Example

r := timerange.New(
	time.Date(2006, 1, 2, 15, 4, 5, 0, time.UTC),
	time.Date(2006, 1, 2, 15, 7, 5, 0, time.UTC),
)
fmt.Print(r)

Output:

[2006-01-02T15:04:05Z, 2006-01-02T15:07:05Z]