Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

ISO 8601:2000 Time


Detailed Description

Functions for handling time specifications in ISO 8601:2000 format.


Data Structures

struct  iso8601_time
 Structure representing a broken down ISO 8601:2000 time and date. More...

Date Formats

Constants representing the supported date formats.

#define ISO8601_CALENDAR_DATE   (0)
 Constant representing the regular calendar date format.
#define ISO8601_ORDINAL_DATE   (1)
 Constant representing the ordinal date format (i.e. date represented as a day of year number).
#define ISO8601_WEEK_DATE   (2)
 Constant represented the week date format (i.e. calendar week + day of week).

Defines

#define ISO8601_YEAR_IMPLIED   (-1)
 Special value for struct iso8601_time::it_year indicating that the year number is implied.
#define ISO8601_MONTH_IMPLIED   (13)
 Special value for struct iso8601_time::it_month indicating that the month number is implied.
#define ISO8601_MDAY_IMPLIED   (32)
 Special value for struct iso8601_time::it_mday indicating that the day of month is implied.
#define ISO8601_WEEK_IMPLIED   (54)
 Special value for struct iso8601_time::it_week indicating that the calendar week number is implied.
#define ISO8601_WDAY_IMPLIED   (8)
 Special value for struct iso8601_time::it_wday indicating that the day of week is implied.
#define ISO8601_YDAY_IMPLIED   (367)
 Special value for struct iso8601_time::it_yday indicating that the day of the year is implied.
#define ISO8601_TZ_LOCALTIME   (-24)
 Special value for struct iso8601_time::it_tz indicating that date is a local time date (i.e. no timezone information is included).

Functions

long iso8601_timezone (void)
 Get the local timezone offset.
void iso8601_time::iso8601_time_init (struct iso8601_time *iso8601_time, bool all_implied)
 Initialize a struct iso8601_time instance.
size_t iso8601_time::iso8601_time_encode (const struct iso8601_time *iso8601_time, bool extended, char *buffer, ptrdiff_t buffer_length)
 Encode a time and date as a combined ISO 8601 date and time of day.
int iso8601_time::iso8601_time_decode (struct iso8601_time *iso8601_time, const char *buffer)
 Decode an ISO 8601 encoded date and time of day.
int iso8601_time::iso8601_time_to_epoch (const struct iso8601_time *iso8601_time, long long *epoch_time)
 Encode a date and time as an epoch representation.
int iso8601_time::iso8601_time_from_epoch (struct iso8601_time *iso8601_time, long long epoch_time, int variant)
 Decode a date in epoch representation.
int iso8601_time::iso8601_time_to_timespec (const struct iso8601_time *iso8601_time, struct timespec *ts)
 Encode a date and time as an instance of struct timespec.
int iso8601_time::iso8601_time_from_timespec (struct iso8601_time *iso8601_time, const struct timespec *ts, int variant)
 Decode a date and time from an instance of struct timespec.
int iso8601_time::iso8601_time_to_timeval (const struct iso8601_time *iso8601_time, struct timeval *tv)
 Encode a date and time as an instance of struct timeval.
int iso8601_time::iso8601_time_from_timeval (struct iso8601_time *iso8601_time, const struct timeval *tv, int variant)
 Decode a date and time from an instance of struct timeval.
int iso8601_time::iso8601_time_to_time_t (const struct iso8601_time *iso8601_time, time_t *t)
 Encode a date and time as a time_t value.
int iso8601_time::iso8601_time_from_time_t (struct iso8601_time *iso8601_time, const time_t *t, int variant)
 Decode a date and time from a time_t value.
sobjiso8601_time::iso8601_time_to_sobj (const struct iso8601_time *iso8601_time, bool epoch)
 Encode a date and time as a simple object instance.
int iso8601_time::iso8601_time_from_sobj (struct iso8601_time *iso8601_time, struct sobj *sobj, int variant, bool cn_required)
 Decode a date and time from a simple object instance.
int iso8601_time::iso8601_time_now (struct iso8601_time *iso8601_time, int variant)
 Initialize a time object with the current date and time.
void iso8601_time::iso8601_time_set_timezone (struct iso8601_time *iso8601_time)
 Set the timezone of the specified time object to the local timezone.
void iso8601_time::iso8601_time_print (const struct iso8601_time *iso8601_time, void *out)
 Print out an ISO 8601 time object to the specified stream.
void iso8601_time::iso8601_time_dump (const struct iso8601_time *iso8601_time, void *out)
 Dump an ISO 8601 time object to the specified stream.


Define Documentation

#define ISO8601_CALENDAR_DATE   (0)
 

Constant representing the regular calendar date format.

#define ISO8601_MDAY_IMPLIED   (32)
 

Special value for struct iso8601_time::it_mday indicating that the day of month is implied.

#define ISO8601_MONTH_IMPLIED   (13)
 

Special value for struct iso8601_time::it_month indicating that the month number is implied.

#define ISO8601_ORDINAL_DATE   (1)
 

Constant representing the ordinal date format (i.e. date represented as a day of year number).

#define ISO8601_TZ_LOCALTIME   (-24)
 

Special value for struct iso8601_time::it_tz indicating that date is a local time date (i.e. no timezone information is included).

#define ISO8601_WDAY_IMPLIED   (8)
 

Special value for struct iso8601_time::it_wday indicating that the day of week is implied.

#define ISO8601_WEEK_DATE   (2)
 

Constant represented the week date format (i.e. calendar week + day of week).

#define ISO8601_WEEK_IMPLIED   (54)
 

Special value for struct iso8601_time::it_week indicating that the calendar week number is implied.

#define ISO8601_YDAY_IMPLIED   (367)
 

Special value for struct iso8601_time::it_yday indicating that the day of the year is implied.

#define ISO8601_YEAR_IMPLIED   (-1)
 

Special value for struct iso8601_time::it_year indicating that the year number is implied.


Function Documentation

int iso8601_time_decode struct iso8601_time iso8601_time,
const char *  buffer
[related, inherited]
 

Decode an ISO 8601 encoded date and time of day.

The function decodes an ISO 8601 encoded date and time of day. If some part of the date is implied (and hence may be omitted in the encoded date and time), the corresponding fields should be present in the specified iso8601_time parameter, either set to a specific value or set to ISO8601_*_IMPLIED.

Parameters:
iso8601_time The time structure receiving the decoded date and time. All fields of iso8601_time that are not specified and not implied by the encoded date and time are set to 0 (undefined). E.g. if a calendar date is specified, the it_yday, it_week, and it_wday fields are set to 0.
buffer Buffer holding the (null-terminated) string representation of the ISO 8601 encoded date. Leading whitespace is ignored, trailing unrecognized characters are ignored.
Returns:
The function returns 0 on success and negative value on error (-1 indicates a syntax error, -2 indicates that an implied field was specified as undefined in the iso8601_time parameter, -3 indicates that the iso8601_time parameter contained invalid (i.e. out of range) values, -4 if a field in the encoded date and time is out of range). The values of the fields in iso8601_time are undefined if the function returns an error code.
Note:
Truncated calendar years (i.e. implied century or decade) are not supported. The year (if not implied) has to be specified completely.

If the time specification is missing or specified with reduced precision, the missing time fields are assumed to be 0, even if the iso8601_time containted different values before tha call.

void iso8601_time_dump const struct iso8601_time iso8601_time,
void *  out
[related, inherited]
 

Dump an ISO 8601 time object to the specified stream.

The function dumps an explicit field-by-field representation of the specified ISO 8601 object to the specified output stream.

Parameters:
iso8601_time The time object.
out The output stream. This is a standard C FILE stream.

size_t iso8601_time_encode const struct iso8601_time iso8601_time,
bool  extended,
char *  buffer,
ptrdiff_t  buffer_length
[related, inherited]
 

Encode a time and date as a combined ISO 8601 date and time of day.

The time is encoded as a calendar date, ordinal date, or week date, depending on the available information. If possibe, the functions will encoded a calendar date; next the function tries to encode an ordinal date; next the function tries to encode a week date.

Fields not relevant for the encoding variant are ignored, even if the values are out of range. If any of the requires values are out of range, the function will fail (return 0).

Parameters:
iso8601_time Structure representing the date and time to be encoded.
extended Flag indicating if an extended date should be encoded. (Extended means that the date fields are separated by hyphens and the time fields are separated by colons.)
buffer The buffer receiving the encoded date and time. No more than buffer_length bytes are written. If the encoded date is shorter than buffer_length characters, the buffer will be null-terminated. If this is a null-pointer, no output is generated (may be used to calculate the size required for the encoded date and time or to check if the parameter iso8601_time is valid).
buffer_length The length of the buffer. This parameter is ignored if buffer is a null-pointer.
Returns:
The function returns the length of the encoded date and time (not counting the terminating null-byte). If the iso8601_time parameter is not valid, the special value 0 is returned.
Note:
The function does not check if the specified date exists (i.e. you may encode the 31st of January). The function will only check if the values are in the specified ranges (as documented for struct iso8601_time).

int iso8601_time_from_epoch struct iso8601_time iso8601_time,
long long  epoch_time,
int  variant
[related, inherited]
 

Decode a date in epoch representation.

The functions fills in the specified iso8601_time parameter with the time encoded in epoch_time, using the specified in the it_tz and it_tzmin fields of the iso8601_time parameter.

Parameters:
iso8601_time The time instance receiving the decoded time. All date fields are filled in by the function.
epoch_time The time in epoch representation.
variant The date variant to be decoded. This is one of the ISO8601_*_DATE constants. For ISO8601_CALENDAR_DATE and ISO8601_ORDINAL_DATE, the it_week field in iso8601_time is set to 0 (undefined). For ISO8601_WEEK_DATE, the fields it_month, it_mday, it_yday are set to 0 (undefined). The reason is the the dates 1st through 3rd of January may be represented as week dates of the previous year.
Returns:
The function returns 0 on success and -1 on error (invalid values for the it_tz and/or it_tzmin fields of iso8601_time).

int iso8601_time_from_sobj struct iso8601_time iso8601_time,
struct sobj sobj,
int  variant,
bool  cn_required
[related, inherited]
 

Decode a date and time from a simple object instance.

The specified simple object may be specified as a string (in ISO 8601-1) or in epoch representation.

Parameters:
iso8601_time The broken down date and time.
sobj The simple object instance to be decoded.
variant The preferred date variant to be decoded. See iso8601_time_from_epoch().
cn_required Flag indicating if a class name {time} is required. If this flag is set, then the specified object must be of class {time}. If this flag is clear, then the specified object may be classless or of class {time}.
Note:
The variant argument is used only if the specified object is encoded as an epoch time. If a string encoded object is specified, then the encoded date variant is returned.

This function is available only if the ISO 8601-1 code is compiled as part of the simple objects library.

Return values:
0 Success.
-1 The specified simple object is not a valid time object.
-2 The values for the iso8601_time.it_tz and/or iso8601_time.it_tzmin were not valid.

int iso8601_time_from_time_t struct iso8601_time iso8601_time,
const time_t *  t,
int  variant
[related, inherited]
 

Decode a date and time from a time_t value.

This function is a convenience frontend for iso8601_time_from_epoch().

Parameters:
iso8601_time The broken down date and time.
t The time in time_t representation.
variant The date variant to be decoded. See iso8601_time_from_epoch().
Returns:
See iso8601_time_from_epoch().
See also:
iso8601_time_from_epoch().

int iso8601_time_from_timespec struct iso8601_time iso8601_time,
const struct timespec *  ts,
int  variant
[related, inherited]
 

Decode a date and time from an instance of struct timespec.

This function is a convenience frontend for iso8601_time_from_epoch().

Parameters:
iso8601_time The broken down date and time.
ts The time in struct timespec representation.
variant The date variant to be decoded. See iso8601_time_from_epoch().
Returns:
See iso8601_time_from_epoch().
See also:
iso8601_time_from_epoch().

int iso8601_time_from_timeval struct iso8601_time iso8601_time,
const struct timeval *  tv,
int  variant
[related, inherited]
 

Decode a date and time from an instance of struct timeval.

This function is a convenience frontend for iso8601_time_from_epoch().

Parameters:
iso8601_time The broken down date and time.
tv The time in struct timeval representation.
variant The date variant to be decoded. See iso8601_time_from_epoch().
Returns:
See iso8601_time_from_epoch().
See also:
iso8601_time_from_epoch().

void iso8601_time_init struct iso8601_time iso8601_time,
bool  all_implied
[related, inherited]
 

Initialize a struct iso8601_time instance.

The function initializes the specified iso8601_time instance to midnigtht (00:00:00) if an undefined or implied date (depending on the specified all_implied flag. The timezone is initialized to UTC.

Parameters:
iso8601_time The instance to be initialized.
all_implied Flag indicating if all date fields should be set to implied. If this flag is clear, all date flags are set to undefined.

int iso8601_time_now struct iso8601_time iso8601_time,
int  variant
[related, inherited]
 

Initialize a time object with the current date and time.

Parameters:
iso8601_time The time object.
variant The date variant. See iso8601_time_from_sobj().
Returns:
The function returns 0 on success and -1 on error (invalid values for the it_tz and/or it_tzmin fields of iso8601_time).

void iso8601_time_print const struct iso8601_time iso8601_time,
void *  out
[related, inherited]
 

Print out an ISO 8601 time object to the specified stream.

If the time object can't be encoded into an ISO 8601 string, then the iso8601_time_dump() function is called.

Parameters:
iso8601_time The time object.
out The output stream. This is a standard C FILE stream.

void iso8601_time_set_timezone struct iso8601_time iso8601_time  )  [related, inherited]
 

Set the timezone of the specified time object to the local timezone.

No date calculations are performed on the time data. The function only sets the iso8601_time::it_tz and iso8601_time::it_tzmin fields.

Parameters:
iso8601_time The time object.

int iso8601_time_to_epoch const struct iso8601_time iso8601_time,
long long *  epoch_time
[related, inherited]
 

Encode a date and time as an epoch representation.

The function evaluates the date fields similar to the iso8601_time_encode() function. If the calendar date fields are specified, these are used. Next, the ordinal date fields are checked. Last, the week date fields are checked.

Parameters:
iso8601_time The broken down date and time.
epoch_time Pointer to a long long variable receiving the epoch representation. This may be a null-pointer.
Returns:
The function returns 0 on success and -1 on error (unspecified date and time or fields in iso8601_time out of range). Note that more error condition return values might be defined in the future, so you should check < 0 instead of == -1.
Note:
This function uses the POSIX.1 functions mktime(). As a consequence, all limitations documented for mktime() apply.

struct sobj * iso8601_time_to_sobj const struct iso8601_time iso8601_time,
bool  epoch
[related, inherited]
 

Encode a date and time as a simple object instance.

Parameters:
iso8601_time The broken down date and time.
epoch Flag indicating if the resulting object should be in epoch representation. If this flag is clear, then the resulting object will be in string representation.
Note:
This function is available only if the ISO 8601-1 code is compiled as part of the simple objects library.
Returns:
A flat reference to a new simple object representing the specified date and time. If the specified date and time object was not valid, then a null-pointer is returned.

int iso8601_time_to_time_t const struct iso8601_time iso8601_time,
time_t *  t
[related, inherited]
 

Encode a date and time as a time_t value.

This function is a convenience frontend for iso8601_time_to_epoch().

Parameters:
iso8601_time The broken down date and time.
t Pointer to a time_t variable receiving the epoch representation.
Returns:
See iso8601_time_to_epoch().
See also:
iso8601_time_to_epoch().

int iso8601_time_to_timespec const struct iso8601_time iso8601_time,
struct timespec *  ts
[related, inherited]
 

Encode a date and time as an instance of struct timespec.

This function is a convenience frontend for iso8601_time_to_epoch().

Parameters:
iso8601_time The broken down date and time.
ts Pointer to a struct timespec variable receiving the epoch representation.
Returns:
See iso8601_time_to_epoch().
See also:
iso8601_time_to_epoch().

int iso8601_time_to_timeval const struct iso8601_time iso8601_time,
struct timeval *  tv
[related, inherited]
 

Encode a date and time as an instance of struct timeval.

This function is a convenience frontend for iso8601_time_to_epoch().

Parameters:
iso8601_time The broken down date and time.
tv Pointer to a struct timeval variable receiving the epoch representation.
Returns:
See iso8601_time_to_epoch().
See also:
iso8601_time_to_epoch().

long iso8601_timezone void   ) 
 

Get the local timezone offset.

Returns:
The function returns the number of seconds east of GMT/UTC.


Generated on Sat Jul 23 16:07:33 2005 for sobject by  doxygen 1.3.9.1