Class GString

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.glib.GString

All Implemented Interfaces:

Proxy

@Generated("org.javagi.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(@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
String	append(String val)	Adds a string onto the end of a GString, expanding it if necessary.
String	appendC(byte c)	Adds a byte onto the end of a GString, expanding it if necessary.
String	appendLen(String val, long len)	Appends len bytes of val to string.
void	appendPrintf(String format, Object... varargs)	Appends a formatted string onto the end of a GString.
String	appendUnichar(int wc)	Converts a Unicode character into UTF-8, and appends it to the string.
String	appendUriEscaped(String unescaped, String reservedCharsAllowed, boolean allowUtf8)	Appends unescaped to string, escaping any characters that are reserved in URIs using URI-style escape sequences.
String	asciiDown()	Converts all uppercase ASCII letters to lowercase ASCII letters.
String	asciiUp()	Converts all lowercase ASCII letters to uppercase ASCII letters.
String	assign(String rval)	Copies the bytes from a string into a GString, destroying any previous contents.
String	copy()	Copies the GLib.String instance and its contents.
String	down()	Deprecated. This function uses the locale-specific tolower() function, which is almost never the right thing.
boolean	equal(String v2)	Compares two strings for equality, returning true if they are equal.
String	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.
@Nullable String	free(boolean freeSegment)	Frees the memory allocated for the GString.
String	freeAndSteal()	Frees the memory allocated for the GString.
byte[]	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 @Nullable Type	getType()	Get the GType of the GString class.
int	hash()	Creates a hash code for str; for use with GHashTable.
String	insert(long pos, String val)	Inserts a copy of a string into a GString, expanding it if necessary.
String	insertC(long pos, byte c)	Inserts a byte into a GString, expanding it if necessary.
String	insertLen(long pos, String val, long len)	Inserts len bytes of val into this String at pos.
String	insertUnichar(long pos, int wc)	Converts a Unicode character into UTF-8, and insert it into the string at the given position.
static String	len(String init, long len)	Creates a new GString with len bytes of the init buffer.
String	overwrite(long pos, String val)	Overwrites part of a string, lengthening it if necessary.
String	overwriteLen(long pos, String val, long len)	Overwrites part of a string, lengthening it if necessary.
String	prepend(String val)	Adds a string on to the start of a GString, expanding it if necessary.
String	prependC(byte c)	Adds a byte onto the start of a GString, expanding it if necessary.
String	prependLen(String val, long len)	Prepends len bytes of val to string.
String	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.
String	setSize(long len)	Sets the length of a GString.
static String	sizedNew(long dflSize)	Creates a new GString, with enough space for dflSize bytes.
static String	take(@Nullable String init)	Creates a new GString, initialized with the given string.
String	truncate(long len)	Cuts off the end of the GString, leaving the first len bytes.
String	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 ProxyInstance

equals, handle, hashCode

Methods inherited from class 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 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

Method Details

getType

public static @Nullable 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 String 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 String take(@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 init 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

Since:

2.78

sizedNew

public static String 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 String 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 String 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 String appendLen(String val,
 long len)

Appends len bytes of val to 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 String 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 String appendUriEscaped(String unescaped,
 String reservedCharsAllowed,
 boolean allowUtf8)

Appends unescaped to 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

Since:

2.16

asciiDown

public String 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 String 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 String 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

copy

public String copy()

Copies the GLib.String instance and its contents.

This will preserve the allocation length of the GLib.String in the copy.

Returns:

a copy of this String

Since:

2.86

down

@Deprecated
public String 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(String 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 String 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 @Nullable 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

Since:

2.76

freeToBytes

public byte[] 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 string; this String itself is freed

Since:

2.34

hash

public int hash()

Creates a hash code for str; for use with GHashTable.

Returns:

hash code for this String

insert

public String 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 String 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 String 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 String 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 String 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

Since:

2.14

overwriteLen

public String 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

Since:

2.14

prepend

public String 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 String 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 String prependLen(String val,
 long len)

Prepends len bytes of val to 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 String 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.

If limit is zero and more than G_MAXUINT instances of find are in the input string, they will all be replaced, but the return value will be capped at G_MAXUINT.

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, up to G_MAXUINT

Since:

2.68

setSize

public String 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 String 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 String 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