Package org.gnome.glib

Class Bytes

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.Bytes

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Bytes
extends ProxyInstance

A simple refcounted 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 g_malloc(), from memory slices, from a GMappedFile or memory from other allocators.

GBytes work well as keys in GHashTable. Use g_bytes_equal() and g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full(). GBytes can also be used as keys in a GTree by passing the g_bytes_compare() function to g_tree_new().

The data pointed to by this bytes must not be modified. For a mutable array of bytes see GByteArray. Use g_bytes_unref_to_array() to create a mutable array for a GBytes sequence. To create an immutable GBytes from a mutable GByteArray, use the g_byte_array_free_to_bytes() function.

Constructor Summary

Constructors

Constructor	Description
Bytes()	Calls Bytes(byte[]) with data = null
Bytes(@org.jetbrains.annotations.Nullable byte[] data)	Creates a new GBytes from data.
Bytes(MemorySegment address)	Create a Bytes proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
int	compare(Bytes bytes2)	Compares the two GBytes values.
boolean	equal(Bytes bytes2)	Compares the two GBytes values being pointed to and returns true if they are equal.
byte[]	getData()	Get the byte data in the GBytes.
MemorySegment	getRegion(long elementSize, long offset, long nElements)	Gets a pointer to a region in this Bytes.
long	getSize()	Get the size of the byte data in the GBytes.
static Type	getType()	Get the GType of the Bytes class
int	hash()	Creates an integer hash code for the byte data in the GBytes.
Bytes	newFromBytes(long offset, long length)	Creates a GBytes which is a subsection of another GBytes.
Bytes	ref()	Increase the reference count on this Bytes.
static Bytes	static_(@org.jetbrains.annotations.Nullable byte[] data)	Creates a new GBytes from static data.
static Bytes	take(@org.jetbrains.annotations.Nullable byte[] data)	Creates a new GBytes from data.
void	unref()	Releases a reference on this Bytes.
byte[]	unrefToArray()	Unreferences the bytes, and returns a new mutable GByteArray containing the same byte data.
byte[]	unrefToData()	Unreferences the bytes, and returns a pointer the same byte data contents.
static Bytes	withFreeFunc(@org.jetbrains.annotations.Nullable byte[] data, @Nullable MemorySegment userData)	Creates a GBytes from data.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Bytes

public Bytes(MemorySegment address)

Create a Bytes proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Bytes

public Bytes(@Nullable
 @org.jetbrains.annotations.Nullable byte[] data)

Creates a new GBytes from data.

data is copied. If size is 0, data may be null.

Parameters:

data - the data to be used for the bytes

Bytes

public Bytes()

Calls Bytes(byte[]) with data = null

Method Details

getType

public static Type getType()

Get the GType of the Bytes class

Returns:

the GType

static_

public static Bytes static_(@Nullable
 @org.jetbrains.annotations.Nullable byte[] data)

Creates a new GBytes from static data.

data must be static (ie: never modified or freed). It may be null if size is 0.

Parameters:

data - the data to be used for the bytes

Returns:

a new GBytes

take

public static Bytes take(@Nullable
 @org.jetbrains.annotations.Nullable byte[] data)

Creates a new GBytes 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 g_free().

For creating GBytes with memory from other allocators, see g_bytes_new_with_free_func().

data may be null if size is 0.

Parameters:

data - the data to be used for the bytes

Returns:

a new GBytes

withFreeFunc

public static Bytes withFreeFunc(@Nullable
 @org.jetbrains.annotations.Nullable byte[] data,
 @Nullable
 @Nullable MemorySegment userData)

Creates a GBytes from data.

When the last reference is dropped, freeFunc will be called with the userData argument.

data must not be modified after this call is made until freeFunc has been called to indicate that the bytes is no longer in use.

data may be null if size is 0.

Parameters:

data - the data to be used for the bytes

userData - data to pass to freeFunc

Returns:

a new GBytes

compare

public int compare(Bytes bytes2)

Compares the two GBytes values.

This function can be used to sort GBytes instances in lexicographical order.

If this Bytes 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 this Bytes has a smaller value at that position it is considered less, otherwise greater than bytes2.

Parameters:

bytes2 - a pointer to a GBytes to compare with this Bytes

Returns:

a negative value if this Bytes is less than bytes2, a positive value if this Bytes is greater than bytes2, and zero if this Bytes is equal to bytes2

equal

public boolean equal(Bytes bytes2)

Compares the two GBytes 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-null GBytes pointers as keys in a GHashTable.

Parameters:

bytes2 - a pointer to a GBytes to compare with this Bytes

Returns:

true if the two keys match.

getData

public byte[] getData()

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

Returns:

a pointer to the byte data, or null

getRegion

public MemorySegment getRegion(long elementSize,
 long offset,
 long nElements)

Gets a pointer to a region in this 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 this 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 this Bytes, plus offset. This will be non-null except for the case where this 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 this Bytes, null effectively always means "error".

Parameters:

elementSize - a non-zero element size

offset - an offset to the start of the region within the this Bytes

nElements - the number of elements in the region

Returns:

the requested region, or null in case of an error

getSize

public long getSize()

Get the size of the byte data in the GBytes.

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

Returns:

the size

hash

public int hash()

Creates an integer hash code for the byte data in the GBytes.

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

Returns:

a hash value corresponding to the key.

newFromBytes

public Bytes newFromBytes(long offset,
 long length)

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

A reference to this 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 this Bytes, then this Bytes will be returned with the reference count incremented by 1. If this Bytes is a slice of another GBytes, then the resulting GBytes will reference the same GBytes instead of this Bytes. This allows consumers to simplify the usage of GBytes when asynchronously writing to streams.

Parameters:

offset - offset which subsection starts at

length - length of subsection

Returns:

a new GBytes

ref

public Bytes ref()

Increase the reference count on this Bytes.

Returns:

the GBytes

unref

public void unref()

Releases a reference on this Bytes. This may result in the bytes being freed. If this Bytes is null, it will return immediately.

unrefToArray

public byte[] unrefToArray()

Unreferences the bytes, and returns a new mutable GByteArray 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 g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the data is copied.

Do not use it if this Bytes contains more than G_MAXUINT bytes. GByteArray stores the length of its data in guint, which may be shorter than gsize, that this Bytes is using.

Returns:

a new mutable GByteArray containing the same byte data

unrefToData

public byte[] unrefToData()

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 g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the data is copied.

Returns:

a pointer to the same byte data, which should be freed with g_free()