rrule

package module
v0.0.0-...-b8d73f1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 16, 2018 License: BSD-3-Clause Imports: 13 Imported by: 0

README

RRule

GoDoc

Package RRule implements recurrence processing according to RFC 5545. See the godoc for usage information.

This implementation was written to overcome performance issues in previous implementations. Those previous ones were generally implemented as direct translations of the venerable python-dateutil, however the algorithms were complicated and probably didn't use Go's language features effectively enough for performance optimization. The observed problem was particularly acute under GopherJS.

The library here is essentially complete. A fair number of various patterns are tested, particularly simple ones. The library has not seen, at the time of this writing, any production usage, however. Issue reports with implementation accuracy or performance problems are particularly welcome.

Licensed under BSD-3. See the LICENSE file.

Documentation

Overview

Package rrule implements recurrence processing as defined by RFC 5545.

FREQ=WEEKLY;BYDAY=MO;INTERVAL=2

would generate occurrences every other week on Monday.

Index

Examples

Constants

This section is empty.

Variables

View Source
var LoadLocation = time.LoadLocation

LoadLocation defaults to the standard library's implementation, but that implementation does not work on every platform. Set this to an alternative implementation when necessary.

Functions

func All

func All(it Iterator, limit int) []time.Time

All returns all instances from the beginning of the iterator up to a limited number. If the limit is 0, all instances are returned, which will include all instances until (roughly) Go's maximum useful time.Time, in the year 219248499.

func WeekdayString

func WeekdayString(wd time.Weekday) string

WeekdayString returns a weekday formatted as the two-letter string used in RFC5545.

Types

type Frequency

type Frequency int

Frequency defines a set of constants for a base factor for how often recurrences happen.

const (
	Secondly Frequency = iota
	Minutely
	Hourly
	Daily
	Weekly
	Monthly
	Yearly
)

Frequencies specified in RFC 5545.

func (Frequency) String

func (f Frequency) String() string

String returns the RFC 5545 string for supported frequencies, and panics otherwise.

type Iterator

type Iterator interface {
	// Peek returns the next time without advancing the iterator, or nil if
	// the iterator has ended.
	Peek() *time.Time

	// Next returns the next time and advances the iterator. Nil is
	// returned if the iterator has ended.
	Next() *time.Time
}

Iterator scans over a series of times.

type QualifiedWeekday

type QualifiedWeekday struct {
	// N, when non-zero, says which instance of the weekday relative to
	// some greater duration. -3 would be "third from the last".
	N  int
	WD time.Weekday
}

QualifiedWeekday can represent a day of the week, or a certain instance of that day of the week.

func (QualifiedWeekday) String

func (wd QualifiedWeekday) String() string

type RRule

type RRule struct {
	Frequency Frequency

	// Either Until or Count may be set, but not both
	Until         time.Time
	UntilFloating bool // If true, the RRule will encode using local time (no offset).

	Count uint64

	// Dtstart is not actually part of the RRule when
	// encoded, but it's included here as a field because
	// it's required when expading the pattern.
	//
	// If zero, time.Now is used when an iterator is generated.
	Dtstart time.Time

	// 0 means the default value, which is 1.
	Interval int

	BySeconds     []int // 0 to 59
	ByMinutes     []int // 0 to 59
	ByHours       []int // 0 to 23
	ByWeekdays    []QualifiedWeekday
	ByMonthDays   []int // 1 to 31
	ByWeekNumbers []int // 1 to 53
	ByMonths      []time.Month
	ByYearDays    []int // 1 to 366
	BySetPos      []int // -366 to 366

	WeekStart *time.Weekday // if nil, Monday
	// contains filtered or unexported fields
}

RRule represents a single pattern within a recurrence.

func ParseRRule

func ParseRRule(str string) (RRule, error)

ParseRRule parses a single RRule pattern.

Example
ParseRRule("FREQ=WEEKLY;BYDAY=1MO,2TU;COUNT=2")
Output:

func (RRule) Describe

func (rrule RRule) Describe() string

Describe returns a rough English description of the recurrence. This is probably not suitable for truly polished UIs, but may be useful in some circumstances.

func (RRule) Iterator

func (rrule RRule) Iterator() Iterator

Iterator returns an Iterator for the pattern. The pattern must be valid or Iterator will panic.

func (RRule) String

func (rrule RRule) String() string

String returns the RFC 5545 representation of the RRule.

func (RRule) Validate

func (rrule RRule) Validate() error

Validate checks that the pattern is valid.

type Recurrence

type Recurrence struct {
	// Dtstart specifies the time to begin recurrence. If zero, time.Now is
	// used when an iterator is generated.  The location of Dtstart is the
	// location that will be used to process the recurrence, which is
	// particularly relevant for calculations affected by Daylight Savings.
	Dtstart time.Time

	// FloatingLocation determines how the Recurrence is encoded to string.
	// If true, Dtstart, RDates, and ExDates will be written in local time,
	// excluding the offset or timezone indicator, to represent a local time
	// independent of timezone. See ParseRecurrence or RFC 5545 for more
	// detail.
	FloatingLocation bool

	// Patterns and instances to include. Repeated instances are included only
	// once, even if defined by multiple patterns.
	//
	// The Dtstart property of RRule and ExRule patterns are
	// ignored, including when the above Dtstart property is zero.
	RRules []RRule
	RDates []time.Time

	// Patterns and instances to exclude. These take precedence over the
	// inclusions. Note: this feature was deprecated in RFC5545, noting its
	// limited (and buggy) adoption and real-world use case. It is
	// implemented here, nonetheless, for maximum flexibility and
	// compatibility.
	ExRules []RRule
	ExDates []time.Time
}

Recurrence expresses a complex pattern of repeating events composed of individual patterns and extra days that are filtered by exclusion patterns and days.

func ParseRecurrence

func ParseRecurrence(src []byte, loc *time.Location) (*Recurrence, error)

ParseRecurrence parses a whole recurrence from an iCalendar object. iCalendar properties recognized are DTSTART, RRULE, EXRULE, RDATE, EXDATE. Others are ignored.

loc defines what "local" means to the parsed rules. Some patterns may specify a "floating" time, one without a timezone or offset, which matches a different actual time in different timezones. For example,

RRULE:FREQ=YEARLY;BYSECOND=-10

might be useful to alert you to start counting down to the new year, no matter your timezone. A rule with a specific timezone, however,

DTSTART;TZID=America/New_York:19991231T000000
RRULE:FREQ=YEARLY;BYSECOND=-10

would track a specific timezone and ignore loc. This example would alert you to count down to the ball dropping in New York's Times Square for each new year.

If nil, time.UTC will be used.

func (Recurrence) Iterator

func (r Recurrence) Iterator() Iterator

Iterator returns an iterator for the recurrence.

func (*Recurrence) String

func (r *Recurrence) String() string

String returns the RFC 5545 representation of the recurrence, which is a newline delimited format.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL