luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-24 21:16:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GDate SECTION

Browse Source 
Move the contents to the struct docs.

Helps: #3037
This commit is contained in:
Matthias Clasen 2023-09-25 08:02:16 -04:00 committed by Philip Withnall
parent 1dae4fc618
commit 55a844a465
2 changed files with 23 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
glib/gdate.c
View File

@ -60,21 +60,21 @@
#endif #endif
/** /**
* SECTION:date * GDate:
* @title: Date and Time Functions
* @short_description: calendrical calculations and miscellaneous time stuff
* *
* The #GDate data structure represents a day between January 1, Year 1, * `GDate` is a struct for calendrical calculations.
*
* The `GDate` data structure represents a day between January 1, Year 1,
* and sometime a few thousand years in the future (right now it will go * and sometime a few thousand years in the future (right now it will go
* to the year 65535 or so, but g_date_set_parse() only parses up to the * to the year 65535 or so, but [method@GLib.Date.set_parse] only parses up to the
* year 8000 or so - just count on "a few thousand"). #GDate is meant to * year 8000 or so - just count on "a few thousand"). `GDate` is meant to
* represent everyday dates, not astronomical dates or historical dates * represent everyday dates, not astronomical dates or historical dates
* or ISO timestamps or the like. It extrapolates the current Gregorian * or ISO timestamps or the like. It extrapolates the current Gregorian
* calendar forward and backward in time; there is no attempt to change * calendar forward and backward in time; there is no attempt to change
* the calendar to match time periods or locations. #GDate does not store * the calendar to match time periods or locations. `GDate` does not store
* time information; it represents a day. * time information; it represents a day.
* *
* The #GDate implementation has several nice features; it is only a * The `GDate` implementation has several nice features; it is only a
* 64-bit struct, so storing large numbers of dates is very efficient. It * 64-bit struct, so storing large numbers of dates is very efficient. It
* can keep both a Julian and day-month-year representation of the date, * can keep both a Julian and day-month-year representation of the date,
* since some calculations are much easier with one representation or the * since some calculations are much easier with one representation or the
@ -84,25 +84,23 @@
* technical sense; technically, Julian dates count from the start of the * technical sense; technically, Julian dates count from the start of the
* Julian period, Jan 1, 4713 BC). * Julian period, Jan 1, 4713 BC).
* *
* #GDate is simple to use. First you need a "blank" date; you can get a * `GDate` is simple to use. First you need a "blank" date; you can get a
* dynamically allocated date from g_date_new(), or you can declare an * dynamically allocated date from [method@GLib.Date.new], or you can declare an
* automatic variable or array and initialize it by * automatic variable or array and initialize it by calling [method@GLib.Date.clear].
* calling g_date_clear(). A cleared date is safe; it's safe to call * A cleared date is safe; it's safe to call [method@GLib.Date.set_dmy] and the other
* g_date_set_dmy() and the other mutator functions to initialize the * mutator functions to initialize the value of a cleared date. However, a cleared date
* value of a cleared date. However, a cleared date is initially * is initially invalid, meaning that it doesn't represent a day that exists.
* invalid, meaning that it doesn't represent a day that exists. * It is undefined to call any of the date calculation routines on an invalid date.
* It is undefined to call any of the date calculation routines on an * If you obtain a date from a user or other unpredictable source, you should check
* invalid date. If you obtain a date from a user or other * its validity with the [method@GLib.Date.valid] predicate. [method@GLib.Date.valid]
* unpredictable source, you should check its validity with the * is also used to check for errors with [method@GLib.Date.set_parse] and other functions
* g_date_valid() predicate. g_date_valid() is also used to check for * that can fail. Dates can be invalidated by calling [method@GLib.Date.clear] again.
* errors with g_date_set_parse() and other functions that can
* fail. Dates can be invalidated by calling g_date_clear() again.
* *
* It is very important to use the API to access the #GDate * It is very important to use the API to access the `GDate` struct. Often only the
* struct. Often only the day-month-year or only the Julian * day-month-year or only the Julian representation is valid. Sometimes neither is valid.
* representation is valid. Sometimes neither is valid. Use the API. * Use the API.
* *
* GLib also features #GDateTime which represents a precise time. * GLib also features `GDateTime` which represents a precise time.
*/ */
/** /**

9
glib/gdate.h
View File

@ -38,15 +38,6 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/* GDate
*
* Date calculations (not time for now, to be resolved). These are a
* mutant combination of Steffen Beyer's DateCalc routines
* (http://www.perl.com/CPAN/authors/id/STBEY/) and Jon Trowbridge's
* date routines (written for in-house software). Written by Havoc
* Pennington <hp@pobox.com>
*/
typedef gint32 GTime GLIB_DEPRECATED_TYPE_IN_2_62_FOR(GDateTime); typedef gint32 GTime GLIB_DEPRECATED_TYPE_IN_2_62_FOR(GDateTime);
typedef guint16 GDateYear; typedef guint16 GDateYear;
typedef guint8 GDateDay; /* day of the month */ typedef guint8 GDateDay; /* day of the month */