Timestamp handling

## 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_date       (GDate *date);
    gint64              zeitgeist_timestamp_from_dmy        (GDateDay day,
                                                             GDateMonth month,
                                                             GDateYear year);
    gint64              zeitgeist_timestamp_from_iso8601    (const gchar *datetime);
    gint64              zeitgeist_timestamp_from_timeval    (GTimeVal *tv);
    gint64              zeitgeist_timestamp_next_midnight   (gint64 timestamp);
    gint64              zeitgeist_timestamp_prev_midnight   (gint64 timestamp);
    void                zeitgeist_timestamp_to_date         (gint64 timestamp,
                                                             GDate *date);
    gchar *             zeitgeist_timestamp_to_iso8601      (gint64 timestamp);
    void                zeitgeist_timestamp_to_timeval      (gint64 timestamp,
                                                             GTimeVal *tv);

## 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 G_GINT64_CONSTANT (1000)

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

### ZEITGEIST_TIMESTAMP_MINUTE

    #define ZEITGEIST_TIMESTAMP_MINUTE G_GINT64_CONSTANT (60000)

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

### ZEITGEIST_TIMESTAMP_HOUR

    #define ZEITGEIST_TIMESTAMP_HOUR G_GINT64_CONSTANT (3600000)

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

### ZEITGEIST_TIMESTAMP_DAY

    #define ZEITGEIST_TIMESTAMP_DAY G_GINT64_CONSTANT (86400000)

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

### ZEITGEIST_TIMESTAMP_WEEK

    #define ZEITGEIST_TIMESTAMP_WEEK G_GINT64_CONSTANT (604800000)

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

### ZEITGEIST_TIMESTAMP_YEAR

    #define ZEITGEIST_TIMESTAMP_YEAR G_GINT64_CONSTANT (31556952000)

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_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. The timestamp is guaranteed to be rounded off to the midnight of the given date.

### 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. If the date is valid the returned timestamp is guaranteed to be rounded off to the midnight of the given date

### 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_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_next_midnight ()

    gint64              zeitgeist_timestamp_next_midnight   (gint64 timestamp);

Calculate the timestamp for the next midnight after `timestamp`

`timestamp` : | The Zeitgeist timestamp to find the next midnight for
Returns : | Returns the timestamp for the first midnight after `timestamp`. If `timestamp` is already midnight (down to the millisecond) this method will return the value for the next midnight. In other words you can call this method recursively in order to iterate, forwards in time, over midnights.

### zeitgeist_timestamp_prev_midnight ()

    gint64              zeitgeist_timestamp_prev_midnight   (gint64 timestamp);

Calculate the timestamp for the midnight just before `timestamp`

`timestamp` : | The Zeitgeist timestamp to find the previous midnight for
Returns : | Returns the timestamp for the first midnight just before `timestamp`. If `timestamp` is already midnight (down to the millisecond) this method will return the value for the midnight before. In other words you can call this method recursively in order to iterate, backwards in time, over midnights.

### 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`

### 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_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