Using Calends in Golang
Calends exposes a very small handful of things for use outside the library
itself. One is the Calends
class, documented here, which should be
the only interface users of the library ever need to touch.
Another thing Calends exposes is the calendars.TAI64NARUXTime
class,
used to store and manipulate the instants of time which make up a
Calends
instance. The rest are interfaces for extending the library’s
functionality. These are covered in the Custom Calendars in Golang section.
Notă
Calends
objects are immutable - all methods return a new
Calends
object where they might otherwise alter the current one.
This is true even of the Calends.Set*
methods. This has the side
effect of using more memory to perform manipulations than updating values on
an existing object would. It makes many operations safer, though, than
mutable objects would allow.
- Calends
The main entry point to Calends and its functionality.
Calends
objects should only be created with theCreate
function, and never directly (especially given its values are all unexported ones).
Create
- func Create(value interface, calendar string, format string) (Calends, error)
- Parametrii
value (
interface{}
) – The value to parse the date(s)/time(s) from.calendar (
string
) – The calendar system to parse the date(s)/time(s) with.format (
string
) – The format the date(s)/time(s) is/are expected to use.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Creates a new
Calends
object, usingcalendar
to select a calendar system, andformat
to parse the contents ofvalue
into theCalends
object’s internal instants. The type ofvalue
can vary based on the calendar system itself, but generally speaking can always be a string.In any case, the value can always be a
map[string]interface{}
, where the keys are any two ofstart
,end
, andduration
. If all three are provided,duration
is ignored in favor of calculating it directly. If only one of the listed keys is provided,value
is passed to the calendar system itself unchanged.The calendar system then converts
value
to acalendars.TAI64NARUXTime
instant, which theCalends
object sets to the appropriate internal value.
Read
- func (Calends) Date(calendar string, format string) (string, error)
- Parametrii
calendar (
string
) – The calendar system to format the date/time with.format (
string
) – The format the date/time is expected to be in.
- Întoarce
The start date of the
Calends
object- Tipul întors
string
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Retrieves the start date of the
Calends
object as a string. The value is generated by the calendar system given incalendar
, according to the format string informat
.
- func (Calends) EndDate(calendar string, format string) (string, error)
- Parametrii
calendar (
string
) – The calendar system to format the date/time with.format (
string
) – The format the date/time is expected to be in.
- Întoarce
The end date of the
Calends
object- Tipul întors
string
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Retrieves the end date of the
Calends
object as a string. The value is generated by the calendar system given incalendar
, according to the format string informat
.
Update
- func (Calends) SetDate(stamp interface, calendar string, format string) (Calends, error)
- Parametrii
value (
interface{}
) – The value to parse the date/time from.calendar (
string
) – The calendar system to parse the date/time with.format (
string
) – The format the date/time is expected to use.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Sets the start date of a
Calends
object, based on theCalends
object’s current value. The inputs are the same as forCreate
, above, except the string → value map option isn’t available, since you’re already specifically setting the start value explicitly.
- func (Calends) SetEndDate(stamp interface, calendar string, format string) (Calends, error)
- Parametrii
value (
interface{}
) – The value to parse the date/time from.calendar (
string
) – The calendar system to parse the date/time with.format (
string
) – The format the date/time is expected to use.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Sets the end date of a
Calends
object, based on theCalends
object’s current value. The inputs are the same as forCreate
, above, except the string → value map option isn’t available, since you’re already specifically setting the end value explicitly.
- func (Calends) SetDuration(duration interface, calendar string) (Calends, error)
- Parametrii
duration (
interface{}
) – The value to parse the new duration from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Sets the duration of a
Calends
object, by adjusting its end point, and using the current start point as an anchor. Theduration
value is interpreted by the calendar system given incalendar
, so is subject to any of its rules.
- func (Calends) SetDurationFromEnd(duration interface, calendar string) (Calends, error)
- Parametrii
duration (
interface{}
) – The value to parse the new duration from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Sets the duration of a
Calends
object, by adjusting its start point, and using the current end point as an anchor. Theduration
value is interpreted by the calendar system given incalendar
, so is subject to any of its rules.
Manipulate
- func (Calends) Add(offset interface, calendar string) (Calends, error)
- Parametrii
offset (
interface{}
) – The value to parse the offset from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Increases the end date of the
Calends
object’s current value byoffset
, as interpreted by the calendar system given incalendar
.
- func (Calends) AddFromEnd(offset interface, calendar string) (Calends, error)
- Parametrii
offset (
interface{}
) – The value to parse the offset from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Increases the start date of the
Calends
object’s current value byoffset
, as interpreted by the calendar system given incalendar
.
- func (Calends) Subtract(offset interface, calendar string) (Calends, error)
- Parametrii
offset (
interface{}
) – The value to parse the offset from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Works the same as
Add
, except it decreases the start date, rather than increasing it.
- func (Calends) SubtractFromEnd(offset interface, calendar string) (Calends, error)
- Parametrii
offset (
interface{}
) – The value to parse the offset from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Works the same as
AddFromEnd
, except it decreases the end date, rather than increasing it.
- func (Calends) Next(offset interface, calendar string) (Calends, error)
- Parametrii
offset (
interface{}
) – The value to parse the offset from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Returns a
Calends
object ofoffset
duration (as interpreted by the calendar system given incalendar
), which abuts theCalends
object’s current value. Ifoffset
is empty,calendar
is ignored, and the current object’s duration is used instead.
- func (Calends) Previous(offset interface, calendar string) (Calends, error)
- Parametrii
offset (
interface{}
) – The value to parse the offset from.calendar (
string
) – The calendar system to parse the date/time with.
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Returns a
Calends
object ofoffset
duration (as interpreted by the calendar system given incalendar
), which abuts theCalends
object’s current value. Ifoffset
is empty,calendar
is ignored, and the current object’s duration is used instead.
Combine
- func (Calends) Merge(c2 Calends) (Calends, error)
- Parametrii
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Returns a
Calends
object spanning from the earliest start date to the latest end date between the currentCalends
object andc2
.
- func (Calends) Intersect(c2 Calends) (Calends, error)
- Parametrii
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Returns a
Calends
object spanning the overlap between the currentCalends
object andc2
. If the current object andc2
don’t overlap, returns an error.
- func (Calends) Gap(c2 Calends) (Calends, error)
- Parametrii
- Întoarce
A new
Calends
object- Tipul întors
- Întoarce
error
when an error occurs;nil
otherwise- Tipul întors
error
ornil
Returns a
Calends
object spanning the gap between the currentCalends
object andc2
. If the current object andc2
overlap (and there is, therefore, no gap to return), returns an error.
Compare
- func (Calends) Difference(c2 Calends, mode string) Float
- Parametrii
- Întoarce
The difference, as an arbitrary-precision floating point number
- Tipul întors
math/big.Float
Returns the difference of the current
Calends
object minusc2
, usingmode
to select which values to use in the calculation. Validmode
s include:start
- use the start date of both the current object andc2
duration
- use the duration of both the current object andc2
end
- use the end date of both the current object andc2
start-end
- use the start of the current object, and the end ofc2
end-start
- use the end of the current object, and the start ofc2
- func (Calends) Compare(c2 Calends, mode string) int
- Parametrii
- Întoarce
A standard comparison result
- Tipul întors
int
Returns
-1
if the currentCalends
object is less thanc2
,0
if they are equal, and1
if the current object is greater thanc2
, usingmode
to select which values to use in the comparison. Validmode
s are the same as for(Calends) Difference
, above.
- func (Calends) Contains(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends
object contains all ofc2
.
- func (Calends) Overlaps(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends
object overlaps withc2
.
- func (Calends) Abuts(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends
object abutsc2
(that is, whether one begins at the same instant the other ends).
- func (Calends) IsSame(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the current
Calends
object covers the same span of time asc2
.
- func (Calends) IsShorter(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the duration of the current
Calends
object andc2
.
- func (Calends) IsSameDuration(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the duration of the current
Calends
object andc2
.
- func (Calends) IsLonger(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the duration of the current
Calends
object andc2
.
- func (Calends) IsBefore(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the entirety of the current
Calends
object with the start date ofc2
.
- func (Calends) StartsBefore(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the start date of the current
Calends
object with the start date ofc2
.
- func (Calends) EndsBefore(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the end date of the current
Calends
object with the start date ofc2
.
- func (Calends) IsDuring(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the entirety of the current
Calends
object lies between the start and end dates ofc2
.
- func (Calends) StartsDuring(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the start date of the current
Calends
object lies between the start and end dates ofc2
.
- func (Calends) EndsDuring(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Checks whether the end date of the current
Calends
object lies between the start and end dates ofc2
.
- func (Calends) IsAfter(c2 Calends) bool
- Parametrii
- Întoarce
The result of the comparison
- Tipul întors
bool
Compares the entirety of the current
Calends
object with the end date ofc2
.
Export
- func (Calends) String() string
- Întoarce
The string representation of the current value.
- Tipul întors
string
Implements the
fmt.Stringer
interface.
- func (Calends) MarshalText() ([]byte, error)
- Întoarce
A byte slice containing the marshalled text.
- Tipul întors
[]byte
- Întoarce
Any error that occurs.
- Tipul întors
error
Implements the
encoding.TextMarshaler
interface.
- func (*Calends) UnmarshalText(in []byte) error
- Parametrii
in (
[]byte
) – A byte slice containing the marshalled text.
- Întoarce
Any error that occurs.
- Tipul întors
error
Implements the
encoding.TextUnmarshaler
interface.
- func (Calends) MarshalJSON() ([]byte, error)
- Întoarce
A byte slice containing the marshalled JSON.
- Tipul întors
[]byte
- Întoarce
Any error that occurs.
- Tipul întors
error
Implements the
encoding/json.Marshaler
interface.
- func (*Calends) UnmarshalJSON(in []byte) error
- Parametrii
in (
[]byte
) – A byte slice containing the marshalled JSON.
- Întoarce
Any error that occurs.
- Tipul întors
error
Implements the
encoding/json.Unmarshaler
interface.