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
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
Memory-managed wrapper type.
Constructors
Bytes (ManagedPtr Bytes) |
Instances
Eq Bytes Source # | |
GBoxed Bytes Source # | |
Defined in GI.GLib.Structs.Bytes | |
ManagedPtrNewtype Bytes Source # | |
Defined in GI.GLib.Structs.Bytes Methods toManagedPtr :: Bytes -> ManagedPtr Bytes # | |
TypedObject Bytes Source # | |
Defined in GI.GLib.Structs.Bytes | |
HasParentTypes Bytes Source # | |
Defined in GI.GLib.Structs.Bytes | |
IsGValue (Maybe Bytes) Source # | Convert |
Defined in GI.GLib.Structs.Bytes Methods gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe Bytes -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe Bytes) # | |
type ParentTypes Bytes Source # | |
Defined in GI.GLib.Structs.Bytes type ParentTypes Bytes = '[] :: [Type] |
Methods
Click to display all available methods, including inherited ones
Methods
compare, equal, hash, newFromBytes, ref, unref, unrefToArray, unrefToData.
Getters
Setters
None.
compare
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> Bytes |
|
-> m Int32 | Returns: a negative value if |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> Bytes |
|
-> m Bool | Returns: |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> 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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> CSize |
|
-> CSize |
|
-> CSize |
|
-> m (Ptr ()) | Returns: the requested region, or |
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
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> 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
newFromBytes
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> CSize |
|
-> CSize |
|
-> m Bytes | Returns: a new |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Maybe ByteString |
|
-> m Bytes | Returns: a new |
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
Increase the reference count on bytes
.
Since: 2.32
unref
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> m ByteString | Returns: a new mutable |
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
Arguments
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> m ByteString | Returns:
a pointer to the same byte data, which should be freed with |
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