README
¶
Calends

A library for handling dates and times across arbitrary calendar systems
Features
More information about each of these features is available in the full documentation.
- Large range and high precision
- Supports date (and time) values in multiple calendar systems:
- Unix time
- TAI64
- Automatic calculation of leap second offsets
- Estimation of undefined past and future leap second insertions
- Automatic updates for handling leap second insertions
- Gregorian
- Disconnect from native
time.Timeimplementation, and its limitations
- Disconnect from native
- Julian
- Julian Day Count
- Hebrew
- Persian
- Chinese
- Meso-American
- Discordian
- Stardate
- Encodes both time spans and instants in a single interface
- Supports calculations and comparisons on spans and instants
- Conversion to/from native date/time types
- Geo-temporally aware
- Time zone support
- Well-defined interfaces for extending the library
- Shared library (
.so/.dll)
Installation
The steps here will vary based on which programming language(s) you're using.
For Golang, simply run go get github.com/danhunsaker/calends, and then place
"github.com/danhunsaker/calends" in the import wherever you intend use it.
For other languages, refer to the full documentation.
Usage
Usage data has been moved to the full documentation.
Calendar Systems
Currently supported calendar systems, and the options available for each, are listed in the full documentation. Also provided there are the docs for how to add your own.
Contributing
Pull requests are always welcome! That said, please be open to discussing the PR content, and possibly revising it if requested. Not all requests can be merged, and not all changes are desired.
Or, you can contribute some money, instead! Check out my Patreon for options, there. Other options will likely be added for one-time donations in the future.
Security Reporting
Report all security-related issues to dan (dot) hunsaker (plus) calends (at)
gmail, and use PGP or GPG protections on
your message (the account's key is 44806AB9, or you can look it up by the
email address). Security issues will be addressed internally before making any
vulnerability announcements.
Documentation
¶
Overview ¶
Package calends is a library for handling dates and times across arbitrary calendar systems.
Dates and times are converted to "TAI64NAXUR instants", values that unambiguously encode moments over 146 billion years into the past or future, in increments as small as 10**-45 seconds (internally called a "roctosecond", but there's no actual prefix for units this small, even though the Planck Time - the smallest meaningful period of time in quantum physics - is 54 of them). Calculations and comparisons are done using these instants, to maintain the highest accuracy possible while working with such values. A single Calends value can hold either a single instant, or a time span between two of them; the duration of such a value is automatically calculated during object creation, for easy use elsewhere. When you need a version of the instant itself (either of them, for a span) that you can use elsewhere, it is converted back to a date/time string in whatever calendar system you need at the time.
Several calendar systems are supported officially, and the library is easily extended to support others without having to modify the core in any way.
Index ¶
- Variables
- type Calends
- func (c Calends) Abuts(z Calends) bool
- func (c Calends) Add(offset interface{}, calendar string) (out Calends, err error)
- func (c Calends) AddFromEnd(offset interface{}, calendar string) (out Calends, err error)
- func (c Calends) Compare(z Calends, mode string) int
- func (c Calends) Contains(z Calends) bool
- func (c Calends) Date(calendar, format string) (string, error)
- func (c Calends) Difference(z Calends, mode string) (out big.Float)
- func (c Calends) Duration() *big.Float
- func (c Calends) EndDate(calendar, format string) (string, error)
- func (c Calends) EndsAfter(z Calends) bool
- func (c Calends) EndsBefore(z Calends) bool
- func (c Calends) EndsDuring(z Calends) bool
- func (c Calends) Gap(z Calends) (Calends, error)
- func (c Calends) Intersect(z Calends) (Calends, error)
- func (c Calends) IsAfter(z Calends) bool
- func (c Calends) IsBefore(z Calends) bool
- func (c Calends) IsDuring(z Calends) bool
- func (c Calends) IsLonger(z Calends) bool
- func (c Calends) IsSame(z Calends) bool
- func (c Calends) IsSameDuration(z Calends) bool
- func (c Calends) IsShorter(z Calends) bool
- func (c Calends) MarshalJSON() ([]byte, error)
- func (c Calends) MarshalText() ([]byte, error)
- func (c Calends) Merge(z Calends) (Calends, error)
- func (c Calends) Next(offset interface{}, calendar string) (Calends, error)
- func (c Calends) Overlaps(z Calends) bool
- func (c Calends) Previous(offset interface{}, calendar string) (Calends, error)
- func (c Calends) SetDate(stamp interface{}, calendar, format string) (Calends, error)
- func (c Calends) SetDuration(duration interface{}, calendar string) (Calends, error)
- func (c Calends) SetDurationFromEnd(duration interface{}, calendar string) (Calends, error)
- func (c Calends) SetEndDate(stamp interface{}, calendar, format string) (Calends, error)
- func (c Calends) StartsAfter(z Calends) bool
- func (c Calends) StartsBefore(z Calends) bool
- func (c Calends) StartsDuring(z Calends) bool
- func (c Calends) String() string
- func (c Calends) Subtract(offset interface{}, calendar string) (Calends, error)
- func (c Calends) SubtractFromEnd(offset interface{}, calendar string) (Calends, error)
- func (c *Calends) UnmarshalJSON(text []byte) error
- func (c *Calends) UnmarshalText(text []byte) error
Constants ¶
This section is empty.
Variables ¶
var Version = "0.0.5"
Version of the library
Functions ¶
This section is empty.
Types ¶
type Calends ¶
type Calends struct {
// contains filtered or unexported fields
}
The Calends type is the core of the library, and the primary interface with it.
func Create ¶
Create is the mechanism for constructing new Calends objects.
It is preferred over using `make`, `new`, or `Calends{}` directly. It takes a date/time value, a calendar name, and a format string, and returns a Calends object representing the instant that date/time value took place. It also returns an error object, if something goes wrong.
If the calendar passed is the empty string (`""`), Calends will use the `"unix"` calendar automatically. If the format is the empty string, Calends will use a default format provided by the calendar system itself.
The date/time value can be one of many types, and the exact list of types supported varies by calendar system. At a minimum, string values should always be supported. The documentation for each calendar system should provide more detail on what other types are supported, and what ways the values can be presented with each.
In any case, the date/time value can either be a single interface{} value, or a map[string]interface{} containing two or three of them. The valid map keys are 'start', 'end', and 'duration'. Any combination of two will create the Calends object with the associated time span. If all three are provided, the 'duration' is ignored, and recalculated from the 'start' and 'end' values exclusively.
func (Calends) Abuts ¶
Abuts checks whether the current object starts when another object ends, or vice-versa, and that neither contains the other.
func (Calends) AddFromEnd ¶
AddFromEnd creates a new Calends object a given offset after the current end point.
func (Calends) Compare ¶
Compare the start time, end time, some mix of those two, or duration of two Calends objects.
func (Calends) Contains ¶
Contains checks whether another object fits entirely within the current one.
func (Calends) Difference ¶
Difference retrieves the difference between the current Calends object and another.
func (Calends) Duration ¶
Duration retrieves the number of seconds between the start and end instants.
func (Calends) EndsAfter ¶
EndsAfter checks whether the current object's end point occurs after another's.
func (Calends) EndsBefore ¶
EndsBefore checks whether the current object's end point occurs before another's.
func (Calends) EndsDuring ¶
EndsDuring checks whether the current object has its end point between another's start and end points.
func (Calends) Gap ¶
Gap gets the gap between two Calends objects.
Creates a new Calends object with the gap in time between the current object and another one
func (Calends) Intersect ¶
Intersect gets the intersection of two Calends objects.
Creates a new Calends object with the overlapping time between the current object and another one
func (Calends) IsAfter ¶
IsAfter checks whether both of the current object's endpoints occur after another object's end point.
func (Calends) IsBefore ¶
IsBefore checks whether both of the current object's endpoints occur before another object's start point.
func (Calends) IsLonger ¶
IsLonger checks whether the current object's duration is greater than another's.
func (Calends) IsSameDuration ¶
IsSameDuration checks whether the current object's duration is equal to another's.
func (Calends) IsShorter ¶
IsShorter checks whether the current object's duration is less than another's.
func (Calends) MarshalJSON ¶
MarshalJSON implements the encoding/json.Marshaler interface.
func (Calends) MarshalText ¶
MarshalText implements the encoding.TextMarshaler interface.
func (Calends) Merge ¶
Merge two Calends objects.
Creates a new Calends object with the earlier start and later end points of the current object and another one
func (Calends) Next ¶
Next creates a new Calends object with a range spanning a given offset, and starting at the current end point.
func (Calends) Overlaps ¶
Overlaps checks whether either of the current object's endpoints occur within another object's period, or vice-versa.
func (Calends) Previous ¶
Previous creates a new Calends object with a range spanning a given offset, and ending at the current start point.
func (Calends) SetDuration ¶
SetDuration creates a new Calends object spanning from the current start point for a given duration.
func (Calends) SetDurationFromEnd ¶
SetDurationFromEnd creates a new Calends object spanning for a given duration to the current end point.
func (Calends) SetEndDate ¶
SetEndDate creates a new Calends object ending at a given date.
func (Calends) StartsAfter ¶
StartsAfter checks whether the current object's start point occurs after another's.
func (Calends) StartsBefore ¶
StartsBefore checks whether the current object's start point occurs before another's.
func (Calends) StartsDuring ¶
StartsDuring checks whether the current object has its start point between another's start and end points.
func (Calends) Subtract ¶
Subtract creates a new Calends object a given offset before the current start point.
func (Calends) SubtractFromEnd ¶
SubtractFromEnd creates a new Calends object a given offset before the current end point.
func (*Calends) UnmarshalJSON ¶
UnmarshalJSON implements the encoding/json.Unmarshaler interface.
func (*Calends) UnmarshalText ¶
UnmarshalText implements the encoding.TextUnmarshaler interface.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package calendars provides the underlying framework that makes Calends function across multiple calendar systems.
|
Package calendars provides the underlying framework that makes Calends function across multiple calendar systems. |