diff options
Diffstat (limited to 'libzeitgeist/timestamp.vala')
| -rw-r--r-- | libzeitgeist/timestamp.vala | 236 |
1 files changed, 236 insertions, 0 deletions
diff --git a/libzeitgeist/timestamp.vala b/libzeitgeist/timestamp.vala new file mode 100644 index 00000000..039ac45d --- /dev/null +++ b/libzeitgeist/timestamp.vala @@ -0,0 +1,236 @@ +/* timestamp.vala + * + * Copyright © 2012 Collabora Ltd. + * By Siegfried-Angel Gevatter Pujals <siegfried@gevatter.com> + * Copyright © 2010 Canonical, Ltd. + * By Mikkel Kamstrup Erlandsen <mikkel.kamstrup@canonical.com> + * + * 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 <http://www.gnu.org/licenses/>. + * + */ + +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 |