Timestamp handling

Timestamp handling — Convenience functions for dealing with timestamps and dates

Synopsis

#include <zeitgeist.h>

#define             ZEITGEIST_TIMESTAMP_SECOND
#define             ZEITGEIST_TIMESTAMP_MINUTE
#define             ZEITGEIST_TIMESTAMP_HOUR
#define             ZEITGEIST_TIMESTAMP_DAY
#define             ZEITGEIST_TIMESTAMP_WEEK
#define             ZEITGEIST_TIMESTAMP_YEAR
gint64              zeitgeist_timestamp_for_now         (void);
gint64              zeitgeist_timestamp_from_timeval    (GTimeVal *tv);
void                zeitgeist_timestamp_to_timeval      (gint64 timestamp,
                                                         GTimeVal *tv);
gint64              zeitgeist_timestamp_from_iso8601    (const gchar *datetime);
gchar*              zeitgeist_timestamp_to_iso8601      (gint64 timestamp);
gint64              zeitgeist_timestamp_from_date       (GDate *date);
gint64              zeitgeist_timestamp_from_dmy        (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);
void                zeitgeist_timestamp_to_date         (gint64 timestamp,
                                                         GDate *date);

Description

A suite of convenience functions for dealing with timestamps and dates.

Zeitgeist timestamps are represented as gint64s with the number of milliseconds since the Unix Epoch.

Details

ZEITGEIST_TIMESTAMP_SECOND

#define ZEITGEIST_TIMESTAMP_SECOND 1000LL

A second represented as a Zeitgeist timestamp (ie. 1000ms)


ZEITGEIST_TIMESTAMP_MINUTE

#define ZEITGEIST_TIMESTAMP_MINUTE 60000LL

A minute represented as a Zeitgeist timestamp (ie. 60000ms)


ZEITGEIST_TIMESTAMP_HOUR

#define ZEITGEIST_TIMESTAMP_HOUR 3600000LL

An hour represented as a Zeitgeist timestamp (ie. 3600000ms)


ZEITGEIST_TIMESTAMP_DAY

#define ZEITGEIST_TIMESTAMP_DAY 86400000LL

A day represented as a Zeitgeist timestamp (ie. 86400000ms)


ZEITGEIST_TIMESTAMP_WEEK

#define ZEITGEIST_TIMESTAMP_WEEK 604800000LL

A week represented as a Zeitgeist timestamp (ie. 604800000ms)


ZEITGEIST_TIMESTAMP_YEAR

#define ZEITGEIST_TIMESTAMP_YEAR 31556952000LL

A year represented as a Zeitgeist timestamp (ie. 31556952000ms). Be warned that a year is not 365 days, but in fact 365.2425 days to account for leap years.


zeitgeist_timestamp_for_now ()

gint64              zeitgeist_timestamp_for_now         (void);

Get the timestamp for the current system time

Returns :

The timestamp for the current system time. Ie. the number of milliseconds since the Unix Epoch

zeitgeist_timestamp_from_timeval ()

gint64              zeitgeist_timestamp_from_timeval    (GTimeVal *tv);

tv :

A GTimeVal instance

Returns :

A gint64 with the total number of milliseconds since the Unix Epoch

zeitgeist_timestamp_to_timeval ()

void                zeitgeist_timestamp_to_timeval      (gint64 timestamp,
                                                         GTimeVal *tv);

Write a Zeitgeist timestamp to a GTimeVal instance. Note that Zeitgeist uses only a millisecond resolution for where GTimeVal uses a microsecond resolution, meaning that the lower three digits of tv.tv_usec will be 0.

timestamp :

A gint64 with a number of milliseconds since the Unix Epoch

tv :

A GTimeVal instance to store the result in

zeitgeist_timestamp_from_iso8601 ()

gint64              zeitgeist_timestamp_from_iso8601    (const gchar *datetime);

Parse a timestamp from a ISO8601 encoded string.

datetime :

A string containing an iso8601 conforming datetime specification

Returns :

The timestamp represented by datetime, or -1 on failure to parse datetime

zeitgeist_timestamp_to_iso8601 ()

gchar*              zeitgeist_timestamp_to_iso8601      (gint64 timestamp);

Convert a timestamp to a human readable ISO8601 format

timestamp :

A Zeitgeist timestamp in ms since the Epoch

Returns :

A newly allocated string containing the ISO8601 format of timestamp. Free with g_free().

zeitgeist_timestamp_from_date ()

gint64              zeitgeist_timestamp_from_date       (GDate *date);

Convert a GDate to a Zeitgeist timestamp.

date :

A GDate to convert

Returns :

date as a timestamp in milliseconds since the Epoch

zeitgeist_timestamp_from_dmy ()

gint64              zeitgeist_timestamp_from_dmy        (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);

Convert a day, month, year tuple into a Zeitgeist timestamp

day :

The day of the month represented as a GDateDay

month :

The month of the year represented as a GDateMonth

year :

The year represented as a GDateYear

Returns :

Input data as a timestamp in milliseconds since the Epoch or -1 in case the provided data does not constitute a valid date

zeitgeist_timestamp_to_date ()

void                zeitgeist_timestamp_to_date         (gint64 timestamp,
                                                         GDate *date);

Write a timestamp to a GDate structure

timestamp :

The Zeitgeist timestamp to convert to a GDate

date :

The place to store the result in. Must be non-NULL