smart_str: mention smart_str_extract()

[arnaud-lb]

This mentions smart_str_extract() in the smart_str page.

smart_str uses an over-allocated string to optimize for append operations. Functions that use smart_str tend to return the over-allocated string directly. This results in unnecessary memory usage, especially for small strings.

The overhead can be up to 231 bytes for strings smaller than that, and 4095 for other strings. This can be avoided for strings smaller than 4096 - zend_string header size - 1 by reallocating the string.

https://github.com/php/php-src/pull/8902 introduces smart_str_trim_to_size(), and calls it in smart_str_extract().

There are other benefits in using smart_str_extract() over accessing .s directly:

• It will return an empty string if .s is null
• It takes car of the trailing NUL byte
• It resets .s to NULL