Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
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.
- newtype Bytes = Bytes (ManagedPtr Bytes)
- noBytes :: Maybe Bytes
- data BytesCompareMethodInfo
- bytesCompare :: (HasCallStack, MonadIO m) => Bytes -> Bytes -> m Int32
- data BytesEqualMethodInfo
- bytesEqual :: (HasCallStack, MonadIO m) => Bytes -> Bytes -> m Bool
- data BytesGetDataMethodInfo
- bytesGetData :: (HasCallStack, MonadIO m) => Bytes -> m (Maybe ByteString)
- data BytesGetSizeMethodInfo
- bytesGetSize :: (HasCallStack, MonadIO m) => Bytes -> m Word64
- data BytesHashMethodInfo
- bytesHash :: (HasCallStack, MonadIO m) => Bytes -> m Word32
- bytesNew :: (HasCallStack, MonadIO m) => Maybe ByteString -> m Bytes
- data BytesNewFromBytesMethodInfo
- bytesNewFromBytes :: (HasCallStack, MonadIO m) => Bytes -> Word64 -> Word64 -> m Bytes
- bytesNewTake :: (HasCallStack, MonadIO m) => Maybe ByteString -> m Bytes
- data BytesRefMethodInfo
- bytesRef :: (HasCallStack, MonadIO m) => Bytes -> m Bytes
- data BytesUnrefMethodInfo
- bytesUnref :: (HasCallStack, MonadIO m) => Bytes -> m ()
- data BytesUnrefToArrayMethodInfo
- bytesUnrefToArray :: (HasCallStack, MonadIO m) => Bytes -> m ByteString
- data BytesUnrefToDataMethodInfo
- bytesUnrefToData :: (HasCallStack, MonadIO m) => Bytes -> m ByteString
Exported types
Methods
compare
data BytesCompareMethodInfo Source #
((~) * signature (Bytes -> m Int32), MonadIO m) => MethodInfo * BytesCompareMethodInfo Bytes signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> Bytes |
|
-> m Int32 | Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is greater, and zero if bytes2 is equal to bytes1 |
Compares the two Bytes
values.
This function can be used to sort GBytes instances in lexographical order.
Since: 2.32
equal
data BytesEqualMethodInfo Source #
((~) * signature (Bytes -> m Bool), MonadIO m) => MethodInfo * BytesEqualMethodInfo Bytes signature Source # | |
getData
data BytesGetDataMethodInfo Source #
((~) * signature (m (Maybe ByteString)), MonadIO m) => MethodInfo * BytesGetDataMethodInfo Bytes signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> m (Maybe ByteString) | Returns:
a pointer to the byte data, or |
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
getSize
data BytesGetSizeMethodInfo Source #
((~) * signature (m Word64), MonadIO m) => MethodInfo * BytesGetSizeMethodInfo Bytes signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> m Word64 | Returns: the size |
hash
data BytesHashMethodInfo Source #
((~) * signature (m Word32), MonadIO m) => MethodInfo * BytesHashMethodInfo Bytes signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> m Word32 | Returns: a hash value corresponding to the key. |
new
:: (HasCallStack, MonadIO m) | |
=> Maybe ByteString |
|
-> m Bytes | Returns: a new |
newFromBytes
newTake
:: (HasCallStack, MonadIO m) | |
=> Maybe ByteString |
|
-> m Bytes | Returns: a new |
Creates a new Bytes
from data
.
After this call, data
belongs to the bytes and may no longer be
modified by the caller. free
will be called on data
when the
bytes is no longer in use. Because of this data
must have been created by
a call to malloc
, malloc0
or realloc
or by one of the many
functions that wrap these calls (such as g_new()
, strdup
, etc).
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
data BytesRefMethodInfo Source #
((~) * signature (m Bytes), MonadIO m) => MethodInfo * BytesRefMethodInfo Bytes signature Source # | |
Increase the reference count on bytes
.
Since: 2.32
unref
data BytesUnrefMethodInfo Source #
((~) * signature (m ()), MonadIO m) => MethodInfo * BytesUnrefMethodInfo Bytes signature Source # | |
:: (HasCallStack, MonadIO m) | |
=> Bytes |
|
-> m () |
Releases a reference on bytes
. This may result in the bytes being
freed.
Since: 2.32
unrefToArray
data BytesUnrefToArrayMethodInfo Source #
((~) * signature (m ByteString), MonadIO m) => MethodInfo * BytesUnrefToArrayMethodInfo Bytes signature Source # | |
:: (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
. In all
other cases the data is copied.
Since: 2.32
unrefToData
data BytesUnrefToDataMethodInfo Source #
((~) * signature (m ByteString), MonadIO m) => MethodInfo * BytesUnrefToDataMethodInfo Bytes signature Source # | |
:: (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
. In all other cases the
data is copied.
Since: 2.32