<GString>

<GString>

Description

The GString struct contains the public fields of a GString.

Functions

append

(define-values (%return) (string:append self val))

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

Parameters

string

a GString

Passed as self

val

the string to append onto the end of string

Passed as val

append-c

(define-values (%return) (string:append-c self c))

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

Parameters

string

a GString

Passed as self

c

the byte to append onto the end of string

Passed as c

append-len

(define-values (%return) (string:append-len self val 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

string

a GString

Passed as self

val

bytes to append

Passed as val

len

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

Passed as len

append-unichar

(define-values (%return) (string:append-unichar self wc))

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

Parameters

string

a GString

Passed as self

wc

a Unicode character

Passed as wc

append-uri-escaped

(define-values
  (%return)
  (string:append-uri-escaped self unescaped reserved-chars-allowed allow-utf8))

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

Parameters

string

a GString

Passed as self

unescaped

a string

Passed as unescaped

reserved_chars_allowed

a string of reserved characters allowed to be used, or NULL

Passed as reserved-chars-allowed

allow_utf8

set TRUE if the escaped string may include UTF8 characters

Passed as allow-utf8

ascii-down

(define-values (%return) (string:ascii-down self))

Converts all uppercase ASCII letters to lowercase ASCII letters.

Parameters

string

a GString

Passed as self

ascii-up

(define-values (%return) (string:ascii-up self))

Converts all lowercase ASCII letters to uppercase ASCII letters.

Parameters

string

a GString

Passed as self

assign

(define-values (%return) (string:assign self 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

string

the destination GString. Its current contents are destroyed.

Passed as self

rval

the string to copy into string

Passed as rval

down

(define-values (%return) (string:down self))

Converts a GString to lowercase.

Parameters

string

a GString

Passed as self

equal?

(define-values (%return) (string:equal? self v2))

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

Parameters

v

a GString

Passed as self

v2

another GString

Passed as v2

erase

(define-values (%return) (string:erase self pos len))

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

Parameters

string

a GString

Passed as self

pos

the position of the content to remove

Passed as pos

len

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

Passed as len

free

(define-values (%return) (string:free self free-segment))

Frees the memory allocated for the GString. If free_segment 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().

Parameters

string

a GString

Passed as self

free_segment

if TRUE, the actual character data is freed as well

Passed as free-segment

free-to-bytes

(define-values (%return) (string:free-to-bytes self))

Transfers ownership of the contents of string to a newly allocated GBytes. The GString structure itself is deallocated, and it is therefore invalid to use 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.

Parameters

string

a GString

Passed as self

hash

(define-values (%return) (string:hash self))

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

Parameters

str

a string to hash

Passed as self

insert

(define-values (%return) (string:insert self pos val))

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

Parameters

string

a GString

Passed as self

pos

the position to insert the copy of the string

Passed as pos

val

the string to insert

Passed as val

insert-c

(define-values (%return) (string:insert-c self pos c))

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

Parameters

string

a GString

Passed as self

pos

the position to insert the byte

Passed as pos

c

the byte to insert

Passed as c

insert-len

(define-values (%return) (string:insert-len self pos val len))

Inserts len bytes of val into 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

string

a GString

Passed as self

pos

position in string where insertion should happen, or -1 for at the end

Passed as pos

val

bytes to insert

Passed as val

len

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

Passed as len

insert-unichar

(define-values (%return) (string:insert-unichar self pos wc))

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

Parameters

string

a GString

Passed as self

pos

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

Passed as pos

wc

a Unicode character

Passed as wc

overwrite

(define-values (%return) (string:overwrite self pos val))

Overwrites part of a string, lengthening it if necessary.

Parameters

string

a GString

Passed as self

pos

the position at which to start overwriting

Passed as pos

val

the string that will overwrite the string starting at pos

Passed as val

overwrite-len

(define-values (%return) (string:overwrite-len self pos val len))

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

Parameters

string

a GString

Passed as self

pos

the position at which to start overwriting

Passed as pos

val

the string that will overwrite the string starting at pos

Passed as val

len

the number of bytes to write from val

Passed as len

prepend

(define-values (%return) (string:prepend self val))

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

Parameters

string

a GString

Passed as self

val

the string to prepend on the start of string

Passed as val

prepend-c

(define-values (%return) (string:prepend-c self c))

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

Parameters

string

a GString

Passed as self

c

the byte to prepend on the start of the GString

Passed as c

prepend-len

(define-values (%return) (string:prepend-len self val 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

string

a GString

Passed as self

val

bytes to prepend

Passed as val

len

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

Passed as len

prepend-unichar

(define-values (%return) (string:prepend-unichar self wc))

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

Parameters

string

a GString

Passed as self

wc

a Unicode character

Passed as wc

replace

(define-values (%return) (string:replace self find replace limit))

Undocumented

Parameters

string

Passed as self

find

Passed as find

replace

Passed as replace

limit

Passed as limit

set-size

(define-values (%return) (string:set-size self 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

string

a GString

Passed as self

len

the new length

Passed as len

truncate

(define-values (%return) (string:truncate self len))

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

Parameters

string

a GString

Passed as self

len

the new size of string

Passed as len

up

(define-values (%return) (string:up self))

Converts a GString to uppercase.

Parameters

string

a GString

Passed as self