glib-2.0/glib/gdatetime.h

0001 /*
0002  * Copyright (C) 2009-2010 Christian Hergert <chris@dronelabs.com>
0003  * Copyright © 2010 Codethink Limited
0004  *
0005  * SPDX-License-Identifier: LGPL-2.1-or-later
0006  *
0007  * This library is free software; you can redistribute it and/or modify
0008  * it under the terms of the GNU Lesser General Public License as
0009  * published by the Free Software Foundation; either version 2.1 of the
0010  * licence, or (at your option) any later version.
0011  *
0012  * This is distributed in the hope that it will be useful, but WITHOUT
0013  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
0014  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
0015  * License for more details.
0016  *
0017  * You should have received a copy of the GNU Lesser General Public License
0018  * along with this library; if not, see <http://www.gnu.org/licenses/>.
0019  *
0020  * Authors: Christian Hergert <chris@dronelabs.com>
0021  *          Thiago Santos <thiago.sousa.santos@collabora.co.uk>
0022  *          Emmanuele Bassi <ebassi@linux.intel.com>
0023  *          Ryan Lortie <desrt@desrt.ca>
0024  */
0025
0026 #ifndef __G_DATE_TIME_H__
0027 #define __G_DATE_TIME_H__
0028
0029 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0030 #error "Only <glib.h> can be included directly."
0031 #endif
0032
0033 #include <glib/gtimezone.h>
0034
0035 G_BEGIN_DECLS
0036
0037 /**
0038  * G_TIME_SPAN_DAY:
0039  *
0040  * Evaluates to a time span of one day.
0041  *
0042  * Since: 2.26
0043  */
0044 #define G_TIME_SPAN_DAY                 (G_GINT64_CONSTANT (86400000000))
0045
0046 /**
0047  * G_TIME_SPAN_HOUR:
0048  *
0049  * Evaluates to a time span of one hour.
0050  *
0051  * Since: 2.26
0052  */
0053 #define G_TIME_SPAN_HOUR                (G_GINT64_CONSTANT (3600000000))
0054
0055 /**
0056  * G_TIME_SPAN_MINUTE:
0057  *
0058  * Evaluates to a time span of one minute.
0059  *
0060  * Since: 2.26
0061  */
0062 #define G_TIME_SPAN_MINUTE              (G_GINT64_CONSTANT (60000000))
0063
0064 /**
0065  * G_TIME_SPAN_SECOND:
0066  *
0067  * Evaluates to a time span of one second.
0068  *
0069  * Since: 2.26
0070  */
0071 #define G_TIME_SPAN_SECOND              (G_GINT64_CONSTANT (1000000))
0072
0073 /**
0074  * G_TIME_SPAN_MILLISECOND:
0075  *
0076  * Evaluates to a time span of one millisecond.
0077  *
0078  * Since: 2.26
0079  */
0080 #define G_TIME_SPAN_MILLISECOND         (G_GINT64_CONSTANT (1000))
0081
0082 /**
0083  * GTimeSpan:
0084  *
0085  * A value representing an interval of time, in microseconds.
0086  *
0087  * Since: 2.26
0088  */
0089 typedef gint64 GTimeSpan;
0090
0091 /**
0092  * GDateTime:
0093  *
0094  * `GDateTime` is a structure that combines a Gregorian date and time
0095  * into a single structure.
0096  *
0097  * `GDateTime` provides many conversion and methods to manipulate dates and times.
0098  * Time precision is provided down to microseconds and the time can range
0099  * (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
0100  * `GDateTime` follows POSIX time in the sense that it is oblivious to leap
0101  * seconds.
0102  *
0103  * `GDateTime` is an immutable object; once it has been created it cannot
0104  * be modified further. All modifiers will create a new `GDateTime`.
0105  * Nearly all such functions can fail due to the date or time going out
0106  * of range, in which case %NULL will be returned.
0107  *
0108  * `GDateTime` is reference counted: the reference count is increased by calling
0109  * [method@GLib.DateTime.ref] and decreased by calling [method@GLib.DateTime.unref].
0110  * When the reference count drops to 0, the resources allocated by the `GDateTime`
0111  * structure are released.
0112  *
0113  * Many parts of the API may produce non-obvious results. As an
0114  * example, adding two months to January 31st will yield March 31st
0115  * whereas adding one month and then one month again will yield either
0116  * March 28th or March 29th.  Also note that adding 24 hours is not
0117  * always the same as adding one day (since days containing daylight
0118  * savings time transitions are either 23 or 25 hours in length).
0119  *
0120  * Since: 2.26
0121  */
0122 typedef struct _GDateTime GDateTime;
0123
0124 GLIB_AVAILABLE_IN_ALL
0125 void                    g_date_time_unref                               (GDateTime      *datetime);
0126 GLIB_AVAILABLE_IN_ALL
0127 GDateTime *             g_date_time_ref                                 (GDateTime      *datetime);
0128
0129 GLIB_AVAILABLE_IN_ALL
0130 GDateTime *             g_date_time_new_now                             (GTimeZone      *tz);
0131 GLIB_AVAILABLE_IN_ALL
0132 GDateTime *             g_date_time_new_now_local                       (void);
0133 GLIB_AVAILABLE_IN_ALL
0134 GDateTime *             g_date_time_new_now_utc                         (void);
0135
0136 GLIB_AVAILABLE_IN_ALL
0137 GDateTime *             g_date_time_new_from_unix_local                 (gint64          t);
0138 GLIB_AVAILABLE_IN_ALL
0139 GDateTime *             g_date_time_new_from_unix_utc                   (gint64          t);
0140
0141 GLIB_AVAILABLE_IN_2_80
0142 GDateTime *             g_date_time_new_from_unix_local_usec            (gint64          usecs);
0143 GLIB_AVAILABLE_IN_2_80
0144 GDateTime *             g_date_time_new_from_unix_utc_usec              (gint64          usecs);
0145
0146 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0147 GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_new_from_unix_local)
0148 GDateTime *             g_date_time_new_from_timeval_local              (const GTimeVal *tv);
0149 GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_new_from_unix_utc)
0150 GDateTime *             g_date_time_new_from_timeval_utc                (const GTimeVal *tv);
0151 G_GNUC_END_IGNORE_DEPRECATIONS
0152
0153 GLIB_AVAILABLE_IN_2_56
0154 GDateTime *             g_date_time_new_from_iso8601                    (const gchar    *text,
0155                                                                          GTimeZone      *default_tz);
0156
0157 GLIB_AVAILABLE_IN_ALL
0158 GDateTime *             g_date_time_new                                 (GTimeZone      *tz,
0159                                                                          gint            year,
0160                                                                          gint            month,
0161                                                                          gint            day,
0162                                                                          gint            hour,
0163                                                                          gint            minute,
0164                                                                          gdouble         seconds);
0165 GLIB_AVAILABLE_IN_ALL
0166 GDateTime *             g_date_time_new_local                           (gint            year,
0167                                                                          gint            month,
0168                                                                          gint            day,
0169                                                                          gint            hour,
0170                                                                          gint            minute,
0171                                                                          gdouble         seconds);
0172 GLIB_AVAILABLE_IN_ALL
0173 GDateTime *             g_date_time_new_utc                             (gint            year,
0174                                                                          gint            month,
0175                                                                          gint            day,
0176                                                                          gint            hour,
0177                                                                          gint            minute,
0178                                                                          gdouble         seconds);
0179
0180 GLIB_AVAILABLE_IN_ALL
0181 G_GNUC_WARN_UNUSED_RESULT
0182 GDateTime *             g_date_time_add                                 (GDateTime      *datetime,
0183                                                                          GTimeSpan       timespan);
0184
0185 GLIB_AVAILABLE_IN_ALL
0186 G_GNUC_WARN_UNUSED_RESULT
0187 GDateTime *             g_date_time_add_years                           (GDateTime      *datetime,
0188                                                                          gint            years);
0189 GLIB_AVAILABLE_IN_ALL
0190 G_GNUC_WARN_UNUSED_RESULT
0191 GDateTime *             g_date_time_add_months                          (GDateTime      *datetime,
0192                                                                          gint            months);
0193 GLIB_AVAILABLE_IN_ALL
0194 G_GNUC_WARN_UNUSED_RESULT
0195 GDateTime *             g_date_time_add_weeks                           (GDateTime      *datetime,
0196                                                                          gint            weeks);
0197 GLIB_AVAILABLE_IN_ALL
0198 G_GNUC_WARN_UNUSED_RESULT
0199 GDateTime *             g_date_time_add_days                            (GDateTime      *datetime,
0200                                                                          gint            days);
0201
0202 GLIB_AVAILABLE_IN_ALL
0203 G_GNUC_WARN_UNUSED_RESULT
0204 GDateTime *             g_date_time_add_hours                           (GDateTime      *datetime,
0205                                                                          gint            hours);
0206 GLIB_AVAILABLE_IN_ALL
0207 G_GNUC_WARN_UNUSED_RESULT
0208 GDateTime *             g_date_time_add_minutes                         (GDateTime      *datetime,
0209                                                                          gint            minutes);
0210 GLIB_AVAILABLE_IN_ALL
0211 G_GNUC_WARN_UNUSED_RESULT
0212 GDateTime *             g_date_time_add_seconds                         (GDateTime      *datetime,
0213                                                                          gdouble         seconds);
0214
0215 GLIB_AVAILABLE_IN_ALL
0216 G_GNUC_WARN_UNUSED_RESULT
0217 GDateTime *             g_date_time_add_full                            (GDateTime      *datetime,
0218                                                                          gint            years,
0219                                                                          gint            months,
0220                                                                          gint            days,
0221                                                                          gint            hours,
0222                                                                          gint            minutes,
0223                                                                          gdouble         seconds);
0224
0225 GLIB_AVAILABLE_IN_ALL
0226 gint                    g_date_time_compare                             (gconstpointer   dt1,
0227                                                                          gconstpointer   dt2);
0228 GLIB_AVAILABLE_IN_ALL
0229 GTimeSpan               g_date_time_difference                          (GDateTime      *end,
0230                                                                          GDateTime      *begin);
0231 GLIB_AVAILABLE_IN_ALL
0232 guint                   g_date_time_hash                                (gconstpointer   datetime);
0233 GLIB_AVAILABLE_IN_ALL
0234 gboolean                g_date_time_equal                               (gconstpointer   dt1,
0235                                                                          gconstpointer   dt2);
0236
0237 GLIB_AVAILABLE_IN_ALL
0238 void                    g_date_time_get_ymd                             (GDateTime      *datetime,
0239                                                                          gint           *year,
0240                                                                          gint           *month,
0241                                                                          gint           *day);
0242
0243 GLIB_AVAILABLE_IN_ALL
0244 gint                    g_date_time_get_year                            (GDateTime      *datetime);
0245 GLIB_AVAILABLE_IN_ALL
0246 gint                    g_date_time_get_month                           (GDateTime      *datetime);
0247 GLIB_AVAILABLE_IN_ALL
0248 gint                    g_date_time_get_day_of_month                    (GDateTime      *datetime);
0249
0250 GLIB_AVAILABLE_IN_ALL
0251 gint                    g_date_time_get_week_numbering_year             (GDateTime      *datetime);
0252 GLIB_AVAILABLE_IN_ALL
0253 gint                    g_date_time_get_week_of_year                    (GDateTime      *datetime);
0254 GLIB_AVAILABLE_IN_ALL
0255 gint                    g_date_time_get_day_of_week                     (GDateTime      *datetime);
0256
0257 GLIB_AVAILABLE_IN_ALL
0258 gint                    g_date_time_get_day_of_year                     (GDateTime      *datetime);
0259
0260 GLIB_AVAILABLE_IN_ALL
0261 gint                    g_date_time_get_hour                            (GDateTime      *datetime);
0262 GLIB_AVAILABLE_IN_ALL
0263 gint                    g_date_time_get_minute                          (GDateTime      *datetime);
0264 GLIB_AVAILABLE_IN_ALL
0265 gint                    g_date_time_get_second                          (GDateTime      *datetime);
0266 GLIB_AVAILABLE_IN_ALL
0267 gint                    g_date_time_get_microsecond                     (GDateTime      *datetime);
0268 GLIB_AVAILABLE_IN_ALL
0269 gdouble                 g_date_time_get_seconds                         (GDateTime      *datetime);
0270
0271 GLIB_AVAILABLE_IN_ALL
0272 gint64                  g_date_time_to_unix                             (GDateTime      *datetime);
0273 GLIB_AVAILABLE_IN_2_80
0274 gint64                  g_date_time_to_unix_usec                        (GDateTime      *datetime);
0275
0276 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0277 GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_to_unix)
0278 gboolean                g_date_time_to_timeval                          (GDateTime      *datetime,
0279                                                                          GTimeVal       *tv);
0280 G_GNUC_END_IGNORE_DEPRECATIONS
0281
0282 GLIB_AVAILABLE_IN_ALL
0283 GTimeSpan               g_date_time_get_utc_offset                      (GDateTime      *datetime);
0284 GLIB_AVAILABLE_IN_2_58
0285 GTimeZone *             g_date_time_get_timezone                        (GDateTime      *datetime);
0286 GLIB_AVAILABLE_IN_ALL
0287 const gchar *           g_date_time_get_timezone_abbreviation           (GDateTime      *datetime);
0288 GLIB_AVAILABLE_IN_ALL
0289 gboolean                g_date_time_is_daylight_savings                 (GDateTime      *datetime);
0290
0291 GLIB_AVAILABLE_IN_ALL
0292 GDateTime *             g_date_time_to_timezone                         (GDateTime      *datetime,
0293                                                                          GTimeZone      *tz);
0294 GLIB_AVAILABLE_IN_ALL
0295 GDateTime *             g_date_time_to_local                            (GDateTime      *datetime);
0296 GLIB_AVAILABLE_IN_ALL
0297 GDateTime *             g_date_time_to_utc                              (GDateTime      *datetime);
0298
0299 GLIB_AVAILABLE_IN_ALL
0300 gchar *                 g_date_time_format                              (GDateTime      *datetime,
0301                                                                          const gchar    *format) G_GNUC_MALLOC;
0302 GLIB_AVAILABLE_IN_2_62
0303 gchar *                 g_date_time_format_iso8601                      (GDateTime      *datetime) G_GNUC_MALLOC;
0304
0305 G_END_DECLS
0306
0307 #endif /* __G_DATE_TIME_H__ */