calendrical calculations and miscellaneous time stuff.
<!-- ##### SECTION Long_Description ##### -->
-<para>\r
-The #GDate data structure represents a day between January 1, Year 1,\r
-and sometime a few thousand years in the future (right now it will go\r
-to the year 65535 or so, but g_date_set_parse() only parses up to the\r
-year 8000 or so - just count on "a few thousand"). #GDate is meant to\r
-represent everyday dates, not astronomical dates or historical dates\r
-or ISO timestamps or the like. It extrapolates the current Gregorian\r
-calendar forward and backward in time; there is no attempt to change\r
-the calendar to match time periods or locations. #GDate does not store\r
-time information; it represents a <emphasis>day</emphasis>.\r
-</para>\r
-\r
-<para>\r
-The #GDate implementation has several nice features; it is only a\r
-64-bit struct, so storing large numbers of dates is very efficient. It\r
-can keep both a Julian and Day-Month-Year representation of the date,\r
-since some calculations are much easier with one representation or the\r
-other. A Julian representation is simply a count of days since some\r
-fixed day in the past; for #GDate the fixed day is January 1, 1 AD.\r
-("Julian" dates in the #GDate API aren't really Julian dates in the\r
-technical sense; technically, Julian dates count from the start of the\r
-Julian period, Jan 1, 4713 BC).\r
-</para>\r
-\r
-<para>\r
-#GDate is simple to use. First you need a "blank" date; you can get a\r
-dynamically allocated date from g_date_new(), or you can declare an\r
-automatic variable or array and initialize it to a sane state by\r
-calling g_date_clear(). A cleared date is sane; it's safe to call\r
-g_date_set_dmy() and the other mutator functions to initialize the\r
-value of a cleared date. However, a cleared date is initially\r
-<emphasis>invalid</emphasis>, meaning that it doesn't represent a day\r
-that exists. It is undefined to call any of the date calculation\r
-routines on an invalid date. If you obtain a date from a user or other\r
-unpredictable source, you should check its validity with the\r
-g_date_valid() predicate. g_date_valid() is also used to check for\r
-errors with g_date_set_parse() and other functions that can\r
-fail. Dates can be invalidated by calling g_date_clear() again.\r
-</para>\r
-\r
-<para>\r
-<emphasis>It is very important to use the API to access the #GDate\r
-struct.</emphasis> Often only the DMY or only the Julian\r
-representation is valid. Sometimes neither is valid. Use the API.\r
-</para>\r
-\r
-<para>\r
-glib doesn't contain any time-manipulation functions; however, there\r
-is a #GTime typedef which is equivalent to time_t, and a #GTimeVal\r
-struct which represents a more precise time (with microseconds). You\r
-can request the current time as a #GTimeVal with g_get_current_time().\r
+<para>
+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
+to the year 65535 or so, but g_date_set_parse() only parses up to the
+year 8000 or so - just count on "a few thousand"). #GDate is meant to
+represent everyday dates, not astronomical dates or historical dates
+or ISO timestamps or the like. It extrapolates the current Gregorian
+calendar forward and backward in time; there is no attempt to change
+the calendar to match time periods or locations. #GDate does not store
+time information; it represents a <emphasis>day</emphasis>.
+</para>
+
+<para>
+The #GDate implementation has several nice features; it is only a
+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,
+since some calculations are much easier with one representation or the
+other. A Julian representation is simply a count of days since some
+fixed day in the past; for #GDate the fixed day is January 1, 1 AD.
+("Julian" dates in the #GDate API aren't really Julian dates in the
+technical sense; technically, Julian dates count from the start of the
+Julian period, Jan 1, 4713 BC).
+</para>
+
+<para>
+#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
+automatic variable or array and initialize it to a sane state by
+calling g_date_clear(). A cleared date is sane; it's safe to call
+g_date_set_dmy() and the other mutator functions to initialize the
+value of a cleared date. However, a cleared date is initially
+<emphasis>invalid</emphasis>, 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. If you obtain a date from a user or other
+unpredictable source, you should check its validity with the
+g_date_valid() predicate. g_date_valid() is also used to check for
+errors with g_date_set_parse() and other functions that can
+fail. Dates can be invalidated by calling g_date_clear() again.
+</para>
+
+<para>
+<emphasis>It is very important to use the API to access the #GDate
+struct.</emphasis> Often only the DMY or only the Julian
+representation is valid. Sometimes neither is valid. Use the API.
+</para>
+
+<para>
+GLib doesn't contain any time-manipulation functions; however, there
+is a #GTime typedef which is equivalent to <type>time_t</type>, and a #GTimeVal
+struct which represents a more precise time (with microseconds). You
+can request the current time as a #GTimeVal with g_get_current_time().
</para>
<!-- ##### SECTION See_Also ##### -->
-<para>\r
-\r
+<para>
+
</para>
<!-- ##### MACRO G_USEC_PER_SEC ##### -->
<!-- ##### STRUCT GTimeVal ##### -->
-<para>\r
-Represents a precise time, with seconds and microseconds. Same as the\r
-<structname>struct timeval</structname> returned by the\r
-<function>gettimeofday()</function> UNIX call.\r
+<para>
+Represents a precise time, with seconds and microseconds. Same as the
+<structname>struct timeval</structname> returned by the
+<function>gettimeofday()</function> UNIX call.
</para>
-@tv_sec:
-@tv_usec:
+@tv_sec: seconds.
+@tv_usec: microseconds.
<!-- ##### FUNCTION g_get_current_time ##### -->
-<para>\r
-Equivalent to <function>gettimeofday()</function>, but also works on\r
-Win32. Returns the current time.\r
+<para>
+Equivalent to <function>gettimeofday()</function>, but also works on
+Win32. Returns the current time.
</para>
-@result:
+@result:
<!-- ##### FUNCTION g_usleep ##### -->
rely on the exact length of the sleep.
</para>
-@microseconds: number of microseconds to pause
+@microseconds: number of microseconds to pause.
<!-- ##### FUNCTION g_time_val_add ##### -->
<!-- ##### STRUCT GDate ##### -->
-<para>\r
-Represents a day between January 1, Year 1 and a few thousand years in\r
-the future. None of its members should be accessed directly. If the\r
-<structname>GDate</structname> is obtained from g_date_new(), it will\r
-be safe to mutate but invalid and thus not safe for calendrical computations.\r
-If it's declared on the stack, it will contain garbage so must be\r
-initialized with g_date_clear(). g_date_clear() makes the date invalid\r
-but sane. An invalid date doesn't represent a day, it's "empty." A\r
-date becomes valid after you set it to a Julian day or you set a day,\r
-month, and year.\r
+<para>
+Represents a day between January 1, Year 1 and a few thousand years in
+the future. None of its members should be accessed directly. If the
+<structname>GDate</structname> is obtained from g_date_new(), it will
+be safe to mutate but invalid and thus not safe for calendrical computations.
+If it's declared on the stack, it will contain garbage so must be
+initialized with g_date_clear(). g_date_clear() makes the date invalid
+but sane. An invalid date doesn't represent a day, it's "empty." A
+date becomes valid after you set it to a Julian day or you set a day,
+month, and year.
</para>
@julian_days:
@year:
<!-- ##### TYPEDEF GTime ##### -->
-<para>\r
-Simply a replacement for time_t. Unrelated to GTimer.\r
+<para>
+Simply a replacement for <type>time_t</type>. Unrelated to #GTimer.
</para>
<!-- ##### ENUM GDateDMY ##### -->
-<para>\r
-This enumeration isn't used in the API, but may be useful if you need\r
-to mark a number as a day, month, or year.\r
+<para>
+This enumeration isn't used in the API, but may be useful if you need
+to mark a number as a day, month, or year.
</para>
@G_DATE_DAY:
@G_DATE_YEAR:
<!-- ##### TYPEDEF GDateDay ##### -->
-<para>\r
-Integer representing a day of the month; between 1 and\r
-31. #G_DATE_BAD_DAY represents an invalid day of the month.\r
+<para>
+Integer representing a day of the month; between 1 and
+31. #G_DATE_BAD_DAY represents an invalid day of the month.
</para>
<!-- ##### ENUM GDateMonth ##### -->
-<para>\r
-Enumeration representing a month; values are #G_DATE_JANUARY,\r
-#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the "invalid" value.\r
-</para>
-
-@G_DATE_BAD_MONTH:
-@G_DATE_JANUARY:
-@G_DATE_FEBRUARY:
-@G_DATE_MARCH:
-@G_DATE_APRIL:
-@G_DATE_MAY:
-@G_DATE_JUNE:
-@G_DATE_JULY:
-@G_DATE_AUGUST:
-@G_DATE_SEPTEMBER:
-@G_DATE_OCTOBER:
-@G_DATE_NOVEMBER:
-@G_DATE_DECEMBER:
+<para>
+Enumeration representing a month; values are #G_DATE_JANUARY,
+#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.
+</para>
+
+@G_DATE_BAD_MONTH: invalid value.
+@G_DATE_JANUARY: January.
+@G_DATE_FEBRUARY: February.
+@G_DATE_MARCH: March.
+@G_DATE_APRIL: April.
+@G_DATE_MAY: May.
+@G_DATE_JUNE: June.
+@G_DATE_JULY: July.
+@G_DATE_AUGUST: August.
+@G_DATE_SEPTEMBER: September.
+@G_DATE_OCTOBER: October.
+@G_DATE_NOVEMBER: November.
+@G_DATE_DECEMBER: December.
<!-- ##### TYPEDEF GDateYear ##### -->
-<para>\r
-Integer representing a year; #G_DATE_BAD_YEAR is the invalid\r
-value. The year must be 1 or higher; negative (BC) years are not\r
-allowed. The year is represented with four digits.\r
+<para>
+Integer representing a year; #G_DATE_BAD_YEAR is the invalid
+value. The year must be 1 or higher; negative (BC) years are not
+allowed. The year is represented with four digits.
</para>
<!-- ##### ENUM GDateWeekday ##### -->
-<para>\r
-Enumeration representing a day of the week; #G_DATE_MONDAY,\r
-#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.\r
+<para>
+Enumeration representing a day of the week; #G_DATE_MONDAY,
+#G_DATE_TUESDAY, etc. #G_DATE_BAD_WEEKDAY is an invalid weekday.
</para>
-@G_DATE_BAD_WEEKDAY:
-@G_DATE_MONDAY:
-@G_DATE_TUESDAY:
-@G_DATE_WEDNESDAY:
-@G_DATE_THURSDAY:
-@G_DATE_FRIDAY:
-@G_DATE_SATURDAY:
-@G_DATE_SUNDAY:
+@G_DATE_BAD_WEEKDAY: invalid value.
+@G_DATE_MONDAY: Monday.
+@G_DATE_TUESDAY: Tuesday.
+@G_DATE_WEDNESDAY: Wednesday.
+@G_DATE_THURSDAY: Thursday.
+@G_DATE_FRIDAY: Friday.
+@G_DATE_SATURDAY: Saturday.
+@G_DATE_SUNDAY: Sunday.
<!-- ##### MACRO G_DATE_BAD_DAY ##### -->
-<para>\r
-Represents an invalid #GDateDay.\r
+<para>
+Represents an invalid #GDateDay.
</para>
<!-- ##### MACRO G_DATE_BAD_JULIAN ##### -->
-<para>\r
-Represents an invalid Julian day number.\r
+<para>
+Represents an invalid Julian day number.
</para>
<!-- ##### MACRO G_DATE_BAD_YEAR ##### -->
-<para>\r
-Represents an invalid year.\r
+<para>
+Represents an invalid year.
</para>
<!-- ##### FUNCTION g_date_new ##### -->
-<para>\r
-Allocate a #GDate and initialize it to a sane state. The new date will\r
-be cleared (as if you'd called g_date_clear()) but invalid (it won't\r
-represent an existing day). Free the return value with g_date_free().\r
+<para>
+Allocates a #GDate and initializes it to a sane state. The new date will
+be cleared (as if you'd called g_date_clear()) but invalid (it won't
+represent an existing day). Free the return value with g_date_free().
</para>
-@Returns: The newly-allocated #GDate
+@Returns: a newly-allocated #GDate.
<!-- ##### FUNCTION g_date_new_dmy ##### -->
-<para>\r
-Like g_date_new(), but also sets the value of the date. Assuming the\r
-day/month/year triplet you pass in represents an existing day, the\r
-returned date will be valid.\r
+<para>
+Like g_date_new(), but also sets the value of the date. Assuming the
+day/month/year triplet you pass in represents an existing day, the
+returned date will be valid.
</para>
-@day: Day of the month
-@month: Month of the year
-@year: Year
-@Returns: Allocated date initialized with @day, @month, and @year
+@day: day of the month.
+@month: month of the year.
+@year: year
+@Returns: a newly-allocated #GDate initialized with @day, @month, and @year.
<!-- ##### FUNCTION g_date_new_julian ##### -->
-<para>\r
-Like g_date_new(), but also sets the value of the date. Assuming the\r
-Julian day number you pass in is valid (greater than 0, less than an\r
-unreasonably large number), the returned date will be valid.\r
+<para>
+Like g_date_new(), but also sets the value of the date. Assuming the
+Julian day number you pass in is valid (greater than 0, less than an
+unreasonably large number), the returned date will be valid.
</para>
-@julian_day: Days since January 1, Year 1
-@Returns: Allocated date initialized with @julian_day
+@julian_day: days since January 1, Year 1.
+@Returns: a newly-allocated #GDate initialized with @julian_day.
<!-- ##### FUNCTION g_date_clear ##### -->
-<para>\r
-Initialize one or more #GDate structs to a sane but invalid\r
-state. The cleared dates will not represent an existing date, but will\r
-not contain garbage. Useful to init a date declared on the stack.\r
-Validity can be tested with g_date_valid().\r
+<para>
+Initializes one or more #GDate structs to a sane but invalid
+state. The cleared dates will not represent an existing date, but will
+not contain garbage. Useful to init a date declared on the stack.
+Validity can be tested with g_date_valid().
</para>
-@date: Pointer to one or more dates to clear
-@n_dates: Number of dates to clear
+@date: pointer to one or more dates to clear.
+@n_dates: number of dates to clear.
<!-- ##### FUNCTION g_date_free ##### -->
-<para>\r
-Free a #GDate returned from g_date_new()\r
+<para>
+Frees a #GDate returned from g_date_new().
</para>
-@date: Date to free
+@date: a #GDate.
<!-- ##### FUNCTION g_date_set_day ##### -->
-<para>\r
-Set the day of the month for a #GDate. If the resulting day-month-year\r
-triplet is invalid, the date will be invalid.\r
+<para>
+Sets the day of the month for a #GDate. If the resulting day-month-year
+triplet is invalid, the date will be invalid.
</para>
-@date: Date to set the day for
-@day: Day to set
+@date: a #GDate.
+@day: day to set.
<!-- ##### FUNCTION g_date_set_month ##### -->
-<para>\r
-Set the month of the year for a #GDate. If the resulting\r
- day-month-year triplet is invalid, the date will be invalid.\r
+<para>
+Sets the month of the year for a #GDate. If the resulting
+day-month-year triplet is invalid, the date will be invalid.
</para>
-@date: Date
-@month: Month to set
+@date: a #GDate.
+@month: month to set.
<!-- ##### FUNCTION g_date_set_year ##### -->
-<para>\r
-Set the year for a #GDate. If the resulting day-month-year triplet is\r
- invalid, the date will be invalid.\r
+<para>
+Sets the year for a #GDate. If the resulting day-month-year triplet is
+invalid, the date will be invalid.
</para>
-@date: Date
-@year: Year to set
+@date: a #GDate.
+@year: year to set.
<!-- ##### FUNCTION g_date_set_dmy ##### -->
-<para>\r
-Set the value of a #GDate from a day, month, and year. The DMY triplet\r
-must be valid; if you aren't sure it is, call g_date_valid_dmy() to\r
-check before you set it.\r
+<para>
+Sets the value of a #GDate from a day, month, and year. The day-month-year
+triplet must be valid; if you aren't sure it is, call g_date_valid_dmy() to
+check before you set it.
</para>
-@date: Date to set the value of
-@day: Day
-@month: Month
-@y: Year
+@date: a #GDate.
+@day: day.
+@month: month.
+@y: year.
<!-- ##### FUNCTION g_date_set_julian ##### -->
-<para>\r
-Set the value of a #GDate from a Julian day number. \r
+<para>
+Sets the value of a #GDate from a Julian day number.
</para>
-@date: Date to set
-@julian_date: Julian day number (days since January 1, Year 1)
+@date: a #GDate.
+@julian_date: Julian day number (days since January 1, Year 1).
<!-- ##### FUNCTION g_date_set_time ##### -->
-<para>\r
-Set the value of a date from a #GTime (time_t) value. To set the value\r
-of a date to the current day, you could write:\r
-<informalexample><programlisting>\r
- g_date_set_time(date, time(NULL));\r
-</programlisting></informalexample>\r
+<para>
+Sets the value of a date from a #GTime (<type>time_t</type>) value.
+To set the value of a date to the current day, you could write:
+<informalexample><programlisting>
+g_date_set_time(date, time(NULL));
+</programlisting></informalexample>
</para>
-@date: Date to update
-@time: #GTime value to set
+@date: a #GDate.
+@time: #GTime value to set.
<!-- ##### FUNCTION g_date_set_parse ##### -->
-<para>\r
-Parse a user-inputted string @str, and try to figure out what date it\r
-represents, taking the current locale into account. If the string is\r
-successfully parsed, the date will be valid after the call. Otherwise,\r
-it will be invalid. You should check using g_date_valid() to see\r
-whether the parsing succeeded.\r
-</para>\r
-\r
-<para>\r
-This function is not appropriate for file formats and the like; it\r
-isn't very precise, and its exact behavior varies with the\r
-locale. It's intended to be a heuristic routine that guesses what the\r
-user means by a given string (and it does work pretty well in that\r
-capacity).\r
-</para>
-
-@date: Date to fill in
-@str: String to parse
+<para>
+Parses a user-inputted string @str, and try to figure out what date it
+represents, taking the current locale into account. If the string is
+successfully parsed, the date will be valid after the call. Otherwise,
+it will be invalid. You should check using g_date_valid() to see
+whether the parsing succeeded.
+</para>
+
+<para>
+This function is not appropriate for file formats and the like; it
+isn't very precise, and its exact behavior varies with the
+locale. It's intended to be a heuristic routine that guesses what the
+user means by a given string (and it does work pretty well in that
+capacity).
+</para>
+
+@date: a #GDate to fill in.
+@str: string to parse.
<!-- ##### FUNCTION g_date_add_days ##### -->
-<para>\r
-Increment a date some number of days. To move forward by weeks, add\r
-weeks*7 days. The date must be valid.\r
+<para>
+Increments a date some number of days. To move forward by weeks, add
+weeks*7 days. The date must be valid.
</para>
-@date: The date to increment
-@n_days: Number of days to move the date forward
+@date: a #GDate to increment.
+@n_days: number of days to move the date forward.
<!-- ##### FUNCTION g_date_subtract_days ##### -->
-<para>\r
-Move a date some number of days into the past. To move by weeks, just\r
-move by weeks*7 days. Date must be valid.\r
+<para>
+Moves a date some number of days into the past. To move by weeks, just
+move by weeks*7 days. The date must be valid.
</para>
-@date: Date to decrement
-@n_days: Number of days to move
+@date: a #GDate to decrement.
+@n_days: number of days to move.
<!-- ##### FUNCTION g_date_add_months ##### -->
-<para>\r
-Increment a date by some number of months. If the day of the month is\r
-greater than 28, this routine may change the day of the month (because\r
-the destination month may not have the current day in it). The date\r
-must be valid.\r
+<para>
+Increments a date by some number of months. If the day of the month is
+greater than 28, this routine may change the day of the month (because
+the destination month may not have the current day in it). The date
+must be valid.
</para>
-@date: Date to increment
-@n_months: Number of months to move forward
+@date: a #GDate to increment.
+@n_months: number of months to move forward.
<!-- ##### FUNCTION g_date_subtract_months ##### -->
-<para>\r
-Move a date some number of months into the past. If the current day of\r
-the month doesn't exist in the destination month, the day of the month\r
-may change. Date must be valid.\r
+<para>
+Moves a date some number of months into the past. If the current day of
+the month doesn't exist in the destination month, the day of the month
+may change. The date must be valid.
</para>
-@date: Date to decrement
-@n_months: Number of months to move
+@date: a #GDate to decrement.
+@n_months: number of months to move.
<!-- ##### FUNCTION g_date_add_years ##### -->
-<para>\r
-Increment a date by some number of years. If the date is February 29,\r
-and the destination year is not a leap year, the date will be changed\r
-to February 28. The date must be valid.\r
+<para>
+Increments a date by some number of years. If the date is February 29,
+and the destination year is not a leap year, the date will be changed
+to February 28. The date must be valid.
</para>
-@date: Date to increment
-@n_years: Number of years to move forward
+@date: a #GDate to increment.
+@n_years: number of years to move forward.
<!-- ##### FUNCTION g_date_subtract_years ##### -->
-<para>\r
-Move a date some number of years into the past. If the current day\r
-doesn't exist in the destination year (i.e. it's February 29 and you\r
-move to a non-leap-year) then the day is changed to February 29. Date\r
-must be valid.\r
+<para>
+Moves a date some number of years into the past. If the current day
+doesn't exist in the destination year (i.e. it's February 29 and you
+move to a non-leap-year) then the day is changed to February 29. The date
+must be valid.
</para>
-@date: Date to decrement
-@n_years: Number of years to move
+@date: a #GDate to decrement.
+@n_years: number of years to move.
<!-- ##### FUNCTION g_date_days_between ##### -->
<para>
-Compute the number of days between two dates.
+Computes the number of days between two dates.
If @date2 is prior to @date1, the returned value is negative.
Both dates must be valid.
</para>
-@date1: The first date
-@date2: The second date
-@Returns: The number of days between @date1 and @date2
+@date1: the first date.
+@date2: the second date.
+@Returns: the number of days between @date1 and @date2.
<!-- ##### FUNCTION g_date_compare ##### -->
-<para>\r
-<function>qsort()</function>-style comparsion function for dates. Both\r
-dates must be valid.\r
+<para>
+<function>qsort()</function>-style comparsion function for dates. Both
+dates must be valid.
</para>
-@lhs: First date to compare
-@rhs: Second date to compare
-@Returns: 0 for equal, less than zero if @lhs is less than @rhs,\r
-greater than zero if @lhs is greater than @rhs
+@lhs: first date to compare.
+@rhs: second date to compare.
+@Returns: 0 for equal, less than zero if @lhs is less than @rhs,
+greater than zero if @lhs is greater than @rhs.
<!-- ##### FUNCTION g_date_clamp ##### -->
<para>
-If @date is prior to @min_date, set @date equal to @min_date.
-If @date falls after @max_date, set @date equal to @max_date.
+If @date is prior to @min_date, sets @date equal to @min_date.
+If @date falls after @max_date, sets @date equal to @max_date.
Either @min_date and @max_date may be %NULL. All non-%NULL dates
must be valid.
</para>
-@date: Date to clamp
-@min_date: Minimum accepted value for @date
-@max_date: Maximum accepted value for @date
+@date: a #GDate to clamp.
+@min_date: minimum accepted value for @date.
+@max_date: maximum accepted value for @date.
<!-- ##### FUNCTION g_date_order ##### -->
<para>
-Check if @date1 is less than or equal to @date2,
+Checks if @date1 is less than or equal to @date2,
and swap the values if this is not the case.
</para>
-@date1: The first date
-@date2: The second date
+@date1: the first date.
+@date2: the second date.
<!-- ##### FUNCTION g_date_get_day ##### -->
-<para>\r
-Return the day of the month; the #GDate must be valid.\r
+<para>
+Returns the day of the month. The date must be valid.
</para>
-@date: Date to extract the day of the month from
-@Returns: Day of the month
+@date: a #GDate to extract the day of the month from.
+@Returns: day of the month.
<!-- ##### FUNCTION g_date_get_month ##### -->
-<para>\r
-Accessor for the month of the year. Date must be valid.\r
+<para>
+Returns the month of the year. The date must be valid.
</para>
-@date: Date to get the month from
-@Returns: A #GDateMonth
+@date: a #GDate to get the month from.
+@Returns: month of the year as a #GDateMonth.
<!-- ##### FUNCTION g_date_get_year ##### -->
-<para>\r
-Accessor; returns the year of a #GDate. The date must be valid.\r
+<para>
+Returns the year of a #GDate. The date must be valid.
</para>
-@date: Date
-@Returns: Year in which the date falls
+@date: a #GDate.
+@Returns: year in which the date falls.
<!-- ##### FUNCTION g_date_get_julian ##### -->
-<para>\r
-Accessor, returns the Julian day or "serial number" of the #GDate. The\r
-Julian day is simply the number of days since January 1, Year 1; i.e.,\r
-January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,\r
-etc. Date must be valid.\r
+<para>
+Returns the Julian day or "serial number" of the #GDate. The
+Julian day is simply the number of days since January 1, Year 1; i.e.,
+January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
+etc. The date must be valid.
</para>
-@date: Date to extract the Julian day from
-@Returns: Julian day
+@date: a #GDate to extract the Julian day from.
+@Returns: Julian day.
<!-- ##### FUNCTION g_date_get_weekday ##### -->
-<para>\r
-Returns the day of the week for a #GDate. The date must be valid.\r
+<para>
+Returns the day of the week for a #GDate. The date must be valid.
</para>
-@date: Date
-@Returns: Day of the week as a #GDateWeekday
+@date: a #GDate.
+@Returns: day of the week as a #GDateWeekday.
<!-- ##### FUNCTION g_date_get_day_of_year ##### -->
-<para>\r
-Return the day of the year, where Jan 1 is the first day of the\r
-year. Date must be valid.\r
+<para>
+Returns the day of the year, where Jan 1 is the first day of the
+year. The date must be valid.
</para>
-@date: Date to extract day of year from
-@Returns: Day of the year
+@date: a #GDate to extract day of year from.
+@Returns: day of the year.
<!-- ##### FUNCTION g_date_get_days_in_month ##### -->
-<para>\r
-Return the number of days in a month, taking leap years into account.\r
+<para>
+Returns the number of days in a month, taking leap years into account.
</para>
-@month: Month
-@year: Year
-@Returns: Number of days in @month during the year @year.
+@month: month.
+@year: year.
+@Returns: number of days in @month during the @year.
<!-- ##### FUNCTION g_date_is_first_of_month ##### -->
-<para>\r
-Returns TRUE if the date is on the first of a month. Date must be valid.\r
+<para>
+Returns %TRUE if the date is on the first of a month. The date must be valid.
</para>
-@date: Date to check
-@Returns: Boolean, if the date is the first of the month
+@date: a #GDate to check.
+@Returns: %TRUE if the date is the first of the month.
<!-- ##### FUNCTION g_date_is_last_of_month ##### -->
-<para>\r
-Returns TRUE if the date is the last day of the month. Date must be valid.\r
+<para>
+Returns %TRUE if the date is the last day of the month. The date must be valid.
</para>
-@date: Date to check
-@Returns: Boolean, if the date is the last day of the month
+@date: a #GDate to check.
+@Returns: %TRUE if the date is the last day of the month.
+
<!-- ##### FUNCTION g_date_is_leap_year ##### -->
-<para>\r
-Returns TRUE if the year is a leap year\r
+<para>
+Returns %TRUE if the year is a leap year.
</para>
-@year: Year to check
-@Returns: Boolean, if the year is a leap year
+@year: year to check.
+@Returns: %TRUE if the year is a leap year.
<!-- ##### FUNCTION g_date_get_monday_week_of_year ##### -->
-<para>\r
-Return the week of the year, where weeks are understood to start on\r
-Monday. If the date is before the first Monday of the year, return\r
-0. Date must be valid.\r
+<para>
+Returns the week of the year, where weeks are understood to start on
+Monday. If the date is before the first Monday of the year, return
+0. The date must be valid.
</para>
-@date: Date to use
-@Returns: Week of the year
+@date: a #GDate.
+@Returns: week of the year.
<!-- ##### FUNCTION g_date_get_monday_weeks_in_year ##### -->
-<para>\r
-Return the number of weeks in the year, where weeks are taken to start\r
-on Monday. Will be 52 or 53. Date must be valid. (Years always have 52\r
-7-day periods, plus 1 or 2 extra days depending on whether it's a leap\r
-year. This function is basically telling you how many Mondays are in\r
-the year, i.e. there are 53 Mondays if one of the extra days happens\r
-to be a Monday.)\r
+<para>
+Returns the number of weeks in the year, where weeks are taken to start
+on Monday. Will be 52 or 53. The date must be valid. (Years always have 52
+7-day periods, plus 1 or 2 extra days depending on whether it's a leap
+year. This function is basically telling you how many Mondays are in
+the year, i.e. there are 53 Mondays if one of the extra days happens
+to be a Monday.)
</para>
-@year: Year
-@Returns: Number of Mondays in the year
+@year: a year.
+@Returns: number of Mondays in the year.
<!-- ##### FUNCTION g_date_get_sunday_week_of_year ##### -->
-<para>\r
-Week of the year during which this date falls, if weeks are understood\r
-to being on Sunday. Date must be valid. Can return 0 if the day is\r
-before the first Sunday of the year.\r
+<para>
+Returns the week of the year during which this date falls, if weeks
+are understood to being on Sunday. The date must be valid. Can return 0 if
+the day is before the first Sunday of the year.
</para>
-@date: Date
-@Returns: Week number
+@date: a #GDate.
+@Returns: week number.
<!-- ##### FUNCTION g_date_get_sunday_weeks_in_year ##### -->
-<para>\r
-Return the number of weeks in the year, where weeks are taken to start\r
-on Sunday. Will be 52 or 53. Date must be valid. (Years always have 52\r
-7-day periods, plus 1 or 2 extra days depending on whether it's a leap\r
-year. This function is basically telling you how many Sundays are in\r
-the year, i.e. there are 53 Sundays if one of the extra days happens\r
-to be a Sunday.)\r
+<para>
+Returns the number of weeks in the year, where weeks are taken to start
+on Sunday. Will be 52 or 53. The date must be valid. (Years always have 52
+7-day periods, plus 1 or 2 extra days depending on whether it's a leap
+year. This function is basically telling you how many Sundays are in
+the year, i.e. there are 53 Sundays if one of the extra days happens
+to be a Sunday.)
</para>
-@year: Year to count weeks in
-@Returns: Number of weeks
+@year: year to count weeks in.
+@Returns: number of weeks.
<!-- ##### FUNCTION g_date_strftime ##### -->
-<para>\r
-Generate a printed representation of the date, in a locale-specific\r
-way. Works just like the standard C <function>strftime()</function>\r
-function, but only accepts date-related formats; time-related formats\r
-give undefined results. Date must be valid.\r
+<para>
+Generates a printed representation of the date, in a locale-specific
+way. Works just like the standard C <function>strftime()</function>
+function, but only accepts date-related formats; time-related formats
+give undefined results. Date must be valid.
</para>
-@s: Destination buffer
-@slen: Max buffer size
-@format: Format string
-@date: valid #GDate
-@Returns: number of characters written to the buffer, or 0 the buffer was too small
+@s: destination buffer.
+@slen: buffer size.
+@format: format string.
+@date: valid #GDate.
+@Returns: number of characters written to the buffer, or 0 the buffer was too small.
<!-- ##### FUNCTION g_date_to_struct_tm ##### -->
-<para>\r
-Fills in the date-related bits of a <structname>struct tm</structname>\r
-using the @date value. Initializes the non-date parts with something\r
-sane but meaningless.\r
+<para>
+Fills in the date-related bits of a <structname>struct tm</structname>
+using the @date value. Initializes the non-date parts with something
+sane but meaningless.
</para>
-@date: Date to set the <structname>struct tm</structname> from
-@tm: <structname>struct tm</structname> to fill
+@date: a #GDate to set the <structname>struct tm</structname> from.
+@tm: <structname>struct tm</structname> to fill.
<!-- ##### FUNCTION g_date_valid ##### -->
-<para>\r
-Returns TRUE if the #GDate represents an existing day. #GDate must not\r
-contain garbage; it should have been initialized with g_date_clear()\r
-if it wasn't allocated by one of the g_date_new() variants.\r
+<para>
+Returns %TRUE if the #GDate represents an existing day. The date must not
+contain garbage; it should have been initialized with g_date_clear()
+if it wasn't allocated by one of the g_date_new() variants.
</para>
-@date: Date to check
+@date: a #GDate to check.
@Returns: Whether the date is valid.
<!-- ##### FUNCTION g_date_valid_day ##### -->
-<para>\r
-Returns TRUE if the day of the month is valid (a day is valid if it's\r
-between 1 and 31 inclusive).\r
+<para>
+Returns %TRUE if the day of the month is valid (a day is valid if it's
+between 1 and 31 inclusive).
</para>
-@day: Day to check.
-@Returns: Boolean, whether the day is valid.
+@day: day to check.
+@Returns: %TRUE if the day is valid.
<!-- ##### FUNCTION g_date_valid_month ##### -->
-<para>\r
-Returns TRUE if the month value is valid. The 12 #GDateMonth\r
-enumeration values are the only valid months.\r
+<para>
+Returns %TRUE if the month value is valid. The 12 #GDateMonth
+enumeration values are the only valid months.
</para>
-@month: Month
-@Returns: Boolean, whether the month is valid
+@month: month.
+@Returns: %TRUE if the month is valid.
<!-- ##### FUNCTION g_date_valid_year ##### -->
-<para>\r
-Returns TRUE if the year is valid. Any year greater than 0 is valid,\r
-though there is a 16-bit limit to what GDate will understand.\r
+<para>
+Returns %TRUE if the year is valid. Any year greater than 0 is valid,
+though there is a 16-bit limit to what #GDate will understand.
</para>
-@year: Year
-@Returns: Boolean, whether the year is valid.
+@year: year.
+@Returns: %TRUE if the year is valid.
<!-- ##### FUNCTION g_date_valid_dmy ##### -->
-<para>\r
-Returns TRUE if the day/month/year triplet forms a valid, existing day\r
-in the range of days GDate understands (Year 1 or later, no more than\r
-a few thousand years in the future).\r
+<para>
+Returns %TRUE if the day/month/year triplet forms a valid, existing day
+in the range of days #GDate understands (Year 1 or later, no more than
+a few thousand years in the future).
</para>
-@day: Day
-@month: Month
-@year: Year
-@Returns: Boolean, whether the date is a valid one
+@day: day.
+@month: month.
+@year: year.
+@Returns: %TRUE if the date is a valid one.
<!-- ##### FUNCTION g_date_valid_julian ##### -->
-<para>\r
-Returns TRUE if the Julian day is valid. Anything greater than zero is basically a\r
-valid Julian, though there is a 32-bit limit.\r
+<para>
+Returns %TRUE if the Julian day is valid. Anything greater than zero is basically a
+valid Julian, though there is a 32-bit limit.
</para>
-@julian_date: Julian day to check
-@Returns: Boolean, whether the Julian day is valid.
+@julian_date: Julian day to check.
+@Returns: %TRUE if the Julian day is valid.
<!-- ##### FUNCTION g_date_valid_weekday ##### -->
-<para>\r
-Returns TRUE if the weekday is valid. The 7 #GDateWeekday enumeration\r
-values are the only valid weekdays.\r
+<para>
+Returns %TRUE if the weekday is valid. The 7 #GDateWeekday enumeration
+values are the only valid weekdays.
</para>
-@weekday: Weekday
-@Returns: Boolean, whether the weekday is valid.
+@weekday: weekday.
+@Returns: %TRUE if the weekday is valid.
<!-- ##### MACRO g_new ##### -->
<para>
-Allocates @count elements of type @type.
+Allocates @n_structs elements of type @struct_type.
The returned pointer is cast to a pointer to the given type.
-If @count is 0 it returns NULL.
+If @count is 0 it returns %NULL.
</para>
-@struct_type:
-@n_structs:
-@Returns: a pointer to the allocated memory, cast to a pointer to @type.
-<!-- # Unused Parameters # -->
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
+@struct_type: the type of the elements to allocate.
+@n_structs: the number of elements to allocate.
+@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
<!-- ##### MACRO g_new0 ##### -->
<para>
-Allocates @count elements of type @type, initialized to 0's.
+Allocates @n_structs elements of type @struct_type, initialized to 0's.
The returned pointer is cast to a pointer to the given type.
-If @count is 0 it returns NULL.
+If @count is 0 it returns %NULL.
</para>
-@struct_type:
-@n_structs:
-@Returns: a pointer to the allocated memory, cast to a pointer to @type.
-<!-- # Unused Parameters # -->
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
+@struct_type: the type of the elements to allocate.
+@n_structs: the number of elements to allocate.
+@Returns: a pointer to the allocated memory, cast to a pointer to @struct_type.
<!-- ##### MACRO g_renew ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
-@count elements of type @type. It returns the new address of the memory,
-which may have been moved.
+@n_struct elements of type @struct_type. It returns the new address of
+the memory, which may have been moved.
</para>
-@struct_type:
+@struct_type: the type of the elements to allocate.
@mem: the currently allocated memory.
-@n_structs:
-@Returns: a pointer to the new allocated memory, cast to a pointer to @type.
-<!-- # Unused Parameters # -->
-@type: the type of the elements to allocate.
-@count: the number of elements to allocate.
+@n_structs: the number of elements to allocate.
+@Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type.
<!-- ##### FUNCTION g_malloc ##### -->
<para>
-Allocates @size bytes of memory.
-If @size is 0 it returns NULL.
+Allocates @n_bytes bytes of memory.
+If @n_bytes is 0 it returns %NULL.
</para>
-@n_bytes:
+@n_bytes: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.
-<!-- # Unused Parameters # -->
-@size: the number of bytes to allocate.
<!-- ##### FUNCTION g_malloc0 ##### -->
<para>
-Allocates @size bytes of memory, initialized to 0's.
-If @size is 0 it returns NULL.
+Allocates @n_bytes bytes of memory, initialized to 0's.
+If @n_bytes is 0 it returns %NULL.
</para>
-@n_bytes:
+@n_bytes: the number of bytes to allocate.
@Returns: a pointer to the allocated memory.
-<!-- # Unused Parameters # -->
-@size: the number of bytes to allocate.
<!-- ##### FUNCTION g_realloc ##### -->
<para>
Reallocates the memory pointed to by @mem, so that it now has space for
-@size bytes of memory. It returns the new address of the memory, which may
+@n_bytes bytes of memory. It returns the new address of the memory, which may
have been moved. @mem may be %NULL, in which case it's considered to
have zero-length. @n_bytes may be 0, in which case %NULL will be returned.
</para>
@mem: the memory to reallocate.
-@n_bytes: new size of the memory in bytes
+@n_bytes: new size of the memory in bytes.
@Returns: the new address of the allocated memory.
-<!-- # Unused Parameters # -->
-@size: the new size of the allocated memory, in bytes.
<!-- ##### FUNCTION g_try_malloc ##### -->
Contrast with g_malloc(), which aborts the program on failure.
</para>
-@n_bytes: number of bytes to allocate
-@Returns: the allocated memory, or %NULL
+@n_bytes: number of bytes to allocate.
+@Returns: the allocated memory, or %NULL.
<!-- ##### FUNCTION g_try_realloc ##### -->
on failure. If @mem is %NULL, behaves the same as g_try_malloc().
</para>
-@mem: previously-allocated memory, or %NULL
-@n_bytes: number of bytes to allocate
-@Returns: the allocated memory, or %NULL
+@mem: previously-allocated memory, or %NULL.
+@n_bytes: number of bytes to allocate.
+@Returns: the allocated memory, or %NULL.
<!-- ##### FUNCTION g_free ##### -->
<para>
Frees the memory pointed to by @mem.
-If @mem is NULL it simply returns.
+If @mem is %NULL it simply returns.
</para>
@mem: the memory to free.
stack frame is cleaned up.
</para>
-@size: number of bytes to allocate
+@size: number of bytes to allocate.
<!-- ##### MACRO g_memmove ##### -->
The source and destination areas may overlap.
</para>
<para>
-In order to use this function, you must include string.h
+In order to use this function, you must include <filename>string.h</filename>
yourself, because this macro will typically simply resolve
-to memmove() and GLib does not include string.h for you.
+to <function>memmove()</function> and GLib does not include <filename>string.h</filename> for you.
</para>
@d: the destination address to copy the bytes to.
<!-- ##### FUNCTION g_memdup ##### -->
<para>
Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
-from @mem. If @mem is NULL it returns NULL.
+from @mem. If @mem is %NULL it returns %NULL.
</para>
@mem: the memory to copy.
@byte_size: the number of bytes to copy.
-@Returns: a pointer to the newly allocated copy of the memory, or NULL if @mem
-is NULL.
+@Returns: a pointer to the newly allocated copy of the memory, or %NULL if @mem
+is %NULL.
<!-- ##### STRUCT GMemVTable ##### -->
<para>
-A set of functions used to perform memory allocation. The same GMemVTable must
+A set of functions used to perform memory allocation. The same #GMemVTable must
be used for all allocations in the same program; a call to g_mem_set_vtable(),
if it exists, should be prior to any use of GLib.
</para>
-@malloc: function to use for allocating memory
-@realloc: function to use for reallocating memory
-@free: function to use to free memory
-@calloc: function to use for allocating zero-filled memory
-@try_malloc: function to use for allocating memory without a default error handler
-@try_realloc: function to use for reallocating memory without a default error handler
+@malloc: function to use for allocating memory.
+@realloc: function to use for reallocating memory.
+@free: function to use to free memory.
+@calloc: function to use for allocating zero-filled memory.
+@try_malloc: function to use for allocating memory without a default error handler.
+@try_realloc: function to use for reallocating memory without a default error handler.
<!-- ##### FUNCTION g_mem_set_vtable ##### -->
<para>
Sets the #GMemVTable to use for memory allocation. You can use this to provide
custom memory allocation routines. THIS FUNCTION MUST BE CALLED BEFORE USING ANY
-OTHER GLIB FUNCTIONS. The vtable only needs to provide malloc, realloc, and free
-functions; GLib can provide default implementations of the others. The malloc
-and realloc implementations should return %NULL on failure, GLib will handle
+OTHER GLIB FUNCTIONS. The @vtable only needs to provide <function>malloc()</function>, <function>realloc()</function>, and <function>free()</function>
+functions; GLib can provide default implementations of the others. The <function>malloc()</function>
+and <function>realloc()</function> implementations should return %NULL on failure, GLib will handle
error-checking for you. @vtable is copied, so need not persist after this
function has been called.
</para>
<!-- ##### VARIABLE glib_mem_profiler_table ##### -->
<para>
-
+A #GMemVTable containing profiling variants of the memory
+allocation functions. Use them together with g_mem_profile()
+in order to get information about the memory allocation pattern
+of your program.
</para>
<!-- ##### FUNCTION g_mem_profile ##### -->
<para>
Outputs a summary of memory usage.
-To use this function you must configure glib with the flag
-'--enable-mem-profile=yes' before compiling.
</para>
<para>
It outputs the frequency of allocations of different sizes,
and the difference between the previous two values, i.e. the number of bytes
still in use.
</para>
-
+<para>
+Note that this function will not output anything unless you have
+previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
+</para>
projects / platform / upstream / glib.git / commitdiff