:right-sidebar: True

StringChunk
===================================================================

.. currentmodule:: gi.repository.GLib





.. class:: StringChunk(*args, **kwargs)
   :no-contents-entry:






``GStringChunk`` provides efficient storage of groups of strings

String chunks are used to store groups of strings. Memory is
allocated in blocks, and as strings are added to the ``GStringChunk``
they are copied into the next free position in a block. When a block
is full a new block is allocated.

When storing a large number of strings, string chunks are more
efficient than using :obj:`~gi.repository.GLib.strdup` since fewer calls to ``malloc()``
are needed, and less memory is wasted in memory allocation overheads.

By adding strings with :obj:`~gi.repository.GLib.StringChunk.insert_const` it is also
possible to remove duplicates.

To create a new ``GStringChunk`` use :obj:`~gi.repository.GLib.StringChunk.new`\.

To add strings to a ``GStringChunk`` use :obj:`~gi.repository.GLib.StringChunk.insert`\.

To add strings to a ``GStringChunk``\, but without duplicating strings
which are already in the ``GStringChunk``\, use :obj:`~gi.repository.GLib.StringChunk.insert_const`\.

To free the entire ``GStringChunk`` use :obj:`~gi.repository.GLib.StringChunk.free`\.
It is not possible to free individual strings.




Methods
-------

.. rst-class:: interim-class

.. class:: StringChunk
   :no-index:


   .. method:: clear() -> None

      Frees all strings contained within the :obj:`~gi.repository.GLib.StringChunk`\.
      After calling :func:`~gi.repository.GLib.StringChunk.clear` it is not safe to
      access any of the strings which were contained within it.


      .. versionadded:: 2.14








   .. method:: free() -> None

      Frees all memory allocated by the :obj:`~gi.repository.GLib.StringChunk`\.
      After calling :func:`~gi.repository.GLib.StringChunk.free` it is not safe to
      access any of the strings which were contained within it.









   .. method:: insert(string: str) -> str

      Adds a copy of ``string`` to the :obj:`~gi.repository.GLib.StringChunk`\.
      It returns a pointer to the new copy of the string
      in the :obj:`~gi.repository.GLib.StringChunk`\. The characters in the string
      can be changed, if necessary, though you should not
      change anything after the end of the string.

      Unlike :func:`~gi.repository.GLib.StringChunk.insert_const`, this function
      does not check for duplicates. Also strings added
      with :func:`~gi.repository.GLib.StringChunk.insert` will not be searched
      by :func:`~gi.repository.GLib.StringChunk.insert_const` when looking for
      duplicates.






      :param string: the string to add




   .. method:: insert_const(string: str) -> str

      Adds a copy of ``string`` to the :obj:`~gi.repository.GLib.StringChunk`\, unless the same
      string has already been added to the :obj:`~gi.repository.GLib.StringChunk` with
      :func:`~gi.repository.GLib.StringChunk.insert_const`.

      This function is useful if you need to copy a large number
      of strings but do not want to waste space storing duplicates.
      But you must remember that there may be several pointers to
      the same string, and so any changes made to the strings
      should be done very carefully.

      Note that :func:`~gi.repository.GLib.StringChunk.insert_const` will not return a
      pointer to a string added with :func:`~gi.repository.GLib.StringChunk.insert`, even
      if they do match.






      :param string: the string to add




   .. method:: insert_len(string: str, len: int) -> str

      Adds a copy of the first ``len`` bytes of ``string`` to the :obj:`~gi.repository.GLib.StringChunk`\.
      The copy is nul-terminated.

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

      The characters in the returned string can be changed, if necessary,
      though you should not change anything after the end of the string.


      .. versionadded:: 2.4





      :param string: bytes to insert

      :param len: number of bytes of ``string`` to insert, or -1 to insert a
             nul-terminated string