/* timestamp.vala * * Copyright © 2012 Collabora Ltd. * By Siegfried-Angel Gevatter Pujals * Copyright © 2010 Canonical, Ltd. * By Mikkel Kamstrup Erlandsen * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation, either version 2.1 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with this program. If not, see . * */ using Zeitgeist; /** * Convenience functions for dealing with timestamps and dates * * include: zeitgeist.h * * A suite of convenience functions for dealing with timestamps and dates. * * Zeitgeist timestamps are represented as ''gint64''s with the number * of milliseconds since the Unix Epoch. */ namespace Zeitgeist.Timestamp { /** * A second represented as a Zeitgeist timestamp (ie. 1000ms) */ public const int64 SECOND = 1000; /** * A minute represented as a Zeitgeist timestamp (ie. 60000ms) */ public const int64 MINUTE = 60000; /** * An hour represented as a Zeitgeist timestamp (ie. 3600000ms) */ public const int64 HOUR = 3600000; /** * A day represented as a Zeitgeist timestamp (ie. 86400000ms) */ public const int64 DAY = 86400000; /** * A week represented as a Zeitgeist timestamp (ie. 604800000ms) */ public const int64 WEEK = 604800000; /** * 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. */ public const int64 YEAR = 31556952000; /** * Convert a {@link GLib.TimeVal} to an amount of milliseconds since * the Unix Epoch * * @param timeval time to convert * * @return number of milliseconds since the Unix Epoch */ public int64 from_timeval (TimeVal timeval) { var m_seconds = (int64) timeval.tv_sec * 1000; return m_seconds + ((int64) timeval.tv_usec / 1000); } /** * Write a Zeitgeist timestamp to a {@link GLib.TimeVal} instance. * Note that Zeitgeist uses only a millisecond resolution, whereas * {@link GLib.TimeVal} has microsecond resolution. This means that * the lower three digits of @tv.tv_usec will always be 0. * * @param timestamp to convert * * @return the equivalent {@link GLib.TimeVal} instance. */ public TimeVal to_timeval (int64 timestamp) { TimeVal timeval = TimeVal(); timeval.tv_sec = (long) (timestamp / 1000); timeval.tv_usec = (long) ((timestamp % 1000) * 1000); return timeval; } /** * Return the current timestamp in milliseconds. * * @return the timestamp for the current system time, in milliseconds * since the Unix Epoch */ public int64 from_now () { return get_real_time () / 1000; } /** * Parse a timestamp from an ISO8601-encoded string. * * @param datetime a string containing an ISO8601-conforming datetime * * @return the timestamp represented by the given string, or -1 if * it can't be parsed */ public int64 from_iso8601 (string datetime) { TimeVal timeval = TimeVal(); if (timeval.from_iso8601 (datetime)) return from_timeval (timeval); else return -1; } /** * Convert a timestamp to a human-readable ISO8601 format * * @param timestamp a timestamp in milliseconds since the Unix Epoch * * @return a newly allocated string containing the ISO8601 version of * the given timestamp */ public string to_iso8601 (int64 timestamp) { TimeVal timeval = to_timeval (timestamp); return timeval.to_iso8601 (); } /** * Convert a ''GDate'' to a Zeitgeist timestamp * * @param date the date to convert * * @return 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. */ public int64 from_date (Date date) { int64 julian = date.get_julian (); return prev_midnight (julian*DAY - 1969*YEAR); } /** * Convert a day, month, year tuple into a Zeitgeist timestamp * * @param day the day of the month * @param month the month of the year * @param year the year * * @return 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. */ public int64 from_dmy (DateDay day, DateMonth month, DateYear year) { Date date = Date (); date.set_dmy (day, month, year); return from_date (date); } /** * Write a timestamp to a {@link GLib.Date} structure * * @param timestamp to convert * @return {@link GLib.Date} initialized to the given timestamp */ public Date to_date (int64 timestamp) { Date date = Date (); TimeVal timeval = to_timeval (timestamp); date.set_time_val (timeval); return date; } /** * 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. * * @param timestamp the Zeitgeist timestamp to find the next midnight for * * @return the timestamp for the next midnight after the given timestamp */ public int64 next_midnight (int64 timestamp) { int64 remainder = timestamp % DAY; if (remainder == 0) return timestamp + DAY; else return (timestamp - remainder) + DAY; } /** * 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. * * @param timestamp the Zeitgeist timestamp to find the previous * midnight for * * @return the timestamp for the midnight just before the given timestamp */ public int64 prev_midnight (int64 timestamp) { int64 remainder = timestamp % DAY; if (remainder == 0) return timestamp - DAY; else return (timestamp - remainder); } } // vim:expandtab:ts=4:sw=4