@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/bytes.js

@@ -1,12 +1,66 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
 import { ByteArray } from "./byte-array.js";
+/**
+ * A simple reference counted data type representing an immutable sequence of
+ * zero or more bytes from an unspecified origin.
+ *
+ * The purpose of a `GBytes` is to keep the memory region that it holds
+ * alive for as long as anyone holds a reference to the bytes.  When
+ * the last reference count is dropped, the memory is released. Multiple
+ * unrelated callers can use byte data in the `GBytes` without coordinating
+ * their activities, resting assured that the byte data will not change or
+ * move while they hold a reference.
+ *
+ * A `GBytes` can come from many different origins that may have
+ * different procedures for freeing the memory region.  Examples are
+ * memory from [func@GLib.malloc], from memory slices, from a
+ * [struct@GLib.MappedFile] or memory from other allocators.
+ *
+ * `GBytes` work well as keys in [struct@GLib.HashTable]. Use
+ * [method@GLib.Bytes.equal] and [method@GLib.Bytes.hash] as parameters to
+ * [func@GLib.HashTable.new] or [func@GLib.HashTable.new_full].
+ * `GBytes` can also be used as keys in a [struct@GLib.Tree] by passing the
+ * [method@GLib.Bytes.compare] function to [ctor@GLib.Tree.new].
+ *
+ * The data pointed to by this bytes must not be modified. For a mutable
+ * array of bytes see [struct@GLib.ByteArray]. Use
+ * [method@GLib.Bytes.unref_to_array] to create a mutable array for a `GBytes`
+ * sequence. To create an immutable `GBytes` from a mutable
+ * [struct@GLib.ByteArray], use the [func@GLib.ByteArray.free_to_bytes]
+ * function.
+ */
 export class Bytes {
     ptr;
+    /**
+     * Creates a new [struct@GLib.Bytes] from @data.
+     *
+     * `data` is copied. If `size` is 0, `data` may be `NULL`.
+     *
+     * As an optimization, [ctor@GLib.Bytes.new] may avoid an extra allocation by
+     * copying the data within the resulting bytes structure if sufficiently small
+     * (since GLib 2.84).
+     * @param data - the data to be used for the bytes
+     * @param size - the size of @data
+     */
     constructor(size, data) {
         const _args = [data, size];
         this.ptr = this.createPtr(_args);
     }
+    /**
+     * Creates a new [struct@GLib.Bytes] from @data.
+     *
+     * After this call, `data` belongs to the `GBytes` and may no longer be
+     * modified by the caller. The memory of `data` has to be dynamically
+     * allocated and will eventually be freed with [func@GLib.free].
+     *
+     * For creating `GBytes` with memory from other allocators, see
+     * [ctor@GLib.Bytes.new_with_free_func].
+     *
+     * `data` may be `NULL` if `size` is 0.
+     * @param data - the data to be used for the bytes
+     * @param size - the size of @data
+     */
     static newTake(size, data) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_new_take", [
             {
@@ -41,6 +95,19 @@ export class Bytes {
             },
         ], { type: "boxed", borrowed: true, innerType: "GBytes" });
     }
+    /**
+     * Compares the two [struct@GLib.Bytes] values.
+     *
+     * This function can be used to sort `GBytes` instances in lexicographical
+     * order.
+     *
+     * If `bytes1` and `bytes2` have different length but the shorter one is a
+     * prefix of the longer one then the shorter one is considered to be less than
+     * the longer one. Otherwise the first byte where both differ is used for
+     * comparison. If `bytes1` has a smaller value at that position it is
+     * considered less, otherwise greater than @bytes2.
+     * @param bytes2 - a pointer to a [struct@GLib.Bytes] to compare with @bytes1
+     */
     compare(bytes2) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_compare", [
             {
@@ -58,6 +125,15 @@ export class Bytes {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Compares the two [struct@GLib.Bytes] values being pointed to and returns
+     * `TRUE` if they are equal.
+     *
+     * This function can be passed to [func@GLib.HashTable.new] as the
+     * `key_equal_func` parameter, when using non-`NULL` `GBytes` pointers as keys in
+     * a [struct@GLib.HashTable].
+     * @param bytes2 - a pointer to a [struct@GLib.Bytes] to compare with @bytes1
+     */
     equal(bytes2) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_equal", [
             {
@@ -75,6 +151,18 @@ export class Bytes {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Get the byte data in the [struct@GLib.Bytes].
+     *
+     * This data should not be modified.
+     *
+     * This function will always return the same pointer for a given `GBytes`.
+     *
+     * `NULL` may be returned if `size` is 0. This is not guaranteed, as the `GBytes`
+     * may represent an empty string with `data` non-`NULL` and `size` as 0. `NULL`
+     * will not be returned if `size` is non-zero.
+     * @param size - location to return size of byte data
+     */
     getData(size) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_get_data", [
             {
@@ -91,6 +179,31 @@ export class Bytes {
             },
         ], { type: "array", itemType: { type: "int", size: 8, unsigned: true } });
     }
+    /**
+     * Gets a pointer to a region in @bytes.
+     *
+     * The region starts at `offset` many bytes from the start of the data
+     * and contains `n_elements` many elements of `element_size` size.
+     *
+     * `n_elements` may be zero, but `element_size` must always be non-zero.
+     * Ideally, `element_size` is a static constant (eg: `sizeof` a struct).
+     *
+     * This function does careful bounds checking (including checking for
+     * arithmetic overflows) and returns a non-`NULL` pointer if the
+     * specified region lies entirely within the @bytes. If the region is
+     * in some way out of range, or if an overflow has occurred, then `NULL`
+     * is returned.
+     *
+     * Note: it is possible to have a valid zero-size region. In this case,
+     * the returned pointer will be equal to the base pointer of the data of
+     * @bytes, plus @offset.  This will be non-`NULL` except for the case
+     * where `bytes` itself was a zero-sized region.  Since it is unlikely
+     * that you will be using this function to check for a zero-sized region
+     * in a zero-sized @bytes, `NULL` effectively always means ‘error’.
+     * @param elementSize - a non-zero element size
+     * @param offset - an offset to the start of the region within the @bytes
+     * @param nElements - the number of elements in the region
+     */
     getRegion(elementSize, offset, nElements) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_get_region", [
             {
@@ -111,6 +224,11 @@ export class Bytes {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Get the size of the byte data in the [struct@GLib.Bytes].
+     *
+     * This function will always return the same value for a given `GBytes`.
+     */
     getSize() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_get_size", [
             {
@@ -119,6 +237,13 @@ export class Bytes {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Creates an integer hash code for the byte data in the [struct@GLib.Bytes].
+     *
+     * This function can be passed to [func@GLib.HashTable.new] as the
+     * `key_hash_func` parameter, when using non-`NULL` `GBytes` pointers as keys in
+     * a [struct@GLib.HashTable].
+     */
     hash() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_hash", [
             {
@@ -127,6 +252,21 @@ export class Bytes {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Creates a [struct@GLib.Bytes] which is a subsection of another `GBytes`.
+     *
+     * The `offset` + `length` may not be longer than the size of @bytes.
+     *
+     * A reference to `bytes` will be held by the newly created `GBytes` until
+     * the byte data is no longer needed.
+     *
+     * Since 2.56, if `offset` is 0 and `length` matches the size of @bytes, then
+     * `bytes` will be returned with the reference count incremented by 1. If `bytes` is a slice of another `GBytes`, then the resulting `GBytes` will reference
+     * the same `GBytes` instead of @bytes. This allows consumers to simplify the
+     * usage of `GBytes` when asynchronously writing to streams.
+     * @param offset - offset which subsection starts at
+     * @param length - length of subsection
+     */
     newFromBytes(offset, length) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_new_from_bytes", [
             {
@@ -149,6 +289,9 @@ export class Bytes {
         });
         return getObject(ptr, Bytes);
     }
+    /**
+     * Increase the reference count on @bytes.
+     */
     ref() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_ref", [
             {
@@ -163,6 +306,12 @@ export class Bytes {
         });
         return getObject(ptr, Bytes);
     }
+    /**
+     * Releases a reference on @bytes.
+     *
+     * This may result in the bytes being freed. If `bytes` is `NULL`, it will
+     * return immediately.
+     */
     unref() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_unref", [
             {
@@ -171,6 +320,21 @@ export class Bytes {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Unreferences the bytes, and returns a new mutable [struct@GLib.ByteArray]
+     * containing the same byte data.
+     *
+     * As an optimization, the byte data is transferred to the array without copying
+     * if this was the last reference to `bytes` and `bytes` was created with
+     * [ctor@GLib.Bytes.new], [ctor@GLib.Bytes.new_take] or
+     * [func@GLib.ByteArray.free_to_bytes] and the buffer was larger than the size
+     * [struct@GLib.Bytes] may internalize within its allocation. In all other cases
+     * the data is copied.
+     *
+     * Do not use it if `bytes` contains more than %G_MAXUINT
+     * bytes. [struct@GLib.ByteArray] stores the length of its data in `guint`,
+     * which may be shorter than `gsize`, that `bytes` is using.
+     */
     unrefToArray() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_unref_to_array", [
             {
@@ -185,6 +349,18 @@ export class Bytes {
         });
         return getObject(ptr, ByteArray);
     }
+    /**
+     * Unreferences the bytes, and returns a pointer the same byte data
+     * contents.
+     *
+     * As an optimization, the byte data is returned without copying if this was
+     * the last reference to `bytes` and `bytes` was created with
+     * [ctor@GLib.Bytes.new], [ctor@GLib.Bytes.new_take] or
+     * [func@GLib.ByteArray.free_to_bytes] and the buffer was larger than the size
+     * [struct@GLib.Bytes] may internalize within its allocation. In all other cases
+     * the data is copied.
+     * @param size - location to place the length of the returned data
+     */
     unrefToData(size) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_bytes_unref_to_data", [
             {

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

@@ -1,13 +1,77 @@
 import { ChecksumType } from "./enums.js";
+/**
+ * GLib provides a generic API for computing checksums (or ‘digests’)
+ * for a sequence of arbitrary bytes, using various hashing algorithms
+ * like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
+ * environments and specifications.
+ *
+ * To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free
+ * a `GChecksum`, use [method@GLib.Checksum.free].
+ *
+ * GLib supports incremental checksums using the `GChecksum` data
+ * structure, by calling [method@GLib.Checksum.update] as long as there’s data
+ * available and then using [method@GLib.Checksum.get_string] or
+ * [method@GLib.Checksum.get_digest] to compute the checksum and return it
+ * either as a string in hexadecimal form, or as a raw sequence of bytes. To
+ * compute the checksum for binary blobs and nul-terminated strings in
+ * one go, use the convenience functions [func@GLib.compute_checksum_for_data]
+ * and [func@GLib.compute_checksum_for_string], respectively.
+ */
 export declare class Checksum {
     ptr: unknown;
+    /**
+     * Creates a new #GChecksum, using the checksum algorithm @checksum_type.
+     * If the `checksum_type` is not known, %NULL is returned.
+     * A #GChecksum can be used to compute the checksum, or digest, of an
+     * arbitrary binary blob, using different hashing algorithms.
+     *
+     * A #GChecksum works by feeding a binary blob through g_checksum_update()
+     * until there is data to be checked; the digest can then be extracted
+     * using g_checksum_get_string(), which will return the checksum as a
+     * hexadecimal string; or g_checksum_get_digest(), which will return a
+     * vector of raw bytes. Once either g_checksum_get_string() or
+     * g_checksum_get_digest() have been called on a #GChecksum, the checksum
+     * will be closed and it won't be possible to call g_checksum_update()
+     * on it anymore.
+     * @param checksumType - the desired type of checksum
+     */
     constructor(checksumType: ChecksumType);
     constructor(_args: unknown[]);
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Gets the length in bytes of digests of type @checksum_type
+     * @param checksumType - a #GChecksumType
+     */
     static typeGetLength(checksumType: ChecksumType): number;
+    /**
+     * Copies a #GChecksum. If `checksum` has been closed, by calling
+     * g_checksum_get_string() or g_checksum_get_digest(), the copied
+     * checksum will be closed as well.
+     */
     copy(): Checksum;
+    /**
+     * Frees the memory allocated for @checksum.
+     */
     free(): void;
+    /**
+     * Gets the digest as a hexadecimal string.
+     *
+     * Once this function has been called the #GChecksum can no longer be
+     * updated with g_checksum_update().
+     *
+     * The hexadecimal characters will be lower case.
+     */
     getString(): string;
+    /**
+     * Resets the state of the `checksum` back to its initial state.
+     */
     reset(): void;
+    /**
+     * Feeds `data` into an existing #GChecksum. The checksum must still be
+     * open, that is g_checksum_get_string() or g_checksum_get_digest() must
+     * not have been called on @checksum.
+     * @param data - buffer used to compute the checksum
+     * @param length - size of the buffer, or -1 if it is a null-terminated string.
+     */
     update(data: number[], length: number): void;
 }

package/dist/generated/glib/checksum.js

@@ -1,5 +1,23 @@
 import { call } from "@gtkx/native";
 import { getObject } from "@gtkx/ffi";
+/**
+ * GLib provides a generic API for computing checksums (or ‘digests’)
+ * for a sequence of arbitrary bytes, using various hashing algorithms
+ * like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
+ * environments and specifications.
+ *
+ * To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free
+ * a `GChecksum`, use [method@GLib.Checksum.free].
+ *
+ * GLib supports incremental checksums using the `GChecksum` data
+ * structure, by calling [method@GLib.Checksum.update] as long as there’s data
+ * available and then using [method@GLib.Checksum.get_string] or
+ * [method@GLib.Checksum.get_digest] to compute the checksum and return it
+ * either as a string in hexadecimal form, or as a raw sequence of bytes. To
+ * compute the checksum for binary blobs and nul-terminated strings in
+ * one go, use the convenience functions [func@GLib.compute_checksum_for_data]
+ * and [func@GLib.compute_checksum_for_string], respectively.
+ */
 export class Checksum {
     ptr;
     constructor(...args) {
@@ -15,6 +33,10 @@ export class Checksum {
             },
         ], { type: "boxed", borrowed: true, innerType: "GChecksum" });
     }
+    /**
+     * Gets the length in bytes of digests of type @checksum_type
+     * @param checksumType - a #GChecksumType
+     */
     static typeGetLength(checksumType) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_checksum_type_get_length", [
             {
@@ -23,6 +45,11 @@ export class Checksum {
             },
         ], { type: "int", size: 64, unsigned: false });
     }
+    /**
+     * Copies a #GChecksum. If `checksum` has been closed, by calling
+     * g_checksum_get_string() or g_checksum_get_digest(), the copied
+     * checksum will be closed as well.
+     */
     copy() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_checksum_copy", [
             {
@@ -37,6 +64,9 @@ export class Checksum {
         });
         return getObject(ptr, Checksum);
     }
+    /**
+     * Frees the memory allocated for @checksum.
+     */
     free() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_checksum_free", [
             {
@@ -45,6 +75,14 @@ export class Checksum {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the digest as a hexadecimal string.
+     *
+     * Once this function has been called the #GChecksum can no longer be
+     * updated with g_checksum_update().
+     *
+     * The hexadecimal characters will be lower case.
+     */
     getString() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_checksum_get_string", [
             {
@@ -53,6 +91,9 @@ export class Checksum {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Resets the state of the `checksum` back to its initial state.
+     */
     reset() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_checksum_reset", [
             {
@@ -61,6 +102,13 @@ export class Checksum {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Feeds `data` into an existing #GChecksum. The checksum must still be
+     * open, that is g_checksum_get_string() or g_checksum_get_digest() must
+     * not have been called on @checksum.
+     * @param data - buffer used to compute the checksum
+     * @param length - size of the buffer, or -1 if it is a null-terminated string.
+     */
     update(data, length) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_checksum_update", [
             {