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.

Примечание

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)

Параметры

value (char* or long long int or double) – The value to parse the date/time from.
start (char* or long long int or double) – The value to parse the start date/time from.
duration (char* or long long int or double) – The value to parse the duration from.
end (char* or long long int or double) – 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.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Creates a new Calends object identifier, using calendar to select a calendar system, and format to parse the contents of value, start, end, and/or duration into the Calends object’s internal instants.

Read

char *Calends_date(long long unsigned int c, char *calendar, char *format)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
calendar (char*) – The calendar system to format the date/time with.
format (char*) – The format the date/time is expected to be in.

Результат

The start date of the Calends object

Тип результата

char*

Retrieves the start date of the Calends object as a string. The value is generated by the calendar system given in calendar, according to the format string in format.

char *Calends_end_date(long long unsigned int c, char *calendar, char *format)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
calendar (char*) – The calendar system to format the date/time with.
format (char*) – The format the date/time is expected to be in.

Результат

The end date of the Calends object

Тип результата

char*

Retrieves the end date of the Calends object as a string. The value is generated by the calendar system given in calendar, according to the format string in format.

char *Calends_duration(long long unsigned int c)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.

Результат

The duration of the Calends object

Тип результата

char*

Retrieves the duration of the Calends object as a string. This value will be 0 if the Calends 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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
value (char* or long long int or double) – 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.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Sets the start date of a Calends object, based on the Calends object’s current value. The inputs are the same as for the Calends_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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
value (char* or long long int or double) – 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.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Sets the end date of a Calends object, based on the Calends object’s current value. The inputs are the same as for the Calends_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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
duration (char* or long long int or double) – The value to parse the new duration from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

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. The duration value is interpreted by the calendar system given in calendar, 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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
duration (char* or long long int or double) – The value to parse the new duration from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

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. The duration value is interpreted by the calendar system given in calendar, so is subject to any of its rules.

Destroy

void Calends_release(long long unsigned int c)

Параметры

c (long long unsigned int) – The identifier of the current Calends 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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
offset (char*) – The value to parse the offset from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Increases the end date of the Calends object’s current value by offset, as interpreted by the calendar system given in calendar.

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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
offset (char*) – The value to parse the offset from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Increases the start date of the Calends object’s current value by offset, as interpreted by the calendar system given in calendar.

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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
offset (char*) – The value to parse the offset from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
offset (char*) – The value to parse the offset from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
offset (char*) – The value to parse the offset from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Returns the identifier of a Calends object of offset duration (as interpreted by the calendar system given in calendar), which abuts the current Calends object’s start value. If offset 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)

Параметры

c (long long unsigned int) – The identifier of the current Calends object.
offset (char*) – The value to parse the offset from.
calendar (char*) – The calendar system to parse the date/time with.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Returns the identifier of a Calends object of offset duration (as interpreted by the calendar system given in calendar), which abuts the current Calends object’s end value. If offset 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)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to merge.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Returns a Calends object spanning from the earliest start date to the latest end date between c1 and c2.

long long unsigned int Calends_intersect(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to intersect.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Returns a Calends object spanning the overlap between c1 and c2. If c1 and c2 don’t overlap, returns an error.

long long unsigned int Calends_gap(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to gap.

Результат

A new Calends object identifier

Тип результата

long long unsigned int

Returns a Calends object spanning the gap between c1 and c2. If c1 and c2 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)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.
mode (char*) – The comparison mode.

Результат

The difference, as a decimal string

Тип результата

char*

Returns the difference of c1 minus c2, using mode to select which values to use in the calculation. Valid modes include:

"start" - use the start date of both c1 and c2
"duration" - use the duration of both c1 and c2
"end" - use the end date of both c1 and c2
"start-end" - use the start of c1, and the end of c2
"end-start" - use the end of c1, and the start of c2

signed char Calends_compare(long long unsigned int c1, long long unsigned int c2, char *mode)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.
mode (char*) – The comparison mode.

Результат

A standard comparison result

Тип результата

signed char

Returns -1 if c1 is less than c2, 0 if they are equal, and 1 if c1 is greater than c2, using mode to select which values to use in the comparison. Valid modes are the same as for Calends_difference(), above.

signed char Calends_contains(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Checks whether c1 contains all of c2.

signed char Calends_overlaps(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Checks whether c1 overlaps with c2.

signed char Calends_abuts(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Checks whether c1 abuts c2 (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)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Checks whether c1 covers the same span of time as c2.

signed char Calends_is_shorter(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the duration of c1 and c2.

signed char Calends_is_same_duration(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the duration of c1 and c2.

signed char Calends_is_longer(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the duration of c1 and c2.

signed char Calends_is_before(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the entirety of c1 with the start date of c2.

signed char Calends_starts_before(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the start date of c1 with the start date of c2.

signed char Calends_ends_before(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the end date of c1 with the start date of c2.

signed char Calends_is_during(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Checks whether the entirety of c1 lies between the start and end dates of c2.

signed char Calends_starts_during(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Checks whether the start date of c1 lies between the start and end dates of c2.

signed char Calends_ends_during(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Checks whether the end date of c1 lies between the start and end dates of c2.

signed char Calends_is_after(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the entirety of c1 with the end date of c2.

signed char Calends_starts_after(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the start date of c1 with the end date of c2.

signed char Calends_ends_after(long long unsigned int c1, long long unsigned int c2)

Параметры

c1 (long long unsigned int) – The identifier of the current Calends object.
c2 (long long unsigned int) – The identifier of the Calends object to compare.

Результат

The result of the comparison

Тип результата

signed char

Compares the end date of c1 with the end date of c2.

Export

char *Calends_string(long long unsigned int c)

Параметры

c (long long unsigned int) – The Calends object to convert.

Результат

The string representation of the current value.

Тип результата

char*

Converts the value of c to a string.

char *Calends_encode_text(long long unsigned int c)

Параметры

c (long long unsigned int) – The Calends object to encode.

Результат

The encoded representation of the current value.

Тип результата

char*

Encodes the value of c as text, for external storage.

long long unsigned int Calends_decode_text(char *in)

Параметры

in (char*) – The encoded representation of a Calends value.

Результат

The decoded Calends object’s identifier.

Тип результата

long long unsigned int

Decodes the value of in to a new Calends object.

char *Calends_encode_json(long long unsigned int c)

Параметры

c (long long unsigned int) – The Calends object to encode.

Результат

The encoded representation of the current value.

Тип результата

char*

Encodes the value of c as JSON, for external communication.

long long unsigned int Calends_decode_json(char *in)

Параметры

in (char*) – The encoded representation of a Calends value.

Результат

The decoded Calends object’s identifier.

Тип результата

long long unsigned int

Decodes the value of in to a new Calends object.

Error Handling

void Calends_register_panic_handler(Calends_panic_handler callback)

Параметры

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 a char* containing the error message supplied by the library, and return nothing.