README
¶
RRule
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.
RFC 7529 is partially implemented. The SKIP and RSCALE clauses are supported, but only Gregorian is implemented. As such, months with the L indicator are also not supported, since these have no use in Gregorian.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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 ¶
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 ¶
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.
Frequencies specified in RFC 5545.
type InvalidBehavior ¶ added in v1.1.0
type InvalidBehavior int
InvalidBehavior specifies how to behave when a pattern generates a date that wouldn't exist, like February 31st.
const ( // OmitInvalid skips invalid dates. This is the only choice for RFC // 5545 and RFC 2445. OmitInvalid InvalidBehavior = iota // NextInvalid chooses the next valid date. So if February 31st were generated, // March 1st would be used. NextInvalid // PrevInvalid chooses the previously valid date. So if February 31st were generated, // the result would be February 28th (or 29th on a leap year). PrevInvalid )
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
// InvalidBehavior defines how to behave when a generated date wouldn't
// exist, like February 31st.
InvalidBehavior InvalidBehavior
WeekStart *time.Weekday // if nil, Monday
}
RRule represents a single pattern within a recurrence.
func ParseRRule ¶
ParseRRule parses a single RRule pattern.
Example ¶
ParseRRule("FREQ=WEEKLY;BYDAY=1MO,2TU;COUNT=2")
Output:
func (RRule) Describe ¶
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 ¶
Iterator returns an Iterator for the pattern. The pattern must be valid or Iterator will panic.
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.
Source Files