calendars

package
v0.0.5 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2018 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package calendars provides the underlying framework that makes Calends function across multiple calendar systems.

It provides an interface for custom calendar systems to implement, and a data type for storing instants in the internal TAI64NAXUR format, so that the various date/time manipulation functions of Calends can easily operate on them. It also provides a handful of utility functions and methods to simplify the conversion process between the calendar system and the internal format.

You generally won't use any of the types, functions, or methods defined here unless you're implementing a calendar system class yourself.

TAI ↔ UTC CONVERSIONS

Part of what the helper methods offer is automatic conversion between UTC and TAI counts. The difference between the two is the inclusion of leap seconds in UTC, to keep noon synchronized with the solar zenith in the times used in day-to-day situations. TAI counts do not include such an offset, and as such there is a difference of a few seconds between the two values, which varies based on when the instant actually occurs.

In order to perform this conversion, Calends makes use of leap second tables available from the Centre de la Rotation de la Terre du Service International de la Rotation Terrestre et des Systèmes de Référence à L’Observatoire de Paris (in English, the Earth Orientation Center, at the International Earth Rotation and Reference Systems Service, itself located in the Paris Observatory). The second of these tables is the full-second offset between TAI and UTC, starting in 1972 (when the leap second system itself was devised). The first, then, is the calculation used to find the offset from 1961 through 1971, which itself is based on the actual differences between Earth's rotation-based time and the actual number of seconds elapsed in that period. Times prior to this period are unadjusted until a more comprehensive offset can reliably be calculated into the past. Times after the latest offset (generally applicable to the present moment) are similarly adjusted only to the latest offset, until a decent approximation can be devised. These tables are updated periodically, and any updates will be reflected by subsequent releases of the Calends library.

GREIORIAN CALENDAR

Supports dates and times in the Gregorian calendar system, the current international standard for communicating dates and times.

Supported Input Types:

  • string
  • []byte
  • time.Time (time.Duration for Offset)

Supported Format Strings:

  • any format supported by the time library or github.com/knz/strtime (or github.com/olebedev/when for Offset)

JDC (JULIAN DAY COUNT) CALENDAR

A count of days since BCE 4713 Jan 01 12:00:00 UTC on the proleptic Julian Calendar. Yes, that's noon. This calendar system is used mostly for astronomy purposes, though there is a modified variant with a narrower scope which counts from midnight instead.

Supported Input Types:

  • string
  • []byte
  • int
  • float64
  • math/big.Float

Supported Format Strings:

  • full - the full, canonical Day Count
  • fullday - the full Day Count, without the fractional time part
  • fulltime - just the fractional time part of the full Day Count
  • modified - an abbreviated Day Count, 2400000.5 less than the full (starts at midnight instead of noon)
  • day - the modified Day Count, without the fractional time part
  • time - just the fractional time part of the modified Day Count

STARDATE (Yes, from Star Trek™) CALENDAR

The science fiction universe of Star Trek™ introduced a calendar system which was simultaneously futuristic (for the time) and arbitrary. Over the decades since its initial use on screen, especially with the growing popularity of the franchise, the "stardate" has been analyzed and explored and refined into a number of different variants, each trying to reconcile the arbitrariness of the on-screen system into something consistent and usable.

This calendar system implementation is an attempt to combine all these variants into a single system, using the format parameter to select which variant to use. It was originally ported in 2018 from code by Aaron Chong (2015 version), under provisions of the MIT License. My thanks for Aaron's use of the MIT License on the original code, which allowed me to port it cleanly and legally.

Original source: http://rinsanity.weebly.com/files/theme/stardate_public.js

Supported Input Types:

  • string
  • []byte
  • int
  • float64
  • math/big.Float

Supported Format Strings:

  • main - One of the older, more widely-accepted variants. Alternately called the "issue number style" stardate, it's a combined TOS/TNG variant, and the one used by Google Calendar. It was originally devised by Anhrew Main in CE 1994, with revisions made through CE 1997. See http://starchive.cs.umanitoba.ca/?stardates/ for the full explanation of this variant.
  • kennedy - In 2006, Richie Kennedy released another combined variant, this one designed to have a single continuous count, more like the Julian Day Count than Main's issue number system.
  • pugh90s - Steve Pugh devised 2 separate variants, one of them in the 1990s, and the other later on. The original version used an unadjusted Gregorian year as the basis for the duration of a given range of stardates, meaning that 0.05 units refer to a larger duration of time during a leap year than it would otherwise.
  • pughfixed - The later of Steve Pugh's systems noted the discrepancy, and opted to adjust the year length value to the actual average length of a Gregorian year, 365.2425 days. This means 0.05 units are always the same duration, but does mean that the Gregorian year doesn't generally start at the same point in consecutive stardate ranges.
  • schmidt - A joint effort between Andreas Schmidt and Graham Kennedy, this variant only covers TNG-era stardates, and while it can be used proleptically, it ignores the alternate format used prior to TNG.
  • guide-equiv - One of five variants proposed by TrekGuide.com, this is the "out-of-universe equivalent" calculation. It isn't intended to be accurate for any use other than personal entertainment.
  • guide-tng - The second of the five TrekGuide variants, this one is the current scale listed for TNG-era stardates, and is show-accurate (or at least as close to it as feasible with an entirely arbitrary system). Note, however, that it is only accurate for TNG-era dates.
  • guide-tos - The third variant, then, covers the TOS-era stardates. Again, it is only accurate to the TOS era.
  • guide-oldtng - The fourth variant is no longer displayed on the TrekGuide site, and was actually pulled from a previous version of the stardates page. It covers the TNG era only, and uses slightly different numbers in its calculations than the current approach - specifically, it assumes Earth years cover 1000 stardates.
  • guide-oldtos - NOTE: The fifth TrekGuide variant actually isn't implemented, yet. Representing the very first set of calculations available in archives of the TrekGuide site, it assumes that 1000 stardates are one Earth year in the TOS era, and calculates dates based on that assumption. This variant was replaced within seven months of that first archival, after it was noticed that TOS-era stardates don't fit a 1000-stardate model.
  • aldrich - A proof of concept originally written in C#, this variant results in dates very close to those produced by Pugh's and Schmidt's, but uses a more simplified calculation to do it.
  • red-dragon - A system devised by/for the Red Dragon Inn roleplaying forum site, it uses a fixed ratio of roughly two and three quarters stardates per Earth day. It makes no representations about accuracy outside the context of the site itself.
  • sto-hynes - John Hynes, creator of the Digital Time site, offers a calculation for STO stardates which appears to be the most accurate variant for those interested in generating those. The system doesn't represent itself as accurate outside the game, but is intentionally proleptic.
  • sto-academy - Based on an online calculator provided by the STO Academy game help site, it is only accurate for stardates within the game, and does not offer to calculate dates for the rest of the franchise.
  • sto-tom - Another variant intended only to calculate STO stardates, this one was attributed to Major Tom, and hosted as a Wolfram Alpha widget.
  • sto-anthodev - Another STO variant, hosted on GitHub.

TAI64 CALENDAR

Supports times that are seconds since CE 1970-01-01 00:00:00 TAI (plus 2**62, when in hexadecimal), as defined at https://cr.yp.to/libtai/tai64.html (though this library includes extensions to the formats described there). These values are also used internally, so this calendar system can be used to directly expose the underlying internal values in a manner that allows them to be used elsewhere.

Supported Input Types:

  • string
  • []byte
  • TAI64NAXURTime
  • math/big.Float for Offset

Supported Format Strings:

  • decimal - decimal; full resolution
  • tai64 - hexadecimal; just seconds
  • tai64n - hexadecimal; with nanoseconds
  • tai64na - hexadecimal; with attoseconds
  • tai64nax - hexadecimal; with xictoseconds
  • tai64naxu - hexadecimal; with uctoseconds
  • tai64naxur - hexadecimal; with roctoseconds

UNIX CALENDAR

Supports times that are seconds since CE 1970-01-01 00:00:00 UTC, commonly used by computer systems for storing date/time values, internally.

Supported Input Types:

  • string
  • []byte
  • int
  • float64
  • math/big.Float

Supported Format Strings:

  • any format supported by math/big.Float

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrUnsupportedInput = errors.New("Unsupported Value")
	ErrInvalidFormat    = errors.New("Invalid Format")
)

Error messages returned by Calends operations.

Functions

func DefaultFormat 

func DefaultFormat(calendar string) string

DefaultFormat returns the associated value from a registered calendar system.

func ErrUnknownCalendar added in v0.0.2 

func ErrUnknownCalendar(calendar string) error

ErrUnknownCalendar generates a "calendar not registered" error including the calendar's actual name in the error message

func FromInternal 

func FromInternal(calendar string, stamp TAI64NAXURTime, format string) (string, error)

FromInternal returns the associated value from a registered calendar system.

func ListRegistered added in v0.0.4 

func ListRegistered() []string

ListRegistered returns the list of calendar systems currently registered.

func RegisterClass 

func RegisterClass(name string, definition CalendarDefinition, defaultFormat string)

RegisterClass registers a calendar system class.

Registers `definition` as `name`, and saves `defaultFormat` for later use while parsing or formatting.

func RegisterElements 

func RegisterElements(
	name string,
	toInternal func(interface{}, string) (TAI64NAXURTime, error),
	fromInternal func(TAI64NAXURTime, string) (string, error),
	offset func(TAI64NAXURTime, interface{}) (TAI64NAXURTime, error),
	defaultFormat string,
)

RegisterElements registers a calendar system from its distinct functions.

Registers `toInternal`, `fromInternal`, and 'offset' as the elements of `name`, and saves `defaultFormat` for later use while parsing or formatting.

func Registered 

func Registered(calendar string) bool

Registered returns whether or not a calendar system has been registered, yet.

func Unregister added in v0.0.4 

func Unregister(name string)

Unregister removes a calendar system from the callback list.

Types

type CalendarDefinition 

type CalendarDefinition interface {
	// Convert a date representation to an internal TAI64NAXURTime
	ToInternal(interface{}, string) (TAI64NAXURTime, error)

	// Convert an internal TAI64NAXURTime to a date representation
	FromInternal(TAI64NAXURTime, string) (string, error)

	// Calculate the TAI64NAXURTime at a given offset from another TAI64NAXURTime
	Offset(TAI64NAXURTime, interface{}) (TAI64NAXURTime, error)
}

CalendarDefinition is the primary interface for defining calendar systems.

type TAI64NAXURTime 

type TAI64NAXURTime struct {
	Seconds int64  // Seconds since 1970-01-01 00:00:00 TAI
	Nano    uint32 // Nanoseconds since the given second
	Atto    uint32 // Attoseconds since the given nanosecond
	Xicto   uint32 // Xictoseconds since the given attosecond
	Ucto    uint32 // Uctoseconds since the given xictosecond
	Rocto   uint32 // Roctoseconds since the given uctosecond
}

TAI64NAXURTime stores a TAI64NAXUR instant in a reliable, easy-converted format.

func Offset 

func Offset(calendar string, stamp TAI64NAXURTime, offset interface{}) (TAI64NAXURTime, error)

Offset returns the associated value from a registered calendar system.

func TAI64NAXURTimeFromDecimalString 

func TAI64NAXURTimeFromDecimalString(in string) TAI64NAXURTime

TAI64NAXURTimeFromDecimalString calculates a TAI64NAXURTime from its decimal string representation.

func TAI64NAXURTimeFromFloat 

func TAI64NAXURTimeFromFloat(in big.Float) TAI64NAXURTime

TAI64NAXURTimeFromFloat calculates a TAI64NAXURTime from its math/big.Float representation.

func TAI64NAXURTimeFromHexString 

func TAI64NAXURTimeFromHexString(in string) TAI64NAXURTime

TAI64NAXURTimeFromHexString calculates a TAI64NAXURTime from its hexadecimal string representation.

func TAItoUTC 

func TAItoUTC(tai TAI64NAXURTime) (utc TAI64NAXURTime)

TAItoUTC adds the UTC leap second offset to a TAI64NAXURTime value.

func ToInternal 

func ToInternal(calendar string, date interface{}, format string) (TAI64NAXURTime, error)

ToInternal returns the associated value from a registered calendar system.

func UTCtoTAI 

func UTCtoTAI(utc TAI64NAXURTime) (tai TAI64NAXURTime)

UTCtoTAI removes the UTC leap second offset from a TAI64NAXURTime value.

func (TAI64NAXURTime) Add 

func (t TAI64NAXURTime) Add(z TAI64NAXURTime) TAI64NAXURTime

Add calculates the sum of two TAI64NAXURTime values.

func (TAI64NAXURTime) Float 

func (t TAI64NAXURTime) Float() *big.Float

Float returns the math/big.Float representation of the TAI64NAXURTime value.

func (TAI64NAXURTime) HexString added in v0.0.2 

func (t TAI64NAXURTime) HexString() string

HexString returns the hex string representation of the TAI64NAXURTime value.

func (*TAI64NAXURTime) MarshalBinary 

func (t *TAI64NAXURTime) MarshalBinary() (out []byte, err error)

MarshalBinary implements the encoding.BinaryMarshaler interface.

func (TAI64NAXURTime) MarshalText 

func (t TAI64NAXURTime) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (TAI64NAXURTime) String 

func (t TAI64NAXURTime) String() string

String returns the decimal string representation of the TAI64NAXURTime value.

func (TAI64NAXURTime) Sub 

func (t TAI64NAXURTime) Sub(z TAI64NAXURTime) TAI64NAXURTime

Sub calculates the difference of two TAI64NAXURTime values.

func (*TAI64NAXURTime) UnmarshalBinary 

func (t *TAI64NAXURTime) UnmarshalBinary(in []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface.

func (*TAI64NAXURTime) UnmarshalText 

func (t *TAI64NAXURTime) UnmarshalText(in []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.