glib/gdatetime.h

   1 /*
   2  * Copyright (C) 2009-2010 Christian Hergert <chris@dronelabs.com>
   3  * Copyright © 2010 Codethink Limited
   4  *
   5  * SPDX-License-Identifier: LGPL-2.1-or-later
   6  *
   7  * This library is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU Lesser General Public License as
   9  * published by the Free Software Foundation; either version 2.1 of the
  10  * licence, or (at your option) any later version.
  11  *
  12  * This is distributed in the hope that it will be useful, but WITHOUT
  13  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
  15  * License for more details.
  16  *
  17  * You should have received a copy of the GNU Lesser General Public License
  18  * along with this library; if not, see <http://www.gnu.org/licenses/>.
  19  *
  20  * Authors: Christian Hergert <chris@dronelabs.com>
  21  *          Thiago Santos <thiago.sousa.santos@collabora.co.uk>
  22  *          Emmanuele Bassi <ebassi@linux.intel.com>
  23  *          Ryan Lortie <desrt@desrt.ca>
  24  */
  25
  26 #ifndef __G_DATE_TIME_H__
  27 #define __G_DATE_TIME_H__
  28
  29 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  30 #error "Only <glib.h> can be included directly."
  31 #endif
  32
  33 #include <glib/gtimezone.h>
  34
  35 G_BEGIN_DECLS
  36
  37 /**
  38  * G_TIME_SPAN_DAY:
  39  *
  40  * Evaluates to a time span of one day.
  41  *
  42  * Since: 2.26
  43  */
  44 #define G_TIME_SPAN_DAY                 (G_GINT64_CONSTANT (86400000000))
  45
  46 /**
  47  * G_TIME_SPAN_HOUR:
  48  *
  49  * Evaluates to a time span of one hour.
  50  *
  51  * Since: 2.26
  52  */
  53 #define G_TIME_SPAN_HOUR                (G_GINT64_CONSTANT (3600000000))
  54
  55 /**
  56  * G_TIME_SPAN_MINUTE:
  57  *
  58  * Evaluates to a time span of one minute.
  59  *
  60  * Since: 2.26
  61  */
  62 #define G_TIME_SPAN_MINUTE              (G_GINT64_CONSTANT (60000000))
  63
  64 /**
  65  * G_TIME_SPAN_SECOND:
  66  *
  67  * Evaluates to a time span of one second.
  68  *
  69  * Since: 2.26
  70  */
  71 #define G_TIME_SPAN_SECOND              (G_GINT64_CONSTANT (1000000))
  72
  73 /**
  74  * G_TIME_SPAN_MILLISECOND:
  75  *
  76  * Evaluates to a time span of one millisecond.
  77  *
  78  * Since: 2.26
  79  */
  80 #define G_TIME_SPAN_MILLISECOND         (G_GINT64_CONSTANT (1000))
  81
  82 /**
  83  * GTimeSpan:
  84  *
  85  * A value representing an interval of time, in microseconds.
  86  *
  87  * Since: 2.26
  88  */
  89 typedef gint64 GTimeSpan;
  90
  91 /**
  92  * GDateTime:
  93  *
  94  * `GDateTime` is a structure that combines a Gregorian date and time
  95  * into a single structure.
  96  *
  97  * `GDateTime` provides many conversion and methods to manipulate dates and times.
  98  * Time precision is provided down to microseconds and the time can range
  99  * (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
 100  * `GDateTime` follows POSIX time in the sense that it is oblivious to leap
 101  * seconds.
 102  *
 103  * `GDateTime` is an immutable object; once it has been created it cannot
 104  * be modified further. All modifiers will create a new `GDateTime`.
 105  * Nearly all such functions can fail due to the date or time going out
 106  * of range, in which case %NULL will be returned.
 107  *
 108  * `GDateTime` is reference counted: the reference count is increased by calling
 109  * [method@GLib.DateTime.ref] and decreased by calling [method@GLib.DateTime.unref].
 110  * When the reference count drops to 0, the resources allocated by the `GDateTime`
 111  * structure are released.
 112  *
 113  * Many parts of the API may produce non-obvious results. As an
 114  * example, adding two months to January 31st will yield March 31st
 115  * whereas adding one month and then one month again will yield either
 116  * March 28th or March 29th.  Also note that adding 24 hours is not
 117  * always the same as adding one day (since days containing daylight
 118  * savings time transitions are either 23 or 25 hours in length).
 119  *
 120  * Since: 2.26
 121  */
 122 typedef struct _GDateTime GDateTime;
 123
 124 GLIB_AVAILABLE_IN_ALL
 125 void                    g_date_time_unref                               (GDateTime      *datetime);
 126 GLIB_AVAILABLE_IN_ALL
 127 GDateTime *             g_date_time_ref                                 (GDateTime      *datetime);
 128
 129 GLIB_AVAILABLE_IN_ALL
 130 GDateTime *             g_date_time_new_now                             (GTimeZone      *tz);
 131 GLIB_AVAILABLE_IN_ALL
 132 GDateTime *             g_date_time_new_now_local                       (void);
 133 GLIB_AVAILABLE_IN_ALL
 134 GDateTime *             g_date_time_new_now_utc                         (void);
 135
 136 GLIB_AVAILABLE_IN_ALL
 137 GDateTime *             g_date_time_new_from_unix_local                 (gint64          t);
 138 GLIB_AVAILABLE_IN_ALL
 139 GDateTime *             g_date_time_new_from_unix_utc                   (gint64          t);
 140
 141 GLIB_AVAILABLE_IN_2_80
 142 GDateTime *             g_date_time_new_from_unix_local_usec            (gint64          usecs);
 143 GLIB_AVAILABLE_IN_2_80
 144 GDateTime *             g_date_time_new_from_unix_utc_usec              (gint64          usecs);
 145
 146 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 147 GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_new_from_unix_local)
 148 GDateTime *             g_date_time_new_from_timeval_local              (const GTimeVal *tv);
 149 GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_new_from_unix_utc)
 150 GDateTime *             g_date_time_new_from_timeval_utc                (const GTimeVal *tv);
 151 G_GNUC_END_IGNORE_DEPRECATIONS
 152
 153 GLIB_AVAILABLE_IN_2_56
 154 GDateTime *             g_date_time_new_from_iso8601                    (const gchar    *text,
 155                                                                          GTimeZone      *default_tz);
 156
 157 GLIB_AVAILABLE_IN_ALL
 158 GDateTime *             g_date_time_new                                 (GTimeZone      *tz,
 159                                                                          gint            year,
 160                                                                          gint            month,
 161                                                                          gint            day,
 162                                                                          gint            hour,
 163                                                                          gint            minute,
 164                                                                          gdouble         seconds);
 165 GLIB_AVAILABLE_IN_ALL
 166 GDateTime *             g_date_time_new_local                           (gint            year,
 167                                                                          gint            month,
 168                                                                          gint            day,
 169                                                                          gint            hour,
 170                                                                          gint            minute,
 171                                                                          gdouble         seconds);
 172 GLIB_AVAILABLE_IN_ALL
 173 GDateTime *             g_date_time_new_utc                             (gint            year,
 174                                                                          gint            month,
 175                                                                          gint            day,
 176                                                                          gint            hour,
 177                                                                          gint            minute,
 178                                                                          gdouble         seconds);
 179
 180 GLIB_AVAILABLE_IN_ALL
 181 G_GNUC_WARN_UNUSED_RESULT
 182 GDateTime *             g_date_time_add                                 (GDateTime      *datetime,
 183                                                                          GTimeSpan       timespan);
 184
 185 GLIB_AVAILABLE_IN_ALL
 186 G_GNUC_WARN_UNUSED_RESULT
 187 GDateTime *             g_date_time_add_years                           (GDateTime      *datetime,
 188                                                                          gint            years);
 189 GLIB_AVAILABLE_IN_ALL
 190 G_GNUC_WARN_UNUSED_RESULT
 191 GDateTime *             g_date_time_add_months                          (GDateTime      *datetime,
 192                                                                          gint            months);
 193 GLIB_AVAILABLE_IN_ALL
 194 G_GNUC_WARN_UNUSED_RESULT
 195 GDateTime *             g_date_time_add_weeks                           (GDateTime      *datetime,
 196                                                                          gint            weeks);
 197 GLIB_AVAILABLE_IN_ALL
 198 G_GNUC_WARN_UNUSED_RESULT
 199 GDateTime *             g_date_time_add_days                            (GDateTime      *datetime,
 200                                                                          gint            days);
 201
 202 GLIB_AVAILABLE_IN_ALL
 203 G_GNUC_WARN_UNUSED_RESULT
 204 GDateTime *             g_date_time_add_hours                           (GDateTime      *datetime,
 205                                                                          gint            hours);
 206 GLIB_AVAILABLE_IN_ALL
 207 G_GNUC_WARN_UNUSED_RESULT
 208 GDateTime *             g_date_time_add_minutes                         (GDateTime      *datetime,
 209                                                                          gint            minutes);
 210 GLIB_AVAILABLE_IN_ALL
 211 G_GNUC_WARN_UNUSED_RESULT
 212 GDateTime *             g_date_time_add_seconds                         (GDateTime      *datetime,
 213                                                                          gdouble         seconds);
 214
 215 GLIB_AVAILABLE_IN_ALL
 216 G_GNUC_WARN_UNUSED_RESULT
 217 GDateTime *             g_date_time_add_full                            (GDateTime      *datetime,
 218                                                                          gint            years,
 219                                                                          gint            months,
 220                                                                          gint            days,
 221                                                                          gint            hours,
 222                                                                          gint            minutes,
 223                                                                          gdouble         seconds);
 224
 225 GLIB_AVAILABLE_IN_ALL
 226 gint                    g_date_time_compare                             (gconstpointer   dt1,
 227                                                                          gconstpointer   dt2);
 228 GLIB_AVAILABLE_IN_ALL
 229 GTimeSpan               g_date_time_difference                          (GDateTime      *end,
 230                                                                          GDateTime      *begin);
 231 GLIB_AVAILABLE_IN_ALL
 232 guint                   g_date_time_hash                                (gconstpointer   datetime);
 233 GLIB_AVAILABLE_IN_ALL
 234 gboolean                g_date_time_equal                               (gconstpointer   dt1,
 235                                                                          gconstpointer   dt2);
 236
 237 GLIB_AVAILABLE_IN_ALL
 238 void                    g_date_time_get_ymd                             (GDateTime      *datetime,
 239                                                                          gint           *year,
 240                                                                          gint           *month,
 241                                                                          gint           *day);
 242
 243 GLIB_AVAILABLE_IN_ALL
 244 gint                    g_date_time_get_year                            (GDateTime      *datetime);
 245 GLIB_AVAILABLE_IN_ALL
 246 gint                    g_date_time_get_month                           (GDateTime      *datetime);
 247 GLIB_AVAILABLE_IN_ALL
 248 gint                    g_date_time_get_day_of_month                    (GDateTime      *datetime);
 249
 250 GLIB_AVAILABLE_IN_ALL
 251 gint                    g_date_time_get_week_numbering_year             (GDateTime      *datetime);
 252 GLIB_AVAILABLE_IN_ALL
 253 gint                    g_date_time_get_week_of_year                    (GDateTime      *datetime);
 254 GLIB_AVAILABLE_IN_ALL
 255 gint                    g_date_time_get_day_of_week                     (GDateTime      *datetime);
 256
 257 GLIB_AVAILABLE_IN_ALL
 258 gint                    g_date_time_get_day_of_year                     (GDateTime      *datetime);
 259
 260 GLIB_AVAILABLE_IN_ALL
 261 gint                    g_date_time_get_hour                            (GDateTime      *datetime);
 262 GLIB_AVAILABLE_IN_ALL
 263 gint                    g_date_time_get_minute                          (GDateTime      *datetime);
 264 GLIB_AVAILABLE_IN_ALL
 265 gint                    g_date_time_get_second                          (GDateTime      *datetime);
 266 GLIB_AVAILABLE_IN_ALL
 267 gint                    g_date_time_get_microsecond                     (GDateTime      *datetime);
 268 GLIB_AVAILABLE_IN_ALL
 269 gdouble                 g_date_time_get_seconds                         (GDateTime      *datetime);
 270
 271 GLIB_AVAILABLE_IN_ALL
 272 gint64                  g_date_time_to_unix                             (GDateTime      *datetime);
 273 GLIB_AVAILABLE_IN_2_80
 274 gint64                  g_date_time_to_unix_usec                        (GDateTime      *datetime);
 275
 276 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 277 GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_to_unix)
 278 gboolean                g_date_time_to_timeval                          (GDateTime      *datetime,
 279                                                                          GTimeVal       *tv);
 280 G_GNUC_END_IGNORE_DEPRECATIONS
 281
 282 GLIB_AVAILABLE_IN_ALL
 283 GTimeSpan               g_date_time_get_utc_offset                      (GDateTime      *datetime);
 284 GLIB_AVAILABLE_IN_2_58
 285 GTimeZone *             g_date_time_get_timezone                        (GDateTime      *datetime);
 286 GLIB_AVAILABLE_IN_ALL
 287 const gchar *           g_date_time_get_timezone_abbreviation           (GDateTime      *datetime);
 288 GLIB_AVAILABLE_IN_ALL
 289 gboolean                g_date_time_is_daylight_savings                 (GDateTime      *datetime);
 290
 291 GLIB_AVAILABLE_IN_ALL
 292 GDateTime *             g_date_time_to_timezone                         (GDateTime      *datetime,
 293                                                                          GTimeZone      *tz);
 294 GLIB_AVAILABLE_IN_ALL
 295 GDateTime *             g_date_time_to_local                            (GDateTime      *datetime);
 296 GLIB_AVAILABLE_IN_ALL
 297 GDateTime *             g_date_time_to_utc                              (GDateTime      *datetime);
 298
 299 GLIB_AVAILABLE_IN_ALL
 300 gchar *                 g_date_time_format                              (GDateTime      *datetime,
 301                                                                          const gchar    *format) G_GNUC_MALLOC;
 302 GLIB_AVAILABLE_IN_2_62
 303 gchar *                 g_date_time_format_iso8601                      (GDateTime      *datetime) G_GNUC_MALLOC;
 304
 305 G_END_DECLS
 306
 307 #endif /* __G_DATE_TIME_H__ */