gi-glib-2.0.30: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.GLib.Structs.Bytes

Contents

- Exported types
- Methods
  - compare
  - equal
  - getData
  - getRegion
  - getSize
  - hash
  - new
  - newFromBytes
  - newTake
  - ref
  - unref
  - unrefToArray
  - unrefToData

Description

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 `malloc`, from memory slices, from a `MappedFile` or memory from other allocators.

`GBytes` work well as keys in `GHashTable`. Use `bytesEqual` and `bytesHash` as parameters to `GHashTable`.`new`() or `GHashTable`.`new_full`(). `GBytes` can also be used as keys in a `Tree` by passing the `bytesCompare` function to `Tree`.`new`().

The data pointed to by this bytes must not be modified. For a mutable array of bytes see `ByteArray`. Use `bytesUnrefToArray` to create a mutable array for a `GBytes` sequence. To create an immutable `GBytes` from a mutable `ByteArray`, use the `byteArrayFreeToBytes` function.

Since: 2.32

Synopsis

- newtype Bytes = Bytes (ManagedPtr Bytes)
- bytesCompare :: (HasCallStack, MonadIO m) => Bytes -> Bytes -> m Int32
- bytesEqual :: (HasCallStack, MonadIO m) => Bytes -> Bytes -> m Bool
- bytesGetData :: (HasCallStack, MonadIO m) => Bytes -> m (Maybe ByteString)
- bytesGetRegion :: (HasCallStack, MonadIO m) => Bytes -> CSize -> CSize -> CSize -> m (Ptr ())
- bytesGetSize :: (HasCallStack, MonadIO m) => Bytes -> m CSize
- bytesHash :: (HasCallStack, MonadIO m) => Bytes -> m Word32
- bytesNew :: (HasCallStack, MonadIO m) => Maybe ByteString -> m Bytes
- bytesNewFromBytes :: (HasCallStack, MonadIO m) => Bytes -> CSize -> CSize -> m Bytes
- bytesNewTake :: (HasCallStack, MonadIO m) => Maybe ByteString -> m Bytes
- bytesRef :: (HasCallStack, MonadIO m) => Bytes -> m Bytes
- bytesUnref :: (HasCallStack, MonadIO m) => Maybe Bytes -> m ()
- bytesUnrefToArray :: (HasCallStack, MonadIO m) => Bytes -> m ByteString
- bytesUnrefToData :: (HasCallStack, MonadIO m) => Bytes -> m ByteString

# Exported types

newtype Bytes Source #

Memory-managed wrapper type.

Constructors

Bytes (ManagedPtr Bytes) |

#### Instances

Instances details

Eq Bytes Source # |
Instance details Defined in GI.GLib.Structs.Bytes Methods (==) :: Bytes -> Bytes -> Bool Source # (/=) :: Bytes -> Bytes -> Bool Source #
GBoxed Bytes Source # |
Instance details Defined in GI.GLib.Structs.Bytes
ManagedPtrNewtype Bytes Source # |
Instance details Defined in GI.GLib.Structs.Bytes Methods toManagedPtr :: Bytes -> ManagedPtr Bytes Source #
TypedObject Bytes Source # |
Instance details Defined in GI.GLib.Structs.Bytes Methods glibType :: IO GType Source #
HasParentTypes Bytes Source # |
Instance details Defined in GI.GLib.Structs.Bytes
IsGValue (Maybe Bytes) Source # | Convert `Bytes` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.GLib.Structs.Bytes Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Bytes -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Bytes) Source #
type ParentTypes Bytes Source # |
Instance details Defined in GI.GLib.Structs.Bytes type ParentTypes Bytes = '[] :: [Type]

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

compare, equal, hash, ref, unref, unrefToArray, unrefToData.

#### Getters

getData, getRegion, getSize.

#### Setters

None.

## compare

bytesCompare Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes1`: a pointer to a `Bytes`
-> Bytes | `bytes2`: a pointer to a `Bytes` to compare with `bytes1`
-> m Int32 | Returns: a negative value if `bytes1` is less than `bytes2`, a positive value if `bytes1` is greater than `bytes2`, and zero if `bytes1` is equal to `bytes2`

Compares the two `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`.

Since: 2.32

## equal

bytesEqual Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes1`: a pointer to a `Bytes`
-> Bytes | `bytes2`: a pointer to a `Bytes` to compare with `bytes1`
-> m Bool | Returns: `TRUE` if the two keys match.

Compares the two `Bytes` values being pointed to and returns `TRUE` if they are equal.

This function can be passed to `GHashTable`.`new`() as the `keyEqualFunc` parameter, when using non-`NULL` `GBytes` pointers as keys in a `GHashTable`.

Since: 2.32

## getData

bytesGetData Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> m (Maybe ByteString) | Returns: a pointer to the byte data

Get the byte data in the `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.

Since: 2.32

## getRegion

bytesGetRegion Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> CSize | `elementSize`: a non-zero element size
-> CSize | `offset`: an offset to the start of the region within the `bytes`
-> CSize | `nElements`: the number of elements in the region
-> m (Ptr ()) | Returns: the requested region, or `NULL` in case of an error

Gets a pointer to a region in `bytes`.

The region starts at `offset` many bytes from the start of the data and contains `nElements` many elements of `elementSize` size.

`nElements` may be zero, but `elementSize` must always be non-zero. Ideally, `elementSize` 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’.

Since: 2.70

## getSize

bytesGetSize Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> m CSize | Returns: the size

Get the size of the byte data in the `Bytes`.

This function will always return the same value for a given `GBytes`.

Since: 2.32

## hash

bytesHash Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a pointer to a `Bytes` key
-> m Word32 | Returns: a hash value corresponding to the key.

Creates an integer hash code for the byte data in the `Bytes`.

This function can be passed to `GHashTable`.`new`() as the `keyHashFunc` parameter, when using non-`NULL` `GBytes` pointers as keys in a `GHashTable`.

Since: 2.32

## new

bytesNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe ByteString | `data`: the data to be used for the bytes
-> m Bytes | Returns: a new `Bytes`

Creates a new `Bytes` from `data`.

`data` is copied. If `size` is 0, `data` may be `NULL`.

As an optimization, `bytesNew` may avoid an extra allocation by copying the data within the resulting bytes structure if sufficiently small (since GLib 2.84).

Since: 2.32

## newFromBytes

bytesNewFromBytes Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> CSize | `offset`: offset which subsection starts at
-> CSize | `length`: length of subsection
-> m Bytes | Returns: a new `Bytes`

Creates a `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.

Since: 2.32

## newTake

bytesNewTake Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe ByteString | `data`: the data to be used for the bytes
-> m Bytes | Returns: a new `Bytes`

Creates a new `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 `free`.

For creating `GBytes` with memory from other allocators, see `Bytes`.`new_with_free_func`().

`data` may be `NULL` if `size` is 0.

Since: 2.32

## ref

bytesRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> m Bytes | Returns: the `Bytes`

Increase the reference count on `bytes`.

Since: 2.32

## unref

bytesUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe Bytes | `bytes`: a `Bytes`
-> m () |

Releases a reference on `bytes`.

This may result in the bytes being freed. If `bytes` is `NULL`, it will return immediately.

Since: 2.32

## unrefToArray

bytesUnrefToArray Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> m ByteString | Returns: a new mutable `ByteArray` containing the same byte data

Unreferences the bytes, and returns a new mutable `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 `bytesNew`, `bytesNewTake` or `byteArrayFreeToBytes` and the buffer was larger than the size `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. `ByteArray` stores the length of its data in `guint`, which may be shorter than `gsize`, that `bytes` is using.

Since: 2.32

## unrefToData

bytesUnrefToData Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> m ByteString | Returns: a pointer to the same byte data, which should be freed with `free`

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 `bytesNew`, `bytesNewTake` or `byteArrayFreeToBytes` and the buffer was larger than the size `Bytes` may internalize within its allocation. In all other cases the data is copied.

Since: 2.32