Using Calends in C/C++
Calends exposes a very small handful of things for use outside the library itself. Documented here are the parts most users will interact with.
Calends also exposes functions and types for extending the library’s functionality. These are covered in the Custom Calendars in C/C++ section.
Bemærk
Because C doesn’t support objects, the library returns an identifier instead
of an actual Calends
value, keeping a reference to the internal
Calends
object in the Golang portions of the process space. This
identifier is specific to the process in which it is generated, and is
therefore only useful within that process itself. To save the value for
later, use one of the marshalling functions documented below, and then the
corresponding unmarshalling function to retrieve it elsewhere.
Create
-
long long unsigned int Calends_create_string(char *value, char *calendar, char *format)
-
long long unsigned int Calends_create_string_range(char *start, char *end, char *calendar, char *format)
-
long long unsigned int Calends_create_string_start_period(char *start, char *duration, char *calendar, char *format)
-
long long unsigned int Calends_create_string_end_period(char *duration, char *end, char *calendar, char *format)
-
long long unsigned int Calends_create_long_long(long long int value, char *calendar, char *format)
-
long long unsigned int Calends_create_long_long_range(long long int start, long long int end, char *calendar, char *format)
-
long long unsigned int Calends_create_long_long_start_period(long long int start, long long int duration, char *calendar, char *format)
-
long long unsigned int Calends_create_long_long_end_period(long long int duration, long long int end, char *calendar, char *format)
-
long long unsigned int Calends_create_double(double value, char *calendar, char *format)
-
long long unsigned int Calends_create_double_range(double start, double end, char *calendar, char *format)
-
long long unsigned int Calends_create_double_start_period(double start, double duration, char *calendar, char *format)
-
long long unsigned int Calends_create_double_end_period(double duration, double end, char *calendar, char *format)
- Parametre
value (
char*
orlong long int
ordouble
) – The value to parse the date/time from.start (
char*
orlong long int
ordouble
) – The value to parse the start date/time from.duration (
char*
orlong long int
ordouble
) – The value to parse the duration from.end (
char*
orlong long int
ordouble
) – The value to parse the end date/time from.calendar (
char*
) – The calendar system to parse the date(s)/time(s) with.format (
char*
) – The format the date(s)/time(s) is/are expected to use.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Creates a new
Calends
object identifier, usingcalendar
to select a calendar system, andformat
to parse the contents ofvalue
,start
,end
, and/orduration
into theCalends
object’s internal instants.
Read
-
char *Calends_date(long long unsigned int c, char *calendar, char *format)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.calendar (
char*
) – The calendar system to format the date/time with.format (
char*
) – The format the date/time is expected to be in.
- Returnerer
The start date of the
Calends
object- Returtype
char*
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
.
-
char *Calends_end_date(long long unsigned int c, char *calendar, char *format)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.calendar (
char*
) – The calendar system to format the date/time with.format (
char*
) – The format the date/time is expected to be in.
- Returnerer
The end date of the
Calends
object- Returtype
char*
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
.
-
char *Calends_duration(long long unsigned int c)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.
- Returnerer
The duration of the
Calends
object- Returtype
char*
Retrieves the duration of the
Calends
object as a string. This value will be0
if theCalends
object is an instant.
Update
-
long long unsigned int Calends_with_date_string(long long unsigned int c, char *value, char *calendar, char *format)
-
long long unsigned int Calends_with_date_long_long(long long unsigned int c, long long int value, char *calendar, char *format)
-
long long unsigned int Calends_with_date_double(long long unsigned int c, double value, char *calendar, char *format)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.value (
char*
orlong long int
ordouble
) – The value to parse the date/time from.calendar (
char*
) – The calendar system to parse the date/time with.format (
char*
) – The format the date/time is expected to use.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Sets the start date of a
Calends
object, based on theCalends
object’s current value. The inputs are the same as for theCalends_create_{type}()
functions, above.
-
long long unsigned int Calends_with_end_date_string(long long unsigned int c, char *value, char *calendar, char *format)
-
long long unsigned int Calends_with_end_date_long_long(long long unsigned int c, long long int value, char *calendar, char *format)
-
long long unsigned int Calends_with_end_date_double(long long unsigned int c, double value, char *calendar, char *format)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.value (
char*
orlong long int
ordouble
) – The value to parse the date/time from.calendar (
char*
) – The calendar system to parse the date/time with.format (
char*
) – The format the date/time is expected to use.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Sets the end date of a
Calends
object, based on theCalends
object’s current value. The inputs are the same as for theCalends_create_{type}()
functions, above.
-
long long unsigned int Calends_with_duration_string(long long unsigned int c, char *duration, char *calendar)
-
long long unsigned int Calends_with_duration_long_long(long long unsigned int c, long long int duration, char *calendar)
-
long long unsigned int Calends_with_duration_double(long long unsigned int c, double duration, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.duration (
char*
orlong long int
ordouble
) – The value to parse the new duration from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
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.
-
long long unsigned int Calends_with_duration_from_end_string(long long unsigned int c, char *duration, char *calendar)
-
long long unsigned int Calends_with_duration_from_end_long_long(long long unsigned int c, long long int duration, char *calendar)
-
long long unsigned int Calends_with_duration_from_end_double(long long unsigned int c, double duration, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.duration (
char*
orlong long int
ordouble
) – The value to parse the new duration from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
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.
Destroy
-
void Calends_release(long long unsigned int c)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.
Releases an internal
Calends
object, freeing its associated memory. Since the memory used in this case is kept within the Golang portion of the process space, we don’t have access to free that memory using more conventional C/C++ methods, so this function offers that functionality instead.
Manipulate
-
long long unsigned int Calends_add_string(long long unsigned int c, char *offset, char *calendar)
-
long long unsigned int Calends_add_long_long(long long unsigned int c, long long int offset, char *calendar)
-
long long unsigned int Calends_add_double(long long unsigned int c, double offset, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.offset (
char*
) – The value to parse the offset from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Increases the end date of the
Calends
object’s current value byoffset
, as interpreted by the calendar system given incalendar
.
-
long long unsigned int Calends_add_from_end_string(long long unsigned int c, char *offset, char *calendar)
-
long long unsigned int Calends_add_from_end_long_long(long long unsigned int c, long long int offset, char *calendar)
-
long long unsigned int Calends_add_from_end_double(long long unsigned int c, double offset, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.offset (
char*
) – The value to parse the offset from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Increases the start date of the
Calends
object’s current value byoffset
, as interpreted by the calendar system given incalendar
.
-
long long unsigned int Calends_subtract_string(long long unsigned int c, char *offset, char *calendar)
-
long long unsigned int Calends_subtract_long_long(long long unsigned int c, long long int offset, char *calendar)
-
long long unsigned int Calends_subtract_double(long long unsigned int c, double offset, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.offset (
char*
) – The value to parse the offset from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Works the same as
Calends_add_{type}()
, except it decreases the start date, rather than increasing it.
-
long long unsigned int Calends_subtract_from_end_string(long long unsigned int c, char *offset, char *calendar)
-
long long unsigned int Calends_subtract_from_end_long_long(long long unsigned int c, long long int offset, char *calendar)
-
long long unsigned int Calends_subtract_from_end_double(long long unsigned int c, double offset, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.offset (
char*
) – The value to parse the offset from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Works the same as
Calends_add_from_end_{type}()
, except it decreases the end date, rather than increasing it.
-
long long unsigned int Calends_next_string(long long unsigned int c, char *offset, char *calendar)
-
long long unsigned int Calends_next_long_long(long long unsigned int c, long long int offset, char *calendar)
-
long long unsigned int Calends_next_double(long long unsigned int c, double offset, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.offset (
char*
) – The value to parse the offset from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Returns the identifier of a
Calends
object ofoffset
duration (as interpreted by the calendar system given incalendar
), which abuts the currentCalends
object’s start value. Ifoffset
is empty,calendar
is ignored, and the current object’s duration is used instead.
-
long long unsigned int Calends_previous_string(long long unsigned int c, char *offset, char *calendar)
-
long long unsigned int Calends_previous_long_long(long long unsigned int c, long long int offset, char *calendar)
-
long long unsigned int Calends_previous_double(long long unsigned int c, double offset, char *calendar)
- Parametre
c (
long long unsigned int
) – The identifier of the currentCalends
object.offset (
char*
) – The value to parse the offset from.calendar (
char*
) – The calendar system to parse the date/time with.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Returns the identifier of a
Calends
object ofoffset
duration (as interpreted by the calendar system given incalendar
), which abuts the currentCalends
object’s end value. Ifoffset
is empty,calendar
is ignored, and the current object’s duration is used instead.
Combine
-
long long unsigned int Calends_merge(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to merge.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Returns a
Calends
object spanning from the earliest start date to the latest end date betweenc1
andc2
.
-
long long unsigned int Calends_intersect(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to intersect.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Returns a
Calends
object spanning the overlap betweenc1
andc2
. Ifc1
andc2
don’t overlap, returns an error.
-
long long unsigned int Calends_gap(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to gap.
- Returnerer
A new
Calends
object identifier- Returtype
long long unsigned int
Returns a
Calends
object spanning the gap betweenc1
andc2
. Ifc1
andc2
overlap (and there is, therefore, no gap to return), returns an error.
Compare
-
char *Calends_difference(long long unsigned int c1, long long unsigned int c2, char *mode)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.mode (
char*
) – The comparison mode.
- Returnerer
The difference, as a decimal string
- Returtype
char*
Returns the difference of
c1
minusc2
, usingmode
to select which values to use in the calculation. Validmode
s include:
-
signed char Calends_compare(long long unsigned int c1, long long unsigned int c2, char *mode)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.mode (
char*
) – The comparison mode.
- Returnerer
A standard comparison result
- Returtype
signed char
Returns
-1
ifc1
is less thanc2
,0
if they are equal, and1
ifc1
is greater thanc2
, usingmode
to select which values to use in the comparison. Validmode
s are the same as forCalends_difference()
, above.
-
signed char Calends_contains(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_overlaps(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_abuts(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
Checks whether
c1
abutsc2
(that is, whether one begins at the same instant the other ends).
-
signed char Calends_is_same(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_is_shorter(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_is_same_duration(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_is_longer(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_is_before(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_starts_before(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_ends_before(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_is_during(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
Checks whether the entirety of
c1
lies between the start and end dates ofc2
.
-
signed char Calends_starts_during(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
Checks whether the start date of
c1
lies between the start and end dates ofc2
.
-
signed char Calends_ends_during(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
Checks whether the end date of
c1
lies between the start and end dates ofc2
.
-
signed char Calends_is_after(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_starts_after(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
-
signed char Calends_ends_after(long long unsigned int c1, long long unsigned int c2)
- Parametre
c1 (
long long unsigned int
) – The identifier of the currentCalends
object.c2 (
long long unsigned int
) – The identifier of theCalends
object to compare.
- Returnerer
The result of the comparison
- Returtype
signed char
Export
-
char *Calends_string(long long unsigned int c)
- Parametre
c (
long long unsigned int
) – TheCalends
object to convert.
- Returnerer
The string representation of the current value.
- Returtype
char*
Converts the value of
c
to a string.
-
char *Calends_encode_text(long long unsigned int c)
- Parametre
c (
long long unsigned int
) – TheCalends
object to encode.
- Returnerer
The encoded representation of the current value.
- Returtype
char*
Encodes the value of
c
as text, for external storage.
-
long long unsigned int Calends_decode_text(char *in)
- Parametre
in (
char*
) – The encoded representation of aCalends
value.
- Returnerer
The decoded
Calends
object’s identifier.- Returtype
long long unsigned int
Decodes the value of
in
to a newCalends
object.
Error Handling
-
void Calends_register_panic_handler(Calends_panic_handler callback)
- Parametre
callback (
void function(char*)
) – A panic handler function.
When errors happen, Go normally returns the error as an additional return value. Since most programming languages don’t support this, the C/C++ interface to the library instead relies on a Golang feature called a
panic
, which is a lot like an exception in many other languages. This function allows users to register a callback function of their own to handle the error conditions which might come up.callback
should accept achar*
containing the error message supplied by the library, and return nothing.