Package org.gnome.glib

Class GString

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.GString

All Implemented Interfaces:

Proxy

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

A GString is an object that handles the memory management of a C string.

The emphasis of GString is on text, typically UTF-8. Crucially, the "str" member of a GString is guaranteed to have a trailing nul character, and it is therefore always safe to call functions such as strchr() or strdup() on it.

However, a GString can also hold arbitrary binary data, because it has a "len" member, which includes any possible embedded nul characters in the data. Conceptually then, GString is like a GByteArray with the addition of many convenience methods for text, and a guaranteed nul terminator.

Constructor Summary

Constructors

Constructor	Description
GString()	Calls GString(java.lang.String) with init = null
GString(@Nullable String init)	Creates a new GString, initialized with the given string.
GString(MemorySegment address)	Create a GString proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
GString	append(String val)	Adds a string onto the end of a GString, expanding it if necessary.
GString	appendC(byte c)	Adds a byte onto the end of a GString, expanding it if necessary.
GString	appendLen(String val, long len)	Appends len bytes of val to this String.
void	appendPrintf(String format, Object... varargs)	Appends a formatted string onto the end of a GString.
GString	appendUnichar(int wc)	Converts a Unicode character into UTF-8, and appends it to the string.
GString	appendUriEscaped(String unescaped, String reservedCharsAllowed, boolean allowUtf8)	Appends unescaped to this String, escaping any characters that are reserved in URIs using URI-style escape sequences.
GString	asciiDown()	Converts all uppercase ASCII letters to lowercase ASCII letters.
GString	asciiUp()	Converts all lowercase ASCII letters to uppercase ASCII letters.
GString	assign(String rval)	Copies the bytes from a string into a GString, destroying any previous contents.
GString	down()	Deprecated. This function uses the locale-specific tolower() function, which is almost never the right thing.
boolean	equal(GString v2)	Compares two strings for equality, returning true if they are equal.
GString	erase(long pos, long len)	Removes len bytes from a GString, starting at position pos.
String	free(boolean freeSegment)	Frees the memory allocated for the GString.
String	freeAndSteal()	Frees the memory allocated for the GString.
Bytes	freeToBytes()	Transfers ownership of the contents of this String to a newly allocated GBytes.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static Type	getType()	Get the GType of the GString class
int	hash()	Creates a hash code for this String; for use with GHashTable.
GString	insert(long pos, String val)	Inserts a copy of a string into a GString, expanding it if necessary.
GString	insertC(long pos, byte c)	Inserts a byte into a GString, expanding it if necessary.
GString	insertLen(long pos, String val, long len)	Inserts len bytes of val into this String at pos.
GString	insertUnichar(long pos, int wc)	Converts a Unicode character into UTF-8, and insert it into the string at the given position.
static GString	len(String init, long len)	Creates a new GString with len bytes of the init buffer.
GString	overwrite(long pos, String val)	Overwrites part of a string, lengthening it if necessary.
GString	overwriteLen(long pos, String val, long len)	Overwrites part of a string, lengthening it if necessary.
GString	prepend(String val)	Adds a string on to the start of a GString, expanding it if necessary.
GString	prependC(byte c)	Adds a byte onto the start of a GString, expanding it if necessary.
GString	prependLen(String val, long len)	Prepends len bytes of val to this String.
GString	prependUnichar(int wc)	Converts a Unicode character into UTF-8, and prepends it to the string.
void	printf(String format, Object... varargs)	Writes a formatted string into a GString.
long	readAllocatedLen()	Read the value of the field allocated_len.
long	readLen()	Read the value of the field len.
String	readStr()	Read the value of the field str.
int	replace(String find, String replace, int limit)	Replaces the string find with the string replace in a GString up to limit times.
GString	setSize(long len)	Sets the length of a GString.
static GString	sizedNew(long dflSize)	Creates a new GString, with enough space for dflSize bytes.
static GString	take(@Nullable String init)	Creates a new GString, initialized with the given string.
GString	truncate(long len)	Cuts off the end of the GString, leaving the first len bytes.
GString	up()	Deprecated. This function uses the locale-specific toupper() function, which is almost never the right thing.
void	writeAllocatedLen(long allocatedLen)	Write a value in the field allocated_len.
void	writeLen(long len)	Write a value in the field len.
void	writeStr(String str, Arena _arena)	Write a value in the field str.

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

GString

public GString(MemorySegment address)

Create a GString proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

GString

public GString(@Nullable
 @Nullable String init)

Creates a new GString, initialized with the given string.

Parameters:

init - the initial text to copy into the string, or null to start with an empty string

GString

public GString()

Calls GString(java.lang.String) with init = null

Method Details

getType

public static Type getType()

Get the GType of the GString class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readStr

public String readStr()

Read the value of the field str.

Returns:

The value of the field str

writeStr

public void writeStr(String str,
 Arena _arena)

Write a value in the field str.

Parameters:

str - The new value for the field str

_arena - to control the memory allocation scope

readLen

public long readLen()

Read the value of the field len.

Returns:

The value of the field len

writeLen

public void writeLen(long len)

Write a value in the field len.

Parameters:

len - The new value for the field len

readAllocatedLen

public long readAllocatedLen()

Read the value of the field allocated_len.

Returns:

The value of the field allocated_len

writeAllocatedLen

public void writeAllocatedLen(long allocatedLen)

Write a value in the field allocated_len.

Parameters:

allocatedLen - The new value for the field allocated_len

len

public static GString len(String init,
 long len)

Creates a new GString with len bytes of the init buffer. Because a length is provided, init need not be nul-terminated, and can contain embedded nul bytes.

Since this function does not stop at nul bytes, it is the caller's responsibility to ensure that init has at least len addressable bytes.

Parameters:

init - initial contents of the string

len - length of init to use

Returns:

a new GString

take

public static GString take(@Nullable
 @Nullable String init)

Creates a new GString, initialized with the given string.

After this call, init belongs to the GString 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().

Parameters:

init - initial text used as the string. Ownership of the string is transferred to the GString. Passing null creates an empty string.

Returns:

the new GString

sizedNew

public static GString sizedNew(long dflSize)

Creates a new GString, with enough space for dflSize bytes. This is useful if you are going to add a lot of text to the string and don't want it to be reallocated too often.

Parameters:

dflSize - the default size of the space allocated to hold the string

Returns:

the new GString

append

public GString append(String val)

Adds a string onto the end of a GString, expanding it if necessary.

Parameters:

val - the string to append onto the end of this String

Returns:

this String

appendC

public GString appendC(byte c)

Adds a byte onto the end of a GString, expanding it if necessary.

Parameters:

c - the byte to append onto the end of this String

Returns:

this String

appendLen

public GString appendLen(String val,
 long len)

Appends len bytes of val to this String.

If len is positive, val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that val has at least len addressable bytes.

If len is negative, val must be nul-terminated and len is considered to request the entire string length. This makes g_string_append_len() equivalent to g_string_append().

Parameters:

val - bytes to append

len - number of bytes of val to use, or -1 for all of val

Returns:

this String

appendPrintf

public void appendPrintf(String format,
 Object... varargs)

Appends a formatted string onto the end of a GString. This function is similar to g_string_printf() except that the text is appended to the GString.

Parameters:

format - the string format. See the printf() documentation

varargs - the parameters to insert into the format string

appendUnichar

public GString appendUnichar(int wc)

Converts a Unicode character into UTF-8, and appends it to the string.

Parameters:

wc - a Unicode character

Returns:

this String

appendUriEscaped

public GString appendUriEscaped(String unescaped,
 String reservedCharsAllowed,
 boolean allowUtf8)

Appends unescaped to this String, escaping any characters that are reserved in URIs using URI-style escape sequences.

Parameters:

unescaped - a string

reservedCharsAllowed - a string of reserved characters allowed to be used, or null

allowUtf8 - set true if the escaped string may include UTF8 characters

Returns:

this String

asciiDown

public GString asciiDown()

Converts all uppercase ASCII letters to lowercase ASCII letters.

Returns:

passed-in this String pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match g_ascii_tolower().

asciiUp

public GString asciiUp()

Converts all lowercase ASCII letters to uppercase ASCII letters.

Returns:

passed-in this String pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match g_ascii_toupper().

assign

public GString assign(String rval)

Copies the bytes from a string into a GString, destroying any previous contents. It is rather like the standard strcpy() function, except that you do not have to worry about having enough space to copy the string.

Parameters:

rval - the string to copy into this String

Returns:

this String

down

@Deprecated
public GString down()

Deprecated.

This function uses the locale-specific tolower() function, which is almost never the right thing. Use g_string_ascii_down() or g_utf8_strdown() instead.

Converts a GString to lowercase.

Returns:

the GString

equal

public boolean equal(GString v2)

Compares two strings for equality, returning true if they are equal. For use with GHashTable.

Parameters:

v2 - another GString

Returns:

true if the strings are the same length and contain the same bytes

erase

public GString erase(long pos,
 long len)

Removes len bytes from a GString, starting at position pos. The rest of the GString is shifted down to fill the gap.

Parameters:

pos - the position of the content to remove

len - the number of bytes to remove, or -1 to remove all following bytes

Returns:

this String

free

public String free(boolean freeSegment)

Frees the memory allocated for the GString. If freeSegment is true it also frees the character data. If it's false, the caller gains ownership of the buffer and must free it after use with g_free().

Instead of passing false to this function, consider using g_string_free_and_steal().

Parameters:

freeSegment - if true, the actual character data is freed as well

Returns:

the character data of this String (i.e. null if freeSegment is true)

freeAndSteal

public String freeAndSteal()

Frees the memory allocated for the GString.

The caller gains ownership of the buffer and must free it after use with g_free().

Returns:

the character data of this String

freeToBytes

public Bytes freeToBytes()

Transfers ownership of the contents of this String to a newly allocated GBytes. The GString structure itself is deallocated, and it is therefore invalid to use this String after invoking this function.

Note that while GString ensures that its buffer always has a trailing nul character (not reflected in its "len"), the returned GBytes does not include this extra nul; i.e. it has length exactly equal to the "len" member.

Returns:

A newly allocated GBytes containing contents of this String; this String itself is freed

hash

public int hash()

Creates a hash code for this String; for use with GHashTable.

Returns:

hash code for this String

insert

public GString insert(long pos,
 String val)

Inserts a copy of a string into a GString, expanding it if necessary.

Parameters:

pos - the position to insert the copy of the string

val - the string to insert

Returns:

this String

insertC

public GString insertC(long pos,
 byte c)

Inserts a byte into a GString, expanding it if necessary.

Parameters:

pos - the position to insert the byte

c - the byte to insert

Returns:

this String

insertLen

public GString insertLen(long pos,
 String val,
 long len)

Inserts len bytes of val into this String at pos.

If len is positive, val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that val has at least len addressable bytes.

If len is negative, val must be nul-terminated and len is considered to request the entire string length.

If pos is -1, bytes are inserted at the end of the string.

Parameters:

pos - position in this String where insertion should happen, or -1 for at the end

val - bytes to insert

len - number of bytes of val to insert, or -1 for all of val

Returns:

this String

insertUnichar

public GString insertUnichar(long pos,
 int wc)

Converts a Unicode character into UTF-8, and insert it into the string at the given position.

Parameters:

pos - the position at which to insert character, or -1 to append at the end of the string

wc - a Unicode character

Returns:

this String

overwrite

public GString overwrite(long pos,
 String val)

Overwrites part of a string, lengthening it if necessary.

Parameters:

pos - the position at which to start overwriting

val - the string that will overwrite the this String starting at pos

Returns:

this String

overwriteLen

public GString overwriteLen(long pos,
 String val,
 long len)

Overwrites part of a string, lengthening it if necessary. This function will work with embedded nuls.

Parameters:

pos - the position at which to start overwriting

val - the string that will overwrite the this String starting at pos

len - the number of bytes to write from val

Returns:

this String

prepend

public GString prepend(String val)

Adds a string on to the start of a GString, expanding it if necessary.

Parameters:

val - the string to prepend on the start of this String

Returns:

this String

prependC

public GString prependC(byte c)

Adds a byte onto the start of a GString, expanding it if necessary.

Parameters:

c - the byte to prepend on the start of the GString

Returns:

this String

prependLen

public GString prependLen(String val,
 long len)

Prepends len bytes of val to this String.

If len is positive, val may contain embedded nuls and need not be nul-terminated. It is the caller's responsibility to ensure that val has at least len addressable bytes.

If len is negative, val must be nul-terminated and len is considered to request the entire string length. This makes g_string_prepend_len() equivalent to g_string_prepend().

Parameters:

val - bytes to prepend

len - number of bytes in val to prepend, or -1 for all of val

Returns:

this String

prependUnichar

public GString prependUnichar(int wc)

Converts a Unicode character into UTF-8, and prepends it to the string.

Parameters:

wc - a Unicode character

Returns:

this String

printf

public void printf(String format,
 Object... varargs)

Writes a formatted string into a GString. This is similar to the standard sprintf() function, except that the GString buffer automatically expands to contain the results. The previous contents of the GString are destroyed.

Parameters:

format - the string format. See the printf() documentation

varargs - the parameters to insert into the format string

replace

public int replace(String find,
 String replace,
 int limit)

Replaces the string find with the string replace in a GString up to limit times. If the number of instances of find in the GString is less than limit, all instances are replaced. If limit is 0, all instances of find are replaced.

If find is the empty string, since versions 2.69.1 and 2.68.4 the replacement will be inserted no more than once per possible position (beginning of string, end of string and between characters). This did not work correctly in earlier versions.

Parameters:

find - the string to find in this String

replace - the string to insert in place of find

limit - the maximum instances of find to replace with replace, or 0 for no limit

Returns:

the number of find and replace operations performed.

setSize

public GString setSize(long len)

Sets the length of a GString. If the length is less than the current length, the string will be truncated. If the length is greater than the current length, the contents of the newly added area are undefined. (However, as always, string->str[string->len] will be a nul byte.)

Parameters:

len - the new length

Returns:

this String

truncate

public GString truncate(long len)

Cuts off the end of the GString, leaving the first len bytes.

Parameters:

len - the new size of this String

Returns:

this String

up

@Deprecated
public GString up()

Deprecated.

This function uses the locale-specific toupper() function, which is almost never the right thing. Use g_string_ascii_up() or g_utf8_strup() instead.

Converts a GString to uppercase.

Returns:

this String