Skip to content

/doc/core/: document zend_string APIs #21642

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LamentXU123 wants to merge 6 commits into
base: master
Choose a base branch
from
+194 −26
Open

/doc/core/: document zend_string APIs #21642

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
38ba41e
Update zend_string.rst
LamentXU123 Apr 5, 2026
a54419a
small fixes
LamentXU123 Apr 5, 2026
b7f5c84
fix doc ci
LamentXU123 Apr 5, 2026
629ec16
adjust sequence
LamentXU123 Apr 6, 2026
a576f8d
Update zend_string.rst
LamentXU123 Apr 6, 2026
f21f2cf
Update zend_string.rst
LamentXU123 Apr 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
small fixes
  • Loading branch information
@LamentXU123
LamentXU123 committed Apr 5, 2026
commit a54419acaeba9c3b58bccc3dc974597d87fd5ade
26 changes: 17 additions & 9 deletions docs/source/core/data-structures/zend_string.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ hashing, and interning helpers.
- - ``zend_string_concat2(s1, l1, s2, l2)``
- Creates a non-persistent string by concatenating two character buffers.

- - ``zend_string_concat3(...)``
- - ``zend_string_concat3(s1, l1, s2, l2, s3, l3)``
- Same as ``zend_string_concat2``, but for three character buffers.

- - ``ZSTR_EMPTY_ALLOC()``
Expand All @@ -116,11 +116,13 @@ hashing, and interning helpers.
- Description

- - ``zend_string_realloc(s, l, p)``
- Resizes a string to length ``l``. May return a different pointer. If shared/interned, a new
allocation is created.
- Changes the size of the string. If the string has a reference count greater than 1 or if
the string is interned, a new string is created. You must always use the return value of
this function, as the original array may have been moved to a new location in memory.

- - ``zend_string_safe_realloc(s, n, m, l, p)``
- Resizes a string to ``n * m + l`` bytes with overflow checks.
- Resizes a string to ``n * m + l`` bytes with overflow checks. Allocates a string of
length ``n * m + l``. This function is commonly useful for encoding changes.

- - ``zend_string_extend(s, l, p)``
- Extends a string to a larger length (``l >= ZSTR_LEN(s)``).
Expand Down Expand Up @@ -194,7 +196,9 @@ strings.
- Returns the reference count. Interned strings always report ``1``.

- - ``zend_string_addref(s)``
- Increments the reference count of a non-interned string.
- Increments the reference count of a non-interned string. the function that is used
most often by far is zend_string_copy(). This function not only increments the refcount,
but also returns the original string. This makes code more readable in practice.

- - ``zend_string_delref(s)``
- Decrements the reference count of a non-interned string.
Expand All @@ -203,14 +207,18 @@ strings.
- Decreases the reference count and frees the string if it goes to 0.

- - ``zend_string_release_ex(s, p)``
- Like ``zend_string_release()``, but chooses the deallocator from ``p``. Use only if the
persistence mode is known by the caller.
- Like ``zend_string_release()``, but allows you to specify whether the passed string is
persistent or non-persistent. If it is persistent, ``p`` should be ``0``.

- - ``zend_string_free(s)``
- Frees a non-interned string directly. The caller must ensure it is no longer shared.
Requires refcount 1 or immutable.You should avoid using these functions, as it is
easy to introduce critical bugs when some API changes from returning new strings to
reusing existing ones.

- - ``zend_string_efree(s)``
- Frees a non-persistent, non-interned string with ``efree``.
- Similar to ``zend_string_free``. Frees a non-persistent, non-interned string
with ``efree``. Requires refcount 1 and not immutable.

There are various functions to compare strings.

Expand Down Expand Up @@ -314,7 +322,7 @@ There are various functions to compare strings.
- Same as ``ZSTR_ALLOCA_ALLOC``, then copies data from ``s`` and appends ``'\0'``.

- - ``ZSTR_ALLOCA_FREE(str, use_heap)``
- Frees memory previously allocated with ``ZSTR_ALLOCA_ALLOC``/``ZSTR_ALLOCA_INIT``.
- Frees memory previously allocated with ``ZSTR_ALLOCA_ALLOC`` / ``ZSTR_ALLOCA_INIT``.

.. list-table:: Interned string APIs
Comment thread
LamentXU123 marked this conversation as resolved.
:header-rows: 1
Expand Down
Loading