libdt

Contents:

struct dt_interval

#include <dt_types.h>

Interval object.

Public Members

unsigned long seconds

Seconds part (>=0UL)

unsigned long nano_seconds

Nano-seconds part (0UL-999999999UL)

struct dt_offset

#include <dt_types.h>

Offset object.

Public Members

dt_interval_t duration

Duration of the offset.

dt_bool_t is_forward

Offset direction.

struct dt_representation

#include <dt_types.h>

Date/time representation object.

Public Members

int year

Year (any, except 0)

unsigned short month

Month (1-12)

unsigned short day

Day (1-28/29/30/31)

unsigned short hour

Hour (0-23)

unsigned short minute

Minute (0-59)

unsigned short second

Second (0-59 or (0-60 if leap second - is not supporting now))

unsigned long nano_second

Nano-second (0UL-999999999UL)

struct dt_timestamp

#include <dt_types.h>

Timestamp object, which is opaque to user.

This timestamp provides a nano-second precision and has no lower limit as time_t has. Do not access it’s fields directly and/or in any way rely on it’s structure as it is a subject to change w/o any announcement.

Public Members

long second

Seconds from some particular moment on Time Continuum (platform-specific)

unsigned long nano_second

Nano-second part (0UL-999999999UL)

struct dt_timezone

#include <dt_types.h>

Timezone representation

Attention

it’s internal implementation can be changed from version to version

file dt.h

#include <libdt/export.h>#include <time.h>#include <libdt/dt_types.h>#include <libdt/dt_convert.h>

Functions

LIBDT_EXPORT dt_bool_t dt_is_leap_year(int year)

Checks for leap year.

Return

Check result

Parameters

• year -

  Year to check (Non-positive years are always not leap)

LIBDT_EXPORT const char* dt_strerror(dt_status_t status)

Returns string represenatation of the datetime error code.

LIBDT_EXPORT dt_bool_t dt_validate_timestamp(const dt_timestamp_t * timestamp)

dt_validate_timestamp Validates timestamp

Return

DT_TRUE if timestamp is valid, otherwise DT_FALSE

Parameters

• timestamp -

  timestamp to validation

LIBDT_EXPORT dt_status_t dt_now(dt_timestamp_t * result)

Returns a current timestamp.

Return

Result status of the operation

Parameters

• result -

  Current timestamp [OUT]

LIBDT_EXPORT dt_status_t dt_compare_timestamps(const dt_timestamp_t * lhs, const dt_timestamp_t * rhs, dt_compare_result_t * result)

Compares two timestamps.

Return

Result status of the operation

Parameters

• lhs -

  First timestamp to compare

• rhs -

  Second timestamp to compare

• result -

  Zero if timestamps are equal, less than zero if first timestamp is before second and more than zero otherwise [OUT]

LIBDT_EXPORT dt_status_t dt_offset_between(const dt_timestamp_t * lhs, const dt_timestamp_t * rhs, dt_offset_t * result)

Obtains an offset between timestamps.

Return

Result status of the operation

Parameters

• lhs -

  First timestamp

• rhs -

  Second timestamp

• result -

  Offset b/w timestamps [OUT]

LIBDT_EXPORT dt_bool_t dt_validate_offset(const dt_offset_t * offset)

dt_validate_offset Validates offset

Return

DT_TRUE if offset is valid, otherwise DT_FALSE

Parameters

• offset -

  offset to validating

LIBDT_EXPORT dt_status_t dt_apply_offset(const dt_timestamp_t * lhs, const dt_offset_t * rhs, dt_timestamp_t * result)

Applies offset on the timestamp.

Return

Result status of the operation

Parameters

• lhs -

  Timestamp to apply the offset on

• rhs -

  Offset to apply on timestamp

• result -

  Result offset [OUT]

LIBDT_EXPORT dt_status_t dt_init_interval(unsigned long seconds, unsigned long nano_seconds, dt_interval_t * result)

Initializes time interval.

Seconds part is to be subtracted from nano-seconds and appended to seconds

Return

Result status of the operation

Parameters

• seconds -

  Seconds

• nano_seconds -

  Nano-seconds

• result -

  interval to initialize [OUT]

LIBDT_EXPORT dt_bool_t dt_validate_interval(const dt_interval_t * test)

Validates interval

Return

DT_FALSE if test is NULL or test is not valid, otherwise DT_TRUE

Parameters

• test -

  Interval to validate

LIBDT_EXPORT dt_status_t dt_compare_intervals(const dt_interval_t * lhs, const dt_interval_t * rhs, dt_compare_result_t * result)

Compares two intervals.

Return

Result status of the operation

Parameters

• lhs -

  First interval to compare

• rhs -

  Second interval to compare

• result -

  Zero if intervals are equal, less than zero if first intervals is less than second and more than zero otherwise [OUT]

LIBDT_EXPORT dt_status_t dt_sum_intervals(const dt_interval_t * lhs, const dt_interval_t * rhs, dt_interval_t * result)

Summarizes two intervals.

Return

Result status of the operation

Parameters

• lhs -

  First interval to summarize

• rhs -

  Second interval to summarize

• result -

  Result interval [OUT]

LIBDT_EXPORT dt_status_t dt_sub_intervals(const dt_interval_t * lhs, const dt_interval_t * rhs, dt_interval_t * result)

Subtracts two intervals.

Note

Zero interval is returned if the greater is subtracting from the lesser one

Return

Result status of the operation

Parameters

• lhs -

  First interval to subtract

• rhs -

  Second interval to subtract

• result -

  Result interval [OUT]

LIBDT_EXPORT dt_status_t dt_mul_interval(const dt_interval_t * lhs, double rhs, dt_interval_t * result)

Multiplies an interval.

Return

Result status of the operation

Parameters

• lhs -

  First interval to multiply

• rhs -

  Multiplier

• result -

  Result interval [OUT]

LIBDT_EXPORT dt_bool_t dt_validate_representation(const dt_representation_t * representation)

Validates a date/time representation.

Return

DT_TRUE if representation is valid, otherwise DT_FALSE TODO: Leap seconds support!

Parameters

• representation -

  Representation to validate

LIBDT_EXPORT dt_status_t dt_init_representation(int year, unsigned short month, unsigned short day, unsigned short hour, unsigned short minute, unsigned short second, unsigned long nano_second, dt_representation_t * result)

Initializes representetion with error checking.

Return

Result status of the operation

Parameters

• year -

  Year

• month -

  Month

• day -

  Day

• hour -

  Hour

• minute -

  Minute

• second -

  Second

• nano_second -

  Nano-second

• result -

  Representation to init [OUT]

LIBDT_EXPORT dt_status_t dt_timezone_lookup(const char * timezone_name, dt_timezone_t * timezone)

Lookups timezone object for future usage in corresponding api. Timezone object must be freed with dt_timezone_cleanup() function on successful operation

Return

Result status of the operation

See

dt_timezone_cleanup

Parameters

• timezone_name -

  name of timezone for lookup, it can be in olsen database format, or in windows standard time format

• timezone -

  [IN/OUT]pointer to timezone object

LIBDT_EXPORT dt_status_t dt_timezone_cleanup(dt_timezone_t * timezone)

Frees resources connected with timezone object.

Return

Result status of the operation

Parameters

• timezone -

  pointer to timezone object

LIBDT_EXPORT dt_status_t dt_timestamp_to_representation(const dt_timestamp_t * timestamp, const dt_timezone_t * timezone, dt_representation_t * representation)

Represents a timestamp using a timezone name.

Return

Result status of the operation

Parameters

• timestamp -

  Timestamp to represent

• timezone -

  Timezone or NULL if local timezone is considered

• representation -

  Timestamp representation [OUT]

LIBDT_EXPORT dt_status_t dt_representation_to_timestamp(const dt_representation_t * representation, const dt_timezone_t * timezone, dt_timestamp_t * first_timestamp, dt_timestamp_t * second_timestamp)

Returns a timestamps for a representation in timezone by it’s name.

It is possible for the representation to have two timestamps, e.g. when a time is “going back” for an hour.

Return

Result status of the operation

Parameters

• representation -

  Representation to fetch a timestamp of

• timezone -

  Timezone or NULL if local timezone is considered

• first_timestamp -

  First representation’s timestamp [OUT]

• second_timestamp -

  Optional second representation’s timestamp (can be NULL, not supported at the moment) [OUT]

LIBDT_EXPORT dt_status_t dt_representation_day_of_week(const dt_representation_t * representation, int * day_of_week)

Returns representation’s week day number.

Return

Result status of the operation

Parameters

• representation -

  Representation object

• day_of_week -

  Representation’s day of week (1-7, 1 is Sunday) [OUT]

LIBDT_EXPORT dt_status_t dt_representation_day_of_year(const dt_representation_t * representation, int * day_of_year)

Returns representation’s day of year.

Return

Result status of the operation

Parameters

• representation -

  Representation object

• day_of_year -

  Representation’s day of year (1-365/366) [OUT]

LIBDT_EXPORT dt_status_t dt_to_string(const dt_representation_t * representation, const char * fmt, char * str_buffer, size_t str_buffer_size)

Converts representation to string.

Return

Result status of the operation

Note

Wrong format handling policy is deciding such as platform depended strftime policy, so watch yours compiler reference for more details.

Parameters

• representation -

  Representation to convert

• fmt -

  Format string, see strptime()/strftime() plus “%f” for nano-seconds

• str_buffer -

  Buffer to fill [OUT]

• str_buffer_size -

  A size of the buffer to fill

LIBDT_EXPORT dt_status_t dt_from_string(const char * str, const char * fmt, dt_representation_t * representation)

Converts string to representation.

Return

Result status of the operation

Parameters

• str -

  A NULL-terminated string to parse

• fmt -

  Format string, see strptime()/strftime() plus “%f” for nano-seconds

• representation -

  Representation object to fill [OUT]

file dt_convert.h

#include <libdt/export.h>#include <libdt/dt_types.h>

Functions

LIBDT_EXPORT dt_status_t dt_posix_time_to_timestamp(time_t time, unsigned long nano_second, dt_timestamp_t * result)

Loads timestamp from POSIX time.

Note

POSIX time (time_t) supports greater than zero values only

Return

Result status of the operation

Parameters

• time -

  POSIX time value

• nano_second -

  Nano-seconds part of the timestamp

• result -

  Timestamp for the POSIX time value [OUT]

LIBDT_EXPORT dt_status_t dt_timestamp_to_posix_time(const dt_timestamp_t * timestamp, time_t * time, unsigned long * nano_second)

Converts timestamp to POSIX time value.

Function returns DT_INVALID_ARGUMENT if a timestamp could not be represented by POSIX time.

Note

POSIX time (time_t) supports greater than zero values only

Return

Result status of the operation

Parameters

• timestamp -

  Timestamp to convert

• time -

  POSIX time for the timestamp [OUT]

• nano_second -

  Optional nano-seconds part of the timestamp (0L-999999999L), could be NULL if not used [OUT]

LIBDT_EXPORT dt_status_t dt_interval_to_timespec(const dt_interval_t * interval, struct timespec * result)

Converts interval to timespec structure.

Return

Result status of the operation

Parameters

• interval -

  Interval to convert to timespec structure

• result -

  Timespec structure [OUT]

LIBDT_EXPORT dt_status_t dt_timespec_to_interval(const struct timespec * ts, dt_interval_t * result)

Converts timespec structure to interval.

Return

Result status of the operation

Parameters

• ts -

  Timespec structure

• result -

  Interval [OUT]

LIBDT_EXPORT dt_status_t dt_representation_to_tm(const dt_representation_t * representation, struct tm * tm)

Converts a localized representation to POSIX breakdown time structure. Nano seconds will be lost!

Return

Result status of the operation

Note

This method does not validate representaion so invalid POSIX breakdown time structure could be returned

Parameters

• representation -

  Representation object

• tm -

  POSIX breakdown time structure for the representation [OUT]

LIBDT_EXPORT dt_status_t dt_tm_to_representation(const struct tm * tm, long nano_second, dt_representation_t * representation)

Converts a POSIX breakdown time structure to representation.

Return

Result status of the operation

Note

Invalid representation could be returned if an invalid POSIX breakdown time structure has been provided

Parameters

• tm -

  POSIX breakdown time structure

• nano_second -

  Nano-second part of the representation

• representation -

  Representation of POSIX breakdown time structure [OUT]

file dt_posix.h

#include <libdt/export.h>#include <time.h>

Defines

DT_INVALID_POSIX_TIME

Libc use this value to indicate an error.

Functions

LIBDT_EXPORT struct tm* localtime_tz(const time_t * time, const char * tz_name, struct tm * result)

Converts time_t to local time in specific Time Zone. See man localtime.

Return

pointer to result tm instance, or NULL in error case.

Parameters

• time -

  - time to format

• tz_name -

  - name of time zone. Must be in format <Area>/<Place>, such as Europe/Moscow or Asia/Oral, or in Windows standard time format.

• result -

  - variable for result. Value will be set to local time representation

LIBDT_EXPORT time_t mktime_tz(const struct tm * tm, const char * tz_name)

Converts local time in specific Time Zone to time_t. See man mktime.

Return

converted time returned or DT_INVALID_POSIX_TIME in error case.

Parameters

• tm -

  - tm instance which will be used to make timestamp

• tz_name -

  - name of time zone. Must be in format <Area>/<Place>, such as Europe/Moscow or Asia/Oral, or in Windows standard time format.

file dt_types.h

Defines

DT_SECONDS_PER_DAY

DT_SECONDS_PER_HOUR

DT_SECONDS_PER_MINUTE

Typedefs

typedef struct dt_timestamp dt_timestamp_t

Timestamp object, which is opaque to user.

This timestamp provides a nano-second precision and has no lower limit as time_t has. Do not access it’s fields directly and/or in any way rely on it’s structure as it is a subject to change w/o any announcement.

typedef struct dt_interval dt_interval_t

Interval object.

typedef struct dt_offset dt_offset_t

Offset object.

typedef struct dt_representation dt_representation_t

Date/time representation object.

typedef struct dt_timezone dt_timezone_t

Timezone representation

Attention

it’s internal implementation can be changed from version to version

Enums

enum dt_status_t

Result status values.

Values:

DT_OK

No error.

DT_INVALID_ARGUMENT

Invalid argument.

DT_TIMEZONE_NOT_FOUND

Timezone not found.

DT_SYSTEM_CALL_ERROR

System call error.

DT_NO_MORE_ITEMS

No more items for enumeration available.

DT_OVERFLOW

Operation caused an overflow.

DT_UNKNOWN_ERROR

Unknown error.

enum dt_bool_t

Boolean type.

Values:

DT_FALSE = 0

DT_TRUE

enum dt_compare_result_t

Compare result.

Values:

DT_LESSER = -1

DT_EQUALS = 0

DT_GREATER = 1

file export.h

Defines

LIBDT_EXPORT

group GeneralPurpose

group Timestamp

group Interval

group Representation

group StringConversion

group TypeConversion

group STDExtendFunctons

dir include

dir include/libdt