@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/time-zone.js

@@ -1,11 +1,107 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * A `GTimeZone` represents a time zone, at no particular point in time.
+ *
+ * The `GTimeZone` struct is refcounted and immutable.
+ *
+ * Each time zone has an identifier (for example, ‘Europe/London’) which is
+ * platform dependent. See [ctor@GLib.TimeZone.new] for information on the
+ * identifier formats. The identifier of a time zone can be retrieved using
+ * [method@GLib.TimeZone.get_identifier].
+ *
+ * A time zone contains a number of intervals. Each interval has an abbreviation
+ * to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating
+ * if the daylight savings time is in effect during that interval. A time zone
+ * always has at least one interval — interval 0. Note that interval abbreviations
+ * are not the same as time zone identifiers (apart from ‘UTC’), and cannot be
+ * passed to [ctor@GLib.TimeZone.new].
+ *
+ * Every UTC time is contained within exactly one interval, but a given
+ * local time may be contained within zero, one or two intervals (due to
+ * incontinuities associated with daylight savings time).
+ *
+ * An interval may refer to a specific period of time (eg: the duration
+ * of daylight savings time during 2010) or it may refer to many periods
+ * of time that share the same properties (eg: all periods of daylight
+ * savings time).  It is also possible (usually for political reasons)
+ * that some properties (like the abbreviation) change between intervals
+ * without other properties changing.
+ */
 export class TimeZone {
     ptr;
     constructor(...args) {
         const _args = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * Creates a #GTimeZone corresponding to @identifier. If `identifier` cannot be
+     * parsed or loaded, %NULL is returned.
+     *
+     * `identifier` can either be an RFC3339/ISO 8601 time offset or
+     * something that would pass as a valid value for the `TZ` environment
+     * variable (including %NULL).
+     *
+     * In Windows, `identifier` can also be the unlocalized name of a time
+     * zone for standard time, for example "Pacific Standard Time".
+     *
+     * Valid RFC3339 time offsets are `"Z"` (for UTC) or
+     * `"±hh:mm"`.  ISO 8601 additionally specifies
+     * `"±hhmm"` and `"±hh"`.  Offsets are
+     * time values to be added to Coordinated Universal Time (UTC) to get
+     * the local time.
+     *
+     * In UNIX, the `TZ` environment variable typically corresponds
+     * to the name of a file in the zoneinfo database, an absolute path to a file
+     * somewhere else, or a string in
+     * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
+     * There  are  no spaces in the specification. The name of standard
+     * and daylight savings time zone must be three or more alphabetic
+     * characters. Offsets are time values to be added to local time to
+     * get Coordinated Universal Time (UTC) and should be
+     * `"[±]hh[[:]mm[:ss]]"`.  Dates are either
+     * `"Jn"` (Julian day with n between 1 and 365, leap
+     * years not counted), `"n"` (zero-based Julian day
+     * with n between 0 and 365) or `"Mm.w.d"` (day d
+     * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
+     * 0 is a Sunday).  Times are in local wall clock time, the default is
+     * 02:00:00.
+     *
+     * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also
+     * accepts POSIX format.  The Windows format uses US rules for all time
+     * zones; daylight savings time is 60 minutes behind the standard time
+     * with date and time of change taken from Pacific Standard Time.
+     * Offsets are time values to be added to the local time to get
+     * Coordinated Universal Time (UTC).
+     *
+     * g_time_zone_new_local() calls this function with the value of the
+     * `TZ` environment variable. This function itself is independent of
+     * the value of `TZ`, but if `identifier` is %NULL then `/etc/localtime`
+     * will be consulted to discover the correct time zone on UNIX and the
+     * registry will be consulted or GetTimeZoneInformation() will be used
+     * to get the local time zone on Windows.
+     *
+     * If intervals are not available, only time zone rules from `TZ`
+     * environment variable or other means, then they will be computed
+     * from year 1900 to 2037.  If the maximum year for the rules is
+     * available and it is greater than 2037, then it will followed
+     * instead.
+     *
+     * See
+     * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
+     * for a precise definition of valid RFC3339 time offsets
+     * (the `time-offset` expansion) and ISO 8601 for the
+     * full list of valid time offsets.  See
+     * The GNU C Library manual
+     * for an explanation of the possible
+     * values of the `TZ` environment variable. See
+     * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
+     * for the list of time zones on Windows.
+     *
+     * You should release the return value by calling g_time_zone_unref()
+     * when you are done with it.
+     * @param identifier - a timezone identifier
+     */
     static zoneNewIdentifier(identifier) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_new_identifier", [
             {
@@ -16,10 +112,34 @@ export class TimeZone {
         ], { type: "boxed", borrowed: true, innerType: "TimeZone" });
         return getObject(ptr, TimeZone);
     }
+    /**
+     * Creates a #GTimeZone corresponding to local time.  The local time
+     * zone may change between invocations to this function; for example,
+     * if the system administrator changes it.
+     *
+     * This is equivalent to calling g_time_zone_new() with the value of
+     * the `TZ` environment variable (including the possibility of %NULL).
+     *
+     * You should release the return value by calling g_time_zone_unref()
+     * when you are done with it.
+     */
     static zoneNewLocal() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_new_local", [], { type: "boxed", borrowed: true, innerType: "TimeZone" });
         return getObject(ptr, TimeZone);
     }
+    /**
+     * Creates a #GTimeZone corresponding to the given constant offset from UTC,
+     * in seconds.
+     *
+     * This is equivalent to calling g_time_zone_new() with a string in the form
+     * `[+|-]hh[:mm[:ss]]`.
+     *
+     * It is possible for this function to fail if `seconds` is too big (greater than
+     * 24 hours), in which case this function will return the UTC timezone for
+     * backwards compatibility. To detect failures like this, use
+     * g_time_zone_new_identifier() directly.
+     * @param seconds - offset to UTC, in seconds
+     */
     static zoneNewOffset(seconds) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_new_offset", [
             {
@@ -29,6 +149,15 @@ export class TimeZone {
         ], { type: "boxed", borrowed: true, innerType: "TimeZone" });
         return getObject(ptr, TimeZone);
     }
+    /**
+     * Creates a #GTimeZone corresponding to UTC.
+     *
+     * This is equivalent to calling g_time_zone_new() with a value like
+     * "Z", "UTC", "+00", etc.
+     *
+     * You should release the return value by calling g_time_zone_unref()
+     * when you are done with it.
+     */
     static zoneNewUtc() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_new_utc", [], { type: "boxed", borrowed: true, innerType: "TimeZone" });
         return getObject(ptr, TimeZone);
@@ -43,6 +172,26 @@ export class TimeZone {
             },
         ], { type: "boxed", borrowed: true, innerType: "GTimeZone" });
     }
+    /**
+     * Finds an interval within `tz` that corresponds to the given @time_,
+     * possibly adjusting `time_` if required to fit into an interval.
+     * The meaning of `time_` depends on @type.
+     *
+     * This function is similar to g_time_zone_find_interval(), with the
+     * difference that it always succeeds (by making the adjustments
+     * described below).
+     *
+     * In any of the cases where g_time_zone_find_interval() succeeds then
+     * this function returns the same value, without modifying @time_.
+     *
+     * This function may, however, modify `time_` in order to deal with
+     * non-existent times.  If the non-existent local `time_` of 02:30 were
+     * requested on March 14th 2010 in Toronto then this function would
+     * adjust `time_` to be 03:00 and return the interval containing the
+     * adjusted time.
+     * @param type - the #GTimeType of @time_
+     * @param time_ - a pointer to a number of seconds since January 1, 1970
+     */
     adjustTime(type, time_) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_adjust_time", [
             {
@@ -62,6 +211,28 @@ export class TimeZone {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Finds an interval within `tz` that corresponds to the given @time_.
+     * The meaning of `time_` depends on @type.
+     *
+     * If `type` is %G_TIME_TYPE_UNIVERSAL then this function will always
+     * succeed (since universal time is monotonic and continuous).
+     *
+     * Otherwise `time_` is treated as local time.  The distinction between
+     * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
+     * the case that the given `time_` is ambiguous.  In Toronto, for example,
+     * 01:30 on November 7th 2010 occurred twice (once inside of daylight
+     * savings time and the next, an hour later, outside of daylight savings
+     * time).  In this case, the different value of `type` would result in a
+     * different interval being returned.
+     *
+     * It is still possible for this function to fail.  In Toronto, for
+     * example, 02:00 on March 14th 2010 does not exist (due to the leap
+     * forward to begin daylight savings time).  -1 is returned in that
+     * case.
+     * @param type - the #GTimeType of @time_
+     * @param time_ - a number of seconds since January 1, 1970
+     */
     findInterval(type, time_) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_find_interval", [
             {
@@ -78,6 +249,15 @@ export class TimeZone {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Determines the time zone abbreviation to be used during a particular
+     * `interval` of time in the time zone @tz.
+     *
+     * For example, in Toronto this is currently "EST" during the winter
+     * months and "EDT" during the summer months when daylight savings time
+     * is in effect.
+     * @param interval - an interval within the timezone
+     */
     getAbbreviation(interval) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_get_abbreviation", [
             {
@@ -90,6 +270,16 @@ export class TimeZone {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Get the identifier of this #GTimeZone, as passed to g_time_zone_new().
+     * If the identifier passed at construction time was not recognised, `UTC` will
+     * be returned. If it was %NULL, the identifier of the local timezone at
+     * construction time will be returned.
+     *
+     * The identifier will be returned in the same format as provided at
+     * construction time: if provided as a time offset, that will be returned by
+     * this function.
+     */
     getIdentifier() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_get_identifier", [
             {
@@ -98,6 +288,14 @@ export class TimeZone {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Determines the offset to UTC in effect during a particular `interval` of time in the time zone @tz.
+     *
+     * The offset is the number of seconds that you add to UTC time to
+     * arrive at local time for `tz` (ie: negative numbers for time zones
+     * west of GMT, positive numbers for east).
+     * @param interval - an interval within the timezone
+     */
     getOffset(interval) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_get_offset", [
             {
@@ -110,6 +308,11 @@ export class TimeZone {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Determines if daylight savings time is in effect during a particular
+     * `interval` of time in the time zone @tz.
+     * @param interval - an interval within the timezone
+     */
     isDst(interval) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_is_dst", [
             {
@@ -122,6 +325,9 @@ export class TimeZone {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Increases the reference count on @tz.
+     */
     ref() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_ref", [
             {
@@ -136,6 +342,9 @@ export class TimeZone {
         });
         return getObject(ptr, TimeZone);
     }
+    /**
+     * Decreases the reference count on @tz.
+     */
     unref() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_time_zone_unref", [
             {

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

@@ -1,32 +1,248 @@
 import { Ref } from "@gtkx/native";
 import { TraverseType } from "./enums.js";
+/**
+ * The GTree struct is an opaque data structure representing a
+ * balanced binary tree. It should be
+ * accessed only by using the following functions.
+ */
 export declare class Tree {
     ptr: unknown;
+    /**
+     * Creates a new #GTree like g_tree_new() and allows to specify functions
+     * to free the memory allocated for the key and value that get called when
+     * removing the entry from the #GTree.
+     * @param keyCompareFunc - qsort()-style comparison function
+     * @param keyCompareData - data to pass to comparison function
+     * @param keyDestroyFunc - a function to free the memory allocated for the key
+     * @param valueDestroyFunc - a function to free the memory allocated for the
+     */
     constructor(keyCompareFunc: (...args: unknown[]) => unknown, keyDestroyFunc: (...args: unknown[]) => unknown, valueDestroyFunc: (...args: unknown[]) => unknown, keyCompareData?: number | null);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Removes all keys and values from the #GTree and decreases its
+     * reference count by one. If keys and/or values are dynamically
+     * allocated, you should either free them first or create the #GTree
+     * using g_tree_new_full(). In the latter case the destroy functions
+     * you supplied will be called on all keys and values before destroying
+     * the #GTree.
+     */
     destroy(): void;
+    /**
+     * Calls the given function for each of the key/value pairs in the #GTree.
+     * The function is passed the key and value of each pair, and the given
+     * `data` parameter. The tree is traversed in sorted order.
+     *
+     * The tree may not be modified while iterating over it (you can't
+     * add/remove items). To remove all items matching a predicate, you need
+     * to add each item to a list in your #GTraverseFunc as you walk over
+     * the tree, then walk the list and remove each item.
+     * @param func - the function to call for each node visited.
+     * @param userData - user data to pass to the function
+     */
     foreach(func: (...args: unknown[]) => unknown, userData?: number | null): void;
+    /**
+     * Calls the given function for each of the nodes in the #GTree.
+     * The function is passed the pointer to the particular node, and the given
+     * `data` parameter. The tree traversal happens in-order.
+     *
+     * The tree may not be modified while iterating over it (you can't
+     * add/remove items). To remove all items matching a predicate, you need
+     * to add each item to a list in your #GTraverseFunc as you walk over
+     * the tree, then walk the list and remove each item.
+     * @param func - the function to call for each node visited.
+     * @param userData - user data to pass to the function
+     */
     foreachNode(func: (...args: unknown[]) => unknown, userData?: number | null): void;
+    /**
+     * Gets the height of a #GTree.
+     *
+     * If the #GTree contains no nodes, the height is 0.
+     * If the #GTree contains only one root node the height is 1.
+     * If the root node has children the height is 2, etc.
+     */
     height(): number;
+    /**
+     * Inserts a key/value pair into a #GTree.
+     *
+     * Inserts a new key and value into a #GTree as g_tree_insert_node() does,
+     * only this function does not return the inserted or set node.
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     insert(key?: number | null, value?: number | null): void;
+    /**
+     * Inserts a key/value pair into a #GTree.
+     *
+     * If the given key already exists in the #GTree its corresponding value
+     * is set to the new value. If you supplied a `value_destroy_func` when
+     * creating the #GTree, the old value is freed using that function. If
+     * you supplied a `key_destroy_func` when creating the #GTree, the passed
+     * key is freed using that function.
+     *
+     * The tree is automatically 'balanced' as new key/value pairs are added,
+     * so that the distance from the root to every leaf is as small as possible.
+     * The cost of maintaining a balanced tree while inserting new key/value
+     * result in a O(n log(n)) operation where most of the other operations
+     * are O(log(n)).
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     insertNode(key?: number | null, value?: number | null): number | null;
+    /**
+     * Gets the value corresponding to the given key. Since a #GTree is
+     * automatically balanced as key/value pairs are added, key lookup
+     * is O(log n) (where n is the number of key/value pairs in the tree).
+     * @param key - the key to look up
+     */
     lookup(key?: number | null): number | null;
+    /**
+     * Looks up a key in the #GTree, returning the original key and the
+     * associated value. This is useful if you need to free the memory
+     * allocated for the original key, for example before calling
+     * g_tree_remove().
+     * @param lookupKey - the key to look up
+     * @param origKey - returns the original key
+     * @param value - returns the value associated with the key
+     */
     lookupExtended(lookupKey?: number | null, origKey?: Ref<number> | null, value?: Ref<number> | null): boolean;
+    /**
+     * Gets the tree node corresponding to the given key. Since a #GTree is
+     * automatically balanced as key/value pairs are added, key lookup
+     * is O(log n) (where n is the number of key/value pairs in the tree).
+     * @param key - the key to look up
+     */
     lookupNode(key?: number | null): number | null;
+    /**
+     * Gets the lower bound node corresponding to the given key,
+     * or %NULL if the tree is empty or all the nodes in the tree
+     * have keys that are strictly lower than the searched key.
+     *
+     * The lower bound is the first node that has its key greater
+     * than or equal to the searched key.
+     * @param key - the key to calculate the lower bound for
+     */
     lowerBound(key?: number | null): number | null;
+    /**
+     * Gets the number of nodes in a #GTree.
+     */
     nnodes(): number;
+    /**
+     * Returns the first in-order node of the tree, or %NULL
+     * for an empty tree.
+     */
     nodeFirst(): number | null;
+    /**
+     * Returns the last in-order node of the tree, or %NULL
+     * for an empty tree.
+     */
     nodeLast(): number | null;
+    /**
+     * Increments the reference count of `tree` by one.
+     *
+     * It is safe to call this function from any thread.
+     */
     ref(): Tree;
+    /**
+     * Removes a key/value pair from a #GTree.
+     *
+     * If the #GTree was created using g_tree_new_full(), the key and value
+     * are freed using the supplied destroy functions, otherwise you have to
+     * make sure that any dynamically allocated values are freed yourself.
+     * If the key does not exist in the #GTree, the function does nothing.
+     *
+     * The cost of maintaining a balanced tree while removing a key/value
+     * result in a O(n log(n)) operation where most of the other operations
+     * are O(log(n)).
+     * @param key - the key to remove
+     */
     remove(key?: number | null): boolean;
+    /**
+     * Removes all nodes from a #GTree and destroys their keys and values,
+     * then resets the #GTree’s root to %NULL.
+     */
     removeAll(): void;
+    /**
+     * Inserts a new key and value into a #GTree as g_tree_replace_node() does,
+     * only this function does not return the inserted or set node.
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     replace(key?: number | null, value?: number | null): void;
+    /**
+     * Inserts a new key and value into a #GTree similar to g_tree_insert_node().
+     * The difference is that if the key already exists in the #GTree, it gets
+     * replaced by the new key. If you supplied a `value_destroy_func` when
+     * creating the #GTree, the old value is freed using that function. If you
+     * supplied a `key_destroy_func` when creating the #GTree, the old key is
+     * freed using that function.
+     *
+     * The tree is automatically 'balanced' as new key/value pairs are added,
+     * so that the distance from the root to every leaf is as small as possible.
+     * @param key - the key to insert
+     * @param value - the value corresponding to the key
+     */
     replaceNode(key?: number | null, value?: number | null): number | null;
+    /**
+     * Searches a #GTree using @search_func.
+     *
+     * The `search_func` is called with a pointer to the key of a key/value
+     * pair in the tree, and the passed in @user_data. If `search_func` returns
+     * 0 for a key/value pair, then the corresponding value is returned as
+     * the result of g_tree_search(). If `search_func` returns -1, searching
+     * will proceed among the key/value pairs that have a smaller key; if
+     * `search_func` returns 1, searching will proceed among the key/value
+     * pairs that have a larger key.
+     * @param searchFunc - a function used to search the #GTree
+     * @param userData - the data passed as the second argument to @search_func
+     */
     search(searchFunc: (...args: unknown[]) => unknown, userData?: number | null): number | null;
+    /**
+     * Searches a #GTree using @search_func.
+     *
+     * The `search_func` is called with a pointer to the key of a key/value
+     * pair in the tree, and the passed in @user_data. If `search_func` returns
+     * 0 for a key/value pair, then the corresponding node is returned as
+     * the result of g_tree_search(). If `search_func` returns -1, searching
+     * will proceed among the key/value pairs that have a smaller key; if
+     * `search_func` returns 1, searching will proceed among the key/value
+     * pairs that have a larger key.
+     * @param searchFunc - a function used to search the #GTree
+     * @param userData - the data passed as the second argument to @search_func
+     */
     searchNode(searchFunc: (...args: unknown[]) => unknown, userData?: number | null): number | null;
+    /**
+     * Removes a key and its associated value from a #GTree without calling
+     * the key and value destroy functions.
+     *
+     * If the key does not exist in the #GTree, the function does nothing.
+     * @param key - the key to remove
+     */
     steal(key?: number | null): boolean;
+    /**
+     * Calls the given function for each node in the #GTree.
+     * @param traverseFunc - the function to call for each node visited. If this
+     * @param traverseType - the order in which nodes are visited, one of %G_IN_ORDER,
+     * @param userData - user data to pass to the function
+     */
     traverse(traverseFunc: (...args: unknown[]) => unknown, traverseType: TraverseType, userData?: number | null): void;
+    /**
+     * Decrements the reference count of `tree` by one.
+     * If the reference count drops to 0, all keys and values will
+     * be destroyed (if destroy functions were specified) and all
+     * memory allocated by `tree` will be released.
+     *
+     * It is safe to call this function from any thread.
+     */
     unref(): void;
+    /**
+     * Gets the upper bound node corresponding to the given key,
+     * or %NULL if the tree is empty or all the nodes in the tree
+     * have keys that are lower than or equal to the searched key.
+     *
+     * The upper bound is the first node that has its key strictly greater
+     * than the searched key.
+     * @param key - the key to calculate the upper bound for
+     */
     upperBound(key?: number | null): number | null;
 }