Ion C
C library for Ion
Data Structures | Macros | Functions
ion_timestamp.h File Reference
#include "ion_types.h"
#include "ion_platform_config.h"
#include "time.h"

Go to the source code of this file.

Data Structures

struct  _ion_timestamp
 

Macros

#define ION_TT_BIT_YEAR   0x01
 
#define ION_TT_BIT_MONTH   0x02
 
#define ION_TT_BIT_DAY   0x04
 
#define ION_TT_BIT_MIN   0x10
 
#define ION_TT_BIT_SEC   0x20 /* with secs must have time & date */
 
#define ION_TT_BIT_FRAC   0x40 /* must have all */
 
#define ION_TS_YEAR   (0x0 | ION_TT_BIT_YEAR)
 
#define ION_TS_MONTH   (ION_TS_YEAR | ION_TT_BIT_MONTH)
 
#define ION_TS_DAY   (ION_TS_MONTH | ION_TT_BIT_DAY)
 
#define ION_TS_MIN   (ION_TS_DAY | ION_TT_BIT_MIN)
 
#define ION_TS_SEC   (ION_TS_MIN | ION_TT_BIT_SEC)
 
#define ION_TS_FRAC   (ION_TS_SEC | ION_TT_BIT_FRAC)
 
#define ION_MAX_TIMESTAMP_STRING   (26+DECQUAD_String) /* y-m-dTh:m:s.<dec>+h:m */
 

Functions

ION_API_EXPORT iERR ion_timestamp_get_precision (const ION_TIMESTAMP *ptime, int *precision)
 
ION_API_EXPORT iERR ion_timestamp_to_string (ION_TIMESTAMP *ptime, char *buffer, SIZE buf_length, SIZE *output_length, decContext *pcontext)
 
ION_API_EXPORT iERR ion_timestamp_parse (ION_TIMESTAMP *ptime, char *buffer, SIZE length, SIZE *p_characters_used, decContext *pcontext)
 
ION_API_EXPORT iERR ion_timestamp_for_time_t (ION_TIMESTAMP *ptime, const time_t *time)
 
ION_API_EXPORT iERR ion_timestamp_to_time_t (const ION_TIMESTAMP *ptime, time_t *time)
 
ION_API_EXPORT iERR ion_timestamp_equals (const ION_TIMESTAMP *ptime1, const ION_TIMESTAMP *ptime2, BOOL *is_equal, decContext *pcontext)
 
ION_API_EXPORT iERR ion_timestamp_instant_equals (const ION_TIMESTAMP *ptime1, const ION_TIMESTAMP *ptime2, BOOL *is_equal, decContext *pcontext)
 
ION_API_EXPORT iERR ion_timestamp_for_year (ION_TIMESTAMP *ptime, int year)
 
ION_API_EXPORT iERR ion_timestamp_for_month (ION_TIMESTAMP *ptime, int year, int month)
 
ION_API_EXPORT iERR ion_timestamp_for_day (ION_TIMESTAMP *ptime, int year, int month, int day)
 
ION_API_EXPORT iERR ion_timestamp_for_minute (ION_TIMESTAMP *ptime, int year, int month, int day, int hours, int minutes)
 
ION_API_EXPORT iERR ion_timestamp_for_second (ION_TIMESTAMP *ptime, int year, int month, int day, int hours, int minutes, int seconds)
 
ION_API_EXPORT iERR ion_timestamp_for_fraction (ION_TIMESTAMP *ptime, int year, int month, int day, int hours, int minutes, int seconds, decQuad *p_fraction, decContext *pcontext)
 
ION_API_EXPORT iERR ion_timestamp_get_thru_year (ION_TIMESTAMP *ptime, int *p_year)
 
ION_API_EXPORT iERR ion_timestamp_get_thru_month (ION_TIMESTAMP *ptime, int *p_year, int *p_month)
 
ION_API_EXPORT iERR ion_timestamp_get_thru_day (ION_TIMESTAMP *ptime, int *p_year, int *p_month, int *p_day)
 
ION_API_EXPORT iERR ion_timestamp_get_thru_minute (ION_TIMESTAMP *ptime, int *p_year, int *p_month, int *p_day, int *p_hour, int *p_minute)
 
ION_API_EXPORT iERR ion_timestamp_get_thru_second (ION_TIMESTAMP *ptime, int *p_year, int *p_month, int *p_day, int *p_hour, int *p_minute, int *p_second)
 
ION_API_EXPORT iERR ion_timestamp_get_thru_fraction (ION_TIMESTAMP *ptime, int *p_year, int *p_month, int *p_day, int *p_hour, int *p_minute, int *p_second, decQuad *p_fraction)
 
ION_API_EXPORT iERR ion_timestamp_has_local_offset (ION_TIMESTAMP *ptime, BOOL *p_has_local_offset)
 
ION_API_EXPORT iERR ion_timestamp_get_local_offset (ION_TIMESTAMP *ptime, int *p_offset_minutes)
 
ION_API_EXPORT iERR ion_timestamp_unset_local_offset (ION_TIMESTAMP *ptime)
 
ION_API_EXPORT iERR ion_timestamp_set_local_offset (ION_TIMESTAMP *ptime, int offset_minutes)
 

Function Documentation

◆ ion_timestamp_equals()

ION_API_EXPORT iERR ion_timestamp_equals ( const ION_TIMESTAMP *  ptime1,
const ION_TIMESTAMP *  ptime2,
BOOL *  is_equal,
decContext *  pcontext 
)

Comparing two timestamps to see whether they represent the same point in time. Two timestamp of different precision will return false

◆ ion_timestamp_for_day()

ION_API_EXPORT iERR ion_timestamp_for_day ( ION_TIMESTAMP *  ptime,
int  year,
int  month,
int  day 
)

Initialize ION_TIMESTAMP object with value specified. It will have ION_TS_DAY precision

Higher precision fields (min, sec, fraction) will be set to 0. Local time zone will be cleared. ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

◆ ion_timestamp_for_fraction()

ION_API_EXPORT iERR ion_timestamp_for_fraction ( ION_TIMESTAMP *  ptime,
int  year,
int  month,
int  day,
int  hours,
int  minutes,
int  seconds,
decQuad *  p_fraction,
decContext *  pcontext 
)

Initialize ION_TIMESTAMP object with value specified. *p_fraction have a range of (0, 1), not including 0 (without significant digit) and 1. 0.0 (0d-1), 0.00(0d-2) is valid, while 0 or 0. is not.

It will have ION_TS_FRAC precision

Local time zone will be cleared. ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

◆ ion_timestamp_for_minute()

ION_API_EXPORT iERR ion_timestamp_for_minute ( ION_TIMESTAMP *  ptime,
int  year,
int  month,
int  day,
int  hours,
int  minutes 
)

Initialize ION_TIMESTAMP object with value specified. It will have ION_TS_MIN precision

Higher precision fields (sec, fraction) will be set to 0. Local time zone will be cleared. ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

◆ ion_timestamp_for_month()

ION_API_EXPORT iERR ion_timestamp_for_month ( ION_TIMESTAMP *  ptime,
int  year,
int  month 
)

Initialize ION_TIMESTAMP object with value specified. It will have ION_TS_MONTH precision

Higher precision fields (day, min, sec, fraction) will be set to 0. Local time zone will be cleared. ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

◆ ion_timestamp_for_second()

ION_API_EXPORT iERR ion_timestamp_for_second ( ION_TIMESTAMP *  ptime,
int  year,
int  month,
int  day,
int  hours,
int  minutes,
int  seconds 
)

Initialize ION_TIMESTAMP object with value specified. It will have ION_TS_SEC precision

Higher precision field (fraction) will be set to 0. Local time zone will be cleared. ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

◆ ion_timestamp_for_time_t()

ION_API_EXPORT iERR ion_timestamp_for_time_t ( ION_TIMESTAMP *  ptime,
const time_t *  time 
)

Initialize ION_TIMESTAMP object with value specified in time_t time_t can be constructed using time() or mktime(), timegm, and it contains ION_TS_SEC precision.

Higher precision fields (fraction) will be set to 0. Local time zone will be cleared. ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

◆ ion_timestamp_for_year()

ION_API_EXPORT iERR ion_timestamp_for_year ( ION_TIMESTAMP *  ptime,
int  year 
)

Initialize ION_TIMESTAMP object with value specified. It will have ION_TS_YEAR precision

Higher precision fields (month, day, min, sec, fraction) will be set to 0. Local time zone will be cleared. ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

◆ ion_timestamp_get_local_offset()

ION_API_EXPORT iERR ion_timestamp_get_local_offset ( ION_TIMESTAMP *  ptime,
int *  p_offset_minutes 
)

Gets the effective local offset of a timestamp. The result is zero for timestamps with offsets "Z", "+00:00", or "-00:00". In other words, if ion_timestamp_has_local_offset returns false, this returns zero.

Parameters
ptimethe timestamp to inspect.
p_local_offsetthe return value, in minutes from GMT; zero when the local offset is unknown.
Returns
IERR_INVALID_ARG if any parameter is null; IERR_NULL_VALUE if the timestamp is null.timestamp.

◆ ion_timestamp_get_precision()

ION_API_EXPORT iERR ion_timestamp_get_precision ( const ION_TIMESTAMP *  ptime,
int *  precision 
)

Get the time precision for the given timestamp object. The precision values are defined as ION_TS_YEAR, ION_TS_MONTH, ION_TS_DAY, ION_TS_MIN, ION_TS_SEC and ION_TS_FRAC

◆ ion_timestamp_get_thru_day()

ION_API_EXPORT iERR ion_timestamp_get_thru_day ( ION_TIMESTAMP *  ptime,
int *  p_year,
int *  p_month,
int *  p_day 
)

Get year, month, day If precision is not up to month/day, 0 will be returned as month/day value.

◆ ion_timestamp_get_thru_fraction()

ION_API_EXPORT iERR ion_timestamp_get_thru_fraction ( ION_TIMESTAMP *  ptime,
int *  p_year,
int *  p_month,
int *  p_day,
int *  p_hour,
int *  p_minute,
int *  p_second,
decQuad *  p_fraction 
)

Get time up to fraction of second precision. If precision is not up to fraction, 0 will be returned.

◆ ion_timestamp_get_thru_minute()

ION_API_EXPORT iERR ion_timestamp_get_thru_minute ( ION_TIMESTAMP *  ptime,
int *  p_year,
int *  p_month,
int *  p_day,
int *  p_hour,
int *  p_minute 
)

Get time up to minute precision. If precision is not up to hour/minute, 0 will be returned as hour/minute value.

◆ ion_timestamp_get_thru_month()

ION_API_EXPORT iERR ion_timestamp_get_thru_month ( ION_TIMESTAMP *  ptime,
int *  p_year,
int *  p_month 
)

Get year, month If precision is not up to month, 0 will be returned as month value.

◆ ion_timestamp_get_thru_second()

ION_API_EXPORT iERR ion_timestamp_get_thru_second ( ION_TIMESTAMP *  ptime,
int *  p_year,
int *  p_month,
int *  p_day,
int *  p_hour,
int *  p_minute,
int *  p_second 
)

Get time up to second precision. If precision is not up to hour/minute/second, 0 will be returned as hour/minute/second value.

◆ ion_timestamp_get_thru_year()

ION_API_EXPORT iERR ion_timestamp_get_thru_year ( ION_TIMESTAMP *  ptime,
int *  p_year 
)

Get year

◆ ion_timestamp_has_local_offset()

ION_API_EXPORT iERR ion_timestamp_has_local_offset ( ION_TIMESTAMP *  ptime,
BOOL *  p_has_local_offset 
)

Determines whether a timestamp has a defined local offset (for example, "+08:00" or "Z". Otherwise, it's local offest is unknown ("-00:00"), and effectively zero.

Parameters
ptimethe timestamp to inspect.
p_has_local_offsetthe return value; false when the local offset is unknown.
Returns
IERR_INVALID_ARG if any parameter is null.

◆ ion_timestamp_instant_equals()

ION_API_EXPORT iERR ion_timestamp_instant_equals ( const ION_TIMESTAMP *  ptime1,
const ION_TIMESTAMP *  ptime2,
BOOL *  is_equal,
decContext *  pcontext 
)

Compare timestamps for instant equality only (i.e. precision and local offsets need not be equivalent). NOTE: if this has any use externally, it could be exposed. If not, it should be removed.

◆ ion_timestamp_parse()

ION_API_EXPORT iERR ion_timestamp_parse ( ION_TIMESTAMP *  ptime,
char *  buffer,
SIZE  length,
SIZE *  p_characters_used,
decContext *  pcontext 
)

Parse timestamp string and construct timestamp object in ptime. This expects a null terminated string.

◆ ion_timestamp_set_local_offset()

ION_API_EXPORT iERR ion_timestamp_set_local_offset ( ION_TIMESTAMP *  ptime,
int  offset_minutes 
)

Changes the local offset of a timestamp. If the timestamp has less than minute precision, the given offset is ignored and the timestamp is unchanged. If the timestamp is changed, ion_timestamp_has_local_offset will be true, and ion_timestamp_get_local_offset will be the given offset.

Parameters
ptimethe timestamp to alter.
offset_minutesthe new local offset, in (positive or negative) minutes from GMT.
Returns
IERR_INVALID_ARG if ptime is null, or if offset_minutes is outside the range -23:59 to +23:59.

◆ ion_timestamp_to_string()

ION_API_EXPORT iERR ion_timestamp_to_string ( ION_TIMESTAMP *  ptime,
char *  buffer,
SIZE  buf_length,
SIZE *  output_length,
decContext *  pcontext 
)

Get the string format of timestamp.

◆ ion_timestamp_to_time_t()

ION_API_EXPORT iERR ion_timestamp_to_time_t ( const ION_TIMESTAMP *  ptime,
time_t *  time 
)

Fill time_t with value in ION_TIMESTAMP

◆ ion_timestamp_unset_local_offset()

ION_API_EXPORT iERR ion_timestamp_unset_local_offset ( ION_TIMESTAMP *  ptime)

Removes any local offset from a timestamp. Afterwards, ion_timestamp_has_local_offset will be false, and ion_timestamp_get_local_offset will be zero.

Parameters
ptimethe timestamp to alter.
Returns
IERR_INVALID_ARG if any parameter is null.