From 70f533febf18d9241f067730bf5c5b1d13cb17fd Mon Sep 17 00:00:00 2001 From: Arnaud Le Blanc Date: Fri, 8 Jul 2022 12:49:46 +0200 Subject: [PATCH 1/3] smart_str: mention smart_str_extract() --- .../php7/internal_types/strings/smart_str.rst | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/Book/php7/internal_types/strings/smart_str.rst b/Book/php7/internal_types/strings/smart_str.rst index 60ffdfe8..60b6533f 100644 --- a/Book/php7/internal_types/strings/smart_str.rst +++ b/Book/php7/internal_types/strings/smart_str.rst @@ -70,6 +70,21 @@ parameter you'll use:: /* Don't forget to release/free it */ smart_str_free(&my_str); +We can also use the embedded ``zend_string`` independently of the ``smart_str``:: + + smart_str my_str = {0}; + + smart_str_appends(&my_str, "Hello, you are using PHP version "); + smart_str_appends(&my_str, PHP_VERSION); + + zend_string *str = smart_str_extract(my_str); + RETURN_STRING(str); + + /* We don't need to free my_str in this case */ + +``smart_str_extract()`` returns a pre-allocated empty string if ``smart_str.s`` +is ``NULL``. Otherwise, it adds a trailing *NUL* byte and trims the allocated +memory to the string size. We used here the simple API, the extended one ends with ``_ex()``, and allows you to tell if you want a persistent or a request-bound allocation for the underlying ``zend_string``. Example:: @@ -92,7 +107,11 @@ smart_str specific tricks * Never forget to finish your string with a call to ``smart_str_0()``. That puts a *NUL* char at the end of the embed string and make it compatible with libc string functions. * Never forget to free your string, with ``smart_str_free()``, once you're done with it. -* ``smart_str`` embeds a ``zend_string``, and then allows you to share that later elsewhere playing with its reference +* Use ``smart_str_extract()`` to get a standalone ``zend_string`` when you have + finished building the string. This takes care of calling ``smart_str_0()``, + and of optimizing allocations. In this case, calling ``smart_str_free()`` is + not necessary. +* You can share the standalone ``zend_string`` later elsewhere playing with its reference counter. Please, visit the :doc:`zend_string dedicated chapter ` to know more about it. * You can play with ``smart_str`` allocations. Look at ``smart_str_alloc()`` and friends. * ``smart_str`` is heavily used into PHP's heart. For example, PHP's From eb160d82040b6046387a16299dc08b6e0192b720 Mon Sep 17 00:00:00 2001 From: Arnaud Le Blanc Date: Fri, 2 Sep 2022 13:26:51 +0200 Subject: [PATCH 2/3] Update Book/php7/internal_types/strings/smart_str.rst Co-authored-by: George Peter Banyard --- Book/php7/internal_types/strings/smart_str.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Book/php7/internal_types/strings/smart_str.rst b/Book/php7/internal_types/strings/smart_str.rst index 60b6533f..8475eb4a 100644 --- a/Book/php7/internal_types/strings/smart_str.rst +++ b/Book/php7/internal_types/strings/smart_str.rst @@ -78,7 +78,7 @@ We can also use the embedded ``zend_string`` independently of the ``smart_str``: smart_str_appends(&my_str, PHP_VERSION); zend_string *str = smart_str_extract(my_str); - RETURN_STRING(str); + RETURN_STR(str); /* We don't need to free my_str in this case */ From 2ca88f006c7d0279758f4561e91874a6015f47ae Mon Sep 17 00:00:00 2001 From: Arnaud Le Blanc Date: Fri, 2 Sep 2022 13:27:12 +0200 Subject: [PATCH 3/3] Update Book/php7/internal_types/strings/smart_str.rst Co-authored-by: Christoph M. Becker --- Book/php7/internal_types/strings/smart_str.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Book/php7/internal_types/strings/smart_str.rst b/Book/php7/internal_types/strings/smart_str.rst index 8475eb4a..c5569f61 100644 --- a/Book/php7/internal_types/strings/smart_str.rst +++ b/Book/php7/internal_types/strings/smart_str.rst @@ -80,7 +80,7 @@ We can also use the embedded ``zend_string`` independently of the ``smart_str``: zend_string *str = smart_str_extract(my_str); RETURN_STR(str); - /* We don't need to free my_str in this case */ + /* We must not free my_str in this case */ ``smart_str_extract()`` returns a pre-allocated empty string if ``smart_str.s`` is ``NULL``. Otherwise, it adds a trailing *NUL* byte and trims the allocated