@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/date.d.ts

@@ -1,68 +1,461 @@
 import { DateWeekday } from "./enums.js";
+/**
+ * `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
+ * 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
+ * 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 day.
+ *
+ * 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).
+ *
+ * `GDate` is simple to use. First you need a "blank" date; you can get a
+ * dynamically allocated date from [ctor@GLib.Date.new], or you can declare an
+ * automatic variable or array and initialize it by calling [method@GLib.Date.clear].
+ * A cleared date is safe; it's safe to call [method@GLib.Date.set_dmy] and the other
+ * mutator functions to initialize the value of a cleared date. However, a cleared date
+ * is initially 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.
+ * If you obtain a date from a user or other unpredictable source, you should check
+ * its validity with the [method@GLib.Date.valid] predicate. [method@GLib.Date.valid]
+ * is also used to check for errors with [method@GLib.Date.set_parse] and other functions
+ * that can fail. Dates can be invalidated by calling [method@GLib.Date.clear] again.
+ *
+ * It is very important to use the API to access the `GDate` struct. Often only the
+ * day-month-year or only the Julian representation is valid. Sometimes neither is valid.
+ * Use the API.
+ *
+ * GLib also features `GDateTime` which represents a precise time.
+ */
 export declare class Date {
     ptr: unknown;
+    /**
+     * Allocates a #GDate and initializes
+     * it to a safe 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().
+     */
     constructor();
+    /**
+     * Create a new #GDate representing the given day-month-year triplet.
+     *
+     * The triplet you pass in must represent a valid date. Use g_date_valid_dmy()
+     * if needed to validate it. The returned #GDate is guaranteed to be non-%NULL
+     * and valid.
+     * @param day - day of the month
+     * @param month - month of the year
+     * @param year - year
+     */
     static newDmy(day: number, month: number, year: number): Date;
+    /**
+     * Create a new #GDate representing the given Julian date.
+     *
+     * The `julian_day` you pass in must be valid. Use g_date_valid_julian() if
+     * needed to validate it. The returned #GDate is guaranteed to be non-%NULL and
+     * valid.
+     * @param julianDay - days since January 1, Year 1
+     */
     static newJulian(julianDay: number): Date;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Returns the number of days in a month, taking leap
+     * years into account.
+     * @param month - month
+     * @param year - year
+     */
     static getDaysInMonth(month: number, year: number): number;
+    /**
+     * 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.)
+     * @param year - a year
+     */
     static getMondayWeeksInYear(year: number): number;
+    /**
+     * 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.)
+     * @param year - year to count weeks in
+     */
     static getSundayWeeksInYear(year: number): number;
+    /**
+     * Calculates the number of weeks in the year.
+     *
+     * The result depends on which day is considered the first day of the week,
+     * which varies by locale. `first_day_of_week` must be valid.
+     *
+     * The result will be either 52 or 53. Years always have 52 seven-day periods,
+     * plus one or two extra days depending on whether it’s a leap year. This
+     * function effectively calculates how many `first_day_of_week` days there are in
+     * the year.
+     * @param year - year to count weeks in
+     * @param firstDayOfWeek - the day which is considered the first day of the week
+     */
     static getWeeksInYear(year: number, firstDayOfWeek: DateWeekday): number;
+    /**
+     * Returns %TRUE if the year is a leap year.
+     *
+     * For the purposes of this function, leap year is every year
+     * divisible by 4 unless that year is divisible by 100. If it
+     * is divisible by 100 it would be a leap year only if that year
+     * is also divisible by 400.
+     * @param year - year to check
+     */
     static isLeapYear(year: number): boolean;
+    /**
+     * Generates a printed representation of the date, in a
+     * locale-specific way.
+     * Works just like the platform's C library strftime() function,
+     * but only accepts date-related formats; time-related formats
+     * give undefined results. Date must be valid. Unlike strftime()
+     * (which uses the locale encoding), works on a UTF-8 format
+     * string and stores a UTF-8 result.
+     *
+     * This function does not provide any conversion specifiers in
+     * addition to those implemented by the platform's C library.
+     * For example, don't expect that using g_date_strftime() would
+     * make the \%F provided by the C99 strftime() work on Windows
+     * where the C library only complies to C89.
+     * @param s - destination buffer
+     * @param slen - buffer size
+     * @param format - format string
+     * @param date - valid #GDate
+     */
     static strftime(s: string, slen: number, format: string, date: Date): number;
+    /**
+     * Returns %TRUE if the day of the month is valid (a day is valid if it's
+     * between 1 and 31 inclusive).
+     * @param day - day to check
+     */
     static validDay(day: number): boolean;
+    /**
+     * 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).
+     * @param day - day
+     * @param month - month
+     * @param year - year
+     */
     static validDmy(day: number, month: number, year: number): boolean;
+    /**
+     * Returns %TRUE if the Julian day is valid. Anything greater than zero
+     * is basically a valid Julian, though there is a 32-bit limit.
+     * @param julianDate - Julian day to check
+     */
     static validJulian(julianDate: number): boolean;
+    /**
+     * Returns %TRUE if the month value is valid. The 12 #GDateMonth
+     * enumeration values are the only valid months.
+     * @param month - month
+     */
     static validMonth(month: number): boolean;
+    /**
+     * Returns %TRUE if the weekday is valid. The seven #GDateWeekday enumeration
+     * values are the only valid weekdays.
+     * @param weekday - weekday
+     */
     static validWeekday(weekday: DateWeekday): boolean;
+    /**
+     * 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.
+     * @param year - year
+     */
     static validYear(year: number): boolean;
+    /**
+     * Increments a date some number of days.
+     * To move forward by weeks, add weeks*7 days.
+     * The date must be valid.
+     * @param nDays - number of days to move the date forward
+     */
     addDays(nDays: number): void;
+    /**
+     * 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.
+     * @param nMonths - number of months to move forward
+     */
     addMonths(nMonths: number): void;
+    /**
+     * 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.
+     * @param nYears - number of years to move forward
+     */
     addYears(nYears: number): void;
+    /**
+     * 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.
+     * Otherwise, `date` is unchanged.
+     * Either of `min_date` and `max_date` may be %NULL.
+     * All non-%NULL dates must be valid.
+     * @param minDate - minimum accepted value for @date
+     * @param maxDate - maximum accepted value for @date
+     */
     clamp(minDate: Date, maxDate: Date): void;
+    /**
+     * Initializes one or more #GDate structs to a safe 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().
+     * @param nDates - number of dates to clear
+     */
     clear(nDates: number): void;
+    /**
+     * qsort()-style comparison function for dates.
+     * Both dates must be valid.
+     * @param rhs - second date to compare
+     */
     compare(rhs: Date): number;
+    /**
+     * Copies a GDate to a newly-allocated GDate. If the input was invalid
+     * (as determined by g_date_valid()), the invalid state will be copied
+     * as is into the new object.
+     */
     copy(): Date;
+    /**
+     * Computes the number of days between two dates.
+     * If `date2` is prior to @date1, the returned value is negative.
+     * Both dates must be valid.
+     * @param date2 - the second date
+     */
     daysBetween(date2: Date): number;
+    /**
+     * Frees a #GDate returned from g_date_new().
+     */
     free(): void;
+    /**
+     * Returns the day of the month. The date must be valid.
+     */
     getDay(): number;
+    /**
+     * Returns the day of the year, where Jan 1 is the first day of the
+     * year. The date must be valid.
+     */
     getDayOfYear(): number;
+    /**
+     * Returns the week of the year, where weeks are interpreted according
+     * to ISO 8601.
+     */
     getIso8601WeekOfYear(): number;
+    /**
+     * 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.
+     */
     getJulian(): number;
+    /**
+     * 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.
+     */
     getMondayWeekOfYear(): number;
+    /**
+     * Returns the month of the year. The date must be valid.
+     */
     getMonth(): number;
+    /**
+     * Returns the week of the year during which this date falls, if
+     * weeks are understood to begin on Sunday. The date must be valid.
+     * Can return 0 if the day is before the first Sunday of the year.
+     */
     getSundayWeekOfYear(): number;
+    /**
+     * Calculates the week of the year during which this date falls.
+     *
+     * The result depends on which day is considered the first day of the week,
+     * which varies by locale. Both `date` and `first_day_of_week` must be valid.
+     *
+     * If `date` is before the start of the first week of the year (for example,
+     * before the first Monday in January if `first_day_of_week` is
+     * [enum@GLib.DateWeekday.MONDAY]) then zero will be returned.
+     * @param firstDayOfWeek - the day which is considered the first day of the week
+     */
     getWeekOfYear(firstDayOfWeek: DateWeekday): number;
+    /**
+     * Returns the day of the week for a #GDate. The date must be valid.
+     */
     getWeekday(): DateWeekday;
+    /**
+     * Returns the year of a #GDate. The date must be valid.
+     */
     getYear(): number;
+    /**
+     * Returns %TRUE if the date is on the first of a month.
+     * The date must be valid.
+     */
     isFirstOfMonth(): boolean;
+    /**
+     * Returns %TRUE if the date is the last day of the month.
+     * The date must be valid.
+     */
     isLastOfMonth(): boolean;
+    /**
+     * Checks if `date1` is less than or equal to @date2,
+     * and swap the values if this is not the case.
+     * @param date2 - the second date
+     */
     order(date2: Date): void;
+    /**
+     * Sets the day of the month for a #GDate. If the resulting
+     * day-month-year triplet is invalid, the date will be invalid.
+     * @param day - day to set
+     */
     setDay(day: number): void;
+    /**
+     * 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.
+     * @param day - day
+     * @param month - month
+     * @param y - year
+     */
     setDmy(day: number, month: number, y: number): void;
+    /**
+     * Sets the value of a #GDate from a Julian day number.
+     * @param julianDate - Julian day number (days since January 1, Year 1)
+     */
     setJulian(julianDate: number): void;
+    /**
+     * Sets the month of the year for a #GDate.  If the resulting
+     * day-month-year triplet is invalid, the date will be invalid.
+     * @param month - month to set
+     */
     setMonth(month: number): void;
+    /**
+     * 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.
+     *
+     * 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).
+     * @param str - string to parse
+     */
     setParse(str: string): void;
+    /**
+     * Sets the value of a date from a #GTime value.
+     * The time to date conversion is done using the user's current timezone.
+     * @param time_ - #GTime value to set.
+     */
     setTime(time_: number): void;
+    /**
+     * Sets the value of a date to the date corresponding to a time
+     * specified as a time_t. The time to date conversion is done using
+     * the user's current timezone.
+     *
+     * To set the value of a date to the current day, you could write:
+     * |[<!-- language="C" -->
+     * time_t now = time (NULL);
+     * if (now == (time_t) -1)
+     * // handle the error
+     * g_date_set_time_t (date, now);
+     * ]|
+     * @param timet - time_t value to set
+     */
     setTimeT(timet: number): void;
+    /**
+     * Sets the value of a date from a #GTimeVal value.  Note that the
+     * `tv_usec` member is ignored, because #GDate can't make use of the
+     * additional precision.
+     *
+     * The time to date conversion is done using the user's current timezone.
+     * @param timeval - #GTimeVal value to set
+     */
     setTimeVal(timeval: number): void;
+    /**
+     * Sets the year for a #GDate. If the resulting day-month-year
+     * triplet is invalid, the date will be invalid.
+     * @param year - year to set
+     */
     setYear(year: number): void;
+    /**
+     * 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.
+     * @param nDays - number of days to move
+     */
     subtractDays(nDays: number): void;
+    /**
+     * 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.
+     * @param nMonths - number of months to move
+     */
     subtractMonths(nMonths: number): void;
+    /**
+     * 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.
+     * @param nYears - number of years to move
+     */
     subtractYears(nYears: number): void;
+    /**
+     * Fills in the date-related bits of a struct tm using the `date` value.
+     * Initializes the non-date parts with something safe but meaningless.
+     * @param tm - struct tm to fill
+     */
     toStructTm(tm: number): void;
+    /**
+     * 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.
+     */
     valid(): boolean;
+    /** the Julian representation of the date */
     get julianDays(): number;
     set julianDays(value: number);
+    /** this bit is set if `julian_days` is valid */
     get julian(): number;
     set julian(value: number);
+    /** this is set if @day, `month` and `year` are valid */
     get dmy(): number;
     set dmy(value: number);
+    /**
+     * the day of the day-month-year representation of the date,
+     * as a number between 1 and 31
+     */
     get day(): number;
     set day(value: number);
+    /**
+     * the month of the day-month-year representation of the date,
+     * as a number between 1 and 12
+     */
     get month(): number;
     set month(value: number);
+    /** the year of the day-month-year representation of the date */
     get year(): number;
     set year(value: number);
 }