gi-glib-2.0.29: GLib bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
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 refcounted data type representing an immutable sequence of zero or more bytes from an unspecified origin.

The purpose of a `Bytes` 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 `Bytes` without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference.

A `Bytes` 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.

`Bytes` work well as keys in `HashTable`. Use `bytesEqual` and `bytesHash` as parameters to `g_hash_table_new()` or `g_hash_table_new_full()`. `Bytes` can also be used as keys in a `Tree` by passing the `bytesCompare` function to `g_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 `Bytes` sequence. To create an immutable `Bytes` 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 -> Word64 -> Word64 -> Word64 -> m (Ptr ())
- bytesGetSize :: (HasCallStack, MonadIO m) => Bytes -> m Word64
- bytesHash :: (HasCallStack, MonadIO m) => Bytes -> m Word32
- bytesNew :: (HasCallStack, MonadIO m) => Maybe ByteString -> m Bytes
- bytesNewFromBytes :: (HasCallStack, MonadIO m) => Bytes -> Word64 -> Word64 -> m Bytes
- bytesNewTake :: (HasCallStack, MonadIO m) => Maybe ByteString -> m Bytes
- bytesRef :: (HasCallStack, MonadIO m) => Bytes -> m Bytes
- bytesUnref :: (HasCallStack, MonadIO m) => 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, newFromBytes, 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 `g_hash_table_new()` as the `keyEqualFunc` parameter, when using non-`Nothing` `Bytes` pointers as keys in a `HashTable`.

Since: 2.32

## getData

bytesGetData Source #

Arguments

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

Get the byte data in the `Bytes`. This data should not be modified.

This function will always return the same pointer for a given `Bytes`.

`Nothing` may be returned if `size` is 0. This is not guaranteed, as the `Bytes` may represent an empty string with `data` non-`Nothing` and `size` as 0. `Nothing` will not be returned if `size` is non-zero.

Since: 2.32

## getRegion

bytesGetRegion Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Bytes | `bytes`: a `Bytes`
-> Word64 | `elementSize`: a non-zero element size
-> Word64 | `offset`: an offset to the start of the region within the `bytes`
-> Word64 | `nElements`: the number of elements in the region
-> m (Ptr ()) | Returns: the requested region, or `Nothing` 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-`Nothing` 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 `Nothing` 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-`Nothing` 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`, `Nothing` effectively always means "error".

Since: 2.70

## getSize

bytesGetSize Source #

Arguments

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

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

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

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 `g_hash_table_new()` as the `keyHashFunc` parameter, when using non-`Nothing` `Bytes` pointers as keys in a `HashTable`.

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 `Nothing`.

Since: 2.32

## newFromBytes

bytesNewFromBytes Source #

Arguments

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

Creates a `Bytes` which is a subsection of another `Bytes`. The `offset` + `length` may not be longer than the size of `bytes`.

A reference to `bytes` will be held by the newly created `Bytes` 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 `Bytes`, then the resulting `Bytes` will reference the same `Bytes` instead of `bytes`. This allows consumers to simplify the usage of `Bytes` 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 `Bytes` 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 `Bytes` with memory from other allocators, see `g_bytes_new_with_free_func()`.

`data` may be `Nothing` 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) |
=> Bytes | `bytes`: a `Bytes`
-> m () |

Releases a reference on `bytes`. This may result in the bytes being freed. If `bytes` is `Nothing`, 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`. 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`. In all other cases the data is copied.

Since: 2.32