:right-sidebar: True String =================================================================== .. currentmodule:: gi.repository.GLib .. class:: String(*args, **kwargs) :no-contents-entry: 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. Constructors ------------ .. rst-class:: interim-class .. class:: String :no-index: .. classmethod:: new(init: str | None = None) -> ~gi.repository.GLib.String Creates a new :obj:`~gi.repository.GLib.String`\, initialized with the given string. :param init: the initial text to copy into the string, or :const:`None` to start with an empty string .. classmethod:: new_len(init: str, len: int) -> ~gi.repository.GLib.String Creates a new :obj:`~gi.repository.GLib.String` 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. :param init: initial contents of the string :param len: length of ``init`` to use .. classmethod:: new_take(init: str | None = None) -> ~gi.repository.GLib.String Creates a new :obj:`~gi.repository.GLib.String`\, initialized with the given string. After this call, ``init`` belongs to the :obj:`~gi.repository.GLib.String` and may no longer be modified by the caller. The memory of ``data`` has to be dynamically allocated and will eventually be freed with :func:`~gi.repository.GLib.free`. .. versionadded:: 2.78 :param init: initial text used as the string. Ownership of the string is transferred to the :obj:`~gi.repository.GLib.String`\. Passing :const:`None` creates an empty string. .. classmethod:: sized_new(dfl_size: int) -> ~gi.repository.GLib.String Creates a new :obj:`~gi.repository.GLib.String`\, with enough space for ``dfl_size`` 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. :param dfl_size: the default size of the space allocated to hold the string Methods ------- .. rst-class:: interim-class .. class:: String :no-index: .. method:: append(val: str) -> ~gi.repository.GLib.String Adds a string onto the end of a :obj:`~gi.repository.GLib.String`\, expanding it if necessary. :param val: the string to append onto the end of ``string`` .. method:: append_c(c: int) -> ~gi.repository.GLib.String Adds a byte onto the end of a :obj:`~gi.repository.GLib.String`\, expanding it if necessary. :param c: the byte to append onto the end of ``string`` .. method:: append_len(val: str, len: int) -> ~gi.repository.GLib.String 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 :func:`~gi.repository.GLib.String.append_len` equivalent to :func:`~gi.repository.GLib.String.append`. :param val: bytes to append :param len: number of bytes of ``val`` to use, or -1 for all of ``val`` .. method:: append_unichar(wc: str) -> ~gi.repository.GLib.String Converts a Unicode character into UTF-8, and appends it to the string. :param wc: a Unicode character .. method:: append_uri_escaped(unescaped: str, reserved_chars_allowed: str, allow_utf8: bool) -> ~gi.repository.GLib.String Appends ``unescaped`` to ``string``\, escaping any characters that are reserved in URIs using URI-style escape sequences. .. versionadded:: 2.16 :param unescaped: a string :param reserved_chars_allowed: a string of reserved characters allowed to be used, or :const:`None` :param allow_utf8: set :const:`True` if the escaped string may include UTF8 characters .. method:: ascii_down() -> ~gi.repository.GLib.String Converts all uppercase ASCII letters to lowercase ASCII letters. .. method:: ascii_up() -> ~gi.repository.GLib.String Converts all lowercase ASCII letters to uppercase ASCII letters. .. method:: assign(rval: str) -> ~gi.repository.GLib.String Copies the bytes from a string into a :obj:`~gi.repository.GLib.String`\, 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. :param rval: the string to copy into ``string`` .. method:: down() -> ~gi.repository.GLib.String Converts a :obj:`~gi.repository.GLib.String` to lowercase. .. deprecated:: 2.2 This function uses the locale-specific tolower() function, which is almost never the right thing. Use :func:`~gi.repository.GLib.String.ascii_down` or :func:`~gi.repository.GLib.utf8_strdown` instead. .. method:: equal(v2: ~gi.repository.GLib.String) -> bool Compares two strings for equality, returning :const:`True` if they are equal. For use with :obj:`~gi.repository.GLib.HashTable`\. :param v2: another :obj:`~gi.repository.GLib.String` .. method:: erase(pos: int, len: int) -> ~gi.repository.GLib.String Removes ``len`` bytes from a :obj:`~gi.repository.GLib.String`\, starting at position ``pos``\. The rest of the :obj:`~gi.repository.GLib.String` is shifted down to fill the gap. :param pos: the position of the content to remove :param len: the number of bytes to remove, or -1 to remove all following bytes .. method:: free(free_segment: bool) -> str | None Frees the memory allocated for the :obj:`~gi.repository.GLib.String`\. If ``free_segment`` is :const:`True` it also frees the character data. If it's :const:`False`, the caller gains ownership of the buffer and must free it after use with :func:`~gi.repository.GLib.free`. Instead of passing :const:`False` to this function, consider using :func:`~gi.repository.GLib.String.free_and_steal`. :param free_segment: if :const:`True`, the actual character data is freed as well .. method:: free_to_bytes() -> ~gi.repository.GLib.Bytes Transfers ownership of the contents of ``string`` to a newly allocated :obj:`~gi.repository.GLib.Bytes`\. The :obj:`~gi.repository.GLib.String` structure itself is deallocated, and it is therefore invalid to use ``string`` after invoking this function. Note that while :obj:`~gi.repository.GLib.String` ensures that its buffer always has a trailing nul character (not reflected in its "len"), the returned :obj:`~gi.repository.GLib.Bytes` does not include this extra nul; i.e. it has length exactly equal to the "len" member. .. versionadded:: 2.34 .. method:: hash() -> int Creates a hash code for ``str``\; for use with :obj:`~gi.repository.GLib.HashTable`\. .. method:: insert(pos: int, val: str) -> ~gi.repository.GLib.String Inserts a copy of a string into a :obj:`~gi.repository.GLib.String`\, expanding it if necessary. :param pos: the position to insert the copy of the string :param val: the string to insert .. method:: insert_c(pos: int, c: int) -> ~gi.repository.GLib.String Inserts a byte into a :obj:`~gi.repository.GLib.String`\, expanding it if necessary. :param pos: the position to insert the byte :param c: the byte to insert .. method:: insert_len(pos: int, val: str, len: int) -> ~gi.repository.GLib.String 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. :param pos: position in ``string`` where insertion should happen, or -1 for at the end :param val: bytes to insert :param len: number of bytes of ``val`` to insert, or -1 for all of ``val`` .. method:: insert_unichar(pos: int, wc: str) -> ~gi.repository.GLib.String Converts a Unicode character into UTF-8, and insert it into the string at the given position. :param pos: the position at which to insert character, or -1 to append at the end of the string :param wc: a Unicode character .. method:: overwrite(pos: int, val: str) -> ~gi.repository.GLib.String Overwrites part of a string, lengthening it if necessary. .. versionadded:: 2.14 :param pos: the position at which to start overwriting :param val: the string that will overwrite the ``string`` starting at ``pos`` .. method:: overwrite_len(pos: int, val: str, len: int) -> ~gi.repository.GLib.String Overwrites part of a string, lengthening it if necessary. This function will work with embedded nuls. .. versionadded:: 2.14 :param pos: the position at which to start overwriting :param val: the string that will overwrite the ``string`` starting at ``pos`` :param len: the number of bytes to write from ``val`` .. method:: prepend(val: str) -> ~gi.repository.GLib.String Adds a string on to the start of a :obj:`~gi.repository.GLib.String`\, expanding it if necessary. :param val: the string to prepend on the start of ``string`` .. method:: prepend_c(c: int) -> ~gi.repository.GLib.String Adds a byte onto the start of a :obj:`~gi.repository.GLib.String`\, expanding it if necessary. :param c: the byte to prepend on the start of the :obj:`~gi.repository.GLib.String` .. method:: prepend_len(val: str, len: int) -> ~gi.repository.GLib.String 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 :func:`~gi.repository.GLib.String.prepend_len` equivalent to :func:`~gi.repository.GLib.String.prepend`. :param val: bytes to prepend :param len: number of bytes in ``val`` to prepend, or -1 for all of ``val`` .. method:: prepend_unichar(wc: str) -> ~gi.repository.GLib.String Converts a Unicode character into UTF-8, and prepends it to the string. :param wc: a Unicode character .. method:: replace(find: str, replace: str, limit: int) -> int Replaces the string ``find`` with the string ``replace`` in a :obj:`~gi.repository.GLib.String` up to ``limit`` times. If the number of instances of ``find`` in the :obj:`~gi.repository.GLib.String` 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. .. versionadded:: 2.68 :param find: the string to find in ``string`` :param replace: the string to insert in place of ``find`` :param limit: the maximum instances of ``find`` to replace with ``replace``\, or ``0`` for no limit .. method:: set_size(len: int) -> ~gi.repository.GLib.String Sets the length of a :obj:`~gi.repository.GLib.String`\. 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.) :param len: the new length .. method:: truncate(len: int) -> ~gi.repository.GLib.String Cuts off the end of the GString, leaving the first ``len`` bytes. :param len: the new size of ``string`` .. method:: up() -> ~gi.repository.GLib.String Converts a :obj:`~gi.repository.GLib.String` to uppercase. .. deprecated:: 2.2 This function uses the locale-specific toupper() function, which is almost never the right thing. Use :func:`~gi.repository.GLib.String.ascii_up` or :func:`~gi.repository.GLib.utf8_strup` instead. Fields ------ .. rst-class:: interim-class .. class:: String :no-index: .. attribute:: allocated_len The number of bytes that can be stored in the string before it needs to be reallocated. May be larger than ``len``\. .. attribute:: len Contains the length of the string, not including the terminating nul byte. .. attribute:: str Points to the character data. It may move as text is added. The ``str`` field is null-terminated and so can be used as an ordinary C string.