timestamp: Zeitgeist Reference Manual

## timestamp timestamp — Convenience functions for dealing with timestamps and dates |

## Functions

gint64 | zeitgeist_timestamp_from_timeval ()
void | zeitgeist_timestamp_to_timeval ()
gint64 | zeitgeist_timestamp_from_now ()
gint64 | zeitgeist_timestamp_from_iso8601 ()
gchar * | zeitgeist_timestamp_to_iso8601 ()
gint64 | zeitgeist_timestamp_from_date ()
gint64 | zeitgeist_timestamp_from_dmy ()
void | zeitgeist_timestamp_to_date ()
gint64 | zeitgeist_timestamp_next_midnight ()
gint64 | zeitgeist_timestamp_prev_midnight ()

## Types and Values

#define | ZEITGEIST_TIMESTAMP_SECOND
#define | ZEITGEIST_TIMESTAMP_MINUTE
#define | ZEITGEIST_TIMESTAMP_HOUR
#define | ZEITGEIST_TIMESTAMP_DAY
#define | ZEITGEIST_TIMESTAMP_WEEK
#define | ZEITGEIST_TIMESTAMP_YEAR

## Description

include: zeitgeist.h

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.

## Functions

### zeitgeist_timestamp_from_timeval ()

    gint64
    zeitgeist_timestamp_from_timeval (GTimeVal *timeval);

Convert a GTimeVal to an amount of milliseconds since the Unix Epoch

#### Parameters

self | the (null) instance |
timeval | . time to convert . | [in]

#### Returns

number of milliseconds since the Unix Epoch

### zeitgeist_timestamp_to_timeval ()

    void
    zeitgeist_timestamp_to_timeval (gint64 timestamp,
                                    GTimeVal *result);

Write a Zeitgeist timestamp to a GTimeVal instance. Note that Zeitgeist uses only a millisecond resolution, whereas GTimeVal has microsecond resolution. This means that the lower three digits of `tv.tv_usec` will always be 0.

#### Parameters

self | the (null) instance |
timestamp | . to convert . | [in]

#### Returns

the equivalent GTimeVal instance.

### zeitgeist_timestamp_from_now ()

    gint64
    zeitgeist_timestamp_from_now (void);

Return the current timestamp in milliseconds.

#### Parameters

self | the (null) instance |

#### Returns

the timestamp for the current system time, in milliseconds since the Unix Epoch

### zeitgeist_timestamp_from_iso8601 ()

    gint64
    zeitgeist_timestamp_from_iso8601 (const gchar *datetime);

Parse a timestamp from an ISO8601-encoded string.

#### Parameters

self | the (null) instance |
datetime | . a string containing an ISO8601-conforming datetime . | [in]

#### Returns

the timestamp represented by the given string, or -1 if it can't be parsed

### zeitgeist_timestamp_to_iso8601 ()

    gchar *
    zeitgeist_timestamp_to_iso8601 (gint64 timestamp);

Convert a timestamp to a human-readable ISO8601 format

#### Parameters

self | the (null) instance |
timestamp | . a timestamp in milliseconds since the Unix Epoch . | [in]

#### Returns

a newly allocated string containing the ISO8601 version of the given timestamp

### zeitgeist_timestamp_from_date ()

    gint64
    zeitgeist_timestamp_from_date (GDate *date);

Convert a GDate to a Zeitgeist timestamp

#### Parameters

self | the (null) instance |
date | . the date to convert . | [in]

#### Returns

the given date expressed as a timestamp in milliseconds since the Epoch. The timestamp is guaranteed to be roudned 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

#### Parameters

self | the (null) instance |
day | . the day of the month . | [in]
month | . the month of the year . | [in]
year | . the year . | [in]

#### Returns

the given date (rounded off to the midnight), expressed as a timestamp in milliseconds since the Epoch, or -1 in case the provided parameters don't constitute a valid date.

### zeitgeist_timestamp_to_date ()

    void
    zeitgeist_timestamp_to_date (gint64 timestamp,
                                 GDate *result);

Write a timestamp to a GDate structure

#### Parameters

self | the (null) instance |
timestamp | . to convert . | [in]

#### Returns

GDate initialized to the given timestamp

### zeitgeist_timestamp_next_midnight ()

    gint64
    zeitgeist_timestamp_next_midnight (gint64 timestamp);

Calculate the timestamp for the next midnight after the given timestamp.

If is 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.

#### Parameters

self | the (null) instance |
timestamp | . the Zeitgeist timestamp to find the next midnight for . | [in]

#### Returns

the timestamp for the next midnight after the given timestamp

### zeitgeist_timestamp_prev_midnight ()

    gint64
    zeitgeist_timestamp_prev_midnight (gint64 timestamp);

Calculate the timestamp for the midnight just before the given timestamp.

If is is already midnight (down to the millisecond), this method will return the value for the previous midnight. In other words, you can call this method recursively in order to iterate, backwards in time, over midnights.

#### Parameters

self | the (null) instance |
timestamp | . the Zeitgeist timestamp to find the previous midnight for . | [in]

#### Returns

the timestamp for the midnight just before the given timestamp

## Types and Values

### ZEITGEIST_TIMESTAMP_SECOND

    #define ZEITGEIST_TIMESTAMP_SECOND ((gint64) 1000)

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

### ZEITGEIST_TIMESTAMP_MINUTE

    #define ZEITGEIST_TIMESTAMP_MINUTE ((gint64) 60000)

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

### ZEITGEIST_TIMESTAMP_HOUR

    #define ZEITGEIST_TIMESTAMP_HOUR ((gint64) 3600000)

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

### ZEITGEIST_TIMESTAMP_DAY

    #define ZEITGEIST_TIMESTAMP_DAY ((gint64) 86400000)

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

### ZEITGEIST_TIMESTAMP_WEEK

    #define ZEITGEIST_TIMESTAMP_WEEK ((gint64) 604800000)

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.