<?php
// ==============================
//            CONTENTS            
// ==============================
// PHP_TEXT_STRINGS - BEGIN
// PHP_TEXT_STRINGS_ADDCSLASHES - string php_text_strings_addcslashes(string $string, string $characters)
// PHP_TEXT_STRINGS_ADDSLASHES - string php_text_strings_addslashes(string $string)
// PHP_TEXT_STRINGS_BIN2HEX - string php_text_strings_bin2hex(string $string)
// PHP_TEXT_STRINGS_CHOP - string php_text_strings_chop(string $string, string $characters = " \n\r\t\v\x00")
// PHP_TEXT_STRINGS_CHR - string php_text_strings_chr(int $codepoint)
// PHP_TEXT_STRINGS_CHUNK_SPLIT - string php_text_strings_chunk_split(string $string, int $length = 76, string $separator = "\r\n")
// OFFLINE | PHP_TEXT_STRINGS_CONVERT_CYR_STRING - string php_text_strings_convert_cyr_string(string $str, string $from, string $to)
// OFFLINE | PHP_TEXT_STRINGS_CONVERT_UUDECODE - string|false php_text_strings_convert_uudecode(string $string)
// OFFLINE | PHP_TEXT_STRINGS_CONVERT_UUENCODE - string php_text_strings_convert_uuencode(string $string)
// PHP_TEXT_STRINGS_COUNT_CHARS - array|string php_text_strings_count_chars(string $string, int $mode = 0)
// PHP_TEXT_STRINGS_CRC32 - int php_text_strings_crc32(string $string)
// PHP_TEXT_STRINGS_CRYPT - string php_text_strings_crypt(string $string, string $salt)
// PHP_TEXT_STRINGS_ECHO - void php_text_strings_echo(string $expressions)
// PHP_TEXT_STRINGS_EXPLODE - array php_text_strings_explode(string $separator, string $string, int $limit = PHP_INT_MAX)
// OFFLINE | PHP_TEXT_STRINGS_FPRINTF - int php_text_strings_fprintf(resource $stream, string $format, mixed $values)
// PHP_TEXT_STRINGS_GET_HTML_TRANSLATION_TABLE - array php_text_strings_get_html_translation_table(int $table, int $flags, string $encoding = "UTF-8")
// PHP_TEXT_STRINGS_HEBREV - string php_text_strings_hebrev(string $string, int $max_chars_per_line = 0)
// OFFLINE | PHP_TEXT_STRINGS_HEBREVC - string php_text_strings_hebrevc(string $hebrew_text, int $max_chars_per_line = 0)
// OFFLINE | PHP_TEXT_STRINGS_HEX2BIN - string|false php_text_strings_hex2bin(string $string)
// PHP_TEXT_STRINGS_HTML_ENTITY_DECODE - string php_text_strings_html_entity_decode(string $string, int $flags, string $encoding = null)
// PHP_TEXT_STRINGS_HTMLENTITIES - string php_text_strings_htmlentities(string $string, int $flags, string $encoding = null, bool $double_encode = true)
// OFFLINE | PHP_TEXT_STRINGS_HTMLSPECIALCHARS_DECODE - string php_text_strings_htmlspecialchars_decode(string $string, int $flags)
// PHP_TEXT_STRINGS_HTMLSPECIALCHARS - string php_text_strings_htmlspecialchars(string $string, int $flags, string $encoding = null, bool $double_encode = true)
// OFFLINE | PHP_TEXT_STRINGS_IMPLODE - string php_text_strings_implode(array $array, string $separator)
// OFFLINE | PHP_TEXT_STRINGS_JOIN - string php_text_strings_join(array $array, string $separator)
// OFFLINE | PHP_TEXT_STRINGS_LCFIRST - string php_text_strings_lcfirst(string $string)
// PHP_TEXT_STRINGS_LEVENSHTEIN - int php_text_strings_levenshtein(string $string1, string $string2, int $insertion_cost = 1, int $replacement_cost = 1, int $deletion_cost = 1)
// PHP_TEXT_STRINGS_LOCALECONV - array php_text_strings_localeconv()
// PHP_TEXT_STRINGS_LTRIM - string php_text_strings_ltrim(string $string, string $characters = " \n\r\t\v\x00")
// PHP_TEXT_STRINGS_MD5_FILE - string|false php_text_strings_md5_file(string $filename, bool $binary = false)
// PHP_TEXT_STRINGS_MD5 - string php_text_strings_md5(string $string, bool $binary = false)
// PHP_TEXT_STRINGS_METAPHONE - string php_text_strings_metaphone(string $string, int $max_phonemes = 0)
// OFFLINE | PHP_TEXT_STRINGS_MONEY_FORMAT - string php_text_strings_money_format(string $format, float $number)
// PHP_TEXT_STRINGS_NL_LANGINFO - string|false php_text_strings_nl_langinfo(int $item)
// PHP_TEXT_STRINGS_NL2BR - string php_text_strings_nl2br(string $string, bool $use_xhtml = true)
// PHP_TEXT_STRINGS_NUMBER_FORMAT - string php_text_strings_number_format(float $num, int $decimals = 0, string $decimal_separator = ".", string $thousands_separator = ",")
// PHP_TEXT_STRINGS_ORD - int php_text_strings_ord(string $character)
// PHP_TEXT_STRINGS_PARSE_STR - void php_text_strings_parse_str(string $string, array& $result)
// PHP_TEXT_STRINGS_PRINT - int php_text_strings_print(string $expression)
// PHP_TEXT_STRINGS_PRINTF - int php_text_strings_printf(string $format, mixed $values)
// PHP_TEXT_STRINGS_QUOTED_PRINTABLE_DECODE - string php_text_strings_quoted_printable_decode(string $string)
// OFFLINE | PHP_TEXT_STRINGS_QUOTED_PRINTABLE_ENCODE - string php_text_strings_quoted_printable_encode(string $string)
// PHP_TEXT_STRINGS_QUOTEMETA - string php_text_strings_quotemeta(string $string)
// PHP_TEXT_STRINGS_RTRIM - string php_text_strings_rtrim(string $string, string $characters = " \n\r\t\v\x00")
// PHP_TEXT_STRINGS_SETLOCALE - string|false php_text_strings_setlocale(int $category, string $locales, string $rest)
// PHP_TEXT_STRINGS_SHA1_FILE - string|false php_text_strings_sha1_file(string $filename, bool $binary = false)
// PHP_TEXT_STRINGS_SHA1 - string php_text_strings_sha1(string $string, bool $binary = false)
// PHP_TEXT_STRINGS_SIMILAR_TEXT - int php_text_strings_similar_text(string $string1, string $string2, float& $percent)
// PHP_TEXT_STRINGS_SOUNDEX - string php_text_strings_soundex(string $string)
// PHP_TEXT_STRINGS_SPRINTF - string php_text_strings_sprintf(string $format, mixed $values)
// PHP_TEXT_STRINGS_SSCANF - array|int|null php_text_strings_sscanf(string $string, string $format, mixed& $vars)
// OFFLINE | PHP_TEXT_STRINGS_STR_CONTAINS - bool php_text_strings_str_contains(string $haystack, string $needle)
// OFFLINE | PHP_TEXT_STRINGS_STR_ENDS_WITH - bool php_text_strings_str_ends_with(string $haystack, string $needle)
// OFFLINE | PHP_TEXT_STRINGS_STR_GETCSV - array php_text_strings_str_getcsv(string $string, string $separator = ",", string $enclosure = "\"", string $escape = "\\")
// OFFLINE | PHP_TEXT_STRINGS_STR_IREPLACE - string|array php_text_strings_str_ireplace(array|string $search, array|string $replace, string|array $subject, int& $count)
// PHP_TEXT_STRINGS_STR_PAD - string php_text_strings_str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT)
// PHP_TEXT_STRINGS_STR_REPEAT - string php_text_strings_str_repeat(string $string, int $times)
// PHP_TEXT_STRINGS_STR_REPLACE - string|array php_text_strings_str_replace(array|string $search, array|string $replace, string|array $subject, int& $count)
// PHP_TEXT_STRINGS_STR_ROT13 - string php_text_strings_str_rot13(string $string)
// PHP_TEXT_STRINGS_STR_SHUFFLE - string php_text_strings_str_shuffle(string $string)
// OFFLINE | PHP_TEXT_STRINGS_STR_SPLIT - array php_text_strings_str_split(string $string, int $length = 1)
// OFFLINE | PHP_TEXT_STRINGS_STR_STARTS_WITH - bool php_text_strings_str_starts_with(string $haystack, string $needle)
// PHP_TEXT_STRINGS_STR_WORD_COUNT - array|int php_text_strings_str_word_count(string $string, int $format = 0, string $characters = null)
// PHP_TEXT_STRINGS_STRCASECMP - int php_text_strings_strcasecmp(string $string1, string $string2)
// PHP_TEXT_STRINGS_STRCHR - string|false php_text_strings_strchr(string $haystack, string $needle, bool $before_needle = false)
// PHP_TEXT_STRINGS_STRCMP - int php_text_strings_strcmp(string $string1, string $string2)
// PHP_TEXT_STRINGS_STRCOLL - int php_text_strings_strcoll(string $string1, string $string2)
// PHP_TEXT_STRINGS_STRCSPN - int php_text_strings_strcspn(string $string, string $characters, int $offset = 0, int $length = null)
// PHP_TEXT_STRINGS_STRIP_TAGS - string php_text_strings_strip_tags(string $string, array|string|null $allowed_tags = null)
// PHP_TEXT_STRINGS_STRIPCSLASHES - string php_text_strings_stripcslashes(string $string)
// OFFLINE | PHP_TEXT_STRINGS_STRIPOS - int|false php_text_strings_stripos(string $haystack, string $needle, int $offset = 0)
// PHP_TEXT_STRINGS_STRIPSLASHES - string php_text_strings_stripslashes(string $string)
// PHP_TEXT_STRINGS_STRISTR - string|false php_text_strings_stristr(string $haystack, string $needle, bool $before_needle = false)
// PHP_TEXT_STRINGS_STRLEN - int php_text_strings_strlen(string $string)
// PHP_TEXT_STRINGS_STRNATCASECMP - int php_text_strings_strnatcasecmp(string $string1, string $string2)
// PHP_TEXT_STRINGS_STRNATCMP - int php_text_strings_strnatcmp(string $string1, string $string2)
// PHP_TEXT_STRINGS_STRNCASECMP - int php_text_strings_strncasecmp(string $string1, string $string2, int $length)
// PHP_TEXT_STRINGS_STRNCMP - int php_text_strings_strncmp(string $string1, string $string2, int $length)
// OFFLINE | PHP_TEXT_STRINGS_STRPBRK - string|false php_text_strings_strpbrk(string $string, string $characters)
// PHP_TEXT_STRINGS_STRPOS - int|false php_text_strings_strpos(string $haystack, string $needle, int $offset = 0)
// PHP_TEXT_STRINGS_STRRCHR - string|false php_text_strings_strrchr(string $haystack, string $needle, bool $before_needle = false)
// PHP_TEXT_STRINGS_STRREV - string php_text_strings_strrev(string $string)
// OFFLINE | PHP_TEXT_STRINGS_STRRIPOS - int|false php_text_strings_strripos(string $haystack, string $needle, int $offset = 0)
// PHP_TEXT_STRINGS_STRRPOS - int|false php_text_strings_strrpos(string $haystack, string $needle, int $offset = 0)
// PHP_TEXT_STRINGS_STRSPN - int php_text_strings_strspn(string $string, string $characters, int $offset = 0, int $length = null)
// PHP_TEXT_STRINGS_STRSTR - string|false php_text_strings_strstr(string $haystack, string $needle, bool $before_needle = false)
// PHP_TEXT_STRINGS_STRTOK - string|false php_text_strings_strtok(string $string, string $token)
// PHP_TEXT_STRINGS_STRTOLOWER - string php_text_strings_strtolower(string $string)
// PHP_TEXT_STRINGS_STRTOUPPER - string php_text_strings_strtoupper(string $string)
// PHP_TEXT_STRINGS_STRTR - string php_text_strings_strtr(string $string, string $from, string $to)
// OFFLINE | PHP_TEXT_STRINGS_SUBSTR_COMPARE - int php_text_strings_substr_compare(string $haystack, string $needle, int $offset, int $length = null, bool $case_insensitive = false)
// PHP_TEXT_STRINGS_SUBSTR_COUNT - int php_text_strings_substr_count(string $haystack, string $needle, int $offset = 0, int $length = null)
// PHP_TEXT_STRINGS_SUBSTR_REPLACE - string|array php_text_strings_substr_replace(array|string $string, array|string $replace, array|int $offset, array|int|null $length = null)
// PHP_TEXT_STRINGS_SUBSTR - string php_text_strings_substr(string $string, int $offset, int $length = null)
// PHP_TEXT_STRINGS_TRIM - string php_text_strings_trim(string $string, string $characters = " \n\r\t\v\x00")
// PHP_TEXT_STRINGS_UCFIRST - string php_text_strings_ucfirst(string $string)
// PHP_TEXT_STRINGS_UCWORDS - string php_text_strings_ucwords(string $string, string $separators = " \t\r\n\f\v")
// OFFLINE | PHP_TEXT_STRINGS_UTF8_DECODE - string php_text_strings_utf8_decode(string $string)
// OFFLINE | PHP_TEXT_STRINGS_UTF8_ENCODE - string php_text_strings_utf8_encode(string $string)
// OFFLINE | PHP_TEXT_STRINGS_VFPRINTF - int php_text_strings_vfprintf(resource $stream, string $format, array $values)
// PHP_TEXT_STRINGS_VPRINTF - int php_text_strings_vprintf(string $format, array $values)
// PHP_TEXT_STRINGS_VSPRINTF - string php_text_strings_vsprintf(string $format, array $values)
// PHP_TEXT_STRINGS_WORDWRAP - string php_text_strings_wordwrap(string $string, int $width = 75, string $break = "\n", bool $cut_long_words = false)
// PHP_TEXT_STRINGS - END
// ==============================


// ============================== BEGIN
//          REQUIREMENTS          
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== INSTALLATION
// CORE (No installation needed to use these functions; they are part of the PHP core)
// ============================== USING FUNCTIONS (103)
// addcslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// addslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// bin2hex() - PHP_4, PHP_5, PHP_7, PHP_8
// chop() - PHP_4, PHP_5, PHP_7, PHP_8
// chr() - PHP_4, PHP_5, PHP_7, PHP_8
// chunk_split() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | convert_cyr_string() - PHP_4, PHP_5, PHP_7
// OFFLINE | convert_uudecode() - PHP_5, PHP_7, PHP_8
// OFFLINE | convert_uuencode() - PHP_5, PHP_7, PHP_8
// count_chars() - PHP_4, PHP_5, PHP_7, PHP_8
// crc32() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// crypt() - PHP_4, PHP_5, PHP_7, PHP_8
// echo() - PHP_4, PHP_5, PHP_7, PHP_8
// explode() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | fprintf() - PHP_5, PHP_7, PHP_8
// get_html_translation_table() - PHP_4, PHP_5, PHP_7, PHP_8
// hebrev() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | hebrevc() - PHP_4, PHP_5, PHP_7
// OFFLINE | hex2bin() - PHP_5 >= PHP_5_4_0, PHP_7, PHP_8
// html_entity_decode() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// htmlentities() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | htmlspecialchars_decode() - PHP_5 >= PHP_5_1_0, PHP_7, PHP_8
// htmlspecialchars() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | implode() - PHP_4, PHP_5, PHP_7
// OFFLINE | join() - PHP_4, PHP_5, PHP_7
// OFFLINE | lcfirst() - PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// levenshtein() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// localeconv() - PHP_4 >= PHP_4_0_5, PHP_5, PHP_7, PHP_8
// ltrim() - PHP_4, PHP_5, PHP_7, PHP_8
// md5_file() - PHP_4 >= PHP_4_2_0, PHP_5, PHP_7, PHP_8
// md5() - PHP_4, PHP_5, PHP_7, PHP_8
// metaphone() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | money_format() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7
// nl_langinfo() - PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// nl2br() - PHP_4, PHP_5, PHP_7, PHP_8
// number_format() - PHP_4, PHP_5, PHP_7, PHP_8
// ord() - PHP_4, PHP_5, PHP_7, PHP_8
// parse_str() - PHP_4, PHP_5, PHP_7, PHP_8
// print() - PHP_4, PHP_5, PHP_7, PHP_8
// printf() - PHP_4, PHP_5, PHP_7, PHP_8
// quoted_printable_decode() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | quoted_printable_encode() - PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// quotemeta() - PHP_4, PHP_5, PHP_7, PHP_8
// rtrim() - PHP_4, PHP_5, PHP_7, PHP_8
// setlocale() - PHP_4, PHP_5, PHP_7, PHP_8
// sha1_file() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// sha1() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// similar_text() - PHP_4, PHP_5, PHP_7, PHP_8
// soundex() - PHP_4, PHP_5, PHP_7, PHP_8
// sprintf() - PHP_4, PHP_5, PHP_7, PHP_8
// sscanf() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// OFFLINE | str_contains() - PHP_8
// OFFLINE | str_ends_with() - PHP_8
// OFFLINE | str_getcsv() - PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// OFFLINE | str_ireplace() - PHP_5, PHP_7, PHP_8
// str_pad() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// str_repeat() - PHP_4, PHP_5, PHP_7, PHP_8
// str_replace() - PHP_4, PHP_5, PHP_7, PHP_8
// str_rot13() - PHP_4 >= PHP_4_2_0, PHP_5, PHP_7, PHP_8
// str_shuffle() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// OFFLINE | str_split() - PHP_5, PHP_7, PHP_8
// OFFLINE | str_starts_with() - PHP_8
// str_word_count() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// strcasecmp() - PHP_4, PHP_5, PHP_7, PHP_8
// strchr() - PHP_4, PHP_5, PHP_7, PHP_8
// strcmp() - PHP_4, PHP_5, PHP_7, PHP_8
// strcoll() - PHP_4 >= PHP_4_0_5, PHP_5, PHP_7, PHP_8
// strcspn() - PHP_4, PHP_5, PHP_7, PHP_8
// strip_tags() - PHP_4, PHP_5, PHP_7, PHP_8
// stripcslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | stripos() - PHP_5, PHP_7, PHP_8
// stripslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// stristr() - PHP_4, PHP_5, PHP_7, PHP_8
// strlen() - PHP_4, PHP_5, PHP_7, PHP_8
// strnatcasecmp() - PHP_4, PHP_5, PHP_7, PHP_8
// strnatcmp() - PHP_4, PHP_5, PHP_7, PHP_8
// strncasecmp() - PHP_4 >= PHP_4_0_2, PHP_5, PHP_7, PHP_8
// strncmp() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | strpbrk() - PHP_5, PHP_7, PHP_8
// strpos() - PHP_4, PHP_5, PHP_7, PHP_8
// strrchr() - PHP_4, PHP_5, PHP_7, PHP_8
// strrev() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | strripos() - PHP_5, PHP_7, PHP_8
// strrpos() - PHP_4, PHP_5, PHP_7, PHP_8
// strspn() - PHP_4, PHP_5, PHP_7, PHP_8
// strstr() - PHP_4, PHP_5, PHP_7, PHP_8
// strtok() - PHP_4, PHP_5, PHP_7, PHP_8
// strtolower() - PHP_4, PHP_5, PHP_7, PHP_8
// strtoupper() - PHP_4, PHP_5, PHP_7, PHP_8
// strtr() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | substr_compare() - PHP_5, PHP_7, PHP_8
// substr_count() - PHP_4, PHP_5, PHP_7, PHP_8
// substr_replace() - PHP_4, PHP_5, PHP_7, PHP_8
// substr() - PHP_4, PHP_5, PHP_7, PHP_8
// trim() - PHP_4, PHP_5, PHP_7, PHP_8
// ucfirst() - PHP_4, PHP_5, PHP_7, PHP_8
// ucwords() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | utf8_decode() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | utf8_encode() - PHP_4, PHP_5, PHP_7, PHP_8
// OFFLINE | vfprintf() - PHP_5, PHP_7, PHP_8
// vprintf() - PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// vsprintf() - PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// wordwrap() - PHP_4 >= PHP_4_0_2, PHP_5, PHP_7, PHP_8
// ============================== USING CLASSES (0)
// ============================== USING DATA_TYPES (10)
// string
// int
// false
// array
// void
// resource
// mixed
// bool
// float
// null
// ============================== END
//          REQUIREMENTS          
// ==============================


// ============================== BEGIN
//        PHP_TEXT_STRINGS        
// ============================== ABOUT
// PHP Manual / Function Reference / Text Processing / Strings
// URL: https://www.php.net/manual/en/book.strings.php
// ============================== DESCRIPTION
// STRINGS
// TYPES_STRINGS
// 
// STRINGS - BEGIN
// Strings
// 
// INTRODUCTION
// INSTALLING_CONFIGURING
// PREDEFINED_CONSTANTS
// STRING_FUNCTIONS
// CHANGELOG
// 
// INTRODUCTION - BEGIN
// Introduction
// 
// These functions all manipulate strings in various ways. Some more specialized sections can be found in the regular expression and URL handling sections.
// For information on how strings behave, especially with regard to usage of single quotes, double quotes, and escape sequences, see the Strings entry in the Types section of the manual.
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/intro.strings.php
// INTRODUCTION - END
// 
// INSTALLING_CONFIGURING - BEGIN
// Installing/Configuring
// 
// REQUIREMENTS
// INSTALLATION
// RUNTIME_CONFIGURATION
// RESOURCE_TYPES
// 
// REQUIREMENTS - BEGIN
// Requirements
// 
// No external libraries are needed to build this extension.
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/strings.requirements.php
// REQUIREMENTS - END
// 
// INSTALLATION - BEGIN
// Installation
// 
// There is no installation needed to use these functions; they are part of the PHP core.
// As of PHP 8.1.0, crypt() can be built against a system crypt library by specifying the --with-external-libcrypt configure option.
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/strings.installation.php
// INSTALLATION - END
// 
// RUNTIME_CONFIGURATION - BEGIN
// Runtime Configuration
// 
// This extension has no configuration directives defined in php.ini.
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/strings.configuration.php
// RUNTIME_CONFIGURATION - END
// 
// RESOURCE_TYPES - BEGIN
// Resource Types
// 
// This extension has no resource types defined.
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/strings.resources.php
// RESOURCE_TYPES - END
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/strings.setup.php
// INSTALLING_CONFIGURING - END
// 
// PREDEFINED_CONSTANTS - BEGIN
// Predefined Constants
// 
// The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.
// 
// CRYPT_SALT_LENGTH (int) -
// CRYPT_STD_DES (int)     - Indicates whether standard DES-based hashes are supported in crypt(). Always 1.
// CRYPT_EXT_DES (int)     - Indicates whether extended DES-based hashes are supported in crypt(). Always 1.
// CRYPT_MD5 (int)         - Indicates whether MD5 hashes are supported in crypt(). Always 1.
// CRYPT_BLOWFISH (int)    - Indicates whether Blowfish hashes are supported in crypt(). Always 1.
// CRYPT_SHA256 (int)      - Indicates whether SHA-256 hashes are supported in crypt(). Always 1.
// CRYPT_SHA512 (int)      - Indicates whether SHA-512 hashes are supported in crypt(). Always 1.
// HTML_SPECIALCHARS (int) -
// HTML_ENTITIES (int)     -
// ENT_COMPAT (int)        -
// ENT_QUOTES (int)        -
// ENT_NOQUOTES (int)      -
// ENT_IGNORE (int)        -
// ENT_SUBSTITUTE (int)    -
// ENT_DISALLOWED (int)    -
// ENT_HTML401 (int)       -
// ENT_XML1 (int)          -
// ENT_XHTML (int)         -
// ENT_HTML5 (int)         -
// CHAR_MAX (int)          -
// LC_CTYPE (int)          -
// LC_NUMERIC (int)        -
// LC_TIME (int)           -
// LC_COLLATE (int)        -
// LC_MONETARY (int)       -
// LC_ALL (int)            -
// LC_MESSAGES (int)       -
// STR_PAD_LEFT (int)      -
// STR_PAD_RIGHT (int)     -
// STR_PAD_BOTH (int)      -
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/string.constants.php
// PREDEFINED_CONSTANTS - END
// 
// STRING_FUNCTIONS - BEGIN
// String Functions
// 
// See Also
// For even more powerful string handling and manipulating functions take a look at the Perl compatible regular expression functions. For working with multibyte character encodings, take a look at the Multibyte String functions.
// 
// Table of Contents
// * addcslashes                - Quote string with slashes in a C style
// * addslashes                 - Quote string with slashes
// * bin2hex                    - Convert binary data into hexadecimal representation
// * chop                       - Alias of rtrim
// * chr                        - Generate a single-byte string from a number
// * chunk_split                - Split a string into smaller chunks
// * convert_cyr_string         - Convert from one Cyrillic character set to another
// * convert_uudecode           - Decode a uuencoded string
// * convert_uuencode           - Uuencode a string
// * count_chars                - Return information about characters used in a string
// * crc32                      - Calculates the crc32 polynomial of a string
// * crypt                      - One-way string hashing
// * echo                       - Output one or more strings
// * explode                    - Split a string by a string
// * fprintf                    - Write a formatted string to a stream
// * get_html_translation_table - Returns the translation table used by htmlspecialchars and htmlentities
// * hebrev                     - Convert logical Hebrew text to visual text
// * hebrevc                    - Convert logical Hebrew text to visual text with newline conversion
// * hex2bin                    - Decodes a hexadecimally encoded binary string
// * html_entity_decode         - Convert HTML entities to their corresponding characters
// * htmlentities               - Convert all applicable characters to HTML entities
// * htmlspecialchars_decode    - Convert special HTML entities back to characters
// * htmlspecialchars           - Convert special characters to HTML entities
// * implode                    - Join array elements with a string
// * join                       - Alias of implode
// * lcfirst                    - Make a string's first character lowercase
// * levenshtein                - Calculate Levenshtein distance between two strings
// * localeconv                 - Get numeric formatting information
// * ltrim                      - Strip whitespace (or other characters) from the beginning of a string
// * md5_file                   - Calculates the md5 hash of a given file
// * md5                        - Calculate the md5 hash of a string
// * metaphone                  - Calculate the metaphone key of a string
// * money_format               - Formats a number as a currency string
// * nl_langinfo                - Query language and locale information
// * nl2br                      - Inserts HTML line breaks before all newlines in a string
// * number_format              - Format a number with grouped thousands
// * ord                        - Convert the first byte of a string to a value between 0 and 255
// * parse_str                  - Parses the string into variables
// * print                      - Output a string
// * printf                     - Output a formatted string
// * quoted_printable_decode    - Convert a quoted-printable string to an 8 bit string
// * quoted_printable_encode    - Convert a 8 bit string to a quoted-printable string
// * quotemeta                  - Quote meta characters
// * rtrim                      - Strip whitespace (or other characters) from the end of a string
// * setlocale                  - Set locale information
// * sha1_file                  - Calculate the sha1 hash of a file
// * sha1                       - Calculate the sha1 hash of a string
// * similar_text               - Calculate the similarity between two strings
// * soundex                    - Calculate the soundex key of a string
// * sprintf                    - Return a formatted string
// * sscanf                     - Parses input from a string according to a format
// * str_contains               - Determine if a string contains a given substring
// * str_ends_with              - Checks if a string ends with a given substring
// * str_getcsv                 - Parse a CSV string into an array
// * str_ireplace               - Case-insensitive version of str_replace
// * str_pad                    - Pad a string to a certain length with another string
// * str_repeat                 - Repeat a string
// * str_replace                - Replace all occurrences of the search string with the replacement string
// * str_rot13                  - Perform the rot13 transform on a string
// * str_shuffle                - Randomly shuffles a string
// * str_split                  - Convert a string to an array
// * str_starts_with            - Checks if a string starts with a given substring
// * str_word_count             - Return information about words used in a string
// * strcasecmp                 - Binary safe case-insensitive string comparison
// * strchr                     - Alias of strstr
// * strcmp                     - Binary safe string comparison
// * strcoll                    - Locale based string comparison
// * strcspn                    - Find length of initial segment not matching mask
// * strip_tags                 - Strip HTML and PHP tags from a string
// * stripcslashes              - Un-quote string quoted with addcslashes
// * stripos                    - Find the position of the first occurrence of a case-insensitive substring in a string
// * stripslashes               - Un-quotes a quoted string
// * stristr                    - Case-insensitive strstr
// * strlen                     - Get string length
// * strnatcasecmp              - Case insensitive string comparisons using a "natural order" algorithm
// * strnatcmp                  - String comparisons using a "natural order" algorithm
// * strncasecmp                - Binary safe case-insensitive string comparison of the first n characters
// * strncmp                    - Binary safe string comparison of the first n characters
// * strpbrk                    - Search a string for any of a set of characters
// * strpos                     - Find the position of the first occurrence of a substring in a string
// * strrchr                    - Find the last occurrence of a character in a string
// * strrev                     - Reverse a string
// * strripos                   - Find the position of the last occurrence of a case-insensitive substring in a string
// * strrpos                    - Find the position of the last occurrence of a substring in a string
// * strspn                     - Finds the length of the initial segment of a string consisting entirely of characters contained within a given mask
// * strstr                     - Find the first occurrence of a string
// * strtok                     - Tokenize string
// * strtolower                 - Make a string lowercase
// * strtoupper                 - Make a string uppercase
// * strtr                      - Translate characters or replace substrings
// * substr_compare             - Binary safe comparison of two strings from an offset, up to length characters
// * substr_count               - Count the number of substring occurrences
// * substr_replace             - Replace text within a portion of a string
// * substr                     - Return part of a string
// * trim                       - Strip whitespace (or other characters) from the beginning and end of a string
// * ucfirst                    - Make a string's first character uppercase
// * ucwords                    - Uppercase the first character of each word in a string
// * utf8_decode                - Converts a string from UTF-8 to ISO-8859-1, replacing invalid or unrepresentable characters
// * utf8_encode                - Converts a string from ISO-8859-1 to UTF-8
// * vfprintf                   - Write a formatted string to a stream
// * vprintf                    - Output a formatted string
// * vsprintf                   - Return a formatted string
// * wordwrap                   - Wraps a string to a given number of characters
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/ref.strings.php
// STRING_FUNCTIONS - END
// 
// CHANGELOG - BEGIN
// Changelog
// 
// The following changes have been made to classes/functions/methods of this extension.
// 
// Version       | Function                   - Description
// 8.3.0         | strrchr                    - The before_needle parameter was added.
// 8.2.0         | lcfirst                    - Case conversion no longer depends on the locale set with setlocale. Only ASCII characters will be converted.
//               | str_ireplace               - Case folding no longer depends on the locale set with setlocale. Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
//               | str_split                  - If string is empty an empty array is now returned. Previously an array containing a single empty string was returned.
//               | strcasecmp                 - This function now returns -1 or 1, where it previously returned a negative or positive number.
//               | strcmp                     - This function now returns -1 or 1, where it previously returned a negative or positive number.
//               | stripos                    - Case folding no longer depends on the locale set with setlocale. Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
//               | stristr                    - Case folding no longer depends on the locale set with setlocale. Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
//               | strnatcasecmp              - This function now returns -1 or 1, where it previously returned a negative or positive number.
//               | strnatcmp                  - This function now returns -1 or 1, where it previously returned a negative or positive number.
//               | strncasecmp                - This function now returns -1 or 1, where it previously returned a negative or positive number.
//               | strncmp                    - This function now returns -1 or 1, where it previously returned a negative or positive number.
//               | strripos                   - Case folding no longer depends on the locale set with setlocale. Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
//               | strtolower                 - Case conversion no longer depends on the locale set with setlocale. Only ASCII characters will be converted.
//               | strtoupper                 - Case conversion no longer depends on the locale set with setlocale. Only ASCII characters will be converted.
//               | substr_compare             - This function now returns -1 or 1, where it previously returned a negative or positive number.
//               | ucfirst                    - Case conversion no longer depends on the locale set with setlocale. Only ASCII characters will be converted.
//               | ucwords                    - Case conversion no longer depends on the locale set with setlocale. Only ASCII characters will be converted.
//               | utf8_decode                - This function has been deprecated.
//               | utf8_encode                - This function has been deprecated.
// 8.1.0         | get_html_translation_table - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
//               | html_entity_decode         - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
//               | htmlentities               - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
//               | htmlspecialchars           - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
//               | htmlspecialchars_decode    - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 8.0.0         | convert_uuencode           - Prior to this version, trying to convert an empty string returned false for no particular reason.
//               | count_chars                - Prior to this version, the function returned false on failure.
//               | crypt                      - The salt is no longer optional.
//               | explode                    - explode will now throw ValueError when separator parameter is given an empty string (""). Previously, explode returned false instead.
//               | fprintf                    - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | fprintf                    - This function no longer returns false on failure.
//               | fprintf                    - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | fprintf                    - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
//               | fprintf                    - Throw a ArgumentCountError when less arguments are given than required; previously this function emitted a E_WARNING instead.
//               | html_entity_decode         - encoding is nullable now.
//               | htmlentities               - encoding is nullable now.
//               | implode                    - Passing the separator after the array is no longer supported.
//               | levenshtein                - Prior to this version, levenshtein had to be called with either two or five arguments.
//               | levenshtein                - Prior to this version, levenshtein would return -1 if one of the argument strings is longer than 255 characters.
//               | metaphone                  - The function returned false on failure.
//               | number_format              - Prior to this version, number_format accepted one, two, or four parameters (but not three).
//               | parse_str                  - result is no longer optional.
//               | printf                     - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
//               | printf                     - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | printf                     - Throw a ArgumentCountError when less arguments are given than required; previously this function emitted a E_WARNING instead.
//               | printf                     - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | printf                     - This function no longer returns false on failure.
//               | soundex                    - Prior to this version, calling the function with an empty string returned false for no particular reason.
//               | sprintf                    - Throw a ArgumentCountError when less arguments are given than required; previously this function emitted a E_WARNING instead.
//               | sprintf                    - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | sprintf                    - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | sprintf                    - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
//               | sprintf                    - This function no longer returns false on failure.
//               | str_split                  - If length is less than 1, a ValueError will be thrown now; previously, an error of level E_WARNING has been raised instead, and the function returned false.
//               | str_word_count             - characters is nullable now.
//               | strcspn                    - length is nullable now.
//               | strip_tags                 - allowed_tags is nullable now.
//               | stripos                    - needle now accepts an empty string.
//               | stripos                    - Passing an int as needle is no longer supported.
//               | stristr                    - Passing an int as needle is no longer supported.
//               | strpos                     - needle now accepts an empty string.
//               | strpos                     - Passing an int as needle is no longer supported.
//               | strrchr                    - needle now accepts an empty string.
//               | strrchr                    - Passing an int as needle is no longer supported.
//               | strripos                   - Passing an int as needle is no longer supported.
//               | strripos                   - needle now accepts an empty string.
//               | strrpos                    - Passing an int as needle is no longer supported.
//               | strrpos                    - needle now accepts an empty string.
//               | strspn                     - length is nullable now.
//               | strstr                     - Passing an int as needle is no longer supported.
//               | strstr                     - needle now accepts an empty string.
//               | substr                     - The function returns an empty string where it previously returned false.
//               | substr                     - length is nullable now. When length is explicitly set to null, the function returns a substring finishing at the end of the string, when it previously returned an empty string.
//               | substr_compare             - length is nullable now.
//               | substr_count               - length is nullable now.
//               | substr_replace             - length is nullable now.
//               | vfprintf                   - This function no longer returns false on failure.
//               | vfprintf                   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | vfprintf                   - Throw a ValueError when less arguments are given than required; previously this function emitted a E_WARNING instead.
//               | vfprintf                   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | vfprintf                   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
//               | vprintf                    - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | vprintf                    - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | vprintf                    - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
//               | vprintf                    - This function no longer returns false on failure.
//               | vprintf                    - Throw a ValueError when less arguments are given than required; previously this function emitted a E_WARNING instead.
//               | vsprintf                   - This function no longer returns false on failure.
//               | vsprintf                   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
//               | vsprintf                   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | vsprintf                   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
//               | vsprintf                   - Throw a ValueError when less arguments are given than required; previously this function emitted a E_WARNING instead.
// 7.4.0         | chr                        - The function no longer silently accepts unsupported codepoints, and casts these to 0.
//               | implode                    - Passing the separator after the array (i.e. using the legacy signature) has been deprecated.
//               | money_format               - This function has been deprecated. Instead, use NumberFormatter::formatCurrency.
//               | str_getcsv                 - The escape parameter now interprets an empty string as signal to disable the proprietary escape mechanism. Formerly, an empty string was treated like the default parameter value.
//               | strip_tags                 - The allowed_tags now alternatively accepts an array.
// 7.3.0         | stripos                    - Passing an int as needle has been deprecated.
//               | stristr                    - Passing an int as needle has been deprecated.
//               | strpos                     - Passing an int as needle has been deprecated.
//               | strrchr                    - Passing an int as needle has been deprecated.
//               | strripos                   - Passing an int as needle has been deprecated.
//               | strrpos                    - Passing an int as needle has been deprecated.
//               | strstr                     - Passing an int as needle has been deprecated.
// 7.2.18, 7.3.5 | substr_compare             - offset may now be equal to the length of haystack.
// 7.2.0         | number_format              - number_format was changed to not being able to return -0, previously -0 could be returned for cases like where num would be -0.01.
//               | parse_str                  - Usage of parse_str without a second parameter now emits an E_DEPRECATED notice.
//               | utf8_decode                - This function has been moved from the XML extension to the core of PHP. In previous versions, it was only available if the XML extension was installed.
//               | utf8_encode                - This function has been moved from the XML extension to the core of PHP. In previous versions, it was only available if the XML extension was installed.
// 7.1.0         | str_shuffle                - The internal randomization algorithm has been changed to use the Mersenne Twister Random Number Generator instead of the libc rand function.
//               | stripos                    - Support for negative offsets has been added.
//               | strpos                     - Support for negative offsets has been added.
//               | substr_count               - Support for negative offsets and lengths has been added. length may also be 0 now.
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/changelog.strings.php
// CHANGELOG - END
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/book.strings.php
// STRINGS - END
// 
// TYPES_STRINGS - BEGIN
// Strings (PHP Manual / Language Reference / Types / Strings)
// 
// A string is a series of characters, where a character is the same as a byte. This means that PHP only supports a 256-character set, and hence does not offer native Unicode support. See details of the string type.
// Note: On 32-bit builds, a string can be as large as up to 2GB (2147483647 bytes maximum)
// 
// Syntax
// A string literal can be specified in four different ways:
// * single quoted
// * double quoted
// * heredoc syntax
// * nowdoc syntax
// 
// Single quoted
// The simplest way to specify a string is to enclose it in single quotes (the character ').
// To specify a literal single quote, escape it with a backslash (\). To specify a literal backslash, double it (\\). All other instances of backslash will be treated as a literal backslash: this means that the other escape sequences you might be used to, such as \r or \n, will be output literally as specified rather than having any special meaning.
// Note: Unlike the double-quoted and heredoc syntaxes, variables and escape sequences for special characters will not be expanded when they occur in single quoted strings.
// [php]
// echo 'this is a simple string';
// 
// echo 'You can also have embedded newlines in
// strings this way as it is
// okay to do';
// 
// // Outputs: Arnold once said: "I'll be back"
// echo 'Arnold once said: "I\'ll be back"';
// 
// // Outputs: You deleted C:\*.*?
// echo 'You deleted C:\\*.*?';
// 
// // Outputs: You deleted C:\*.*?
// echo 'You deleted C:\*.*?';
// 
// // Outputs: This will not expand: \n a newline
// echo 'This will not expand: \n a newline';
// 
// // Outputs: Variables do not $expand $either
// echo 'Variables do not $expand $either';
// [/php]
// 
// Double quoted
// If the string is enclosed in double-quotes ("), PHP will interpret the following escape sequences for special characters:
// Escaped characters
// Sequence           - Meaning
// \n                 - linefeed (LF or 0x0A (10) in ASCII)
// \r                 - carriage return (CR or 0x0D (13) in ASCII)
// \t                 - horizontal tab (HT or 0x09 (9) in ASCII)
// \v                 - vertical tab (VT or 0x0B (11) in ASCII)
// \e                 - escape (ESC or 0x1B (27) in ASCII)
// \f                 - form feed (FF or 0x0C (12) in ASCII)
// \\                 - backslash
// \$                 - dollar sign
// \"                 - double-quote
// \[0-7]{1,3}        - Octal: the sequence of characters matching the regular expression [0-7]{1,3} is a character in octal notation (e.g. "\101" === "A"), which silently overflows to fit in a byte (e.g. "\400" === "\000")
// \x[0-9A-Fa-f]{1,2} - Hexadecimal: the sequence of characters matching the regular expression [0-9A-Fa-f]{1,2} is a character in hexadecimal notation (e.g. "\x41" === "A")
// \u{[0-9A-Fa-f]+}   - Unicode: the sequence of characters matching the regular expression [0-9A-Fa-f]+ is a Unicode codepoint, which will be output to the string as that codepoint's UTF-8 representation. The braces are required in the sequence. E.g. "\u{41}" === "A"
// As in single quoted strings, escaping any other character will result in the backslash being printed too.
// The most important feature of double-quoted strings is the fact that variable names will be expanded. See string parsing for details.
// 
// Heredoc
// A third way to delimit strings is the heredoc syntax: <<<. After this operator, an identifier is provided, then a newline. The string itself follows, and then the same identifier again to close the quotation.
// The closing identifier may be indented by space or tab, in which case the indentation will be stripped from all lines in the doc string. Prior to PHP 7.3.0, the closing identifier must begin in the first column of the line.
// Also, the closing identifier must follow the same naming rules as any other label in PHP: it must contain only alphanumeric characters and underscores, and must start with a non-digit character or underscore.
// [example]
// Example #1 Basic Heredoc example as of PHP 7.3.0
// [php]
// // no indentation
// echo <<<END
//       a
//      b
//     c
// \n
// END;
// 
// // 4 spaces of indentation
// echo <<<END
//       a
//      b
//     c
//     END;
// [/php]
// Output of the above example in PHP 7.3:
// [result]
//       a
//      b
//     c
// 
//   a
//  b
// c
// [/result]
// [/example]
// If the closing identifier is indented further than any lines of the body, then a ParseError will be thrown:
// [example]
// Example #2 Closing identifier must not be indented further than any lines of the body
// [php]
// echo <<<END
//   a
//  b
// c
//    END;
// [/php]
// Output of the above example in PHP 7.3:
// [result]
// PHP Parse error:  Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4
// [/result]
// [/example]
// If the closing identifier is indented, tabs can be used as well, however, tabs and spaces must not be intermixed regarding the indentation of the closing identifier and the indentation of the body (up to the closing identifier). In any of these cases, a ParseError will be thrown. These whitespace constraints have been included because mixing tabs and spaces for indentation is harmful to legibility.
// [example]
// Example #3 Different indentation for body (spaces) closing identifier
// [php]
// // All the following code do not work.
// 
// // different indentation for body (spaces) ending marker (tabs)
// {
//     echo <<<END
//      a
//         END;
// }
// 
// // mixing spaces and tabs in body
// {
//     echo <<<END
//         a
//      END;
// }
// 
// // mixing spaces and tabs in ending marker
// {
//     echo <<<END
//           a
//          END;
// }
// [/php]
// Output of the above example in PHP 7.3:
// [result]
// PHP Parse error:  Invalid indentation - tabs and spaces cannot be mixed in example.php line 8
// [/result]
// [/example]
// The closing identifier for the body string is not required to be followed by a semicolon or newline. For example, the following code is allowed as of PHP 7.3.0:
// [example]
// Example #4 Continuing an expression after a closing identifier
// [php]
// $values = [<<<END
// a
//   b
//     c
// END, 'd e f'];
// var_dump($values);
// [/php]
// Output of the above example in PHP 7.3:
// [result]
// array(2) {
//   [0] =>
//   string(11) "a
//   b
//     c"
//   [1] =>
//   string(5) "d e f"
// }
// [/result]
// [/example]
//  Warning: If the closing identifier was found at the start of a line, then regardless of whether it was a part of another word, it may be considered as the closing identifier and causes a ParseError.
//  [example]
//  Example #5 Closing identifier in body of the string tends to cause ParseError
//  [php]
//  $values = [<<<END
//  a
//  b
//  END ING
//  END, 'd e f'];
//  [/php]
//  Output of the above example in PHP 7.3:
//  [result]
//  PHP Parse error:  syntax error, unexpected identifier "ING", expecting "]" in example.php on line 6
//  [result]
//  [/example]
//  To avoid this problem, it is safe to follow the simple rule: do not choose as a closing identifier if it appears in the body of the text.
//  Warning: Prior to PHP 7.3.0, it is very important to note that the line with the closing identifier must contain no other characters, except a semicolon (;). That means especially that the identifier may not be indented, and there may not be any spaces or tabs before or after the semicolon. It's also important to realize that the first character before the closing identifier must be a newline as defined by the local operating system. This is \n on UNIX systems, including macOS. The closing delimiter must also be followed by a newline.
//  If this rule is broken and the closing identifier is not "clean", it will not be considered a closing identifier, and PHP will continue looking for one. If a proper closing identifier is not found before the end of the current file, a parse error will result at the last line.
//  [example]
//  Example #6 Invalid example, prior to PHP 7.3.0
//  [php]
//  class foo {
//      public $bar = <<<EOT
//  bar
//      EOT;
//  }
//  // Identifier must not be indented
//  [/php]
//  [/example]
//  [example]
//  Example #7 Valid example, even prior to PHP 7.3.0
//  [php]
//  class foo {
//      public $bar = <<<EOT
//  bar
//  EOT;
//  }
//  [/php]
//  [/example]
//  Heredocs containing variables can not be used for initializing class properties.
// Heredoc text behaves just like a double-quoted string, without the double quotes. This means that quotes in a heredoc do not need to be escaped, but the escape codes listed above can still be used. Variables are expanded, but the same care must be taken when expressing complex variables inside a heredoc as with strings.
// [example]
// Example #8 Heredoc string quoting example
// [php]
// $str = <<<EOD
// Example of string
// spanning multiple lines
// using heredoc syntax.
// EOD;
// 
// /* More complex example, with variables. */
// class foo
// {
//     var $foo;
//     var $bar;
// 
//     function __construct()
//     {
//         $this->foo = 'Foo';
//         $this->bar = array('Bar1', 'Bar2', 'Bar3');
//     }
// }
// 
// $foo = new foo();
// $name = 'MyName';
// 
// echo <<<EOT
// My name is "$name". I am printing some $foo->foo.
// Now, I am printing some {$foo->bar[1]}.
// This should print a capital 'A': \x41
// EOT;
// [/php]
// The above example will output:
// [result]
// My name is "MyName". I am printing some Foo.
// Now, I am printing some Bar2.
// This should print a capital 'A': A
// [/result]
// [/example]
// It is also possible to use the Heredoc syntax to pass data to function arguments:
// [example]
// Example #9 Heredoc in arguments example
// [php]
// var_dump(array(<<<EOD
// foobar!
// EOD
// ));
// [/php]
// [/example]
// It's possible to initialize static variables and class properties/constants using the Heredoc syntax:
// [example]
// Example #10 Using Heredoc to initialize static values
// [php]
// // Static variables
// function foo()
// {
//     static $bar = <<<LABEL
// Nothing in here...
// LABEL;
// }
// 
// // Class properties/constants
// class foo
// {
//     const BAR = <<<FOOBAR
// Constant example
// FOOBAR;
// 
//     public $baz = <<<FOOBAR
// Property example
// FOOBAR;
// }
// [/php]
// [/example]
// The opening Heredoc identifier may optionally be enclosed in double quotes:
// [example]
// Example #11 Using double quotes in Heredoc
// [php]
// echo <<<"FOOBAR"
// Hello World!
// FOOBAR;
// [/php]
// [/example]
// Nowdoc
// Nowdocs are to single-quoted strings what heredocs are to double-quoted strings. A nowdoc is specified similarly to a heredoc, but no parsing is done inside a nowdoc. The construct is ideal for embedding PHP code or other large blocks of text without the need for escaping. It shares some features in common with the SGML <![CDATA[ ]]> construct, in that it declares a block of text which is not for parsing.
// A nowdoc is identified with the same <<< sequence used for heredocs, but the identifier which follows is enclosed in single quotes, e.g. <<<'EOT'. All the rules for heredoc identifiers also apply to nowdoc identifiers, especially those regarding the appearance of the closing identifier.
// [example]
// Example #12 Nowdoc string quoting example
// [php]
// echo <<<'EOD'
// Example of string spanning multiple lines
// using nowdoc syntax. Backslashes are always treated literally,
// e.g. \\ and \'.
// EOD;
// [/php]
// The above example will output:
// [result]
// Example of string spanning multiple lines
// using nowdoc syntax. Backslashes are always treated literally,
// e.g. \\ and \'.
// [/result]
// [/example]
// [example]
// Example #13 Nowdoc string quoting example with variables
// [php]
// class foo
// {
//     public $foo;
//     public $bar;
// 
//     function __construct()
//     {
//         $this->foo = 'Foo';
//         $this->bar = array('Bar1', 'Bar2', 'Bar3');
//     }
// }
// 
// $foo = new foo();
// $name = 'MyName';
// 
// echo <<<'EOT'
// My name is "$name". I am printing some $foo->foo.
// Now, I am printing some {$foo->bar[1]}.
// This should not print a capital 'A': \x41
// EOT;
// [/php]
// The above example will output:
// [result]
// My name is "$name". I am printing some $foo->foo.
// Now, I am printing some {$foo->bar[1]}.
// This should not print a capital 'A': \x41
// [/result]
// [/example]
// [example]
// Example #14 Static data example
// [php]
// class foo {
//     public $bar = <<<'EOT'
// bar
// EOT;
// }
// [/php]
// [/example]
// 
// Variable parsing
// When a string is specified in double quotes or with heredoc, variables are parsed within it.
// There are two types of syntax: a simple one and a complex one. The simple syntax is the most common and convenient. It provides a way to embed a variable, an array value, or an object property in a string with a minimum of effort.
// The complex syntax can be recognised by the curly braces surrounding the expression.
// 
// Simple syntax
// If a dollar sign ($) is encountered, the parser will greedily take as many tokens as possible to form a valid variable name. Enclose the variable name in curly braces to explicitly specify the end of the name.
// [example]
// [php]
// $juice = "apple";
// 
// echo "He drank some $juice juice.".PHP_EOL;
// // Unintended. "s" is a valid character for a variable name, so this refers to $juices, not $juice.
// echo "He drank some juice made of $juices.";
// // Explicitly specify the end of the variable name by enclosing the reference in braces.
// echo "He drank some juice made of {$juice}s.";
// [/php]
// The above example will output:
// [result]
// He drank some apple juice.
// He drank some juice made of .
// He drank some juice made of apples.
// [/result]
// [/example]
// Similarly, an array index or an object property can be parsed. With array indices, the closing square bracket (]) marks the end of the index. The same rules apply to object properties as to simple variables.
// [example]
// Example #15 Simple syntax example
// [php]
// $juices = array("apple", "orange", "koolaid1" => "purple");
// 
// echo "He drank some $juices[0] juice.".PHP_EOL;
// echo "He drank some $juices[1] juice.".PHP_EOL;
// echo "He drank some $juices[koolaid1] juice.".PHP_EOL;
// 
// class people {
//     public $john = "John Smith";
//     public $jane = "Jane Smith";
//     public $robert = "Robert Paulsen";
// 
//     public $smith = "Smith";
// }
// 
// $people = new people();
// 
// echo "$people->john drank some $juices[0] juice.".PHP_EOL;
// echo "$people->john then said hello to $people->jane.".PHP_EOL;
// echo "$people->john's wife greeted $people->robert.".PHP_EOL;
// echo "$people->robert greeted the two $people->smiths."; // Won't work
// [/php]
// The above example will output:
// [result]
// He drank some apple juice.
// He drank some orange juice.
// He drank some purple juice.
// John Smith drank some apple juice.
// John Smith then said hello to Jane Smith.
// John Smith's wife greeted Robert Paulsen.
// Robert Paulsen greeted the two .
// [/result]
// [/example]
// As of PHP 7.1.0 also negative numeric indices are supported.
// [example]
// Example #16 Negative numeric indices
// [php]
// $string = 'string';
// echo "The character at index -2 is $string[-2].", PHP_EOL;
// $string[-3] = 'o';
// echo "Changing the character at index -3 to o gives $string.", PHP_EOL;
// [/php]
// The above example will output:
// [result]
// The character at index -2 is n.
// Changing the character at index -3 to o gives strong.
// [/result]
// [/example]
// For anything more complex, you should use the complex syntax.
// 
// Complex (curly) syntax
// This isn't called complex because the syntax is complex, but because it allows for the use of complex expressions.
// Any scalar variable, array element or object property with a string representation can be included via this syntax. The expression is written the same way as it would appear outside the string, and then wrapped in { and }. Since { can not be escaped, this syntax will only be recognised when the $ immediately follows the {. Use {\$ to get a literal {$. Some examples to make it clear:
// [example]
// [php]
// // Show all errors
// error_reporting(E_ALL);
// 
// $great = 'fantastic';
// 
// // Won't work, outputs: This is { fantastic}
// echo "This is { $great}";
// 
// // Works, outputs: This is fantastic
// echo "This is {$great}";
// 
// // Works
// echo "This square is {$square->width}00 centimeters broad.";
// 
// 
// // Works, quoted keys only work using the curly brace syntax
// echo "This works: {$arr['key']}";
// 
// 
// // Works
// echo "This works: {$arr[4][3]}";
// 
// // This is wrong for the same reason as $foo[bar] is wrong  outside a string.
// // In other words, it will still work, but only because PHP first looks for a
// // constant named foo; an error of level E_NOTICE (undefined constant) will be
// // thrown.
// echo "This is wrong: {$arr[foo][3]}";
// 
// // Works. When using multi-dimensional arrays, always use braces around arrays
// // when inside of strings
// echo "This works: {$arr['foo'][3]}";
// 
// // Works.
// echo "This works: " . $arr['foo'][3];
// 
// echo "This works too: {$obj->values[3]->name}";
// 
// echo "This is the value of the var named $name: {${$name}}";
// 
// echo "This is the value of the var named by the return value of getName(): {${getName()}}";
// 
// echo "This is the value of the var named by the return value of \$object->getName(): {${$object->getName()}}";
// 
// // Won't work, outputs: This is the return value of getName(): {getName()}
// echo "This is the return value of getName(): {getName()}";
// 
// // Won't work, outputs: C:\folder\{fantastic}.txt
// echo "C:\folder\{$great}.txt"
// // Works, outputs: C:\folder\fantastic.txt
// echo "C:\\folder\\{$great}.txt"
// [/php]
// It is also possible to access class properties using variables within strings using this syntax.
// [php]
// class foo {
//     var $bar = 'I am bar.';
// }
// 
// $foo = new foo();
// $bar = 'bar';
// $baz = array('foo', 'bar', 'baz', 'quux');
// echo "{$foo->$bar}\n";
// echo "{$foo->{$baz[1]}}\n";
// [/php]
// The above example will output:
// [result]
// I am bar.
// I am bar.
// [/result]
// [/example]
// Note: The value accessed from functions, method calls, static class variables, and class constants inside {$} will be interpreted as the name of a variable in the scope in which the string is defined. Using single curly braces ({}) will not work for accessing the return values of functions or methods or the values of class constants or static class variables.
// [example]
// [php]
// // Show all errors.
// error_reporting(E_ALL);
// 
// class beers {
//     const softdrink = 'rootbeer';
//     public static $ale = 'ipa';
// }
// 
// $rootbeer = 'A & W';
// $ipa = 'Alexander Keith\'s';
// 
// // This works; outputs: I'd like an A & W
// echo "I'd like an {${beers::softdrink}}\n";
// 
// // This works too; outputs: I'd like an Alexander Keith's
// echo "I'd like an {${beers::$ale}}\n";
// [/php]
// [/example]
// 
// String access and modification by character
// Characters within strings may be accessed and modified by specifying the zero-based offset of the desired character after the string using square array brackets, as in $str[42]. Think of a string as an array of characters for this purpose. The functions substr() and substr_replace() can be used when you want to extract or replace more than 1 character.
// Note: As of PHP 7.1.0, negative string offsets are also supported. These specify the offset from the end of the string. Formerly, negative offsets emitted E_NOTICE for reading (yielding an empty string) and E_WARNING for writing (leaving the string untouched).
// Note: Prior to PHP 8.0.0, strings could also be accessed using braces, as in $str{42}, for the same purpose. This curly brace syntax was deprecated as of PHP 7.4.0 and no longer supported as of PHP 8.0.0.
// Warning: Writing to an out of range offset pads the string with spaces. Non-integer types are converted to integer. Illegal offset type emits E_WARNING. Only the first character of an assigned string is used. As of PHP 7.1.0, assigning an empty string throws a fatal error. Formerly, it assigned a NULL byte.
// Warning: Internally, PHP strings are byte arrays. As a result, accessing or modifying a string using array brackets is not multi-byte safe, and should only be done with strings that are in a single-byte encoding such as ISO-8859-1.
// Note: As of PHP 7.1.0, applying the empty index operator on an empty string throws a fatal error. Formerly, the empty string was silently converted to an array.
// [example]
// Example #17 Some string examples
// [php]
// // Get the first character of a string
// $str = 'This is a test.';
// $first = $str[0];
// 
// // Get the third character of a string
// $third = $str[2];
// 
// // Get the last character of a string.
// $str = 'This is still a test.';
// $last = $str[strlen($str)-1];
// 
// // Modify the last character of a string
// $str = 'Look at the sea';
// $str[strlen($str)-1] = 'e';
// 
// [/php]
// [/example]
// String offsets have to either be integers or integer-like strings, otherwise a warning will be thrown.
// [example]
// Example #18 Example of Illegal String Offsets
// [php]
// $str = 'abc';
// 
// var_dump($str['1']);
// var_dump(isset($str['1']));
// 
// var_dump($str['1.0']);
// var_dump(isset($str['1.0']));
// 
// var_dump($str['x']);
// var_dump(isset($str['x']));
// 
// var_dump($str['1x']);
// var_dump(isset($str['1x']));
// [/php]
// The above example will output:
// [result]
// string(1) "b"
// bool(true)
// 
// Warning: Illegal string offset '1.0' in /tmp/t.php on line 7
// string(1) "b"
// bool(false)
// 
// Warning: Illegal string offset 'x' in /tmp/t.php on line 9
// string(1) "a"
// bool(false)
// string(1) "b"
// bool(false)
// [/result]
// [/example]
// Note: Accessing variables of other types (not including arrays or objects implementing the appropriate interfaces) using [] or {} silently returns null.
// Note: Characters within string literals can be accessed using [] or {}.
// Note: Accessing characters within string literals using the {} syntax has been deprecated in PHP 7.4. This has been removed in PHP 8.0.
// 
// Useful functions and operators
// Strings may be concatenated using the '.' (dot) operator. Note that the '+' (addition) operator will not work for this. See String operators for more information.
// There are a number of useful functions for string manipulation.
// See the string functions section for general functions, and the Perl-compatible regular expression functions for advanced find & replace functionality.
// There are also functions for URL strings, and functions to encrypt/decrypt strings (Sodium and Hash).
// Finally, see also the character type functions.
// 
// Converting to string
// A value can be converted to a string using the (string) cast or the strval() function. String conversion is automatically done in the scope of an expression where a string is needed. This happens when using the echo or print functions, or when a variable is compared to a string. The sections on Types and Type Juggling will make the following clearer. See also the settype() function.
// A bool true value is converted to the string "1". bool false is converted to "" (the empty string). This allows conversion back and forth between bool and string values.
// An int or float is converted to a string representing the number textually (including the exponent part for floats). Floating point numbers can be converted using exponential notation (4.1E+6).
// Note: As of PHP 8.0.0, the decimal point character is always a period ("."). Prior to PHP 8.0.0, the decimal point character is defined in the script's locale (category LC_NUMERIC). See the setlocale() function.
// Arrays are always converted to the string "Array"; because of this, echo and print can not by themselves show the contents of an array. To view a single element, use a construction such as echo $arr['foo']. See below for tips on viewing the entire contents.
// In order to convert objects to string, the magic method __toString must be used.
// Resources are always converted to strings with the structure "Resource id #1", where 1 is the resource number assigned to the resource by PHP at runtime. While the exact structure of this string should not be relied on and is subject to change, it will always be unique for a given resource within the lifetime of a script being executed (ie a Web request or CLI process) and won't be reused. To get a resource's type, use the get_resource_type() function.
// null is always converted to an empty string.
// As stated above, directly converting an array, object, or resource to a string does not provide any useful information about the value beyond its type. See the functions print_r() and var_dump() for more effective means of inspecting the contents of these types.
// Most PHP values can also be converted to strings for permanent storage. This method is called serialization, and is performed by the serialize() function.
// 
// Details of the String Type
// The string in PHP is implemented as an array of bytes and an integer indicating the length of the buffer. It has no information about how those bytes translate to characters, leaving that task to the programmer. There are no limitations on the values the string can be composed of; in particular, bytes with value 0 (“NUL bytes”) are allowed anywhere in the string (however, a few functions, said in this manual not to be “binary safe”, may hand off the strings to libraries that ignore data after a NUL byte.)
// This nature of the string type explains why there is no separate “byte” type in PHP – strings take this role. Functions that return no textual data – for instance, arbitrary data read from a network socket – will still return strings.
// Given that PHP does not dictate a specific encoding for strings, one might wonder how string literals are encoded. For instance, is the string "á" equivalent to "\xE1" (ISO-8859-1), "\xC3\xA1" (UTF-8, C form), "\x61\xCC\x81" (UTF-8, D form) or any other possible representation? The answer is that string will be encoded in whatever fashion it is encoded in the script file. Thus, if the script is written in ISO-8859-1, the string will be encoded in ISO-8859-1 and so on. However, this does not apply if Zend Multibyte is enabled; in that case, the script may be written in an arbitrary encoding (which is explicitly declared or is detected) and then converted to a certain internal encoding, which is then the encoding that will be used for the string literals. Note that there are some constraints on the encoding of the script (or on the internal encoding, should Zend Multibyte be enabled) – this almost always means that this encoding should be a compatible superset of ASCII, such as UTF-8 or ISO-8859-1. Note, however, that state-dependent encodings where the same byte values can be used in initial and non-initial shift states may be problematic.
// Of course, in order to be useful, functions that operate on text may have to make some assumptions about how the string is encoded. Unfortunately, there is much variation on this matter throughout PHP’s functions:
// * Some functions assume that the string is encoded in some (any) single-byte encoding, but they do not need to interpret those bytes as specific characters. This is case of, for instance, substr(), strpos(), strlen() or strcmp(). Another way to think of these functions is that operate on memory buffers, i.e., they work with bytes and byte offsets.
// * Other functions are passed the encoding of the string, possibly they also assume a default if no such information is given. This is the case of htmlentities() and the majority of the functions in the mbstring extension.
// * Others use the current locale (see setlocale()), but operate byte-by-byte.
// * Finally, they may just assume the string is using a specific encoding, usually UTF-8. This is the case of most functions in the intl extension and in the PCRE extension (in the last case, only when the u modifier is used).
// Ultimately, this means writing correct programs using Unicode depends on carefully avoiding functions that will not work and that most likely will corrupt the data and using instead the functions that do behave correctly, generally from the intl and mbstring extensions. However, using functions that can handle Unicode encodings is just the beginning. No matter the functions the language provides, it is essential to know the Unicode specification. For instance, a program that assumes there is only uppercase and lowercase is making a wrong assumption.
// 
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-11-11)
// URL: https://www.php.net/manual/en/language.types.string.php
// TYPES_STRINGS - END
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_ADDCSLASHES  
// ============================== PUBLIC
// ============================== ABOUT
// Quote string with slashes in a C style.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// addcslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_addcslashes($string, $characters)
{
$return_addcslashes = null;

// ========== ADDCSLASHES - BEGIN
// ===== ABOUT
// Quote string with slashes in a C style
// ===== DESCRIPTION
// Returns a string with backslashes before characters that are listed in characters parameter.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// addcslashes(string $string, string $characters): string
// ===== CODE
$return_addcslashes = addcslashes(

$string, // string string - The string to be escaped.

$characters // string characters - A list of characters to be escaped. If characters contains characters \n, \r etc., they are converted in C-like style, while other non-alphanumeric characters with ASCII codes lower than 32 and higher than 126 converted to octal representation.
// When you define a sequence of characters in the characters argument make sure that you know what characters come between the characters that you set as the start and end of the range.
// [php]
// echo addcslashes('foo[ ]', 'A..z');
// // output:  \f\o\o\[ \]
// // All upper and lower-case letters will be escaped
// // ... but so will the [\]^_`
// [/php]
// Also, if the first character in a range has a higher ASCII value than the second character in the range, no range will be constructed. Only the start, end and period characters will be escaped. Use the ord() function to find the ASCII value for a character.
// [php]
// echo addcslashes("zoo['.']", 'z..A');
// // output:  \zoo['\.']
// [/php]
// Be careful if you choose to escape characters 0, a, b, f, n, r, t and v. They will be converted to \0, \a, \b, \f, \n, \r, \t and \v, all of which are predefined escape sequences in C. Many of these sequences are also defined in other C-derived languages, including PHP, meaning that you may not get the desired result if you use the output of addcslashes() to generate code in those languages with these characters defined in characters.

); // Return Values
// Returns the escaped string.
// 
// [examples]
// Examples
// [example]
// characters like "\0..\37", which would escape all characters with ASCII code between 0 and 31.
// Example #1 addcslashes() example
// [php]
// $escaped = addcslashes($not_escaped, "\0..\37!@\177..\377");
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/function.addcslashes.php
// ========== ADDCSLASHES - END

// SYNTAX:
// string addcslashes(string $string, string $characters)

return $return_addcslashes; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_ADDCSLASHES  
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_ADDSLASHES  
// ============================== PUBLIC
// ============================== ABOUT
// Quote string with slashes.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// addslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_addslashes($string)
{
$return_addslashes = null;

// ========== ADDSLASHES - BEGIN
// ===== ABOUT
// Quote string with slashes
// ===== DESCRIPTION
// Returns a string with backslashes added before characters that need to be escaped. These characters are:
// * single quote (')
// * double quote (")
// * backslash (\)
// * NUL (the NUL byte)
// A use case of addslashes() is escaping the aforementioned characters in a string that is to be evaluated by PHP:
// [php]
// $str = "O'Reilly?";
// eval("echo '" . addslashes($str) . "';");
// [/php]
// The addslashes() is sometimes incorrectly used to try to prevent SQL Injection. Instead, database-specific escaping functions and/or prepared statements should be used.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// addslashes(string $string): string
// ===== CODE
$return_addslashes = addslashes(

$string // string string - The string to be escaped.

); // Return Values
// Returns the escaped string.
// 
// [examples]
// Examples
// [example]
// Example #1 An addslashes() example
// [php]
// $str = "Is your name O'Reilly?";
// 
// // Outputs: Is your name O\'Reilly?
// echo addslashes($str);
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/function.addslashes.php
// ========== ADDSLASHES - END

// SYNTAX:
// string addslashes(string $string)

return $return_addslashes; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_ADDSLASHES  
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_BIN2HEX    
// ============================== PUBLIC
// ============================== ABOUT
// Convert binary data into hexadecimal representation.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// bin2hex() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_bin2hex($string)
{
$return_bin2hex = null;

// ========== BIN2HEX - BEGIN
// ===== ABOUT
// Convert binary data into hexadecimal representation
// ===== DESCRIPTION
// Returns an ASCII string containing the hexadecimal representation of string. The conversion is done byte-wise with the high-nibble first.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// bin2hex(string $string): string
// ===== CODE
$return_bin2hex = bin2hex(

$string // string - A string.

); // Return Values
// Returns the hexadecimal representation of the given string.
// 
// [examples]
// Examples
// [example]
// Example #1 bin2hex() example
// [php]
// 
// $hex = bin2hex('Hello world!');
// 
// var_dump($hex);
// var_dump(hex2bin($hex));
// [/php]
// The above example will output:
// [result]
// string(24) "48656c6c6f20776f726c6421"
// string(12) "Hello world!"
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.bin2hex.php
// ========== BIN2HEX - END

// SYNTAX:
// string bin2hex(string $string)

return $return_bin2hex; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_BIN2HEX    
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_CHOP     
// ============================== PUBLIC
// ============================== ABOUT
// Strip whitespace (or other characters) from the end of a string.
// 
// chop - Alias of rtrim().
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// chop() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_chop($string, $characters = " \n\r\t\v\x00")
{
$return_chop = null;

// ========== CHOP - BEGIN
// ===== ABOUT
// chop - Alias of rtrim()
// ===== DESCRIPTION
// This function is an alias of: rtrim().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// ===== CODE
$return_chop = chop(

$string, // string $string

$characters // string $characters

); // Return
// string
// 
// Notes
// Note: chop() is different than the Perl chop() function, which removes the last character in the string.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.chop.php
// ========== CHOP - END

// ========== RTRIM - BEGIN
// ===== ABOUT
// Strip whitespace (or other characters) from the end of a string
// ===== DESCRIPTION
// This function returns a string with whitespace (or other characters) stripped from the end of string.
// Without the second parameter, rtrim() will strip these characters:
// * " "  (ASCII 32 (0x20)), an ordinary space.
// * "\t" (ASCII 9 (0x09)) , a tab.
// * "\n" (ASCII 10 (0x0A)), a new line (line feed).
// * "\r" (ASCII 13 (0x0D)), a carriage return.
// * "\0" (ASCII 0 (0x00)) , the NULL-byte.
// * "\v" (ASCII 11 (0x0B)), a vertical tab.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// rtrim(string $string, string $characters = " \n\r\t\v\x00"): string
// ===== CODE
// $return_rtrim = rtrim(

// $string, // string string - The input string.

// $characters // string characters - You can also specify the characters you want to strip, by means of the characters parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.

// ); // Return Values
// Returns the modified string.
// 
// [examples]
// Examples
// [example]
// Example #1 Usage example of rtrim()
// [php]
// 
// $text = "\t\tThese are a few words :) ...  ";
// $binary = "\x09Example string\x0A";
// $hello  = "Hello World";
// var_dump($text, $binary, $hello);
// 
// print "\n";
// 
// $trimmed = rtrim($text);
// var_dump($trimmed);
// 
// $trimmed = rtrim($text, " \t.");
// var_dump($trimmed);
// 
// $trimmed = rtrim($hello, "Hdle");
// var_dump($trimmed);
// 
// // trim the ASCII control characters at the end of $binary
// // (from 0 to 31 inclusive)
// $clean = rtrim($binary, "\x00..\x1F");
// var_dump($clean);
// 
// [/php]
// The above example will output:
// [result]
// string(32) "        These are a few words :) ...  "
// string(16) "    Example string
// "
// string(11) "Hello World"
// 
// string(30) "        These are a few words :) ..."
// string(26) "        These are a few words :)"
// string(9) "Hello Wor"
// string(15) "    Example string"
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.rtrim.php
// ========== RTRIM - END

// SYNTAX:
// string chop(string $string, string $characters = " \n\r\t\v\x00")

return $return_chop; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_CHOP     
// ==============================


// ============================== BEGIN
//      PHP_TEXT_STRINGS_CHR      
// ============================== PUBLIC
// ============================== ABOUT
// Generate a single-byte string from a number.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// chr() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_chr($codepoint)
{
$return_chr = null;

// ========== CHR - BEGIN
// ===== ABOUT
// Generate a single-byte string from a number
// ===== DESCRIPTION
// Returns a one-character string containing the character specified by interpreting codepoint as an unsigned integer.
// This can be used to create a one-character string in a single-byte encoding such as ASCII, ISO-8859, or Windows 1252, by passing the position of a desired character in the encoding's mapping table. However, note that this function is not aware of any string encoding, and in particular cannot be passed a Unicode code point value to generate a string in a multibyte encoding like UTF-8 or UTF-16.
// This function complements ord().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// chr(int $codepoint): string
// ===== CODE
$return_chr = chr(

$codepoint // int $codepoint - An integer between 0 and 255.
// Values outside the valid range (0..255) will be bitwise and'ed with 255, which is equivalent to the following algorithm:
// [php]
// while ($bytevalue < 0) {
//     $bytevalue += 256;
// }
// $bytevalue %= 256;
// [/php]

); // Return Values
// A single-character string containing the specified byte.
// 
// Changelog
// Version - Description
// 7.4.0   - The function no longer silently accepts unsupported codepoints, and casts these to 0.
// 
// [examples]
// Examples
// [example]
// Example #1 chr() example
// [php]
// // Assumes the string will be used as ASCII or an ASCII-compatible encoding
// 
// $str = "The string ends in escape: ";
// $str .= chr(27); /* add an escape character at the end of $str */
// 
// /* Often this is more useful */
// 
// $str = sprintf("The string ends in escape: %c", 27);
// [/php]
// [/example]
// [example]
// Example #2 Overflow behavior
// [php]
// echo chr(-159), chr(833), PHP_EOL;
// [/php]
// The above example will output:
// [result]
// aA
// [/result]
// [/example]
// [example]
// Example #3 Building a UTF-8 string from individual bytes
// [php]
// $str = chr(240) . chr(159) . chr(144) . chr(152);
// echo $str;
// [/php]
// The above example will output:
// [result]
// 🐘
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-07-23)
// URL: https://www.php.net/manual/en/function.chr.php
// ========== CHR - END

// SYNTAX:
// string chr(int $codepoint)

return $return_chr; // string
}
// ============================== END
//      PHP_TEXT_STRINGS_CHR      
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_CHUNK_SPLIT  
// ============================== PUBLIC
// ============================== ABOUT
// Split a string into smaller chunks.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// chunk_split() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_chunk_split($string, $length = 76, $separator = "\r\n")
{
$return_chunk_split = null;

// ========== CHUNK_SPLIT - BEGIN
// ===== ABOUT
// Split a string into smaller chunks
// ===== DESCRIPTION
// Can be used to split a string into smaller chunks which is useful for e.g. converting base64_encode() output to match RFC 2045 semantics. It inserts separator every length characters.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// chunk_split(string $string, int $length = 76, string $separator = "\r\n"): string
// ===== CODE
$return_chunk_split = chunk_split(

$string, // string string - The string to be chunked.

$length, // int length - The chunk length.

$separator // string separator - The line ending sequence.

); // Return Values
// Returns the chunked string.
// 
// [examples]
// Examples
// [example]
// Example #1 chunk_split() example
// [php]
// // format $data using RFC 2045 semantics
// $new_string = chunk_split(base64_encode($data));
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.chunk-split.php
// ========== CHUNK_SPLIT - END

// SYNTAX:
// string chunk_split(string $string, int $length = 76, string $separator = "\r\n")

return $return_chunk_split; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_CHUNK_SPLIT  
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_CONVERT_CYR_STRING
// ============================== OFFLINE
// ============================== ABOUT
// Convert from one Cyrillic character set to another.
// 
// Warning: This function has been DEPRECATED as of PHP 7.4.0, and REMOVED as of PHP 8.0.0. Relying on this function is highly discouraged.
// ============================== SUPPORT
// PHP_4 - PHP_7
// ============================== USING FUNCTIONS (1)
// convert_cyr_string() - PHP_4, PHP_5, PHP_7
// ============================== CODE
/*
function php_text_strings_convert_cyr_string($str, $from, $to)
{
$return_convert_cyr_string = null;

// ========== CONVERT_CYR_STRING - BEGIN
// ===== ABOUT
// Convert from one Cyrillic character set to another
// Warning: This function has been DEPRECATED as of PHP 7.4.0, and REMOVED as of PHP 8.0.0. Relying on this function is highly discouraged.
// ===== DESCRIPTION
// Converts from one Cyrillic character set to another.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7
// ===== SYNTAX
// convert_cyr_string(string $str, string $from, string $to): string
// ===== CODE
$return_convert_cyr_string = convert_cyr_string(

$str, // string str - The string to be converted.

$from, // string from - The source Cyrillic character set, as a single character.

$to // string to - The target Cyrillic character set, as a single character.
// 
// Supported characters are:
// * k - koi8-r
// * w - windows-1251
// * i - iso8859-5
// * a - x-cp866
// * d - x-cp866
// * m - x-mac-cyrillic

); // Return Values
// Returns the converted string.
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-22)
// URL: https://www.php.net/manual/en/function.convert-cyr-string.php
// ========== CONVERT_CYR_STRING - END

// SYNTAX:
// string convert_cyr_string(string $str, string $from, string $to)

return $return_convert_cyr_string; // string
}
*/
// ============================== END
// PHP_TEXT_STRINGS_CONVERT_CYR_STRING
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_CONVERT_UUDECODE
// ============================== OFFLINE
// ============================== ABOUT
// Decode a uuencoded string.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// convert_uudecode() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_convert_uudecode($string)
{
$return_convert_uudecode = false;

// ========== CONVERT_UUDECODE - BEGIN
// ===== ABOUT
// Decode a uuencoded string
// ===== DESCRIPTION
// convert_uudecode() decodes a uuencoded string.
// Note: convert_uudecode() neither accepts the begin nor the end line, which are part of uuencoded files.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// convert_uudecode(string $string): string|false
// ===== CODE
$return_convert_uudecode = convert_uudecode(

$string // string string - The uuencoded data.

); // Return Values
// Returns the decoded data as a string or false on failure.
// 
// [examples]
// Examples
// [example]
// Example #1 convert_uudecode() example
// [php]
// echo convert_uudecode("+22!L;W9E(%!(4\"$`\n`");
// [/php]
// The above example will output:
// [result]
// I love PHP!
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.convert-uudecode.php
// ========== CONVERT_UUDECODE - END

// SYNTAX:
// string|false convert_uudecode(string $string)

return $return_convert_uudecode; // string|false
}
*/
// ============================== END
// PHP_TEXT_STRINGS_CONVERT_UUDECODE
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_CONVERT_UUENCODE
// ============================== OFFLINE
// ============================== ABOUT
// Uuencode a string.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// convert_uuencode() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_convert_uuencode($string)
{
$return_convert_uuencode = null;

// ========== CONVERT_UUENCODE - BEGIN
// ===== ABOUT
// Uuencode a string
// ===== DESCRIPTION
// convert_uuencode() encodes a string using the uuencode algorithm.
// Uuencode translates all strings (including binary data) into printable characters, making them safe for network transmissions. Uuencoded data is about 35% larger than the original.
// Note: convert_uuencode() neither produces the begin nor the end line, which are part of uuencoded files.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// convert_uuencode(string $string): string
// ===== CODE
$return_convert_uuencode = convert_uuencode(

$string // string string - The data to be encoded.

); // Return Values
// Returns the uuencoded data.
// 
// Changelog
// Version - Description
// 8.0.0   - Prior to this version, trying to convert an empty string returned false for no particular reason.
// 
// [examples]
// Examples
// [example]
// Example #1 convert_uuencode() example
// [php]
// $some_string = "test\ntext text\r\n";
// 
// echo convert_uuencode($some_string);
// [/php]
// The above example will output:
// [result]
// 0=&5S=`IT97AT('1E>'0-"@``
// `
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.convert-uuencode.php
// ========== CONVERT_UUENCODE - END

// SYNTAX:
// string convert_uuencode(string $string)

return $return_convert_uuencode; // string
}
*/
// ============================== END
// PHP_TEXT_STRINGS_CONVERT_UUENCODE
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_COUNT_CHARS  
// ============================== PUBLIC
// ============================== ABOUT
// Return information about characters used in a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// count_chars() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_count_chars($string, $mode = 0)
{
$return_count_chars = null;

// ========== COUNT_CHARS - BEGIN
// ===== ABOUT
// Return information about characters used in a string
// ===== DESCRIPTION
// Counts the number of occurrences of every byte-value (0..255) in string and returns it in various ways.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// count_chars(string $string, int $mode = 0): array|string
// ===== CODE
$return_count_chars = count_chars(

$string, // string string - The examined string.

$mode // int mode - See return values.

); // Return Values
// Depending on mode count_chars() returns one of the following:
// * 0 - an array with the byte-value as key and the frequency of every byte as value.
// * 1 - same as 0 but only byte-values with a frequency greater than zero are listed.
// * 2 - same as 0 but only byte-values with a frequency equal to zero are listed.
// * 3 - a string containing all unique characters is returned.
// * 4 - a string containing all not used characters is returned.
// 
// Changelog
// Version - Description
// 8.0.0   - Prior to this version, the function returned false on failure.
// 
// [examples]
// Examples
// [example]
// Example #1 count_chars() example
// [php]
// $data = "Two Ts and one F.";
// 
// foreach (count_chars($data, 1) as $i => $val) {
//    echo "There were $val instance(s) of \"" , chr($i) , "\" in the string.\n";
// }
// [/php]
// The above example will output:
// [result]
// There were 4 instance(s) of " " in the string.
// There were 1 instance(s) of "." in the string.
// There were 1 instance(s) of "F" in the string.
// There were 2 instance(s) of "T" in the string.
// There were 1 instance(s) of "a" in the string.
// There were 1 instance(s) of "d" in the string.
// There were 1 instance(s) of "e" in the string.
// There were 2 instance(s) of "n" in the string.
// There were 2 instance(s) of "o" in the string.
// There were 1 instance(s) of "s" in the string.
// There were 1 instance(s) of "w" in the string.
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.count-chars.php
// ========== COUNT_CHARS - END

// SYNTAX:
// array|string count_chars(string $string, int $mode = 0)

return $return_count_chars; // array|string
}
// ============================== END
//  PHP_TEXT_STRINGS_COUNT_CHARS  
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_CRC32     
// ============================== PUBLIC
// ============================== ABOUT
// Calculates the crc32 polynomial of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// crc32() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_crc32($string)
{
$return_crc32 = 0;

// ========== CRC32 - BEGIN
// ===== ABOUT
// Calculates the crc32 polynomial of a string
// ===== DESCRIPTION
// Generates the cyclic redundancy checksum polynomial of 32-bit lengths of the string. This is usually used to validate the integrity of data being transmitted.
//  Warning:
//  Because PHP's integer type is signed many crc32 checksums will result in negative integers on 32bit platforms. On 64bit installations all crc32() results will be positive integers though.
//  So you need to use the "%u" formatter of sprintf() or printf() to get the string representation of the unsigned crc32() checksum in decimal format.
//  For a hexadecimal representation of the checksum you can either use the "%x" formatter of sprintf() or printf() or the dechex() conversion functions, both of these also take care of converting the crc32() result to an unsigned integer.
//  Having 64bit installations also return negative integers for higher result values was considered but would break the hexadecimal conversion as negatives would get an extra 0xFFFFFFFF######## offset then. As hexadecimal representation seems to be the most common use case we decided to not break this even if it breaks direct decimal comparisons in about 50% of the cases when moving from 32 to 64bits.
//  In retrospect having the function return an integer maybe wasn't the best idea and returning a hex string representation right away (as e.g. md5() does) might have been a better plan to begin with.
//  For a more portable solution you may also consider the generic hash(). hash("crc32b", $str) will return the same string as str_pad(dechex(crc32($str)), 8, '0', STR_PAD_LEFT).
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// crc32(string $string): int
// ===== CODE
$return_crc32 = crc32(

$string // string string - The data.

); // Return Values
// Returns the crc32 checksum of string as an integer.
// 
// [examples]
// Examples
// [example]
// Example #1 Displaying a crc32 checksum
// This example shows how to print a converted checksum with the printf() function:
// [php]
// $checksum = crc32("The quick brown fox jumped over the lazy dog.");
// printf("%u\n", $checksum);
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.crc32.php
// ========== CRC32 - END

// SYNTAX:
// int crc32(string $string)

return $return_crc32; // int
}
// ============================== END
//     PHP_TEXT_STRINGS_CRC32     
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_CRYPT     
// ============================== PUBLIC
// ============================== ABOUT
// One-way string hashing.
// 
// Warning: This function is not (yet) binary safe!
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// crypt() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_crypt($string, $salt)
{
$return_crypt = null;

// ========== CRYPT - BEGIN
// ===== ABOUT
// One-way string hashing
// Warning: This function is not (yet) binary safe!
// ===== DESCRIPTION
// crypt() will return a hashed string using the standard Unix DES-based algorithm or alternative algorithms. password_verify() is compatible with crypt(). Therefore, password hashes created by crypt() can be used with password_verify().
// Prior to PHP 8.0.0, the salt parameter was optional. However, crypt() creates a weak hash without the salt, and raises an E_NOTICE error without it. Make sure to specify a strong enough salt for better security.
// password_hash() uses a strong hash, generates a strong salt, and applies proper rounds automatically. password_hash() is a simple crypt() wrapper and compatible with existing password hashes. Use of password_hash() is encouraged.
// The hash type is triggered by the salt argument. If no salt is provided, PHP will auto-generate either a standard two character (DES) salt, or a twelve character (MD5), depending on the availability of MD5 crypt(). PHP sets a constant named CRYPT_SALT_LENGTH which indicates the longest valid salt allowed by the available hashes.
// The standard DES-based crypt() returns the salt as the first two characters of the output. It also only uses the first eight characters of string, so longer strings that start with the same eight characters will generate the same result (when the same salt is used).
// 
// The following hash types are supported:
// * CRYPT_STD_DES  - Standard DES-based hash with a two character salt from the alphabet "./0-9A-Za-z". Using invalid characters in the salt will cause crypt() to fail.
// * CRYPT_EXT_DES  - Extended DES-based hash. The "salt" is a 9-character string consisting of an underscore followed by 4 characters of iteration count and 4 characters of salt. Each of these 4-character strings encode 24 bits, least significant character first. The values 0 to 63 are encoded as ./0-9A-Za-z. Using invalid characters in the salt will cause crypt() to fail.
// * CRYPT_MD5      - MD5 hashing with a twelve character salt starting with $1$
// * CRYPT_BLOWFISH - Blowfish hashing with a salt as follows: "$2a$", "$2x$" or "$2y$", a two digit cost parameter, "$", and 22 characters from the alphabet "./0-9A-Za-z". Using characters outside of this range in the salt will cause crypt() to return a zero-length string. The two digit cost parameter is the base-2 logarithm of the iteration count for the underlying Blowfish-based hashing algorithm and must be in range 04-31, values outside this range will cause crypt() to fail. "$2x$" hashes are potentially weak; "$2a$" hashes are compatible and mitigate this weakness. For new hashes, "$2y$" should be used.
// * CRYPT_SHA256   - SHA-256 hash with a sixteen character salt prefixed with $5$. If the salt string starts with 'rounds=<N>$', the numeric value of N is used to indicate how many times the hashing loop should be executed, much like the cost parameter on Blowfish. The default number of rounds is 5000, there is a minimum of 1000 and a maximum of 999,999,999. Any selection of N outside this range will be truncated to the nearest limit.
// * CRYPT_SHA512   - SHA-256 hash with a sixteen character salt prefixed with $5$. If the salt string starts with 'rounds=<N>$', the numeric value of N is used to indicate how many times the hashing loop should be executed, much like the cost parameter on Blowfish. The default number of rounds is 5000, there is a minimum of 1000 and a maximum of 999,999,999. Any selection of N outside this range will be truncated to the nearest limit.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// crypt(string $string, string $salt): string
// ===== CODE
$return_crypt = crypt(

$string, // string string - The string to be hashed.
// Caution: Using the CRYPT_BLOWFISH algorithm, will result in the string parameter being truncated to a maximum length of 72 bytes.

$salt // string salt - A salt string to base the hashing on. If not provided, the behaviour is defined by the algorithm implementation and can lead to unexpected results.

); // Return Values
// Returns the hashed string or a string that is shorter than 13 characters and is guaranteed to differ from the salt on failure.
// Warning: When validating passwords, a string comparison function that isn't vulnerable to timing attacks should be used to compare the output of crypt() to the previously known hash. PHP provides hash_equals() for this purpose.
// 
// Changelog
// Version - Description
// 8.0.0   - The salt is no longer optional.
// 
// [examples]
// Examples
// [example]
// Example #1 crypt() examples
// [php]
// $user_input = 'rasmuslerdorf';
// $hashed_password = '$6$rounds=1000000$NJy4rIPjpOaU$0ACEYGg/aKCY3v8O8AfyiO7CTfZQ8/W231Qfh2tRLmfdvFD6XfHk12u6hMr9cYIA4hnpjLNSTRtUwYr9km9Ij/';
// 
// // Validate an existing crypt() hash in a way that is compatible with non-PHP software.
// if (hash_equals($hashed_password, crypt($user_input, $hashed_password))) {
//    echo "Password verified!";
// }
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: There is no decrypt function, since crypt() uses a one-way algorithm.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.crypt.php
// ========== CRYPT - END

// SYNTAX:
// string crypt(string $string, string $salt)

return $return_crypt; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_CRYPT     
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_ECHO     
// ============================== PUBLIC
// ============================== ABOUT
// Output one or more strings.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// echo() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_echo($expressions)
{

// ========== ECHO - BEGIN
// ===== ABOUT
// Output one or more strings
// ===== DESCRIPTION
// Outputs one or more expressions, with no additional newlines or spaces.
// echo is not a function but a language construct. Its arguments are a list of expressions following the echo keyword, separated by commas, and not delimited by parentheses. Unlike some other language constructs, echo does not have any return value, so it cannot be used in the context of an expression.
// echo also has a shortcut syntax, where you can immediately follow the opening tag with an equals sign. This syntax is available even with the short_open_tag configuration setting disabled.
// I have < ?=$foo? > foo.
// The major differences to print are that echo accepts multiple arguments and doesn't have a return value.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// echo(string ...$expressions): void
// ===== CODE
echo(

$expressions // string $expressions - One or more string expressions to output, separated by commas. Non-string values will be coerced to strings, even when the strict_types directive is enabled.

); // Return Values
// No value is returned.
// 
// [examples]
// Examples
// [example]
// Example #1 echo examples
// [php]
// echo "echo does not require parentheses.";
// 
// // Strings can either be passed individually as multiple arguments or
// // concatenated together and passed as a single argument
// echo 'This ', 'string ', 'was ', 'made ', 'with multiple parameters.', "\n";
// echo 'This ' . 'string ' . 'was ' . 'made ' . 'with concatenation.' . "\n";
// 
// // No newline or space is added; the below outputs "helloworld" all on one line
// echo "hello";
// echo "world";
// 
// // Same as above
// echo "hello", "world";
// 
// echo "This string spans
// multiple lines. The newlines will be
// output as well";
// 
// echo "This string spans\nmultiple lines. The newlines will be\noutput as well.";
// 
// // The argument can be any expression which produces a string
// $foo = "example";
// echo "foo is $foo"; // foo is example
// 
// $fruits = ["lemon", "orange", "banana"];
// echo implode(" and ", $fruits); // lemon and orange and banana
// 
// // Non-string expressions are coerced to string, even if declare(strict_types=1) is used
// echo 6 * 7; // 42
// 
// // Because echo does not behave as an expression, the following code is invalid.
// ($some_var) ? echo 'true' : echo 'false';
// 
// // However, the following examples will work:
// ($some_var) ? print 'true' : print 'false'; // print is also a construct, but
//                                             // it is a valid expression, returning 1,
//                                             // so it may be used in this context.
// 
// echo $some_var ? 'true': 'false'; // evaluating the expression first and passing it to echo
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: Because this is a language construct and not a function, it cannot be called using variable functions, or named arguments.
//  Note: Using with parentheses
//  Surrounding a single argument to echo with parentheses will not raise a syntax error, and produces syntax which looks like a normal function call. However, this can be misleading, because the parentheses are actually part of the expression being output, not part of the echo syntax itself.
//  [example]
//  [php]
//  echo "hello";
//  // outputs "hello"
//  
//  echo("hello");
//  // also outputs "hello", because ("hello") is a valid expression
//  
//  echo(1 + 2) * 3;
//  // outputs "9"; the parentheses cause 1+2 to be evaluated first, then 3*3
//  // the echo statement sees the whole expression as one argument
//  
//  echo "hello", " world";
//  // outputs "hello world"
//  
//  echo("hello"), (" world");
//  // outputs "hello world"; the parentheses are part of each expression
//  
//  echo("hello", " world");
//  // Throws a Parse Error because ("hello", " world") is not a valid expression
//  [/php]
//  [/example]
//  Tip: Passing multiple arguments to echo can avoid complications arising from the precedence of the concatenation operator in PHP. For instance, the concatenation operator has higher precedence than the ternary operator, and prior to PHP 8.0.0 had the same precedence as addition and subtraction:
//  [example]
//  [php]
//  // Below, the expression 'Hello ' . isset($name) is evaluated first,
//  // and is always true, so the argument to echo is always $name
//  echo 'Hello ' . isset($name) ? $name : 'John Doe' . '!';
//  
//  // The intended behaviour requires additional parentheses
//  echo 'Hello ' . (isset($name) ? $name : 'John Doe') . '!';
//  
//  // In PHP prior to 8.0.0, the below outputs "2", rather than "Sum: 3"
//  echo 'Sum: ' . 1 + 2;
//  
//  // Again, adding parentheses ensures the intended order of evaluation
//  echo 'Sum: ' . (1 + 2);
//  [/php]
//  [/example]
//  If multiple arguments are passed in, then parentheses will not be required to enforce precedence, because each expression is separate:
//  [example]
//  [php]
//  echo "Hello ", isset($name) ? $name : "John Doe", "!";
//  
//  echo "Sum: ", 1 + 2;
//  [/php]
//  [/example]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.echo.php
// ========== ECHO - END

// SYNTAX:
// void echo(string $expressions)

// Return: void
}
// ============================== END
//     PHP_TEXT_STRINGS_ECHO     
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_EXPLODE    
// ============================== PUBLIC
// ============================== ABOUT
// Split a string by a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// explode() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== USING CONSTANTS (1)
// PHP_INT_MAX - explode()
// ============================== CODE
function php_text_strings_explode($separator, $string, $limit = PHP_INT_MAX)
{
$return_explode = null;

// ========== EXPLODE - BEGIN
// ===== ABOUT
// Split a string by a string
// ===== DESCRIPTION
// Returns an array of strings, each of which is a substring of string formed by splitting it on boundaries formed by the string separator.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// explode(string $separator, string $string, int $limit = PHP_INT_MAX): array
// ===== CODE
$return_explode = explode(

$separator, // string separator - The boundary string.

$string, // string string - The input string.

$limit // int limit - If limit is set and positive, the returned array will contain a maximum of limit elements with the last element containing the rest of string.
// If the limit parameter is negative, all components except the last -limit are returned.
// If the limit parameter is zero, then this is treated as 1.
// Note: Prior to PHP 8.0, implode() accepted its parameters in either order. explode() has never supported this: you must ensure that the separator argument comes before the string argument.

); // Return Values
// Returns an array of strings created by splitting the string parameter on boundaries formed by the separator.
// If separator is an empty string (""), explode() throws a ValueError. If separator contains a value that is not contained in string and a negative limit is used, then an empty array will be returned, otherwise an array containing string will be returned. If separator values appear at the start or end of string, said values will be added as an empty array value either in the first or last position of the returned array respectively.
// 
// Changelog
// Version - Description
// 8.0.0   - explode() will now throw ValueError when separator parameter is given an empty string (""). Previously, explode() returned false instead.
// 
// [examples]
// Examples
// [example]
// Example #1 explode() examples
// [php]
// // Example 1
// $pizza  = "piece1 piece2 piece3 piece4 piece5 piece6";
// $pieces = explode(" ", $pizza);
// echo $pieces[0]; // piece1
// echo $pieces[1]; // piece2
// 
// // Example 2
// $data = "foo:*:1023:1000::/home/foo:/bin/sh";
// list($user, $pass, $uid, $gid, $gecos, $home, $shell) = explode(":", $data);
// echo $user; // foo
// echo $pass; // *
// 
// [/php]
// [/example]
// [example]
// Example #2 explode() return examples
// [php]
// //
// // A string that doesn't contain the delimiter will simply
// // return a one-length array of the original string.
// //
// $input1 = "hello";
// $input2 = "hello,there";
// $input3 = ',';
// var_dump( explode( ',', $input1 ) );
// var_dump( explode( ',', $input2 ) );
// var_dump( explode( ',', $input3 ) );
// 
// [/php]
// The above example will output:
// [result]
// array(1)
// (
//     [0] => string(5) "hello"
// )
// array(2)
// (
//     [0] => string(5) "hello"
//     [1] => string(5) "there"
// )
// array(2)
// (
//     [0] => string(0) ""
//     [1] => string(0) ""
// )
// [/result]
// [/example]
// [example]
// Example #3 limit parameter examples
// [php]
// $str = 'one|two|three|four';
// 
// // positive limit
// print_r(explode('|', $str, 2));
// 
// // negative limit
// print_r(explode('|', $str, -1));
// [/php]
// The above example will output:
// [result]
// Array
// (
//     [0] => one
//     [1] => two|three|four
// )
// Array
// (
//     [0] => one
//     [1] => two
//     [2] => three
// )
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.explode.php
// ========== EXPLODE - END

// SYNTAX:
// array explode(string $separator, string $string, int $limit = PHP_INT_MAX)

return $return_explode; // array
}
// ============================== END
//    PHP_TEXT_STRINGS_EXPLODE    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_FPRINTF    
// ============================== OFFLINE
// ============================== ABOUT
// Write a formatted string to a stream.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// fprintf() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_fprintf($stream, $format, $values)
{
$return_fprintf = 0;

// ========== FPRINTF - BEGIN
// ===== ABOUT
// Write a formatted string to a stream
// ===== DESCRIPTION
// Write a string produced according to format to the stream resource specified by stream.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// fprintf(resource $stream, string $format, mixed ...$values): int
// ===== CODE
$return_fprintf = fprintf(

$stream, // resource stream - A file system pointer resource that is typically created using fopen().

$format, // string format - The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.
// A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier.
// Argnum
// An integer followed by a dollar sign $, to specify which number argument to treat in the conversion.
// Flags
// Flag    - Description
// -       - Left-justify within the given field width; Right justification is the default
// +       - Prefix positive numbers with a plus sign +; Default only negative are prefixed with a negative sign.
// (space) - Pads the result with spaces. This is the default.
// 0       - Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros.
// '(char) - Pads the result with the character (char).
// Width
// Either an integer that says how many characters (minimum) this conversion should result in, or *. If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.
// Precision
// A period . optionally followed by either an integer or *, whose meaning depends on the specifier:
// * For e, E, f and F specifiers : this is the number of digits to be printed after the decimal point (by default, this is 6).
// * For g, G, h and H specifiers : this is the maximum number of significant digits to be printed.
// * For s specifier              : it acts as a cutoff point, setting a maximum character limit to the string.
// Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.
// Specifiers
// Specifier - Description
// %         - A literal percent character. No argument is required.
// b         - The argument is treated as an integer and presented as a binary number.
// c         - The argument is treated as an integer and presented as the character with that ASCII.
// d         - The argument is treated as an integer and presented as a (signed) decimal number.
// e         - The argument is treated as scientific notation (e.g. 1.2e+2).
// E         - Like the e specifier but uses uppercase letter (e.g. 1.2E+2).
// f         - The argument is treated as a float and presented as a floating-point number (locale aware).
// F         - The argument is treated as a float and presented as a floating-point number (non-locale aware).
// g         - General format.
//             Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
//             If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
// G         - Like the g specifier but uses E and f.
// h         - Like the g specifier but uses F. Available as of PHP 8.0.0.
// H         - Like the g specifier but uses E and F. Available as of PHP 8.0.0.
// o         - The argument is treated as an integer and presented as an octal number.
// s         - The argument is treated and presented as a string.
// u         - The argument is treated as an integer and presented as an unsigned decimal number.
// x         - The argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).
// X         - The argument is treated as an integer and presented as a hexadecimal number (with uppercase letters).
// Warning: The c type specifier ignores padding and width
// Warning: Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
// Variables will be co-erced to a suitable type for the specifier:
// Type Handling
// Type   - Specifiers
// string - s
// int    - d, u, c, o, x, X, b
// float  - e, E, f, F, g, G, h, H

$values // mixed values

); // Return Values
// Returns the length of the string written.
// 
// Errors/Exceptions
// As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ArgumentCountError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
// 
// Changelog
// Version - Description
// 8.0.0   - This function no longer returns false on failure.
// 8.0.0   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ArgumentCountError when less arguments are given than required; previously this function emitted a E_WARNING instead.
// 
// [examples]
// Examples
// [example]
// Example #1 fprintf(): zero-padded integers
// [php]
// if (!($fp = fopen('date.txt', 'w'))) {
//     return;
// }
// 
// fprintf($fp, "%04d-%02d-%02d", $year, $month, $day);
// // will write the formatted ISO date to date.txt
// [/php]
// [/example]
// [example]
// Example #2 fprintf(): formatting currency
// [php]
// if (!($fp = fopen('currency.txt', 'w'))) {
//     return;
// }
// 
// $money1 = 68.75;
// $money2 = 54.35;
// $money = $money1 + $money2;
// // echo $money will output "123.1";
// $len = fprintf($fp, '%01.2f', $money);
// // will write "123.10" to currency.txt
// 
// echo "wrote $len bytes to currency.txt";
// // use the return value of fprintf to determine how many bytes we wrote
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.fprintf.php
// ========== FPRINTF - END

// SYNTAX:
// int fprintf(resource $stream, string $format, mixed $values)

return $return_fprintf; // int
}
*/
// ============================== END
//    PHP_TEXT_STRINGS_FPRINTF    
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_GET_HTML_TRANSLATION_TABLE
// ============================== PUBLIC
// ============================== ABOUT
// Returns the translation table used by htmlspecialchars() and htmlentities().
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// get_html_translation_table() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_get_html_translation_table($table, $flags, $encoding = "UTF-8")
{
$return_get_html_translation_table = null;

// ========== GET_HTML_TRANSLATION_TABLE - BEGIN
// ===== ABOUT
// Returns the translation table used by htmlspecialchars() and htmlentities()
// ===== DESCRIPTION
// get_html_translation_table() will return the translation table that is used internally for htmlspecialchars() and htmlentities().
// Note: Special characters can be encoded in several ways. E.g. " can be encoded as &quot;, &#34; or &#x22. get_html_translation_table() returns only the form used by htmlspecialchars() and htmlentities().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// get_html_translation_table(int $table = HTML_SPECIALCHARS, int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, string $encoding = "UTF-8"): array
// ===== CODE
$return_get_html_translation_table = get_html_translation_table(

$table, // int table - Which table to return. Either HTML_ENTITIES or HTML_SPECIALCHARS.

$flags, // flags - A bitmask of one or more of the following flags, which specify which quotes the table will contain as well as which document type the table is for. The default is ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// Available flags constants
// Constant Name  - Description
// ENT_COMPAT     - Table will contain entities for double-quotes, but not for single-quotes.
// ENT_QUOTES     - Table will contain entities for both double and single quotes.
// ENT_NOQUOTES   - Table will neither contain entities for single quotes nor for double quotes.
// ENT_SUBSTITUTE - Replace invalid code unit sequences with a Unicode Replacement Character U+FFFD (UTF-8) or &#xFFFD; (otherwise) instead of returning an empty string.
// ENT_HTML401    - Table for HTML 4.01.
// ENT_XML1       - Table for XML 1.
// ENT_XHTML      - Table for XHTML.
// ENT_HTML5      - Table for HTML 5.

$encoding // string encoding - Encoding to use. If omitted, the default value for this argument is UTF-8.
// The following character sets are supported:
// 
// Supported charsets
// Charset     | Aliases                      | Description
// ISO-8859-1  | ISO8859-1                    | Western European, Latin-1.
// ISO-8859-5  | ISO8859-5                    | Little used cyrillic charset (Latin/Cyrillic).
// ISO-8859-15 | ISO8859-15                   | Western European, Latin-9. Adds the Euro sign, French and Finnish letters missing in Latin-1 (ISO-8859-1).
// UTF-8       |                              | ASCII compatible multi-byte 8-bit Unicode.
// cp866       | ibm866, 866                  | DOS-specific Cyrillic charset.
// cp1251      | Windows-1251, win-1251, 1251 | Windows-specific Cyrillic charset.
// cp1252      | Windows-1252, 1252           | Windows specific charset for Western European.
// KOI8-R      | koi8-ru, koi8r               | Russian.
// BIG5        | 950                          | Traditional Chinese, mainly used in Taiwan.
// GB2312      | 936                          | Simplified Chinese, national standard character set.
// BIG5-HKSCS  |                              | Big5 with Hong Kong extensions, Traditional Chinese.
// Shift_JIS   | SJIS, SJIS-win, cp932, 932   | Japanese
// EUC-JP      | EUCJP, eucJP-win             | Japanese
// MacRoman    |                              | Charset that was used by Mac OS.
// ''          |                              | An empty string activates detection from script encoding (Zend multibyte), default_charset and current locale (see nl_langinfo() and setlocale()), in this order. Not recommended.
// Note: Any other character sets are not recognized. The default encoding will be used instead and a warning will be emitted.

); // Return Values
// Returns the translation table as an array, with the original characters as keys and entities as values.
// 
// Changelog
// Version - Description
// 8.1.0   - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// [examples]
// Examples
// [example]
// Example #1 Translation Table Example
// [php]
// var_dump(get_html_translation_table(HTML_ENTITIES, ENT_QUOTES | ENT_HTML5));
// [/php]
// The above example will output something similar to:
// [result]
// array(1510) {
//   ["
// "]=>
//   string(9) "&NewLine;"
//   ["!"]=>
//   string(6) "&excl;"
//   ["""]=>
//   string(6) "&quot;"
//   ["#"]=>
//   string(5) "&num;"
//   ["$"]=>
//   string(8) "&dollar;"
//   ["%"]=>
//   string(8) "&percnt;"
//   ["&"]=>
//   string(5) "&amp;"
//   ["'"]=>
//   string(6) "&apos;"
//   // ...
// }
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.get-html-translation-table.php
// ========== GET_HTML_TRANSLATION_TABLE - END

// SYNTAX:
// array get_html_translation_table(int $table, int $flags, string $encoding = "UTF-8")

return $return_get_html_translation_table; // array
}
// ============================== END
// PHP_TEXT_STRINGS_GET_HTML_TRANSLATION_TABLE
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_HEBREV    
// ============================== PUBLIC
// ============================== ABOUT
// Convert logical Hebrew text to visual text.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// hebrev() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_hebrev($string, $max_chars_per_line = 0)
{
$return_hebrev = null;

// ========== HEBREV - BEGIN
// ===== ABOUT
// Convert logical Hebrew text to visual text
// ===== DESCRIPTION
// Converts logical Hebrew text to visual text.
// The function tries to avoid breaking words.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// hebrev(string $string, int $max_chars_per_line = 0): string
// ===== CODE
$return_hebrev = hebrev(

$string, // string string - A Hebrew input string.

$max_chars_per_line // int max_chars_per_line - This optional parameter indicates maximum number of characters per line that will be returned.

); // Return Values
// Returns the visual string.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-20)
// URL: https://www.php.net/manual/en/function.hebrev.php
// ========== HEBREV - END

// SYNTAX:
// string hebrev(string $string, int $max_chars_per_line = 0)

return $return_hebrev; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_HEBREV    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_HEBREVC    
// ============================== OFFLINE
// ============================== ABOUT
// Convert logical Hebrew text to visual text with newline conversion.
// 
// Warning: This function has been DEPRECATED as of PHP 7.4.0, and REMOVED as of PHP 8.0.0. Relying on this function is highly discouraged.
// ============================== SUPPORT
// PHP_4 - PHP_7
// ============================== USING FUNCTIONS (1)
// hebrevc() - PHP_4, PHP_5, PHP_7
// ============================== CODE
/*
function php_text_strings_hebrevc($hebrew_text, $max_chars_per_line = 0)
{
$return_hebrevc = null;

// ========== HEBREVC - BEGIN
// ===== ABOUT
// Convert logical Hebrew text to visual text with newline conversion
// Warning: This function has been DEPRECATED as of PHP 7.4.0, and REMOVED as of PHP 8.0.0. Relying on this function is highly discouraged.
// ===== DESCRIPTION
// This function is similar to hebrev() with the difference that it converts newlines (\n) to "<br>\n".
// The function tries to avoid breaking words.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7
// ===== SYNTAX
// hebrevc(string $hebrew_text, int $max_chars_per_line = 0): string
// ===== CODE
$return_hebrevc = hebrevc(

$hebrew_text, // string hebrew_text - A Hebrew input string.

$max_chars_per_line // int max_chars_per_line - This optional parameter indicates maximum number of characters per line that will be returned.

); // Return Values
// Returns the visual string.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-22)
// URL: https://www.php.net/manual/en/function.hebrevc.php
// ========== HEBREVC - END

// SYNTAX:
// string hebrevc(string $hebrew_text, int $max_chars_per_line = 0)

return $return_hebrevc; // string
}
*/
// ============================== END
//    PHP_TEXT_STRINGS_HEBREVC    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_HEX2BIN    
// ============================== OFFLINE
// ============================== ABOUT
// Decodes a hexadecimally encoded binary string.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// hex2bin() - PHP_5 >= PHP_5_4_0, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_hex2bin($string)
{
$return_hex2bin = false;

// ========== HEX2BIN - BEGIN
// ===== ABOUT
// Decodes a hexadecimally encoded binary string
// ===== DESCRIPTION
// Decodes a hexadecimally encoded binary string.
// Caution: This function does NOT convert a hexadecimal number to a binary number. This can be done using the base_convert() function.
// ===== SUPPORTED
// PHP_5 >= PHP_5_4_0, PHP_7, PHP_8
// ===== SYNTAX
// hex2bin(string $string): string|false
// ===== CODE
$return_hex2bin = hex2bin(

$string // string string - Hexadecimal representation of data.

); // Return Values
// Returns the binary representation of the given data or false on failure.
// 
// Errors/Exceptions
// If the hexadecimal input string is of odd length or invalid hexadecimal string an E_WARNING level error is thrown.
// 
// [examples]
// Examples
// [example]
// Example #1 hex2bin() example
// [php]
// $hex = hex2bin("6578616d706c65206865782064617461");
// var_dump($hex);
// [/php]
// The above example will output something similar to:
// [result]
// string(16) "example hex data"
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.hex2bin.php
// ========== HEX2BIN - END

// SYNTAX:
// string|false hex2bin(string $string)

return $return_hex2bin; // string|false
}
*/
// ============================== END
//    PHP_TEXT_STRINGS_HEX2BIN    
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_HTML_ENTITY_DECODE
// ============================== PUBLIC
// ============================== ABOUT
// Convert HTML entities to their corresponding characters.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// html_entity_decode() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_html_entity_decode($string, $flags, $encoding = null)
{
$return_html_entity_decode = null;

// ========== HTML_ENTITY_DECODE - BEGIN
// ===== ABOUT
// Convert HTML entities to their corresponding characters
// ===== DESCRIPTION
// html_entity_decode() is the opposite of htmlentities() in that it converts HTML entities in the string to their corresponding characters.
// More precisely, this function decodes all the entities (including all numeric entities) that a) are necessarily valid for the chosen document type - i.e., for XML, this function does not decode named entities that might be defined in some DTD - and b) whose character or characters are in the coded character set associated with the chosen encoding and are permitted in the chosen document type. All other entities are left as is.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// html_entity_decode(string $string, int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, ?string $encoding = null): string
// ===== CODE
$return_html_entity_decode = html_entity_decode(

$string, // string string - The input string.

$flags, // int flags - A bitmask of one or more of the following flags, which specify how to handle quotes and which document type to use. The default is ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// Available flags constants
// Constant Name  - Description
// ENT_COMPAT     - Will convert double-quotes and leave single-quotes alone.
// ENT_QUOTES     - Will convert both double and single quotes.
// ENT_NOQUOTES   - Will leave both double and single quotes unconverted.
// ENT_SUBSTITUTE - Replace invalid code unit sequences with a Unicode Replacement Character U+FFFD (UTF-8) or &#xFFFD; (otherwise) instead of returning an empty string.
// ENT_HTML401    - Handle code as HTML 4.01.
// ENT_XML1       - Handle code as XML 1.
// ENT_XHTML      - Handle code as XHTML.
// ENT_HTML5      - Handle code as HTML 5.

$encoding // string encoding - An optional argument defining the encoding used when converting characters.
// If omitted, encoding defaults to the value of the default_charset configuration option.
// Although this argument is technically optional, you are highly encouraged to specify the correct value for your code if the default_charset configuration option may be set incorrectly for the given input.
// The following character sets are supported:
// 
// Supported charsets
// Charset     | Aliases                      - Description
// ISO-8859-1  | ISO8859-1                    - Western European, Latin-1.
// ISO-8859-5  | ISO8859-5                    - Little used cyrillic charset (Latin/Cyrillic).
// ISO-8859-15 | ISO8859-15                   - Western European, Latin-9. Adds the Euro sign, French and Finnish letters missing in Latin-1 (ISO-8859-1).
// UTF-8       |                              - ASCII compatible multi-byte 8-bit Unicode.
// cp866       | ibm866, 866                  - DOS-specific Cyrillic charset.
// cp1251      | Windows-1251, win-1251, 1251 - Windows-specific Cyrillic charset.
// cp1252      | Windows-1252, 1252           - Windows specific charset for Western European.
// KOI8-R      | koi8-ru, koi8r               - Russian.
// BIG5        | 950                          - Traditional Chinese, mainly used in Taiwan.
// GB2312      | 936                          - Simplified Chinese, national standard character set.
// BIG5-HKSCS  |                              - Big5 with Hong Kong extensions, Traditional Chinese.
// Shift_JIS   | SJIS, SJIS-win, cp932, 932   - Japanese
// EUC-JP      | EUCJP, eucJP-win             - Japanese
// MacRoman    |                              - Charset that was used by Mac OS.
// ''          |                              - An empty string activates detection from script encoding (Zend multibyte), default_charset and current locale (see nl_langinfo() and setlocale()), in this order. Not recommended.
// Note: Any other character sets are not recognized. The default encoding will be used instead and a warning will be emitted.

); // Return Values
// Returns the decoded string.
// 
// Changelog
// Version - Description
// 8.1.0   - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 8.0.0   - encoding is nullable now.
// 
// [examples]
// Examples
// [example]
// Example #1 Decoding HTML entities
// [php]
// $orig = "I'll \"walk\" the <b>dog</b> now";
// 
// $a = htmlentities($orig);
// 
// $b = html_entity_decode($a);
// 
// echo $a; // I'll &quot;walk&quot; the &lt;b&gt;dog&lt;/b&gt; now
// 
// echo $b; // I'll "walk" the <b>dog</b> now
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: You might wonder why trim(html_entity_decode('&nbsp;')); doesn't reduce the string to an empty string, that's because the '&nbsp;' entity is not ASCII code 32 (which is stripped by trim()) but ASCII code 160 (0xa0) in the default ISO 8859-1 encoding.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.html-entity-decode.php
// ========== HTML_ENTITY_DECODE - END

// SYNTAX:
// string html_entity_decode(string $string, int $flags, string $encoding = null)

return $return_html_entity_decode; // string
}
// ============================== END
// PHP_TEXT_STRINGS_HTML_ENTITY_DECODE
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_HTMLENTITIES 
// ============================== PUBLIC
// ============================== ABOUT
// Convert all applicable characters to HTML entities.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// htmlentities() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_htmlentities($string, $flags, $encoding = null, $double_encode = true)
{
$return_htmlentities = null;

// ========== HTMLENTITIES - BEGIN
// ===== ABOUT
// Convert all applicable characters to HTML entities
// ===== DESCRIPTION
// This function is identical to htmlspecialchars() in all ways, except with htmlentities(), all characters which have HTML character entity equivalents are translated into these entities. The get_html_translation_table() function can be used to return the translation table used dependent upon the provided flags constants.
// If you want to decode instead (the reverse) you can use html_entity_decode().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// htmlentities(
//    string $string,
//    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
//    ?string $encoding = null,
//    bool $double_encode = true
// ): string
// ===== CODE
$return_htmlentities = htmlentities(

$string, // string string - The input string.

$flags, // int flags - A bitmask of one or more of the following flags, which specify how to handle quotes, invalid code unit sequences and the used document type. The default is ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// Available flags constants
// Constant Name  - Description
// ENT_COMPAT     - Will convert double-quotes and leave single-quotes alone.
// ENT_QUOTES     - Will convert both double and single quotes.
// ENT_NOQUOTES   - Will leave both double and single quotes unconverted.
// ENT_IGNORE     - Silently discard invalid code unit sequences instead of returning an empty string. Using this flag is discouraged as it > may have security implications.
// ENT_SUBSTITUTE - Replace invalid code unit sequences with a Unicode Replacement Character U+FFFD (UTF-8) or &#FFFD; (otherwise) instead of returning an empty string.
// ENT_DISALLOWED - Replace invalid code points for the given document type with a Unicode Replacement Character U+FFFD (UTF-8) or &#FFFD; (otherwise) instead of leaving them as is. This may be useful, for instance, to ensure the well-formedness of XML documents with embedded external content.
// ENT_HTML401    - Handle code as HTML 4.01.
// ENT_XML1       - Handle code as XML 1.
// ENT_XHTML      - Handle code as XHTML.
// ENT_HTML5      - Handle code as HTML 5.

$encoding, // string encoding - An optional argument defining the encoding used when converting characters.
// If omitted, encoding defaults to the value of the default_charset configuration option.
// Although this argument is technically optional, you are highly encouraged to specify the correct value for your code if the default_charset configuration option may be set incorrectly for the given input.
// The following character sets are supported:
// 
// Supported charsets
// Charset     | Aliases                      - Description
// ISO-8859-1  | ISO8859-1                    - Western European, Latin-1.
// ISO-8859-5  | ISO8859-5                    - Little used cyrillic charset (Latin/Cyrillic).
// ISO-8859-15 | ISO8859-15                   - Western European, Latin-9. Adds the Euro sign, French and Finnish letters missing in Latin-1 (ISO-8859-1).
// UTF-8       |                              -  ASCII compatible multi-byte 8-bit Unicode.
// cp866       | ibm866, 866                  - DOS-specific Cyrillic charset.
// cp1251      | Windows-1251, win-1251, 1251 - Windows-specific Cyrillic charset.
// cp1252      | Windows-1252, 1252           - Windows specific charset for Western European.
// KOI8-R      | koi8-ru, koi8r               - Russian.
// BIG5        | 950                          - Traditional Chinese, mainly used in Taiwan.
// GB2312      | 936                          - Simplified Chinese, national standard character set.
// BIG5-HKSCS  |                              - Big5 with Hong Kong extensions, Traditional Chinese.
// Shift_JIS   | SJIS, SJIS-win, cp932, 932   - Japanese
// EUC-JP      | EUCJP, eucJP-win             - Japanese
// MacRoman    |                              - Charset that was used by Mac OS.
// ''          |                              - An empty string activates detection from script encoding (Zend multibyte), default_charset and current locale (see nl_langinfo() and setlocale()), in this order. Not recommended.
// Note: Any other character sets are not recognized. The default encoding will be used instead and a warning will be emitted.

$double_encode // bool double_encode - When double_encode is turned off PHP will not encode existing html entities. The default is to convert everything.

); // Return Values
// Returns the encoded string.
// If the input string contains an invalid code unit sequence within the given encoding an empty string will be returned, unless either the ENT_IGNORE or ENT_SUBSTITUTE flags are set.
// 
// Changelog
// Version - Description
// 8.1.0   - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 8.0.0   - encoding is nullable now.
// 
// [examples]
// Examples
// [example]
// Example #1 A htmlentities() example
// [php]
// $str = "A 'quote' is <b>bold</b>";
// 
// // Outputs: A 'quote' is &lt;b&gt;bold&lt;/b&gt;
// echo htmlentities($str);
// 
// // Outputs: A &#039;quote&#039; is &lt;b&gt;bold&lt;/b&gt;
// echo htmlentities($str, ENT_QUOTES);
// [/php]
// [/example]
// [example]
// Example #2 Usage of ENT_IGNORE
// [php]
// $str = "\x8F!!!";
// 
// // Outputs an empty string
// echo htmlentities($str, ENT_QUOTES, "UTF-8");
// 
// // Outputs "!!!"
// echo htmlentities($str, ENT_QUOTES | ENT_IGNORE, "UTF-8");
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.htmlentities.php
// ========== HTMLENTITIES - END

// SYNTAX:
// string htmlentities(string $string, int $flags, string $encoding = null, bool $double_encode = true)

return $return_htmlentities; // string
}
// ============================== END
// PHP_TEXT_STRINGS_HTMLENTITIES 
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_HTMLSPECIALCHARS_DECODE
// ============================== OFFLINE
// ============================== ABOUT
// Convert special HTML entities back to characters.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// htmlspecialchars_decode() - PHP_5 >= PHP_5_1_0, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_htmlspecialchars_decode($string, $flags)
{
$return_htmlspecialchars_decode = null;

// ========== HTMLSPECIALCHARS_DECODE - BEGIN
// ===== ABOUT
// Convert special HTML entities back to characters
// ===== DESCRIPTION
// This function is the opposite of htmlspecialchars(). It converts special HTML entities back to characters.
// The converted entities are: &amp;, &quot; (when ENT_NOQUOTES is not set), &#039; (when ENT_QUOTES is set), &lt; and &gt;.
// ===== SUPPORTED
// PHP_5 >= PHP_5_1_0, PHP_7, PHP_8
// ===== SYNTAX
// htmlspecialchars_decode(string $string, int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401): string
// ===== CODE
$return_htmlspecialchars_decode = htmlspecialchars_decode(

$string, // string string - The string to decode.

$flags // int flags - A bitmask of one or more of the following flags, which specify how to handle quotes and which document type to use. The default is ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// Available flags constants
// Constant Name  - Description
// ENT_COMPAT     - Will convert double-quotes and leave single-quotes alone.
// ENT_QUOTES     - Will convert both double and single quotes.
// ENT_NOQUOTES   - Will leave both double and single quotes unconverted.
// ENT_SUBSTITUTE - Replace invalid code unit sequences with a Unicode Replacement Character U+FFFD (UTF-8) or &#xFFFD; (otherwise) instead of returning an empty string.
// ENT_HTML401    - Handle code as HTML 4.01.
// ENT_XML1       - Handle code as XML 1.
// ENT_XHTML      - Handle code as XHTML.
// ENT_HTML5      - Handle code as HTML 5.

); // Return Values
// Returns the decoded string.
// 
// Changelog
// Version - Description
// 8.1.0   - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// [examples]
// Examples
// [example]
// Example #1 A htmlspecialchars_decode() example
// [php]
// $str = "<p>this -&gt; &quot;</p>\n";
// 
// echo htmlspecialchars_decode($str);
// 
// // note that here the quotes aren't converted
// echo htmlspecialchars_decode($str, ENT_NOQUOTES);
// [/php]
// The above example will output:
// [result]
// <p>this -> "</p>
// <p>this -> &quot;</p>
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.htmlspecialchars-decode.php
// ========== HTMLSPECIALCHARS_DECODE - END

// SYNTAX:
// string htmlspecialchars_decode(string $string, int $flags)

return $return_htmlspecialchars_decode; // string
}
*/
// ============================== END
// PHP_TEXT_STRINGS_HTMLSPECIALCHARS_DECODE
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_HTMLSPECIALCHARS
// ============================== PUBLIC
// ============================== ABOUT
// Convert special characters to HTML entities.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// htmlspecialchars() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_htmlspecialchars($string, $flags, $encoding = null, $double_encode = true)
{
$return_htmlspecialchars = null;

// ========== HTMLSPECIALCHARS - BEGIN
// ===== ABOUT
// Convert special characters to HTML entities
// ===== DESCRIPTION
// Certain characters have special significance in HTML, and should be represented by HTML entities if they are to preserve their meanings. This function returns a string with these conversions made. If you require all input substrings that have associated named entities to be translated, use htmlentities() instead.
// If the input string passed to this function and the final document share the same character set, this function is sufficient to prepare input for inclusion in most contexts of an HTML document. If, however, the input can represent characters that are not coded in the final document character set and you wish to retain those characters (as numeric or named entities), both this function and htmlentities() (which only encodes substrings that have named entity equivalents) may be insufficient. You may have to use mb_encode_numericentity() instead.
// Performed translations
// Character        - Replacement
// & (ampersand)    - &amp;
// " (double quote) - &quot;, unless ENT_NOQUOTES is set
// ' (single quote) - &#039; (for ENT_HTML401) or &apos; (for ENT_XML1, ENT_XHTML or ENT_HTML5), but only when ENT_QUOTES is set
// < (less than)    - &lt;
// > (greater than) - &gt;
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// htmlspecialchars(
//    string $string,
//    int $flags = ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401,
//    ?string $encoding = null,
//    bool $double_encode = true
// ): string
// ===== CODE
$return_htmlspecialchars = htmlspecialchars(

$string, // string string - The string being converted.

$flags, // int flags - A bitmask of one or more of the following flags, which specify how to handle quotes, invalid code unit sequences and the used document type. The default is ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// Available flags constants
// Constant Name  - Description
// ENT_COMPAT     - Will convert double-quotes and leave single-quotes alone.
// ENT_QUOTES     - Will convert both double and single quotes.
// ENT_NOQUOTES   - Will leave both double and single quotes unconverted.
// ENT_IGNORE     - Silently discard invalid code unit sequences instead of returning an empty string. Using this flag is discouraged as it > may have security implications.
// ENT_SUBSTITUTE - Replace invalid code unit sequences with a Unicode Replacement Character U+FFFD (UTF-8) or &#xFFFD; (otherwise) instead of returning an empty string.
// ENT_DISALLOWED - Replace invalid code points for the given document type with a Unicode Replacement Character U+FFFD (UTF-8) or &#xFFFD; (otherwise) instead of leaving them as is. This may be useful, for instance, to ensure the well-formedness of XML documents with embedded external content.
// ENT_HTML401    - Handle code as HTML 4.01.
// ENT_XML1       - Handle code as XML 1.
// ENT_XHTML      - Handle code as XHTML.
// ENT_HTML5      - Handle code as HTML 5.

$encoding, // string encoding - An optional argument defining the encoding used when converting characters.
// If omitted, encoding defaults to the value of the default_charset configuration option.
// Although this argument is technically optional, you are highly encouraged to specify the correct value for your code if the default_charset configuration option may be set incorrectly for the given input.
// For the purposes of this function, the encodings ISO-8859-1, ISO-8859-15, UTF-8, cp866, cp1251, cp1252, and KOI8-R are effectively equivalent, provided the string itself is valid for the encoding, as the characters affected by htmlspecialchars() occupy the same positions in all of these encodings.
// The following character sets are supported:
// 
// Supported charsets
// Charset     | Aliases                      - Description
// ISO-8859-1  | ISO8859-1                    - Western European, Latin-1.
// ISO-8859-5  | ISO8859-5                    - Little used cyrillic charset (Latin/Cyrillic).
// ISO-8859-15 | ISO8859-15                   - Western European, Latin-9. Adds the Euro sign, French and Finnish letters missing in Latin-1 (ISO-8859-1).
// UTF-8       |                              - ASCII compatible multi-byte 8-bit Unicode.
// cp866       | ibm866, 866                  - DOS-specific Cyrillic charset.
// cp1251      | Windows-1251, win-1251, 1251 - Windows-specific Cyrillic charset.
// cp1252      | Windows-1252, 1252           - Windows specific charset for Western European.
// KOI8-R      | koi8-ru, koi8r               - Russian.
// BIG5        | 950                          - Traditional Chinese, mainly used in Taiwan.
// GB2312      | 936                          - Simplified Chinese, national standard character set.
// BIG5-HKSCS  |                              - Big5 with Hong Kong extensions, Traditional Chinese.
// Shift_JIS   | SJIS, SJIS-win, cp932, 932   - Japanese
// EUC-JP      | EUCJP, eucJP-win             - Japanese
// MacRoman    |                              - Charset that was used by Mac OS.
// ''          |                              - An empty string activates detection from script encoding (Zend multibyte), default_charset and current locale (see nl_langinfo() and setlocale()), in this order. Not recommended.
// Note: Any other character sets are not recognized. The default encoding will be used instead and a warning will be emitted.

$double_encode // bool double_encode - When double_encode is turned off PHP will not encode existing html entities, the default is to convert everything.

); // Return Values
// The converted string.
// If the input string contains an invalid code unit sequence within the given encoding an empty string will be returned, unless either the ENT_IGNORE or ENT_SUBSTITUTE flags are set.
// 
// Changelog
// Version - Description
// 8.1.0   - flags changed from ENT_COMPAT to ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401.
// 
// [examples]
// Examples
// [example]
// Example #1 htmlspecialchars() example
// [php]
// $new = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
// echo $new; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: Note that this function does not translate anything beyond what is listed above. For full entity translation, see htmlentities().
//  Note:
//  In case of an ambiguous flags value, the following rules apply:
//  * When neither of ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES is present, the default is ENT_NOQUOTES.
//  * When more than one of ENT_COMPAT, ENT_QUOTES, ENT_NOQUOTES is present, ENT_QUOTES takes the highest precedence, followed by ENT_COMPAT.
//  * When neither of ENT_HTML401, ENT_HTML5, ENT_XHTML, ENT_XML1 is present, the default is ENT_HTML401.
//  * When more than one of ENT_HTML401, ENT_HTML5, ENT_XHTML, ENT_XML1 is present, ENT_HTML5 takes the highest precedence, followed by ENT_XHTML, ENT_XML1 and ENT_HTML401.
//  * When more than one of ENT_DISALLOWED, ENT_IGNORE, ENT_SUBSTITUTE are present, ENT_IGNORE takes the highest precedence, followed by ENT_SUBSTITUTE.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.htmlspecialchars.php
// ========== HTMLSPECIALCHARS - END

// SYNTAX:
// string htmlspecialchars(string $string, int $flags, string $encoding = null, bool $double_encode = true)

return $return_htmlspecialchars; // string
}
// ============================== END
// PHP_TEXT_STRINGS_HTMLSPECIALCHARS
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_IMPLODE    
// ============================== OFFLINE
// ============================== ABOUT
// Join array elements with a string.
// ============================== DESCRIPTION
// PHP_4, PHP_5, PHP_7 (PHP_7_4_0)
// string implode(array $array, string $separator)
// 
// PHP_8 (PHP_8_0_0)
// string implode(string $separator, array $array)
// ============================== SUPPORT
// PHP_4 - PHP_7
// ============================== USING FUNCTIONS (1)
// implode() - PHP_4, PHP_5, PHP_7
// ============================== CODE
/*
function php_text_strings_implode($array, $separator)
{
$return_implode = null;

// ========== IMPLODE - BEGIN
// ===== ABOUT
// Join array elements with a string
// ===== DESCRIPTION
// Join array elements with a separator string.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// implode(string $separator, array $array): string
// 
// Alternative signature (not supported with named arguments):
// implode(array $array): string
// 
// Legacy signature (deprecated as of PHP 7.4.0, removed as of PHP 8.0.0):
// implode(array $array, string $separator): string
// ===== CODE
$return_implode = implode(

$array, // array array

$separator // string separator

// string separator - Optional. Defaults to an empty string.

// array array - The array of strings to implode.

); // Return Values
// Returns a string containing a string representation of all the array elements in the same order, with the separator string between each element.
// 
// Changelog
// Version - Description
// 8.0.0   - Passing the separator after the array is no longer supported.
// 7.4.0   - Passing the separator after the array (i.e. using the legacy signature) has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 implode() example
// [php]
// 
// $array = ['lastname', 'email', 'phone'];
// var_dump(implode(",", $array)); // string(20) "lastname,email,phone"
// 
// // Empty string when using an empty array:
// var_dump(implode('hello', [])); // string(0) ""
// 
// // The separator is optional:
// var_dump(implode(['a', 'b', 'c'])); // string(3) "abc"
// 
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.implode.php
// ========== IMPLODE - END

// SYNTAX:
// string implode(array $array, string $separator)
// * PHP_4 - PHP_7 (PHP_7_4_0)

// string implode(string $separator, array $array)
// * PHP_8 (PHP_8_0_0)

return $return_implode; // string
}
*/
// ============================== END
//    PHP_TEXT_STRINGS_IMPLODE    
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_JOIN     
// ============================== OFFLINE
// ============================== ABOUT
// Join array elements with a string.
// 
// join - Alias of implode().
// ============================== SUPPORT
// PHP_4 - PHP_7
// ============================== USING FUNCTIONS (1)
// join() - PHP_4, PHP_5, PHP_7
// ============================== CODE
/*
function php_text_strings_join($array, $separator)
{
$return_join = null;

// ========== JOIN - BEGIN
// ===== ABOUT
// join - Alias of implode()
// ===== DESCRIPTION
// This function is an alias of: implode().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// ===== CODE
$return_join = join(

$array, // array array - The array of strings to implode.

$separator // string separator - Optional. Defaults to an empty string.

); // Return
// string
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.join.php
// ========== JOIN - END

// ========== IMPLODE - BEGIN
// ===== ABOUT
// Join array elements with a string
// ===== DESCRIPTION
// Join array elements with a separator string.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// implode(string $separator, array $array): string
// 
// Alternative signature (not supported with named arguments):
// implode(array $array): string
// 
// Legacy signature (deprecated as of PHP 7.4.0, removed as of PHP 8.0.0):
// implode(array $array, string $separator): string
// ===== CODE
// $return_implode = implode(

// $array, // array array

// $separator // string separator

// string separator - Optional. Defaults to an empty string.

// array array - The array of strings to implode.

// ); // Return Values
// Returns a string containing a string representation of all the array elements in the same order, with the separator string between each element.
// 
// Changelog
// Version - Description
// 8.0.0   - Passing the separator after the array is no longer supported.
// 7.4.0   - Passing the separator after the array (i.e. using the legacy signature) has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 implode() example
// [php]
// 
// $array = ['lastname', 'email', 'phone'];
// var_dump(implode(",", $array)); // string(20) "lastname,email,phone"
// 
// // Empty string when using an empty array:
// var_dump(implode('hello', [])); // string(0) ""
// 
// // The separator is optional:
// var_dump(implode(['a', 'b', 'c'])); // string(3) "abc"
// 
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.implode.php
// ========== IMPLODE - END

// SYNTAX:
// string join(array $array, string $separator)
// * PHP_4 - PHP_7 (PHP_7_4_0)

// string join(string $separator, array $array)
// * PHP_8 (PHP_8_0_0)

return $return_join; // string
}
*/
// ============================== END
//     PHP_TEXT_STRINGS_JOIN     
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_LCFIRST    
// ============================== OFFLINE
// ============================== ABOUT
// Make a string's first character lowercase.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// lcfirst() - PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_lcfirst($string)
{
$return_lcfirst = null;

// ========== LCFIRST - BEGIN
// ===== ABOUT
// Make a string's first character lowercase
// ===== DESCRIPTION
// Returns a string with the first character of string lowercased if that character is an ASCII character in the range "A" (0x41) to "Z" (0x5a).
// ===== SUPPORTED
// PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// ===== SYNTAX
// lcfirst(string $string): string
// ===== CODE
$return_lcfirst = lcfirst(

$string // string string - The input string.

); // Return Values
// Returns the resulting string.
// 
// Changelog
// Version - Description
// 8.2.0   - Case conversion no longer depends on the locale set with setlocale(). Only ASCII characters will be converted.
// 
// [examples]
// Examples
// [example]
// Example #1 lcfirst() example
// [php]
// $foo = 'HelloWorld';
// $foo = lcfirst($foo);             // helloWorld
// 
// $bar = 'HELLO WORLD!';
// $bar = lcfirst($bar);             // hELLO WORLD!
// $bar = lcfirst(strtoupper($bar)); // hELLO WORLD!
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.lcfirst.php
// ========== LCFIRST - END

// SYNTAX:
// string lcfirst(string $string)

return $return_lcfirst; // string
}
*/
// ============================== END
//    PHP_TEXT_STRINGS_LCFIRST    
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_LEVENSHTEIN  
// ============================== PUBLIC
// ============================== ABOUT
// Calculate Levenshtein distance between two strings.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// levenshtein() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_levenshtein($string1, $string2, $insertion_cost = 1, $replacement_cost = 1, $deletion_cost = 1)
{
$return_levenshtein = 0;

// ========== LEVENSHTEIN - BEGIN
// ===== ABOUT
// Calculate Levenshtein distance between two strings
// ===== DESCRIPTION
// The Levenshtein distance is defined as the minimal number of characters you have to replace, insert or delete to transform string1 into string2. The complexity of the algorithm is O(m*n), where n and m are the length of string1 and string2 (rather good when compared to similar_text(), which is O(max(n,m)**3), but still expensive).
// If insertion_cost, replacement_cost and/or deletion_cost are unequal to 1, the algorithm adapts to choose the cheapest transforms. E.g. if $insertion_cost + $deletion_cost < $replacement_cost, no replacements will be done, but rather inserts and deletions instead.
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// levenshtein(
//    string $string1,
//    string $string2,
//    int $insertion_cost = 1,
//    int $replacement_cost = 1,
//    int $deletion_cost = 1
// ): int
// ===== CODE
$return_levenshtein = levenshtein(

$string1, // string string1 - One of the strings being evaluated for Levenshtein distance.

$string2, // string string2 - One of the strings being evaluated for Levenshtein distance.

$insertion_cost, // int insertion_cost - Defines the cost of insertion.

$replacement_cost, // int replacement_cost - Defines the cost of replacement.

$deletion_cost // int deletion_cost - Defines the cost of deletion.

); // Return Values
// This function returns the Levenshtein-Distance between the two argument strings.
// 
// Changelog
// Version - Description
// 8.0.0   - Prior to this version, levenshtein() had to be called with either two or five arguments.
// 8.0.0   - Prior to this version, levenshtein() would return -1 if one of the argument strings is longer than 255 characters.
// 
// [examples]
// Examples
// [example]
// Example #1 levenshtein() example
// [php]
// input misspelled word
// $input = 'carrrot';
// 
// // array of words to check against
// $words  = array('apple','pineapple','banana','orange',
//                 'radish','carrot','pea','bean','potato');
// 
// // no shortest distance found, yet
// $shortest = -1;
// 
// // loop through words to find the closest
// foreach ($words as $word) {
// 
//     // calculate the distance between the input word,
//     // and the current word
//     $lev = levenshtein($input, $word);
// 
//     // check for an exact match
//     if ($lev == 0) {
// 
//         // closest word is this one (exact match)
//         $closest = $word;
//         $shortest = 0;
// 
//         // break out of the loop; we've found an exact match
//         break;
//     }
// 
//     // if this distance is less than the next found shortest
//     // distance, OR if a next shortest word has not yet been found
//     if ($lev <= $shortest || $shortest < 0) {
//         // set the closest match, and shortest distance
//         $closest  = $word;
//         $shortest = $lev;
//     }
// }
// 
// echo "Input word: $input\n";
// if ($shortest == 0) {
//     echo "Exact match found: $closest\n";
// } else {
//     echo "Did you mean: $closest?\n";
// }
// 
// [/php]
// The above example will output:
// [result]
// Input word: carrrot
// Did you mean: carrot?
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.levenshtein.php
// ========== LEVENSHTEIN - END

// SYNTAX:
// int levenshtein(string $string1, string $string2, int $insertion_cost = 1, int $replacement_cost = 1, int $deletion_cost = 1)

return $return_levenshtein; // int
}
// ============================== END
//  PHP_TEXT_STRINGS_LEVENSHTEIN  
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_LOCALECONV  
// ============================== PUBLIC
// ============================== ABOUT
// Get numeric formatting information.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// localeconv() - PHP_4 >= PHP_4_0_5, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_localeconv()
{
$return_localeconv = null;

// ========== LOCALECONV - BEGIN
// ===== ABOUT
// Get numeric formatting information
// ===== DESCRIPTION
// Returns an associative array containing localized numeric and monetary formatting information.
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_5, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// localeconv(): array
// ===== CODE
$return_localeconv = localeconv(

// This function has no parameters.

); // Return Values
// localeconv() returns data based upon the current locale as set by setlocale(). The associative array that is returned contains the following fields:
// Array element     - Description
// decimal_point     - Decimal point character
// thousands_sep     - Thousands separator
// grouping          - Array containing numeric groupings
// int_curr_symbol   - International currency symbol (i.e. USD)
// currency_symbol   - Local currency symbol (i.e. $)
// mon_decimal_point - Monetary decimal point character
// mon_thousands_sep - Monetary thousands separator
// mon_grouping      - Array containing monetary groupings
// positive_sign     - Sign for positive values
// negative_sign     - Sign for negative values
// int_frac_digits   - International fractional digits
// frac_digits       - Local fractional digits
// p_cs_precedes     - true if currency_symbol precedes a positive value, false if it succeeds one
// p_sep_by_space    - true if a space separates currency_symbol from a positive value, false otherwise
// n_cs_precedes     - true if currency_symbol precedes a negative value, false if it succeeds one
// n_sep_by_space    - true if a space separates currency_symbol from a negative value, false otherwise
// p_sign_posn       -
//                     * 0 - Parentheses surround the quantity and currency_symbol
//                     * 1 - The sign string precedes the quantity and currency_symbol
//                     * 2 - The sign string succeeds the quantity and currency_symbol
//                     * 3 - The sign string immediately precedes the currency_symbol
//                     * 4 - The sign string immediately succeeds the currency_symbol
// n_sign_posn       -
//                     * 0 - Parentheses surround the quantity and currency_symbol
//                     * 1 - The sign string precedes the quantity and currency_symbol
//                     * 2 - The sign string succeeds the quantity and currency_symbol
//                     * 3 - The sign string immediately precedes the currency_symbol
//                     * 4 - The sign string immediately succeeds the currency_symbol
// The p_sign_posn, and n_sign_posn contain a string of formatting options. Each number representing one of the above listed conditions.
// The grouping fields contain arrays that define the way numbers should be grouped. For example, the monetary grouping field for the nl_NL locale (in UTF-8 mode with the euro sign), would contain a 2 item array with the values 3 and 3. The higher the index in the array, the farther left the grouping is. If an array element is equal to CHAR_MAX, no further grouping is done. If an array element is equal to 0, the previous element should be used.
// 
// [examples]
// Examples
// [example]
// Example #1 localeconv() example
// [php]
// if (false !== setlocale(LC_ALL, 'nl_NL.UTF-8@euro')) {
//     $locale_info = localeconv();
//     print_r($locale_info);
// }
// [/php]
// The above example will output:
// [result]
// Array
// (
//     [decimal_point] => .
//     [thousands_sep] =>
//     [int_curr_symbol] => EUR
//     [currency_symbol] => €
//     [mon_decimal_point] => ,
//     [mon_thousands_sep] =>
//     [positive_sign] =>
//     [negative_sign] => -
//     [int_frac_digits] => 2
//     [frac_digits] => 2
//     [p_cs_precedes] => 1
//     [p_sep_by_space] => 1
//     [n_cs_precedes] => 1
//     [n_sep_by_space] => 1
//     [p_sign_posn] => 1
//     [n_sign_posn] => 2
//     [grouping] => Array
//         (
//         )
// 
//     [mon_grouping] => Array
//         (
//             [0] => 3
//             [1] => 3
//         )
// 
// )
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.localeconv.php
// ========== LOCALECONV - END

// SYNTAX:
// array localeconv()

return $return_localeconv; // array
}
// ============================== END
//  PHP_TEXT_STRINGS_LOCALECONV  
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_LTRIM     
// ============================== PUBLIC
// ============================== ABOUT
// Strip whitespace (or other characters) from the beginning of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// ltrim() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_ltrim($string, $characters = " \n\r\t\v\x00")
{
$return_ltrim = null;

// ========== LTRIM - BEGIN
// ===== ABOUT
// Strip whitespace (or other characters) from the beginning of a string
// ===== DESCRIPTION
// Strip whitespace (or other characters) from the beginning of a string.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// ltrim(string $string, string $characters = " \n\r\t\v\x00"): string
// ===== CODE
$return_ltrim = ltrim(

$string, // string string - The input string.

$characters // string characters - You can also specify the characters you want to strip, by means of the characters parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.

); // Return Values
// This function returns a string with whitespace stripped from the beginning of string. Without the second parameter, ltrim() will strip these characters:
// * " "  (ASCII 32 (0x20)), an ordinary space.
// * "\t" (ASCII 9 (0x09)), a tab.
// * "\n" (ASCII 10 (0x0A)), a new line (line feed).
// * "\r" (ASCII 13 (0x0D)), a carriage return.
// * "\0" (ASCII 0 (0x00)), the NUL-byte.
// * "\v" (ASCII 11 (0x0B)), a vertical tab.
// 
// [examples]
// Examples
// [example]
// Example #1 Usage example of ltrim()
// [php]
// 
// $text = "\t\tThese are a few words :) ...  ";
// $binary = "\x09Example string\x0A";
// $hello  = "Hello World";
// var_dump($text, $binary, $hello);
// 
// print "\n";
// 
// 
// $trimmed = ltrim($text);
// var_dump($trimmed);
// 
// $trimmed = ltrim($text, " \t.");
// var_dump($trimmed);
// 
// $trimmed = ltrim($hello, "Hdle");
// var_dump($trimmed);
// 
// // trim the ASCII control characters at the beginning of $binary
// // (from 0 to 31 inclusive)
// $clean = ltrim($binary, "\x00..\x1F");
// var_dump($clean);
// 
// [/php]
// The above example will output:
// [result]
// string(32) "        These are a few words :) ...  "
// string(16) "    Example string
// "
// string(11) "Hello World"
// 
// string(30) "These are a few words :) ...  "
// string(30) "These are a few words :) ...  "
// string(7) "o World"
// string(15) "Example string
// "
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.ltrim.php
// ========== LTRIM - END

// SYNTAX:
// string ltrim(string $string, string $characters = " \n\r\t\v\x00")

return $return_ltrim; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_LTRIM     
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_MD5_FILE   
// ============================== PUBLIC
// ============================== ABOUT
// Calculates the md5 hash of a given file.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// md5_file() - PHP_4 >= PHP_4_2_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_md5_file($filename, $binary = false)
{
$return_md5_file = false;

// ========== MD5_FILE - BEGIN
// ===== ABOUT
// Calculates the md5 hash of a given file
// ===== DESCRIPTION
// Calculates the MD5 hash of the file specified by the filename parameter using the > RSA Data Security, Inc. MD5 Message-Digest Algorithm, and returns that hash. The hash is a 32-character hexadecimal number.
// ===== SUPPORTED
// PHP_4 >= PHP_4_2_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// md5_file(string $filename, bool $binary = false): string|false
// ===== CODE
$return_md5_file = md5_file(

$filename, // string filename - The filename

$binary // bool binary - When true, returns the digest in raw binary format with a length of 16.

); // Return Values
// Returns a string on success, false otherwise.
// 
// [examples]
// Examples
// [example]
// Example #1 Usage example of md5_file()
// [php]
// $file = 'php-5.3.0alpha2-Win32-VC9-x64.zip';
// 
// echo 'MD5 file hash of ' . $file . ': ' . md5_file($file);
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.md5-file.php
// ========== MD5_FILE - END

// SYNTAX:
// string|false md5_file(string $filename, bool $binary = false)

return $return_md5_file; // string|false
}
// ============================== END
//   PHP_TEXT_STRINGS_MD5_FILE   
// ==============================


// ============================== BEGIN
//      PHP_TEXT_STRINGS_MD5      
// ============================== PUBLIC
// ============================== ABOUT
// Calculate the md5 hash of a string.
// 
// Warning: It is not recommended to use this function to secure passwords, due to the fast nature of this hashing algorithm. See the Password Hashing FAQ for details and best practices.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// md5() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_md5($string, $binary = false)
{
$return_md5 = null;

// ========== MD5 - BEGIN
// ===== ABOUT
// Calculate the md5 hash of a string
// Warning: It is not recommended to use this function to secure passwords, due to the fast nature of this hashing algorithm. See the Password Hashing FAQ for details and best practices.
// ===== DESCRIPTION
// Calculates the MD5 hash of string using the > RSA Data Security, Inc. MD5 Message-Digest Algorithm, and returns that hash.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// md5(string $string, bool $binary = false): string
// ===== CODE
$return_md5 = md5(

$string, // string string - The string.

$binary // bool binary - If the optional binary is set to true, then the md5 digest is instead returned in raw binary format with a length of 16.

); // Return Values
// Returns the hash as a 32-character hexadecimal number.
// 
// [examples]
// Examples
// [example]
// Example #1 A md5() example
// [php]
// $str = 'apple';
// 
// if (md5($str) === '1f3870be274f6c49b3e31a0c6728957f') {
//     echo "Would you like a green or red apple?";
// }
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.md5.php
// ========== MD5 - END

// SYNTAX:
// string md5(string $string, bool $binary = false)

return $return_md5; // string
}
// ============================== END
//      PHP_TEXT_STRINGS_MD5      
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_METAPHONE   
// ============================== PUBLIC
// ============================== ABOUT
// Calculate the metaphone key of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// metaphone() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_metaphone($string, $max_phonemes = 0)
{
$return_metaphone = null;

// ========== METAPHONE - BEGIN
// ===== ABOUT
// Calculate the metaphone key of a string
// ===== DESCRIPTION
// Calculates the metaphone key of string.
// Similar to soundex() metaphone creates the same key for similar sounding words. It's more accurate than soundex() as it knows the basic rules of English pronunciation. The metaphone generated keys are of variable length.
// Metaphone was developed by Lawrence Philips <lphilips at verity dot com>. It is described in ["Practical Algorithms for Programmers", Binstock & Rex, Addison Wesley, 1995].
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// metaphone(string $string, int $max_phonemes = 0): string
// ===== CODE
$return_metaphone = metaphone(

$string, // string string - The input string.

$max_phonemes // int max_phonemes - This parameter restricts the returned metaphone key to max_phonemes characters in length. However, the resulting phonemes are always transcribed completely, so the resulting string length may be slightly longer than max_phonemes. The default value of 0 means no restriction.

); // Return Values
// Returns the metaphone key as a string.
// 
// Changelog
// Version - Description
// 8.0.0   - The function returned false on failure.
// 
// [examples]
// Examples
// [example]
// Example #1 metaphone() basic example
// [php]
// var_dump(metaphone('programming'));
// var_dump(metaphone('programmer'));
// [/php]
// The above example will output:
// [result]
// string(7) "PRKRMNK"
// string(6) "PRKRMR"
// [/result]
// [/example]
// [example]
// Example #2 Using the max_phonemes parameter
// [php]
// var_dump(metaphone('programming', 5));
// var_dump(metaphone('programmer', 5));
// [/php]
// The above example will output:
// [result]
// string(5) "PRKRM"
// string(5) "PRKRM"
// [/result]
// [/example]
// [example]
// Example #3 Using the max_phonemes parameter
// In this example, metaphone() is advised to produce a string of five characters, but that would require to split the final phoneme ('x' is supposed to be transcribed to 'KS'), so the function returns a string with six characters.
// [php]
// var_dump(metaphone('Asterix', 5));
// [/php]
// The above example will output:
// [result]
// string(6) "ASTRKS"
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.metaphone.php
// ========== METAPHONE - END

// SYNTAX:
// string metaphone(string $string, int $max_phonemes = 0)

return $return_metaphone; // string
}
// ============================== END
//   PHP_TEXT_STRINGS_METAPHONE   
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_MONEY_FORMAT 
// ============================== OFFLINE
// ============================== ABOUT
// Formats a number as a currency string.
// 
// Warning: This function has been DEPRECATED as of PHP 7.4.0, and REMOVED as of PHP 8.0.0. Relying on this function is highly discouraged.
// ============================== SUPPORT
// PHP_4 - PHP_7
// ============================== USING FUNCTIONS (1)
// money_format() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7
// ============================== CODE
/*
function php_text_strings_money_format($format, $number)
{
$return_money_format = null;

// ========== MONEY_FORMAT - BEGIN
// ===== ABOUT
// Formats a number as a currency string
// Warning: This function has been DEPRECATED as of PHP 7.4.0, and REMOVED as of PHP 8.0.0. Relying on this function is highly discouraged.
// ===== DESCRIPTION
// money_format() returns a formatted version of number. This function wraps the C library function strfmon(), with the difference that this implementation converts only one number at a time.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7
// ===== SYNTAX
// money_format(string $format, float $number): string
// ===== CODE
$return_money_format = money_format(

$format, // string format - The format specification consists of the following sequence:
// * a % character
// * optional flags
// * optional field width
// * optional left precision
// * optional right precision
// * a required conversion character
// Flags  - One or more of the optional flags below can be used:
// =f     - The character = followed by a (single byte) character f to be used as the numeric fill character. The default fill character is space.
// ^      - Disable the use of grouping characters (as defined by the current locale).
// + or ( - Specify the formatting style for positive and negative numbers. If + is used, the locale's equivalent for + and - will be used. If ( is used, negative amounts are enclosed in parenthesis. If no specification is given, the default is +.
// !      - Suppress the currency symbol from the output string.
// -      - If present, it will make all fields left-justified (padded to the right), as opposed to the default which is for the fields to be right-justified (padded to the left).
// Field width
// w      - A decimal digit string specifying a minimum field width. Field will be right-justified unless the flag - is used. Default value is 0 (zero).
// Left precision
// #n     - The maximum number of digits (n) expected to the left of the decimal character (e.g. the decimal point). It is used usually to keep formatted output aligned in the same columns, using the fill character if the number of digits is less than n. If the number of actual digits is bigger than n, then this specification is ignored.
// If grouping has not been suppressed using the ^ flag, grouping separators will be inserted before the fill characters (if any) are added. Grouping separators will not be applied to fill characters, even if the fill character is a digit.
// To ensure alignment, any characters appearing before or after the number in the formatted output such as currency or sign symbols are padded as necessary with space characters to make their positive and negative formats an equal length.
// Right precision
// .p     - A period followed by the number of digits (p) after the decimal character. If the value of p is 0 (zero), the decimal character and the digits to its right will be omitted. If no right precision is included, the default will dictated by the current locale in use. The amount being formatted is rounded to the specified number of digits prior to formatting.
// Conversion characters
// i      - The number is formatted according to the locale's international currency format (e.g. for the USA locale: USD 1,234.56).
// n      - The number is formatted according to the locale's national currency format (e.g. for the de_DE locale: EU1.234,56).
// %      - Returns the % character.

$number // float number - The number to be formatted.

); // Return Values
// Returns the formatted string. Characters before and after the formatting string will be returned unchanged. Non-numeric number causes returning null and emitting E_WARNING.
// 
// Changelog
// Version - Description
// 7.4.0   - This function has been deprecated. Instead, use NumberFormatter::formatCurrency().
// 
// [examples]
// Examples
// [example]
// Example #1 money_format() Example
// We will use different locales and format specifications to illustrate the use of this function.
// [php]
// 
// $number = 1234.56;
// 
// // let's print the international format for the en_US locale
// setlocale(LC_MONETARY, 'en_US');
// echo money_format('%i', $number) . "\n";
// // USD 1,234.56
// 
// // Italian national format with 2 decimals`
// setlocale(LC_MONETARY, 'it_IT');
// echo money_format('%.2n', $number) . "\n";
// // Eu 1.234,56
// 
// // Using a negative number
// $number = -1234.5672;
// 
// // US national format, using () for negative numbers
// // and 10 digits for left precision
// setlocale(LC_MONETARY, 'en_US');
// echo money_format('%(#10n', $number) . "\n";
// // ($        1,234.57)
// 
// // Similar format as above, adding the use of 2 digits of right
// // precision and '*' as a fill character
// echo money_format('%=*(#10.2n', $number) . "\n";
// // ($********1,234.57)
// 
// // Let's justify to the left, with 14 positions of width, 8 digits of
// // left precision, 2 of right precision, without the grouping character
// // and using the international format for the de_DE locale.
// setlocale(LC_MONETARY, 'de_DE');
// echo money_format('%=*^-14#8.2i', 1234.56) . "\n";
// // Eu 1234,56****
// 
// // Let's add some blurb before and after the conversion specification
// setlocale(LC_MONETARY, 'en_GB');
// $fmt = 'The final value is %i (after a 10%% discount)';
// echo money_format($fmt, 1234.56) . "\n";
// // The final value is  GBP 1,234.56 (after a 10% discount)
// 
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: The function money_format() is only defined if the system has strfmon capabilities. For example, Windows does not, so money_format() is undefined in Windows.
// Note: The LC_MONETARY category of the locale settings, affects the behavior of this function. Use setlocale() to set to the appropriate default locale before using this function.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.money-format.php
// ========== MONEY_FORMAT - END

// SYNTAX:
// string money_format(string $format, float $number)

return $return_money_format; // string
}
*/
// ============================== END
// PHP_TEXT_STRINGS_MONEY_FORMAT 
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_NL_LANGINFO  
// ============================== PUBLIC
// ============================== ABOUT
// Query language and locale information.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// nl_langinfo() - PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_nl_langinfo($item)
{
$return_nl_langinfo = false;

// ========== NL_LANGINFO - BEGIN
// ===== ABOUT
// Query language and locale information
// ===== DESCRIPTION
// nl_langinfo() is used to access individual elements of the locale categories. Unlike localeconv(), which returns all of the elements, nl_langinfo() allows you to select any specific element.
// ===== SUPPORTED
// PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// nl_langinfo(int $item): string|false
// ===== CODE
$return_nl_langinfo = nl_langinfo(

$item // int item - item may be an integer value of the element or the constant name of the element. The following is a list of constant names for item that may be used and their description. Some of these constants may not be defined or hold no value for certain locales.
// nl_langinfo Constants
// Constant          - Description
// LC_TIME Category Constants
// ABDAY_(1-7)       - Abbreviated name of n-th day of the week.
// DAY_(1-7)         - Name of the n-th day of the week (DAY_1 = Sunday).
// ABMON_(1-12)      - Abbreviated name of the n-th month of the year.
// MON_(1-12)        - Name of the n-th month of the year.
// AM_STR            - String for Ante meridian.
// PM_STR            - String for Post meridian.
// D_T_FMT           - String that can be used as the format string for strftime() to represent time and date.
// D_FMT             - String that can be used as the format string for strftime() to represent date.
// T_FMT             - String that can be used as the format string for strftime() to represent time.
// T_FMT_AMPM        - String that can be used as the format string for strftime() to represent time in 12-hour format with ante/post meridian.
// ERA               - Alternate era.
// ERA_YEAR          - Year in alternate era format.
// ERA_D_T_FMT       - Date and time in alternate era format (string can be used in strftime()).
// ERA_D_FMT         - Date in alternate era format (string can be used in strftime()).
// ERA_T_FMT         - Time in alternate era format (string can be used in strftime()).
// LC_MONETARY       - Category Constants
// INT_CURR_SYMBOL   - International currency symbol.
// CURRENCY_SYMBOL   - Local currency symbol.
// CRNCYSTR          - Same value as CURRENCY_SYMBOL.
// MON_DECIMAL_POINT - Decimal point character.
// MON_THOUSANDS_SEP - Thousands separator (groups of three digits).
// MON_GROUPING      - Like "grouping" element.
// POSITIVE_SIGN     - Sign for positive values.
// NEGATIVE_SIGN     - Sign for negative values.
// INT_FRAC_DIGITS   - International fractional digits.
// FRAC_DIGITS       - Local fractional digits.
// P_CS_PRECEDES     - Returns 1 if CURRENCY_SYMBOL precedes a positive value.
// P_SEP_BY_SPACE    - Returns 1 if a space separates CURRENCY_SYMBOL from a positive value.
// N_CS_PRECEDES     - Returns 1 if CURRENCY_SYMBOL precedes a negative value.
// N_SEP_BY_SPACE    - Returns 1 if a space separates CURRENCY_SYMBOL from a negative value.
// P_SIGN_POSN       -
//                     * Returns 0 if parentheses surround the quantity and CURRENCY_SYMBOL.
//                     * Returns 1 if the sign string precedes the quantity and CURRENCY_SYMBOL.
//                     * Returns 2 if the sign string follows the quantity and CURRENCY_SYMBOL.
//                     * Returns 3 if the sign string immediately precedes the CURRENCY_SYMBOL.
//                     * Returns 4 if the sign string immediately follows the CURRENCY_SYMBOL.
// N_SIGN_POSN       - 
// LC_NUMERIC        - Category Constants
// DECIMAL_POINT     - Decimal point character.
// RADIXCHAR         - Same value as DECIMAL_POINT.
// THOUSANDS_SEP     - Separator character for thousands (groups of three digits).
// THOUSEP           - Same value as THOUSANDS_SEP.
// GROUPING          - 
// LC_MESSAGES       - Category Constants
// YESEXPR           - Regex string for matching "yes" input.
// NOEXPR            - Regex string for matching "no" input.
// YESSTR            - Output string for "yes".
// NOSTR             - Output string for "no".
// LC_CTYPE          - Category Constants
// CODESET           - Return a string with the name of the character encoding.

); // Return Values
// Returns the element as a string, or false if item is not valid.
// 
// [examples]
// Examples
// [example]
// Example #1 nl_langinfo() example
// [php]
// 
// var_dump(nl_langinfo(CODESET));
// var_dump(nl_langinfo(YESEXPR));
// [/php]
// The above example will output something similar to:
// [result]
// string(14) "ANSI_X3.4-1968"
// string(5) "^[yY]"
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is not implemented on Windows platforms.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.nl-langinfo.php
// ========== NL_LANGINFO - END

// SYNTAX:
// string|false nl_langinfo(int $item)

return $return_nl_langinfo; // string|false
}
// ============================== END
//  PHP_TEXT_STRINGS_NL_LANGINFO  
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_NL2BR     
// ============================== PUBLIC
// ============================== ABOUT
// Inserts HTML line breaks before all newlines in a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// nl2br() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_nl2br($string, $use_xhtml = true)
{
$return_nl2br = null;

// ========== NL2BR - BEGIN
// ===== ABOUT
// Inserts HTML line breaks before all newlines in a string
// ===== DESCRIPTION
// Returns string with <br /> or <br> inserted before all newlines (\r\n, \n\r, \n and \r).
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// nl2br(string $string, bool $use_xhtml = true): string
// ===== CODE
$return_nl2br = nl2br(

$string, // string string - The input string.

$use_xhtml // bool use_xhtml - Whether to use XHTML compatible line breaks or not.

); // Return Values
// Returns the altered string.
// 
// [examples]
// Examples
// [example]
// Example #1 Using nl2br()
// [php]
// echo nl2br("foo isn't\n bar");
// [/php]
// The above example will output:
// [result]
// foo isn't<br />
//  bar
// [/result]
// [/example]
// [example]
// Example #2 Generating valid HTML markup using the use_xhtml parameter
// [php]
// echo nl2br("Welcome\r\nThis is my HTML document", false);
// [/php]
// The above example will output:
// [result]
// Welcome<br>
// This is my HTML document
// [/result]
// [/example]
// [example]
// Example #3 Various newline separators
// [php]
// $string = "This\r\nis\n\ra\nstring\r";
// echo nl2br($string);
// [/php]
// The above example will output:
// [result]
// This<br />
// is<br />
// a<br />
// string<br />
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.nl2br.php
// ========== NL2BR - END

// SYNTAX:
// string nl2br(string $string, bool $use_xhtml = true)

return $return_nl2br; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_NL2BR     
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_NUMBER_FORMAT
// ============================== PUBLIC
// ============================== ABOUT
// Format a number with grouped thousands.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// number_format() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_number_format($num, $decimals = 0, $decimal_separator = ".", $thousands_separator = ",")
{
$return_number_format = null;

// ========== NUMBER_FORMAT - BEGIN
// ===== ABOUT
// Format a number with grouped thousands
// ===== DESCRIPTION
// Formats a number with grouped thousands and optionally decimal digits using the rounding half up rule.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// number_format(
//    float $num,
//    int $decimals = 0,
//    ?string $decimal_separator = ".",
//    ?string $thousands_separator = ","
// ): string
// ===== CODE
$return_number_format = number_format(

$num, // float num - The number being formatted.

$decimals, // int decimals - Sets the number of decimal digits. If 0, the decimal_separator is omitted from the return value.

$decimal_separator, // string decimal_separator - Sets the separator for the decimal point.

$thousands_separator // string thousands_separator - Sets the thousands separator.

); // Return Values
// A formatted version of num.
// 
// Changelog
// Version - Description
// 8.0.0   - Prior to this version, number_format() accepted one, two, or four parameters (but not three).
// 7.2.0   - number_format() was changed to not being able to return -0, previously -0 could be returned for cases like where num would be -0.01.
// 
// [examples]
// Examples
// [example]
// Example #1 number_format() Example
// For instance, French notation usually use two decimals, comma (',') as decimal separator, and space (' ') as thousand separator. The following example demonstrates various ways to format a number:
// [php]
// 
// $number = 1234.56;
// 
// // english notation (default)
// $english_format_number = number_format($number);
// // 1,235
// 
// // French notation
// $nombre_format_francais = number_format($number, 2, ',', ' ');
// // 1 234,56
// 
// $number = 1234.5678;
// 
// // english notation without thousands separator
// $english_format_number = number_format($number, 2, '.', '');
// // 1234.57
// 
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.number-format.php
// ========== NUMBER_FORMAT - END

// SYNTAX:
// string number_format(float $num, int $decimals = 0, string $decimal_separator = ".", string $thousands_separator = ",")

return $return_number_format; // string
}
// ============================== END
// PHP_TEXT_STRINGS_NUMBER_FORMAT
// ==============================


// ============================== BEGIN
//      PHP_TEXT_STRINGS_ORD      
// ============================== PUBLIC
// ============================== ABOUT
// Convert the first byte of a string to a value between 0 and 255.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// ord() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_ord($character)
{
$return_ord = 0;

// ========== ORD - BEGIN
// ===== ABOUT
// Convert the first byte of a string to a value between 0 and 255
// ===== DESCRIPTION
// Interprets the binary value of the first byte of character as an unsigned integer between 0 and 255.
// If the string is in a single-byte encoding, such as ASCII, ISO-8859, or Windows 1252, this is equivalent to returning the position of a character in the character set's mapping table. However, note that this function is not aware of any string encoding, and in particular will never identify a Unicode code point in a multi-byte encoding such as UTF-8 or UTF-16.
// This function complements chr().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// ord(string $character): int
// ===== CODE
$return_ord = ord(

$character // string $character - A character.

); // Return Values
// An integer between 0 and 255.
// 
// [examples]
// Examples
// [example]
// Example #1 ord() example
// [php]
// $str = "\n";
// if (ord($str) == 10) {
//     echo "The first character of \$str is a line feed.\n";
// }
// [/php]
// [/example]
// [example]
// Example #2 Examining the individual bytes of a UTF-8 string
// [php]
// declare(encoding='UTF-8');
// $str = "🐘";
// for ( $pos=0; $pos < strlen($str); $pos ++ ) {
//  $byte = substr($str, $pos);
//  echo 'Byte ' . $pos . ' of $str has value ' . ord($byte) . PHP_EOL;
// }
// [/php]
// The above example will output:
// [result]
// 
// Byte 0 of $str has value 240
// Byte 1 of $str has value 159
// Byte 2 of $str has value 144
// Byte 3 of $str has value 152
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.ord.php
// ========== ORD - END

// SYNTAX:
// int ord(string $character)

return $return_ord; // int
}
// ============================== END
//      PHP_TEXT_STRINGS_ORD      
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_PARSE_STR   
// ============================== PUBLIC
// ============================== ABOUT
// Parses the string into variables.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// parse_str() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_parse_str($string, & $result)
{

// ========== PARSE_STR - BEGIN
// ===== ABOUT
// Parses the string into variables
// ===== DESCRIPTION
// Parses string as if it were the query string passed via a URL and sets variables in the current scope (or in the array if result is provided).
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// parse_str(string $string, array &$result): void
// ===== CODE
parse_str(

$string, // string string - The input string.

$result // array& result - If the second parameter result is present, variables are stored in this variable as array elements instead.
// Warning: Using this function without the result parameter is highly DISCOURAGED and DEPRECATED as of PHP 7.2. As of PHP 8.0.0, the result parameter is mandatory.

); // Return Values
// No value is returned.
// 
// Changelog
// Version - Description
// 8.0.0   - result is no longer optional.
// 7.2.0   - Usage of parse_str() without a second parameter now emits an E_DEPRECATED notice.
// 
// [examples]
// Examples
// [example]
// Example #1 Using parse_str()
// [php]
// $str = "first=value&arr[]=foo+bar&arr[]=baz";
// 
// // Recommended
// parse_str($str, $output);
// echo $output['first'];  // value
// echo $output['arr'][0]; // foo bar
// echo $output['arr'][1]; // baz
// 
// // DISCOURAGED
// parse_str($str);
// echo $first;  // value
// echo $arr[0]; // foo bar
// echo $arr[1]; // baz
// [/php]
// Because variables in PHP can't have dots and spaces in their names, those are converted to underscores. Same applies to naming of respective key names in case of using this function with result parameter.
// [/example]
// [example]
// Example #2 parse_str() name mangling
// [php]
// parse_str("My Value=Something");
// echo $My_Value; // Something
// 
// parse_str("My Value=Something", $output);
// echo $output['My_Value']; // Something
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: All variables created (or values returned into array if second parameter is set) are already urldecode()d.
// Note: To get the current QUERY_STRING, you may use the variable $_SERVER['QUERY_STRING']. Also, you may want to read the section on variables from external sources.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.parse-str.php
// ========== PARSE_STR - END

// SYNTAX:
// void parse_str(string $string, array& $result)

// Return: void
}
// ============================== END
//   PHP_TEXT_STRINGS_PARSE_STR   
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_PRINT     
// ============================== PUBLIC
// ============================== ABOUT
// Output a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// print() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_print($expression)
{
$return_print = 0;

// ========== PRINT - BEGIN
// ===== ABOUT
// Output a string
// ===== DESCRIPTION
// Outputs expression.
// print is not a function but a language construct. Its argument is the expression following the print keyword, and is not delimited by parentheses.
// The major differences to echo are that print only accepts a single argument and always returns 1.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// print(string $expression): int
// ===== CODE
$return_print = print(

$expression // string expression - The expression to be output. Non-string values will be coerced to strings, even when the strict_types directive is enabled.

); // Return Values
// Returns 1, always.
// 
// [examples]
// Examples
// [example]
// Example #1 print examples
// [php]
// print "print does not require parentheses.";
// 
// // No newline or space is added; the below outputs "helloworld" all on one line
// print "hello";
// print "world";
// 
// print "This string spans
// multiple lines. The newlines will be
// output as well";
// 
// print "This string spans\nmultiple lines. The newlines will be\noutput as well.";
// 
// // The argument can be any expression which produces a string
// $foo = "example";
// print "foo is $foo"; // foo is example
// 
// $fruits = ["lemon", "orange", "banana"];
// print implode(" and ", $fruits); // lemon and orange and banana
// 
// // Non-string expressions are coerced to string, even if declare(strict_types=1) is used
// print 6 * 7; // 42
// 
// // Because print has a return value, it can be used in expressions
// // The following outputs "hello world"
// if ( print "hello" ) {
//     echo " world";
// }
// 
// // The following outputs "true"
// ( 1 === 1 ) ? print 'true' : print 'false';
// [/php]
// [/example]
// [/examples]
// 
// Notes
//  Note: Using with parentheses
//  Surrounding the argument to print with parentheses will not raise a syntax error, and produces syntax which looks like a normal function call. However, this can be misleading, because the parentheses are actually part of the expression being output, not part of the print syntax itself.
//  [example]
//  [php]
//  print "hello";
//  // outputs "hello"
//  
//  print("hello");
//  // also outputs "hello", because ("hello") is a valid expression
//  
//  print(1 + 2) * 3;
//  // outputs "9"; the parentheses cause 1+2 to be evaluated first, then 3*3
//  // the print statement sees the whole expression as one argument
//  
//  if ( print("hello") && false ) {
//      print " - inside if";
//  }
//  else {
//      print " - inside else";
//  }
//  // outputs " - inside if"
//  // the expression ("hello") && false is first evaluated, giving false
//  // this is coerced to the empty string "" and printed
//  // the print construct then returns 1, so code in the if block is run
//  [/php]
//  [/example]
//  When using print in a larger expression, placing both the keyword and its argument in parentheses may be necessary to give the intended result:
//  [example]
//  [php]
//  if ( (print "hello") && false ) {
//      print " - inside if";
//  }
//  else {
//      print " - inside else";
//  }
//  // outputs "hello - inside else"
//  // unlike the previous example, the expression (print "hello") is evaluated first
//  // after outputting "hello", print returns 1
//  // since 1 && false is false, code in the else block is run
//  
//  print "hello " && print "world";
//  // outputs "world1"; print "world" is evaluated first,
//  // then the expression "hello " && 1 is passed to the left-hand print
//  
//  (print "hello ") && (print "world");
//  // outputs "hello world"; the parentheses force the print expressions
//  // to be evaluated before the &&
//  [/php]
//  [/example]
// Note: Because this is a language construct and not a function, it cannot be called using variable functions, or named arguments.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-21)
// URL: https://www.php.net/manual/en/function.print.php
// ========== PRINT - END

// SYNTAX:
// int print(string $expression)

return $return_print; // int
}
// ============================== END
//     PHP_TEXT_STRINGS_PRINT     
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_PRINTF    
// ============================== PUBLIC
// ============================== ABOUT
// Output a formatted string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// printf() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_printf($format, $values)
{
$return_printf = 0;

// ========== PRINTF - BEGIN
// ===== ABOUT
// Output a formatted string
// ===== DESCRIPTION
// Produces output according to format.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// printf(string $format, mixed ...$values): int
// ===== CODE
$return_printf = printf(

$format, // string format - The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.
// A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier.
// Argnum
// An integer followed by a dollar sign $, to specify which number argument to treat in the conversion.
// Flags
// Flag      - Description
// -         - Left-justify within the given field width; Right justification is the default
// +         - Prefix positive numbers with a plus sign +; Default only negative are prefixed with a negative sign.
// (space)   - Pads the result with spaces. This is the default.
// 0         - Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros.
// '(char)   - Pads the result with the character (char).
// Width
// Either an integer that says how many characters (minimum) this conversion should result in, or *. If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.
// Precision
// A period . optionally followed by either an integer or *, whose meaning depends on the specifier:
// * For e, E, f and F specifiers : this is the number of digits to be printed after the decimal point (by default, this is 6).
// * For g, G, h and H specifiers : this is the maximum number of significant digits to be printed.
// * For s specifier              : it acts as a cutoff point, setting a maximum character limit to the string.
// Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.
// Specifiers
// Specifier - Description
// %         - A literal percent character. No argument is required.
// b         - The argument is treated as an integer and presented as a binary number.
// c         - The argument is treated as an integer and presented as the character with that ASCII.
// d         - The argument is treated as an integer and presented as a (signed) decimal number.
// e         - The argument is treated as scientific notation (e.g. 1.2e+2).
// E         - Like the e specifier but uses uppercase letter (e.g. 1.2E+2).
// f         - The argument is treated as a float and presented as a floating-point number (locale aware).
// F         - The argument is treated as a float and presented as a floating-point number (non-locale aware).
// g         - General format.
//             Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
//             If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
// G         - Like the g specifier but uses E and f.
// h         - Like the g specifier but uses F. Available as of PHP 8.0.0.
// H         - Like the g specifier but uses E and F. Available as of PHP 8.0.0.
// o         - The argument is treated as an integer and presented as an octal number.
// s         - The argument is treated and presented as a string.
// u         - The argument is treated as an integer and presented as an unsigned decimal number.
// x         - The argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).
// X         - The argument is treated as an integer and presented as a hexadecimal number (with uppercase letters).
// Warning: The c type specifier ignores padding and width
// Warning: Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
// Variables will be co-erced to a suitable type for the specifier:
// Type Handling
// Type   - Specifiers
// string - s
// int    - d, u, c, o, x, X, b
// float  - e, E, f, F, g, G, h, H

$values // mixed values

); // Return Values
// Returns the length of the outputted string.
// 
// Errors/Exceptions
// As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ArgumentCountError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
// 
// Changelog
// Version - Description
// 8.0.0   - This function no longer returns false on failure.
// 8.0.0   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ArgumentCountError when less arguments are given than required; previously this function emitted a E_WARNING instead.
// 
// [examples]
// Examples
// [example]
// Example #1 printf(): various examples
// [php]
// $n =  43951789;
// $u = -43951789;
// $c = 65; // ASCII 65 is 'A'
// 
// // notice the double %%, this prints a literal '%' character
// printf("%%b = '%b'\n", $n); // binary representation
// printf("%%c = '%c'\n", $c); // print the ascii character, same as chr() function
// printf("%%d = '%d'\n", $n); // standard integer representation
// printf("%%e = '%e'\n", $n); // scientific notation
// printf("%%u = '%u'\n", $n); // unsigned integer representation of a positive integer
// printf("%%u = '%u'\n", $u); // unsigned integer representation of a negative integer
// printf("%%f = '%f'\n", $n); // floating point representation
// printf("%%o = '%o'\n", $n); // octal representation
// printf("%%s = '%s'\n", $n); // string representation
// printf("%%x = '%x'\n", $n); // hexadecimal representation (lower-case)
// printf("%%X = '%X'\n", $n); // hexadecimal representation (upper-case)
// 
// printf("%%+d = '%+d'\n", $n); // sign specifier on a positive integer
// printf("%%+d = '%+d'\n", $u); // sign specifier on a negative integer
// [/php]
// The above example will output:
// [result]
// %b = '10100111101010011010101101'
// %c = 'A'
// %d = '43951789'
// %e = '4.39518e+7'
// %u = '43951789'
// %u = '4251015507'
// %f = '43951789.000000'
// %o = '247523255'
// %s = '43951789'
// %x = '29ea6ad'
// %X = '29EA6AD'
// %+d = '+43951789'
// %+d = '-43951789'
// [/result]
// [/example]
// [example]
// Example #2 printf(): string specifiers
// [php]
// $s = 'monkey';
// $t = 'many monkeys';
// 
// printf("[%s]\n",        $s); // standard string output
// printf("[%10s]\n",      $s); // right-justification with spaces
// printf("[%-10s]\n",     $s); // left-justification with spaces
// printf("[%010s]\n",     $s); // zero-padding works on strings too
// printf("[%'#10s]\n",    $s); // use the custom padding character '#'
// printf("[%'#*s]\n", 10, $s); // Provide the padding width as an additional argument
// printf("[%10.9s]\n",    $t); // right-justification but with a cutoff of 8 characters
// printf("[%-10.9s]\n",   $t); // left-justification but with a cutoff of 8 characters
// [/php]
// The above example will output:
// [result]
// [monkey]
// [    monkey]
// [monkey    ]
// [0000monkey]
// [####monkey]
// [####monkey]
// [ many monk]
// [many monk ]
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.printf.php
// ========== PRINTF - END

// SYNTAX:
// int printf(string $format, mixed $values)

return $return_printf; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_PRINTF    
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_QUOTED_PRINTABLE_DECODE
// ============================== PUBLIC
// ============================== ABOUT
// Convert a quoted-printable string to an 8 bit string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// quoted_printable_decode() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_quoted_printable_decode($string)
{
$return_quoted_printable_decode = null;

// ========== QUOTED_PRINTABLE_DECODE - BEGIN
// ===== ABOUT
// Convert a quoted-printable string to an 8 bit string
// ===== DESCRIPTION
// This function returns an 8-bit binary string corresponding to the decoded quoted printable string (according to > RFC2045, section 6.7, not > RFC2821, section 4.5.2, so additional periods are not stripped from the beginning of line).
// This function is similar to imap_qprint(), except this one does not require the IMAP module to work.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// quoted_printable_decode(string $string): string
// ===== CODE
$return_quoted_printable_decode = quoted_printable_decode(

$string // string string - The input string.

); // Return Values
// Returns the 8-bit binary string.
// 
// [examples]
// Examples
// [example]
// Example #1 quoted_printable_decode() example
// [php]
// 
// $encoded = quoted_printable_encode('Möchten Sie ein paar Äpfel?');
// 
// var_dump($encoded);
// var_dump(quoted_printable_decode($encoded));
// [/php]
// The above example will output:
// [result]
// string(37) "M=C3=B6chten Sie ein paar =C3=84pfel?"
// string(29) "Möchten Sie ein paar Äpfel?"
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.quoted-printable-decode.php
// ========== QUOTED_PRINTABLE_DECODE - END

// SYNTAX:
// string quoted_printable_decode(string $string)

return $return_quoted_printable_decode; // string
}
// ============================== END
// PHP_TEXT_STRINGS_QUOTED_PRINTABLE_DECODE
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_QUOTED_PRINTABLE_ENCODE
// ============================== OFFLINE
// ============================== ABOUT
// Convert a 8 bit string to a quoted-printable string.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// quoted_printable_encode() - PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_quoted_printable_encode($string)
{
$return_quoted_printable_encode = null;

// ========== QUOTED_PRINTABLE_ENCODE - BEGIN
// ===== ABOUT
// Convert a 8 bit string to a quoted-printable string
// ===== DESCRIPTION
// Returns a quoted printable string created according to > RFC2045, section 6.7.
// This function is similar to imap_8bit(), except this one does not require the IMAP module to work.
// ===== SUPPORTED
// PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// ===== SYNTAX
// quoted_printable_encode(string $string): string
// ===== CODE
$return_quoted_printable_encode = quoted_printable_encode(

$string // string string - The input string.

); // Return Values
// Returns the encoded string.
// 
// [examples]
// Examples
// [example]
// Example #1 quoted_printable_encode() example
// [php]
// 
// $encoded = quoted_printable_encode('Möchten Sie ein paar Äpfel?');
// 
// var_dump($encoded);
// var_dump(quoted_printable_decode($encoded));
// [/php]
// The above example will output:
// [result]
// string(37) "M=C3=B6chten Sie ein paar =C3=84pfel?"
// string(29) "Möchten Sie ein paar Äpfel?"
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.quoted-printable-encode.php
// ========== QUOTED_PRINTABLE_ENCODE - END

// SYNTAX:
// string quoted_printable_encode(string $string)

return $return_quoted_printable_encode; // string
}
*/
// ============================== END
// PHP_TEXT_STRINGS_QUOTED_PRINTABLE_ENCODE
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_QUOTEMETA   
// ============================== PUBLIC
// ============================== ABOUT
// Quote meta characters.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// quotemeta() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_quotemeta($string)
{
$return_quotemeta = null;

// ========== QUOTEMETA - BEGIN
// ===== ABOUT
// Quote meta characters
// ===== DESCRIPTION
// Returns a version of str with a backslash character (\) before every character that is among these:
// . \ + * ? [ ^ ] ( $ )
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// quotemeta(string $string): string
// ===== CODE
$return_quotemeta = quotemeta(

$string // string string - The input string.

); // Return Values
// Returns the string with meta characters quoted, or false if an empty string is given as string.
// 
// [examples]
// Examples
// [example]
// Example #1 quotemeta() example
// [php]
// 
// var_dump(quotemeta('PHP is a popular scripting language. Fast, flexible, and pragmatic.'));
// [/php]
// The above example will output:
// [result]
// string(69) "PHP is a popular scripting language\. Fast, flexible, and pragmatic\."
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.quotemeta.php
// ========== QUOTEMETA - END

// SYNTAX:
// string quotemeta(string $string)

return $return_quotemeta; // string
}
// ============================== END
//   PHP_TEXT_STRINGS_QUOTEMETA   
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_RTRIM     
// ============================== PUBLIC
// ============================== ABOUT
// Strip whitespace (or other characters) from the end of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// rtrim() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_rtrim($string, $characters = " \n\r\t\v\x00")
{
$return_rtrim = null;

// ========== RTRIM - BEGIN
// ===== ABOUT
// Strip whitespace (or other characters) from the end of a string
// ===== DESCRIPTION
// This function returns a string with whitespace (or other characters) stripped from the end of string.
// Without the second parameter, rtrim() will strip these characters:
// * " "  (ASCII 32 (0x20)), an ordinary space.
// * "\t" (ASCII 9 (0x09)) , a tab.
// * "\n" (ASCII 10 (0x0A)), a new line (line feed).
// * "\r" (ASCII 13 (0x0D)), a carriage return.
// * "\0" (ASCII 0 (0x00)) , the NULL-byte.
// * "\v" (ASCII 11 (0x0B)), a vertical tab.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// rtrim(string $string, string $characters = " \n\r\t\v\x00"): string
// ===== CODE
$return_rtrim = rtrim(

$string, // string string - The input string.

$characters // string characters - You can also specify the characters you want to strip, by means of the characters parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.

); // Return Values
// Returns the modified string.
// 
// [examples]
// Examples
// [example]
// Example #1 Usage example of rtrim()
// [php]
// 
// $text = "\t\tThese are a few words :) ...  ";
// $binary = "\x09Example string\x0A";
// $hello  = "Hello World";
// var_dump($text, $binary, $hello);
// 
// print "\n";
// 
// $trimmed = rtrim($text);
// var_dump($trimmed);
// 
// $trimmed = rtrim($text, " \t.");
// var_dump($trimmed);
// 
// $trimmed = rtrim($hello, "Hdle");
// var_dump($trimmed);
// 
// // trim the ASCII control characters at the end of $binary
// // (from 0 to 31 inclusive)
// $clean = rtrim($binary, "\x00..\x1F");
// var_dump($clean);
// 
// [/php]
// The above example will output:
// [result]
// string(32) "        These are a few words :) ...  "
// string(16) "    Example string
// "
// string(11) "Hello World"
// 
// string(30) "        These are a few words :) ..."
// string(26) "        These are a few words :)"
// string(9) "Hello Wor"
// string(15) "    Example string"
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.rtrim.php
// ========== RTRIM - END

// SYNTAX:
// string rtrim(string $string, string $characters = " \n\r\t\v\x00")

return $return_rtrim; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_RTRIM     
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_SETLOCALE   
// ============================== PUBLIC
// ============================== ABOUT
// Set locale information.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// setlocale() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_setlocale($category, $locales, $rest)
{
$return_setlocale = false;

// ========== SETLOCALE - BEGIN
// ===== ABOUT
// Set locale information
// ===== DESCRIPTION
// Sets locale information.
// Warning: The locale information is maintained per process, not per thread. If you are running PHP on a multithreaded server API , you may experience sudden changes in locale settings while a script is running, though the script itself never called setlocale(). This happens due to other scripts running in different threads of the same process at the same time, changing the process-wide locale using setlocale(). On Windows, locale information is maintained per thread as of PHP 7.0.5.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// setlocale(int $category, string $locales, string ...$rest): string|false
// 
// Alternative signature (not supported with named arguments):
// setlocale(int $category, array $locale_array): string|false
// ===== CODE
$return_setlocale = setlocale(

$category, // int category - category is a named constant specifying the category of the functions affected by the locale setting:
// * LC_ALL      - for all of the below
// * LC_COLLATE  - for string comparison, see strcoll()
// * LC_CTYPE    - for character classification and conversion, for example ctype_alpha()
// * LC_MONETARY - for localeconv()
// * LC_NUMERIC  - for decimal separator (See also localeconv())
// * LC_TIME     - for date and time formatting with strftime()
// * LC_MESSAGES - for system responses (available if PHP was compiled with libintl)

$locales, // string locales - If locales is the empty string "", the locale names will be set from the values of environment variables with the same names as the above categories, or from "LANG".
// If locales is "0", the locale setting is not affected, only the current setting is returned.
// If locales is followed by additional parameters then each parameter is tried to be set as new locale until success. This is useful if a locale is known under different names on different systems or for providing a fallback for a possibly not available locale.

$rest // string rest - Optional string parameters to try as locale settings until success.

// array locale_array - Each array element is tried to be set as new locale until success. This is useful if a locale is known under different names on different systems or for providing a fallback for a possibly not available locale.
// Note: On Windows, setlocale(LC_ALL, '') sets the locale names from the system's regional/language settings (accessible via Control Panel).

); // Return Values
// Returns the new current locale, or false if the locale functionality is not implemented on your platform, the specified locale does not exist or the category name is invalid.
// An invalid category name also causes a warning message. Category/locale names can be found in > RFC 1766 and > ISO 639. Different systems have different naming schemes for locales.
// Note: The return value of setlocale() depends on the system that PHP is running. It returns exactly what the system setlocale function returns.
// 
// [examples]
// Examples
// [example]
// Example #1 setlocale() Examples
// [php]
// // Set locale to Dutch
// setlocale(LC_ALL, 'nl_NL');
// 
// // Output: vrijdag 22 december 1978
// echo strftime("%A %e %B %Y", mktime(0, 0, 0, 12, 22, 1978));
// 
// // try different possible locale names for german
// $loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'de', 'ge');
// echo "Preferred locale for german on this system is '$loc_de'";
// [/php]
// [/example]
// [example]
// Example #2 setlocale() Examples for Windows
// [php]
// // Set locale to Dutch
// setlocale(LC_ALL, 'nld_nld');
// 
// // Output: vrijdag 22 december 1978
// echo strftime("%A %d %B %Y", mktime(0, 0, 0, 12, 22, 1978));
// 
// // try different possible locale names for german
// $loc_de = setlocale(LC_ALL, 'de_DE@euro', 'de_DE', 'deu_deu');
// echo "Preferred locale for german on this system is '$loc_de'";
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Tip: Windows users will find useful information about locales strings at Microsoft's MSDN website. Supported language strings can be found in the > language strings documentation and supported country/region strings in the > country/region strings documentation.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.setlocale.php
// ========== SETLOCALE - END

// SYNTAX:
// string|false setlocale(int $category, string $locales, string $rest)

return $return_setlocale; // string|false
}
// ============================== END
//   PHP_TEXT_STRINGS_SETLOCALE   
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_SHA1_FILE   
// ============================== PUBLIC
// ============================== ABOUT
// Calculate the sha1 hash of a file.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// sha1_file() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_sha1_file($filename, $binary = false)
{
$return_sha1_file = false;

// ========== SHA1_FILE - BEGIN
// ===== ABOUT
// Calculate the sha1 hash of a file
// ===== DESCRIPTION
// Calculates the sha1 hash of the file specified by filename using the > US Secure Hash Algorithm 1, and returns that hash. The hash is a 40-character hexadecimal number.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// sha1_file(string $filename, bool $binary = false): string|false
// ===== CODE
$return_sha1_file = sha1_file(

$filename, // string filename - The filename of the file to hash.

$binary // bool binary - When true, returns the digest in raw binary format with a length of 20.

); // Return Values
// Returns a string on success, false otherwise.
// 
// [examples]
// Examples
// [example]
// Example #1 sha1_file() example
// [php]
// foreach(glob('/home/Kalle/myproject/*.php') as $ent)
// {
//     if(is_dir($ent))
//     {
//         continue;
//     }
// 
//     echo $ent . ' (SHA1: ' . sha1_file($ent) . ')', PHP_EOL;
// }
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.sha1-file.php
// ========== SHA1_FILE - END

// SYNTAX:
// string|false sha1_file(string $filename, bool $binary = false)

return $return_sha1_file; // string|false
}
// ============================== END
//   PHP_TEXT_STRINGS_SHA1_FILE   
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_SHA1     
// ============================== PUBLIC
// ============================== ABOUT
// Calculate the sha1 hash of a string.
// 
// Warning: It is not recommended to use this function to secure passwords, due to the fast nature of this hashing algorithm. See the Password Hashing FAQ for details and best practices.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// sha1() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_sha1($string, $binary = false)
{
$return_sha1 = null;

// ========== SHA1 - BEGIN
// ===== ABOUT
// Calculate the sha1 hash of a string
// Warning: It is not recommended to use this function to secure passwords, due to the fast nature of this hashing algorithm. See the Password Hashing FAQ for details and best practices.
// ===== DESCRIPTION
// Calculates the sha1 hash of string using the > US Secure Hash Algorithm 1.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// sha1(string $string, bool $binary = false): string
// ===== CODE
$return_sha1 = sha1(

$string, // string string - The input string.

$binary // bool binary - If the optional binary is set to true, then the sha1 digest is instead returned in raw binary format with a length of 20, otherwise the returned value is a 40-character hexadecimal number.

); // Return Values
// Returns the sha1 hash as a string.
// 
// [examples]
// Examples
// [example]
// Example #1 A sha1() example
// [php]
// $str = 'apple';
// 
// if (sha1($str) === 'd0be2dc421be4fcd0172e5afceea3970e2f3d940') {
//     echo "Would you like a green or red apple?";
// }
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.sha1.php
// ========== SHA1 - END

// SYNTAX:
// string sha1(string $string, bool $binary = false)

return $return_sha1; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_SHA1     
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_SIMILAR_TEXT 
// ============================== PUBLIC
// ============================== ABOUT
// Calculate the similarity between two strings.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// similar_text() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_similar_text($string1, $string2, & $percent)
{
$return_similar_text = 0;

// ========== SIMILAR_TEXT - BEGIN
// ===== ABOUT
// Calculate the similarity between two strings
// ===== DESCRIPTION
// This calculates the similarity between two strings as described in Programming Classics: Implementing the World's Best Algorithms by Oliver (ISBN 0-131-00413-1). Note that this implementation does not use a stack as in Oliver's pseudo code, but recursive calls which may or may not speed up the whole process. Note also that the complexity of this algorithm is O(N**3) where N is the length of the longest string.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// similar_text(string $string1, string $string2, float &$percent = null): int
// ===== CODE
$return_similar_text = similar_text(

$string1, // string string1 - The first string.

$string2, // string string2 - The second string.
// Note: Swapping the string1 and string2 may yield a different result; see the example below.

$percent // float& percent - By passing a reference as third argument, similar_text() will calculate the similarity in percent, by dividing the result of similar_text() by the average of the lengths of the given strings times 100.

); // Return Values
// Returns the number of matching chars in both strings.
// The number of matching characters is calculated by finding the longest first common substring, and then doing this for the prefixes and the suffixes, recursively. The lengths of all found common substrings are added.
// 
// [examples]
// Examples
// [example]
// Example #1 similar_text() argument swapping example
// This example shows that swapping the string1 and string2 argument may yield different results.
// [php]
// $sim = similar_text('bafoobar', 'barfoo', $perc);
// echo "similarity: $sim ($perc %)\n";
// $sim = similar_text('barfoo', 'bafoobar', $perc);
// echo "similarity: $sim ($perc %)\n";
// [/php]
// The above example will output something similar to:
// [result]
// similarity: 5 (71.428571428571 %)
// similarity: 3 (42.857142857143 %)
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.similar-text.php
// ========== SIMILAR_TEXT - END

// SYNTAX:
// int similar_text(string $string1, string $string2, float& $percent)

return $return_similar_text; // int
}
// ============================== END
// PHP_TEXT_STRINGS_SIMILAR_TEXT 
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_SOUNDEX    
// ============================== PUBLIC
// ============================== ABOUT
// Calculate the soundex key of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// soundex() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_soundex($string)
{
$return_soundex = null;

// ========== SOUNDEX - BEGIN
// ===== ABOUT
// Calculate the soundex key of a string
// ===== DESCRIPTION
// Calculates the soundex key of string.
// Soundex keys have the property that words pronounced similarly produce the same soundex key, and can thus be used to simplify searches in databases where you know the pronunciation but not the spelling.
// This particular soundex function is one described by Donald Knuth in "The Art Of Computer Programming, vol. 3: Sorting And Searching", Addison-Wesley (1973), pp. 391-392.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// soundex(string $string): string
// ===== CODE
$return_soundex = soundex(

$string // string string - The input string.

); // Return Values
// Returns the soundex key as a string with four characters. If at least one letter is contained in string, the returned string starts with a letter. Otherwise "0000" is returned.
// 
// Changelog
// Version - Description
// 8.0.0   - Prior to this version, calling the function with an empty string returned false for no particular reason.
// 
// [examples]
// Examples
// [example]
// Example #1 Soundex Examples
// [php]
// soundex("Euler")       == soundex("Ellery");    // E460
// soundex("Gauss")       == soundex("Ghosh");     // G200
// soundex("Hilbert")     == soundex("Heilbronn"); // H416
// soundex("Knuth")       == soundex("Kant");      // K530
// soundex("Lloyd")       == soundex("Ladd");      // L300
// soundex("Lukasiewicz") == soundex("Lissajous"); // L222
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.soundex.php
// ========== SOUNDEX - END

// SYNTAX:
// string soundex(string $string)

return $return_soundex; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_SOUNDEX    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_SPRINTF    
// ============================== PUBLIC
// ============================== ABOUT
// Return a formatted string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// sprintf() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_sprintf($format, $values)
{
$return_sprintf = null;

// ========== SPRINTF - BEGIN
// ===== ABOUT
// Return a formatted string
// ===== DESCRIPTION
// Returns a string produced according to the formatting string format.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// sprintf(string $format, mixed ...$values): string
// ===== CODE
$return_sprintf = sprintf(

$format, // string format - The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.
// A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier.
// Argnum
// An integer followed by a dollar sign $, to specify which number argument to treat in the conversion.
// Flags
// Flag    - Description
// -       - Left-justify within the given field width; Right justification is the default
// +       - Prefix positive numbers with a plus sign +; Default only negative are prefixed with a negative sign.
// (space) - Pads the result with spaces. This is the default.
// 0       - Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros.
// '(char) - Pads the result with the character (char).
// Width
// Either an integer that says how many characters (minimum) this conversion should result in, or *. If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.
// Precision
// A period . optionally followed by either an integer or *, whose meaning depends on the specifier:
// * For e, E, f and F specifiers: this is the number of digits to be printed after the decimal point (by default, this is 6).
// * For g, G, h and H specifiers: this is the maximum number of significant digits to be printed.
// * For s specifier: it acts as a cutoff point, setting a maximum character limit to the string.
// Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.
// Specifiers
// Specifier - Description
// %         - A literal percent character. No argument is required.
// b         - The argument is treated as an integer and presented as a binary number.
// c         - The argument is treated as an integer and presented as the character with that ASCII.
// d         - The argument is treated as an integer and presented as a (signed) decimal number.
// e         - The argument is treated as scientific notation (e.g. 1.2e+2).
// E         - Like the e specifier but uses uppercase letter (e.g. 1.2E+2).
// f         - The argument is treated as a float and presented as a floating-point number (locale aware).
// F         - The argument is treated as a float and presented as a floating-point number (non-locale aware).
// g         - General format.
//             Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
//             If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
// G         - Like the g specifier but uses E and f.
// h         - Like the g specifier but uses F. Available as of PHP 8.0.0.
// H         - Like the g specifier but uses E and F. Available as of PHP 8.0.0.
// o         - The argument is treated as an integer and presented as an octal number.
// s         - The argument is treated and presented as a string.
// u         - The argument is treated as an integer and presented as an unsigned decimal number.
// x         - The argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).
// X         - The argument is treated as an integer and presented as a hexadecimal number (with uppercase letters).
// Warning: The c type specifier ignores padding and width
// Warning: Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
// Variables will be co-erced to a suitable type for the specifier:
// Type Handling
// Type   - Specifiers
// string - s
// int    - d, u, c, o, x, X, b
// float  - e, E, f, F, g, G, h, H

$values // mixed values

); // Return Values
// Returns a string produced according to the formatting string format.
// 
// Errors/Exceptions
// As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ArgumentCountError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
// 
// Changelog
// Version - Description
// 8.0.0   - This function no longer returns false on failure.
// 8.0.0   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ArgumentCountError when less arguments are given than required; previously this function emitted a E_WARNING instead.
// 
// [examples]
// Examples
// [example]
// Example #1 Argument swapping
// The format string supports argument numbering/swapping.
// [php]
// $num = 5;
// $location = 'tree';
// 
// $format = 'There are %d monkeys in the %s';
// echo sprintf($format, $num, $location);
// [/php]
// The above example will output:
// [result]
// There are 5 monkeys in the tree
// However imagine we are creating a format string in a separate file, commonly because we would like to internationalize it and we rewrite it as:
// [/result]
// [php]
// $format = 'The %s contains %d monkeys';
// echo sprintf($format, $num, $location);
// [/php]
// We now have a problem. The order of the placeholders in the format string does not match the order of the arguments in the code. We would like to leave the code as is and simply indicate in the format string which arguments the placeholders refer to. We would write the format string like this instead:
// [php]
// $format = 'The %2$s contains %1$d monkeys';
// echo sprintf($format, $num, $location);
// [/php]
// An added benefit is that placeholders can be repeated without adding more arguments in the code.
// [php]
// $format = 'The %2$s contains %1$d monkeys.
//            That\'s a nice %2$s full of %1$d monkeys.';
// echo sprintf($format, $num, $location);
// [/php]
// When using argument swapping, the n$ position specifier must come immediately after the percent sign (%), before any other specifiers, as shown below.
// [/example]
// [example]
// Example #2 Specifying padding character
// [php]
// echo sprintf("%'.9d\n", 123);
// echo sprintf("%'.09d\n", 123);
// [/php]
// The above example will output:
// [result]
// ......123
// 000000123
// [/result]
// [/example]
// [example]
// Example #3 Position specifier with other specifiers
// [php]
// $format = 'The %2$s contains %1$04d monkeys';
// echo sprintf($format, $num, $location);
// [/php]
// The above example will output:
// [result]
// The tree contains 0005 monkeys
// [/result]
// [/example]
// [example]
// Example #4 sprintf(): zero-padded integers
// [php]
// $isodate = sprintf("%04d-%02d-%02d", $year, $month, $day);
// [/php]
// [/example]
// [example]
// Example #5 sprintf(): formatting currency
// [php]
// $money1 = 68.75;
// $money2 = 54.35;
// $money = $money1 + $money2;
// echo $money;
// echo "\n";
// $formatted = sprintf("%01.2f", $money);
// echo $formatted;
// [/php]
// The above example will output:
// [result]
// 123.1
// 123.10
// [/result]
// [/example]
// [example]
// Example #6 sprintf(): scientific notation
// [php]
// $number = 362525200;
// 
// echo sprintf("%.3e", $number);
// [/php]
// The above example will output:
// [result]
// 3.625e+8
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.sprintf.php
// ========== SPRINTF - END

// SYNTAX:
// string sprintf(string $format, mixed $values)

return $return_sprintf; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_SPRINTF    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_SSCANF    
// ============================== PUBLIC
// ============================== ABOUT
// Parses input from a string according to a format.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// sscanf() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_sscanf($string, $format, & $vars)
{
$return_sscanf = null;

// ========== SSCANF - BEGIN
// ===== ABOUT
// Parses input from a string according to a format
// ===== DESCRIPTION
// The function sscanf() is the input analog of printf(). sscanf() reads from the string string and interprets it according to the specified format.
// Any whitespace in the format string matches any whitespace in the input string. This means that even a tab (\t) in the format string can match a single space character in the input string.
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// sscanf(string $string, string $format, mixed &...$vars): array|int|null
// ===== CODE
$return_sscanf = sscanf(

$string, // string string - The input string being parsed.

$format, // string format - The interpreted format for string, which is described in the documentation for sprintf() with following differences:
// * Function is not locale-aware.
// * F, g, G and b are not supported.
// * D stands for decimal number.
// * i stands for integer with base detection.
// * n stands for number of characters processed so far.
// * s stops reading at any whitespace character.
// * * instead of argnum$ suppresses the assignment of this conversion specification.

$vars // mixed& vars - Optionally pass in variables by reference that will contain the parsed values.

); // Return Values
// If only two parameters were passed to this function, the values parsed will be returned as an array. Otherwise, if optional parameters are passed, the function will return the number of assigned values. The optional parameters must be passed by reference.
// If there are more substrings expected in the format than there are available within string, null will be returned.
// 
// [examples]
// Examples
// [example]
// Example #1 sscanf() Example
// [php]
// // getting the serial number
// list($serial) = sscanf("SN/2350001", "SN/%d");
// // and the date of manufacturing
// $mandate = "January 01 2000";
// list($month, $day, $year) = sscanf($mandate, "%s %d %d");
// echo "Item $serial was manufactured on: $year-" . substr($month, 0, 3) . "-$day\n";
// [/php]
// If optional parameters are passed, the function will return the number of assigned values.
// [/example]
// [example]
// Example #2 sscanf() - using optional parameters
// [php]
// // get author info and generate DocBook entry
// $auth = "24\tLewis Carroll";
// $n = sscanf($auth, "%d\t%s %s", $id, $first, $last);
// echo "<author id='$id'>
//     <firstname>$first</firstname>
//     <surname>$last</surname>
// </author>\n";
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.sscanf.php
// ========== SSCANF - END

// SYNTAX:
// array|int|null sscanf(string $string, string $format, mixed& $vars)

return $return_sscanf; // array|int|null
}
// ============================== END
//    PHP_TEXT_STRINGS_SSCANF    
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STR_CONTAINS 
// ============================== OFFLINE
// ============================== ABOUT
// Determine if a string contains a given substring.
// ============================== SUPPORT
// PHP_8
// ============================== USING FUNCTIONS (1)
// str_contains() - PHP_8
// ============================== CODE
/*
function php_text_strings_str_contains($haystack, $needle)
{
$return_str_contains = false;

// ========== STR_CONTAINS - BEGIN
// ===== ABOUT
// Determine if a string contains a given substring
// ===== DESCRIPTION
// Performs a case-sensitive check indicating if needle is contained in haystack.
// ===== SUPPORTED
// PHP_8
// ===== SYNTAX
// str_contains(string $haystack, string $needle): bool
// ===== CODE
$return_str_contains = str_contains(

$haystack, // string haystack - The string to search in.

$needle // string needle - The substring to search for in the haystack.

); // Return Values
// Returns true if needle is in haystack, false otherwise.
// 
// [examples]
// Examples
// [example]
// Example #1 Using the empty string ''
// [php]
// if (str_contains('abc', '')) {
//     echo "Checking the existence of the empty string will always return true";
// }
// [/php]
// The above example will output:
// [result]
// Checking the existence of the empty string will always return true
// [/result]
// [/example]
// [example]
// Example #2 Showing case-sensitivity
// [php]
// $string = 'The lazy fox jumped over the fence';
// 
// if (str_contains($string, 'lazy')) {
//     echo "The string 'lazy' was found in the string\n";
// }
// 
// if (str_contains($string, 'Lazy')) {
//     echo 'The string "Lazy" was found in the string';
// } else {
//     echo '"Lazy" was not found because the case does not match';
// }
// 
// [/php]
// The above example will output:
// [result]
// The string 'lazy' was found in the string
// "Lazy" was not found because the case does not match
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.str-contains.php
// ========== STR_CONTAINS - END

// SYNTAX:
// bool str_contains(string $haystack, string $needle)

return $return_str_contains; // bool
}
*/
// ============================== END
// PHP_TEXT_STRINGS_STR_CONTAINS 
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STR_ENDS_WITH
// ============================== OFFLINE
// ============================== ABOUT
// Checks if a string ends with a given substring.
// ============================== SUPPORT
// PHP_8
// ============================== USING FUNCTIONS (1)
// str_ends_with() - PHP_8
// ============================== CODE
/*
function php_text_strings_str_ends_with($haystack, $needle)
{
$return_str_ends_with = false;

// ========== STR_ENDS_WITH - BEGIN
// ===== ABOUT
// Checks if a string ends with a given substring
// ===== DESCRIPTION
// Performs a case-sensitive check indicating if haystack ends with needle.
// ===== SUPPORTED
// PHP_8
// ===== SYNTAX
// str_ends_with(string $haystack, string $needle): bool
// ===== CODE
$return_str_ends_with = str_ends_with(

$haystack, // string haystack - The string to search in.

$needle // string needle - The substring to search for in the haystack.

); // Return Values
// Returns true if haystack ends with needle, false otherwise.
// 
// [examples]
// Examples
// [example]
// Example #1 Using the empty string ''
// [php]
// if (str_ends_with('abc', '')) {
//     echo "All strings end with the empty string";
// }
// [/php]
// The above example will output:
// [result]
// All strings end with the empty string
// [/result]
// [/example]
// [example]
// Example #2 Showing case-sensitivity
// [php]
// $string = 'The lazy fox jumped over the fence';
// 
// if (str_ends_with($string, 'fence')) {
//     echo "The string ends with 'fence'\n";
// }
// 
// if (str_ends_with($string, 'Fence')) {
//     echo 'The string ends with "Fence"';
// } else {
//     echo '"Fence" was not found because the case does not match';
// }
// 
// [/php]
// The above example will output:
// [result]
// The string ends with 'fence'
// "Fence" was not found because the case does not match
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.str-ends-with.php
// ========== STR_ENDS_WITH - END

// SYNTAX:
// bool str_ends_with(string $haystack, string $needle)

return $return_str_ends_with; // bool
}
*/
// ============================== END
// PHP_TEXT_STRINGS_STR_ENDS_WITH
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STR_GETCSV  
// ============================== OFFLINE
// ============================== ABOUT
// Parse a CSV string into an array.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_getcsv() - PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_str_getcsv($string, $separator = ",", $enclosure = "\"", $escape = "\\")
{
$return_str_getcsv = null;

// ========== STR_GETCSV - BEGIN
// ===== ABOUT
// Parse a CSV string into an array
// ===== DESCRIPTION
// Parses a string input for fields in CSV format and returns an array containing the fields read.
// Note: The locale settings are taken into account by this function. If LC_CTYPE is e.g. en_US.UTF-8, strings in one-byte encodings may be read wrongly by this function.
// ===== SUPPORTED
// PHP_5 >= PHP_5_3_0, PHP_7, PHP_8
// ===== SYNTAX
// str_getcsv(
//    string $string,
//    string $separator = ",",
//    string $enclosure = "\"",
//    string $escape = "\\"
// ): array
// ===== CODE
$return_str_getcsv = str_getcsv(

$string, // string string - The string to parse.

$separator, // string separator - Set the field delimiter (one single-byte character only).

$enclosure, // string enclosure - Set the field enclosure character (one single-byte character only).

$escape // string escape - Set the escape character (at most one single-byte character). Defaults as a backslash (\) An empty string ("") disables the proprietary escape mechanism.
// Note: Usually an enclosure character is escaped inside a field by doubling it; however, the escape character can be used as an alternative. So for the default parameter values "" and \" have the same meaning. Other than allowing to escape the enclosure character the escape character has no special meaning; it isn't even meant to escape itself.

); // Return Values
// Returns an indexed array containing the fields read.
// 
// Changelog
// Version - Description
// 7.4.0   - The escape parameter now interprets an empty string as signal to disable the proprietary escape mechanism. Formerly, an empty string was treated like the default parameter value.
// 
// [examples]
// Examples
// [example]
// Example #1 str_getcsv() example
// [php]
// 
// $string = 'PHP,Java,Python,Kotlin,Swift';
// $data = str_getcsv($string);
// 
// var_dump($data);
// [/php]
// The above example will output:
// [result]
// array(5) {
//   [0]=>
//   string(3) "PHP"
//   [1]=>
//   string(4) "Java"
//   [2]=>
//   string(6) "Python"
//   [3]=>
//   string(6) "Kotlin"
//   [4]=>
//   string(5) "Swift"
// }
// [/result]
// [/example]
// [example]
// Example #2 str_getcsv() example with an empty string
// Caution: On an empty string this function returns the value [null] instead of an empty array.
// [php]
// 
// $string = '';
// $data = str_getcsv($string);
// 
// var_dump($data);
// [/php]
// The above example will output:
// [result]
// array(1) {
//   [0]=>
//   NULL
// }
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.str-getcsv.php
// ========== STR_GETCSV - END

// SYNTAX:
// array str_getcsv(string $string, string $separator = ",", string $enclosure = "\"", string $escape = "\\")

return $return_str_getcsv; // array
}
*/
// ============================== END
//  PHP_TEXT_STRINGS_STR_GETCSV  
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STR_IREPLACE 
// ============================== OFFLINE
// ============================== ABOUT
// Case-insensitive version of str_replace().
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_ireplace() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_str_ireplace($search, $replace, $subject, & $count)
{
$return_str_ireplace = null;

// ========== STR_IREPLACE - BEGIN
// ===== ABOUT
// Case-insensitive version of str_replace()
// ===== DESCRIPTION
// This function returns a string or an array with all occurrences of search in subject (ignoring case) replaced with the given replace value.
// To replace text based on a pattern rather than a fixed string, use preg_replace() with the i pattern modifier.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_ireplace(
//    array|string $search,
//    array|string $replace,
//    string|array $subject,
//    int &$count = null
// ): string|array
// ===== CODE
$return_str_ireplace = str_ireplace(

// If search and replace are arrays, then str_ireplace() takes a value from each array and uses them to search and replace on subject. If replace has fewer values than search, then an empty string is used for the rest of replacement values. If search is an array and replace is a string, then this replacement string is used for every value of search. The converse would not make sense, though.
// If search or replace are arrays, their elements are processed first to last.

$search, // array|string search - The value being searched for, otherwise known as the needle. An array may be used to designate multiple needles.

$replace, // array|string replace - The replacement value that replaces found search values. An array may be used to designate multiple replacements.

$subject, // string|array subject - The string or array being searched and replaced on, otherwise known as the haystack.
// If subject is an array, then the search and replace is performed with every entry of subject, and the return value is an array as well.

$count // int& count - If passed, this will be set to the number of replacements performed.

); // Return Values
// Returns a string or an array of replacements.
// 
// Changelog
// Version - Description
// 8.2.0   - Case folding no longer depends on the locale set with setlocale(). Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
// 
// [examples]
// Examples
// [example]
// Example #1 str_ireplace() example
// [php]
// $bodytag = str_ireplace("%body%", "black", "<body text=%BODY%>");
// echo $bodytag; // <body text=black>
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
//  Caution:
//  Replacement order gotcha
//  Because str_ireplace() replaces left to right, it might replace a previously inserted value when doing multiple replacements. Example #2 in the str_replace() documentation demonstrates how this may affect you in practice.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-21)
// URL: https://www.php.net/manual/en/function.str-ireplace.php
// ========== STR_IREPLACE - END

// SYNTAX:
// string|array str_ireplace(array|string $search, array|string $replace, string|array $subject, int& $count)

return $return_str_ireplace; // string|array
}
*/
// ============================== END
// PHP_TEXT_STRINGS_STR_IREPLACE 
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STR_PAD    
// ============================== PUBLIC
// ============================== ABOUT
// Pad a string to a certain length with another string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_pad() - PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ============================== USING CONSTANTS (1)
// STR_PAD_RIGHT - str_pad()
// ============================== CODE
function php_text_strings_str_pad($string, $length, $pad_string = " ", $pad_type = STR_PAD_RIGHT)
{
$return_str_pad = null;

// ========== STR_PAD - BEGIN
// ===== ABOUT
// Pad a string to a certain length with another string
// ===== DESCRIPTION
// This function returns the string string padded on the left, the right, or both sides to the specified padding length. If the optional argument pad_string is not supplied, the string is padded with spaces, otherwise it is padded with characters from pad_string up to the limit.
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_1, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_pad(
//    string $string,
//    int $length,
//    string $pad_string = " ",
//    int $pad_type = STR_PAD_RIGHT
// ): string
// ===== CODE
$return_str_pad = str_pad(

$string, // string string - The input string.

$length, // int length - The desired length of the final padded string. If the value of length is negative, less than, or equal to the length of the input string, no padding takes place, and string will be returned.

$pad_string, // string pad_string - 
// Note: The pad_string may be truncated if the required number of padding characters can't be evenly divided by the pad_string's length.

$pad_type // int pad_type - Optional argument pad_type can be STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If pad_type is not specified it is assumed to be STR_PAD_RIGHT.

); // Return Values
// Returns the padded string.
// 
// [examples]
// Examples
// [example]
// Example #1 str_pad() example
// [php]
// $input = "Alien";
// echo str_pad($input, 10);                      // produces "Alien     "
// echo str_pad($input, 10, "-=", STR_PAD_LEFT);  // produces "-=-=-Alien"
// echo str_pad($input, 10, "_", STR_PAD_BOTH);   // produces "__Alien___"
// echo str_pad($input,  6, "___");               // produces "Alien_"
// echo str_pad($input,  3, "*");                 // produces "Alien"
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.str-pad.php
// ========== STR_PAD - END

// SYNTAX:
// string str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT)

return $return_str_pad; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_STR_PAD    
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STR_REPEAT  
// ============================== PUBLIC
// ============================== ABOUT
// Repeat a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_repeat() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_str_repeat($string, $times)
{
$return_str_repeat = null;

// ========== STR_REPEAT - BEGIN
// ===== ABOUT
// Repeat a string
// ===== DESCRIPTION
// Returns string repeated times times.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_repeat(string $string, int $times): string
// ===== CODE
$return_str_repeat = str_repeat(

$string, // string string - The string to be repeated.

$times // int times - Number of time the string string should be repeated.
// times has to be greater than or equal to 0. If the times is set to 0, the function will return an empty string.

); // Return Values
// Returns the repeated string.
// 
// [examples]
// Examples
// [example]
// Example #1 str_repeat() example
// [php]
// echo str_repeat("-=", 10);
// [/php]
// The above example will output:
// [result]
// -=-=-=-=-=-=-=-=-=-=
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.str-repeat.php
// ========== STR_REPEAT - END

// SYNTAX:
// string str_repeat(string $string, int $times)

return $return_str_repeat; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_STR_REPEAT  
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STR_REPLACE  
// ============================== PUBLIC
// ============================== ABOUT
// Replace all occurrences of the search string with the replacement string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_replace() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_str_replace($search, $replace, $subject, & $count)
{
$return_str_replace = null;

// ========== STR_REPLACE - BEGIN
// ===== ABOUT
// Replace all occurrences of the search string with the replacement string
// ===== DESCRIPTION
// This function returns a string or an array with all occurrences of search in subject replaced with the given replace value.
// To replace text based on a pattern rather than a fixed string, use preg_replace().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_replace(
//    array|string $search,
//    array|string $replace,
//    string|array $subject,
//    int &$count = null
// ): string|array
// ===== CODE
$return_str_replace = str_replace(

// If search and replace are arrays, then str_replace() takes a value from each array and uses them to search and replace on subject. If replace has fewer values than search, then an empty string is used for the rest of replacement values. If search is an array and replace is a string, then this replacement string is used for every value of search. The converse would not make sense, though.
// If search or replace are arrays, their elements are processed first to last.

$search, // array|string search - The value being searched for, otherwise known as the needle. An array may be used to designate multiple needles.

$replace, // array|string replace - The replacement value that replaces found search values. An array may be used to designate multiple replacements.

$subject, // string|array subject - The string or array being searched and replaced on, otherwise known as the haystack.
// If subject is an array, then the search and replace is performed with every entry of subject, and the return value is an array as well.

$count // int& count - If passed, this will be set to the number of replacements performed.

); // Return Values
// This function returns a string or an array with the replaced values.
// 
// [examples]
// Examples
// [example]
// Example #1 Basic str_replace() examples
// [php]
// // Provides: <body text='black'>
// $bodytag = str_replace("%body%", "black", "<body text='%body%'>");
// 
// // Provides: Hll Wrld f PHP
// $vowels = array("a", "e", "i", "o", "u", "A", "E", "I", "O", "U");
// $onlyconsonants = str_replace($vowels, "", "Hello World of PHP");
// 
// // Provides: You should eat pizza, beer, and ice cream every day
// $phrase  = "You should eat fruits, vegetables, and fiber every day.";
// $healthy = array("fruits", "vegetables", "fiber");
// $yummy   = array("pizza", "beer", "ice cream");
// 
// $newphrase = str_replace($healthy, $yummy, $phrase);
// 
// // Provides: 2
// $str = str_replace("ll", "", "good golly miss molly!", $count);
// echo $count;
// [/php]
// [/example]
// [example]
// Example #2 Examples of potential str_replace() gotchas
// [php]
// // Order of replacement
// $str     = "Line 1\nLine 2\rLine 3\r\nLine 4\n";
// $order   = array("\r\n", "\n", "\r");
// $replace = '<br />';
// 
// // Processes \r\n's first so they aren't converted twice.
// $newstr = str_replace($order, $replace, $str);
// 
// // Outputs F because A is replaced with B, then B is replaced with C, and so on...
// // Finally E is replaced with F, because of left to right replacements.
// $search  = array('A', 'B', 'C', 'D', 'E');
// $replace = array('B', 'C', 'D', 'E', 'F');
// $subject = 'A';
// echo str_replace($search, $replace, $subject);
// 
// // Outputs: apearpearle pear
// // For the same reason mentioned above
// $letters = array('a', 'p');
// $fruit   = array('apple', 'pear');
// $text    = 'a p';
// $output  = str_replace($letters, $fruit, $text);
// echo $output;
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
//  Caution:
//  Replacement order gotcha
//  Because str_replace() replaces left to right, it might replace a previously inserted value when doing multiple replacements. See also the examples in this document.
// Note: This function is case-sensitive. Use str_ireplace() for case-insensitive replace.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.str-replace.php
// ========== STR_REPLACE - END

// SYNTAX:
// string|array str_replace(array|string $search, array|string $replace, string|array $subject, int& $count)

return $return_str_replace; // string|array
}
// ============================== END
//  PHP_TEXT_STRINGS_STR_REPLACE  
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_STR_ROT13   
// ============================== PUBLIC
// ============================== ABOUT
// Perform the rot13 transform on a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_rot13() - PHP_4 >= PHP_4_2_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_str_rot13($string)
{
$return_str_rot13 = null;

// ========== STR_ROT13 - BEGIN
// ===== ABOUT
// Perform the rot13 transform on a string
// ===== DESCRIPTION
// Performs the ROT13 encoding on the string argument and returns the resulting string.
// The ROT13 encoding simply shifts every letter by 13 places in the alphabet while leaving non-alpha characters untouched. Encoding and decoding are done by the same function, passing an encoded string as argument will return the original version.
// ===== SUPPORTED
// PHP_4 >= PHP_4_2_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_rot13(string $string): string
// ===== CODE
$return_str_rot13 = str_rot13(

$string // string string - The input string.

); // Return Values
// Returns the ROT13 version of the given string.
// 
// [examples]
// Examples
// [example]
// Example #1 str_rot13() example
// [php]
// 
// echo str_rot13('PHP 4.3.0'); // CUC 4.3.0
// 
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.str-rot13.php
// ========== STR_ROT13 - END

// SYNTAX:
// string str_rot13(string $string)

return $return_str_rot13; // string
}
// ============================== END
//   PHP_TEXT_STRINGS_STR_ROT13   
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STR_SHUFFLE  
// ============================== PUBLIC
// ============================== ABOUT
// Randomly shuffles a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_shuffle() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_str_shuffle($string)
{
$return_str_shuffle = null;

// ========== STR_SHUFFLE - BEGIN
// ===== ABOUT
// Randomly shuffles a string
// ===== DESCRIPTION
// str_shuffle() shuffles a string. One permutation of all possible is created.
//  Caution: This function does not generate cryptographically secure values, and must not be used for cryptographic purposes, or purposes that require returned values to be unguessable.
//  If cryptographically secure randomness is required, the Random\Randomizer may be used with the Random\Engine\Secure engine. For simple use cases, the random_int() and random_bytes() functions provide a convenient and secure API that is backed by the operating system’s CSPRNG.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_shuffle(string $string): string
// ===== CODE
$return_str_shuffle = str_shuffle(

$string // string string - The input string.

); // Return Values
// Returns the shuffled string.
// 
// Changelog
// Version - Description
// 7.1.0   - The internal randomization algorithm has been changed to use the > Mersenne Twister Random Number Generator instead of the libc rand function.
// 
// [examples]
// Examples
// [example]
// Example #1 str_shuffle() example
// [php]
// $str = 'abcdef';
// $shuffled = str_shuffle($str);
// 
// // This will echo something like: bfdaec
// echo $shuffled;
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.str-shuffle.php
// ========== STR_SHUFFLE - END

// SYNTAX:
// string str_shuffle(string $string)

return $return_str_shuffle; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_STR_SHUFFLE  
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_STR_SPLIT   
// ============================== OFFLINE
// ============================== ABOUT
// Convert a string to an array.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_split() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_str_split(string $string, int $length = 1)
{
$return_str_split = null;

// ========== STR_SPLIT - BEGIN
// ===== ABOUT
// Convert a string to an array
// ===== DESCRIPTION
// Converts a string to an array.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_split(string $string, int $length = 1): array
// ===== CODE
$return_str_split = str_split(

$string, // string string - The input string.

$length // int length - Maximum length of the chunk.

); // Return Values
// If the optional length parameter is specified, the returned array will be broken down into chunks with each being length in length, except the final chunk which may be shorter if the string does not divide evenly. The default length is 1, meaning every chunk will be one byte in size.
// 
// Errors/Exceptions
// If length is less than 1, a ValueError will be thrown.
// 
// Changelog
// Version - Description
// 8.2.0   - If string is empty an empty array is now returned. Previously an array containing a single empty string was returned.
// 8.0.0   - If length is less than 1, a ValueError will be thrown now; previously, an error of level E_WARNING has been raised instead, and the function returned false.
// 
// [examples]
// Examples
// [example]
// Example #1 Example uses of str_split()
// [php]
// 
// $str = "Hello Friend";
// 
// $arr1 = str_split($str);
// $arr2 = str_split($str, 3);
// 
// print_r($arr1);
// print_r($arr2);
// 
// [/php]
// The above example will output:
// [result]
// Array
// (
//     [0] => H
//     [1] => e
//     [2] => l
//     [3] => l
//     [4] => o
//     [5] =>
//     [6] => F
//     [7] => r
//     [8] => i
//     [9] => e
//     [10] => n
//     [11] => d
// )
// 
// Array
// (
//     [0] => Hel
//     [1] => lo
//     [2] => Fri
//     [3] => end
// )
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: str_split() will split into bytes, rather than characters when dealing with a multi-byte encoded string. Use mb_str_split() to split the string into code points.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.str-split.php
// ========== STR_SPLIT - END

// SYNTAX:
// array str_split(string $string, int $length = 1)

return $return_str_split; // array
}
*/
// ============================== END
//   PHP_TEXT_STRINGS_STR_SPLIT   
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STR_STARTS_WITH
// ============================== OFFLINE
// ============================== ABOUT
// Checks if a string starts with a given substring.
// ============================== SUPPORT
// PHP_8
// ============================== USING FUNCTIONS (1)
// str_starts_with() - PHP_8
// ============================== CODE
/*
function php_text_strings_str_starts_with($haystack, $needle)
{
$return_str_starts_with = false;

// ========== STR_STARTS_WITH - BEGIN
// ===== ABOUT
// Checks if a string starts with a given substring
// ===== DESCRIPTION
// Performs a case-sensitive check indicating if haystack begins with needle.
// ===== SUPPORTED
// PHP_8
// ===== SYNTAX
// str_starts_with(string $haystack, string $needle): bool
// ===== CODE
$return_str_starts_with = str_starts_with(

$haystack, // string haystack - The string to search in.

$needle // string needle - The substring to search for in the haystack.

); // Return Values
// Returns true if haystack begins with needle, false otherwise.
// 
// [examples]
// Examples
// [example]
// Example #1 Using the empty string ''
// [php]
// if (str_starts_with('abc', '')) {
//     echo "All strings start with the empty string";
// }
// [/php]
// The above example will output:
// [result]
// All strings start with the empty string
// [/result]
// [/example]
// [example]
// Example #2 Showing case-sensitivity
// [php]
// $string = 'The lazy fox jumped over the fence';
// 
// if (str_starts_with($string, 'The')) {
//     echo "The string starts with 'The'\n";
// }
// 
// if (str_starts_with($string, 'the')) {
//     echo 'The string starts with "the"';
// } else {
//     echo '"the" was not found because the case does not match';
// }
// 
// [/php]
// The above example will output:
// [result]
// The string starts with 'The'
// "the" was not found because the case does not match
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.str-starts-with.php
// ========== STR_STARTS_WITH - END

// SYNTAX:
// bool str_starts_with(string $haystack, string $needle)

return $return_str_starts_with; // bool
}
*/
// ============================== END
// PHP_TEXT_STRINGS_STR_STARTS_WITH
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STR_WORD_COUNT
// ============================== PUBLIC
// ============================== ABOUT
// Return information about words used in a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// str_word_count() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_str_word_count($string, $format = 0, $characters = null)
{
$return_str_word_count = 0;

// ========== STR_WORD_COUNT - BEGIN
// ===== ABOUT
// Return information about words used in a string
// ===== DESCRIPTION
// Counts the number of words inside string. If the optional format is not specified, then the return value will be an integer representing the number of words found. In the event the format is specified, the return value will be an array, content of which is dependent on the format. The possible value for the format and the resultant outputs are listed below.
// For the purpose of this function, 'word' is defined as a locale dependent string containing alphabetic characters, which also may contain, but not start with "'" and "-" characters. Note that multibyte locales are not supported.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// str_word_count(string $string, int $format = 0, ?string $characters = null): array|int
// ===== CODE
$return_str_word_count = str_word_count(

$string, // string string - The string

$format, // int format - Specify the return value of this function. The current supported values are:
// * 0 - returns the number of words found
// * 1 - returns an array containing all the words found inside the string
// * 2 - returns an associative array, where the key is the numeric position of the word inside the string and the value is the actual word itself

$characters // string characters - A list of additional characters which will be considered as 'word'

); // Return Values
// Returns an array or an integer, depending on the format chosen.
// 
// Changelog
// Version - Description
// 8.0.0   - characters is nullable now.
// 
// [examples]
// Examples
// [example]
// Example #1 A str_word_count() example
// [php]
// 
// $str = "Hello fri3nd, you're
//        looking          good today!";
// 
// print_r(str_word_count($str, 1));
// print_r(str_word_count($str, 2));
// print_r(str_word_count($str, 1, 'àáãç3'));
// 
// echo str_word_count($str);
// 
// [/php]
// The above example will output:
// [result]
// Array
// (
//     [0] => Hello
//     [1] => fri
//     [2] => nd
//     [3] => you're
//     [4] => looking
//     [5] => good
//     [6] => today
// )
// 
// Array
// (
//     [0] => Hello
//     [6] => fri
//     [10] => nd
//     [14] => you're
//     [29] => looking
//     [46] => good
//     [51] => today
// )
// 
// Array
// (
//     [0] => Hello
//     [1] => fri3nd
//     [2] => you're
//     [3] => looking
//     [4] => good
//     [5] => today
// )
// 
// 7
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.str-word-count.php
// ========== STR_WORD_COUNT - END

// SYNTAX:
// array|int str_word_count(string $string, int $format = 0, string $characters = null)

return $return_str_word_count; // array|int
}
// ============================== END
// PHP_TEXT_STRINGS_STR_WORD_COUNT
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STRCASECMP  
// ============================== PUBLIC
// ============================== ABOUT
// Binary safe case-insensitive string comparison.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strcasecmp() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strcasecmp($string1, $string2)
{
$return_strcasecmp = 0;

// ========== STRCASECMP - BEGIN
// ===== ABOUT
// Binary safe case-insensitive string comparison
// ===== DESCRIPTION
// Binary safe case-insensitive string comparison. The comparison is not locale aware; only ASCII letters are compared in a case-insensitive way.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strcasecmp(string $string1, string $string2): int
// ===== CODE
$return_strcasecmp = strcasecmp(

$string1, // string string1 - The first string

$string2 // string string2 - The second string

); // Return Values
// Returns -1 if string1 is less than string2; 1 if string1 is greater than string2, and 0 if they are equal.
// 
// Changelog
// Version - Description
// 8.2.0   - This function now returns -1 or 1, where it previously returned a negative or positive number.
// 
// [examples]
// Examples
// [example]
// Example #1 strcasecmp() example
// [php]
// $var1 = "Hello";
// $var2 = "hello";
// if (strcasecmp($var1, $var2) == 0) {
//     echo '$var1 is equal to $var2 in a case-insensitive string comparison';
// }
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strcasecmp.php
// ========== STRCASECMP - END

// SYNTAX:
// int strcasecmp(string $string1, string $string2)

return $return_strcasecmp; // int
}
// ============================== END
//  PHP_TEXT_STRINGS_STRCASECMP  
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRCHR    
// ============================== PUBLIC
// ============================== ABOUT
// Find the first occurrence of a string.
// 
// strchr - Alias of strstr().
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strchr() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strchr($haystack, $needle, $before_needle = false)
{
$return_strchr = false;

// ========== STRCHR - BEGIN
// ===== ABOUT
// strchr - Alias of strstr()
// ===== DESCRIPTION
// This function is an alias of: strstr().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// ===== CODE
$return_strchr = strchr(

$haystack, // string $haystack

$needle, // string $needle

$before_needle // bool $before_needle

); // Return
// string|false
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.strchr.php
// ========== STRCHR - END

// ========== STRSTR - BEGIN
// ===== ABOUT
// Find the first occurrence of a string
// ===== DESCRIPTION
// Returns part of haystack string starting from and including the first occurrence of needle to the end of haystack.
// Note: This function is case-sensitive. For case-insensitive searches, use stristr().
// Note: If you only want to determine if a particular needle occurs within haystack, use the faster and less memory intensive function strpos() instead.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strstr(string $haystack, string $needle, bool $before_needle = false): string|false
// ===== CODE
// $return_strstr = strstr(

// $haystack, // string haystack - The input string.

// $needle, // string needle - The string to search for.
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

// $before_needle // bool before_needle - If true, strstr() returns the part of the haystack before the first occurrence of the needle (excluding the needle).

// ); // Return Values
// Returns the portion of string, or false if needle is not found.
// 
// Changelog
// Version - Description
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 strstr() example
// [php]
// $email  = 'name@example.com';
// $domain = strstr($email, '@');
// echo $domain; // prints @example.com
// 
// $user = strstr($email, '@', true);
// echo $user; // prints name
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.strstr.php
// ========== STRSTR - END

// SYNTAX:
// string|false strchr(string $haystack, string $needle, bool $before_needle = false)

return $return_strchr; // string|false
}
// ============================== END
//    PHP_TEXT_STRINGS_STRCHR    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRCMP    
// ============================== PUBLIC
// ============================== ABOUT
// Binary safe string comparison.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strcmp() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strcmp($string1, $string2)
{
$return_strcmp = 0;

// ========== STRCMP - BEGIN
// ===== ABOUT
// Binary safe string comparison
// ===== DESCRIPTION
// Note that this comparison is case sensitive.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strcmp(string $string1, string $string2): int
// ===== CODE
$return_strcmp = strcmp(

$string1, // string string1 - The first string.

$string2 // string string2 - The second string.

); // Return Values
// Returns -1 if string1 is less than string2; 1 if string1 is greater than string2, and 0 if they are equal.
// 
// Changelog
// Version - Description
// 8.2.0   - This function now returns -1 or 1, where it previously returned a negative or positive number.
// 
// [examples]
// Examples
// [example]
// Example #1 strcmp() example
// [php]
// $var1 = "Hello";
// $var2 = "hello";
// if (strcmp($var1, $var2) !== 0) {
//     echo '$var1 is not equal to $var2 in a case sensitive string comparison';
// }
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strcmp.php
// ========== STRCMP - END

// SYNTAX:
// int strcmp(string $string1, string $string2)

return $return_strcmp; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_STRCMP    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRCOLL    
// ============================== PUBLIC
// ============================== ABOUT
// Locale based string comparison.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strcoll() - PHP_4 >= PHP_4_0_5, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strcoll($string1, $string2)
{
$return_strcoll = 0;

// ========== STRCOLL - BEGIN
// ===== ABOUT
// Locale based string comparison
// ===== DESCRIPTION
// Note that this comparison is case sensitive, and unlike strcmp() this function is not binary safe.
// strcoll() uses the current locale for doing the comparisons. If the current locale is C or POSIX, this function is equivalent to strcmp().
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_5, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strcoll(string $string1, string $string2): int
// ===== CODE
$return_strcoll = strcoll(

$string1, // string string1 - The first string.

$string2 // string string2 - The second string.

); // Return Values
// Returns < 0 if string1 is less than string2; > 0 if string1 is greater than string2, and 0 if they are equal.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-21)
// URL: https://www.php.net/manual/en/function.strcoll.php
// ========== STRCOLL - END

// SYNTAX:
// int strcoll(string $string1, string $string2)

return $return_strcoll; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_STRCOLL    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRCSPN    
// ============================== PUBLIC
// ============================== ABOUT
// Find length of initial segment not matching mask.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strcspn() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strcspn($string, $characters, $offset = 0, $length = null)
{
$return_strcspn = 0;

// ========== STRCSPN - BEGIN
// ===== ABOUT
// Find length of initial segment not matching mask
// ===== DESCRIPTION
// Returns the length of the initial segment of string which does not contain any of the characters in characters.
// If offset and length are omitted, then all of string will be examined. If they are included, then the effect will be the same as calling strcspn(substr($string, $offset, $length), $characters) (see substr for more information).
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strcspn(
//    string $string,
//    string $characters,
//    int $offset = 0,
//    ?int $length = null
// ): int
// ===== CODE
$return_strcspn = strcspn(

$string, // string string - The string to examine.

$characters, // string characters - The string containing every disallowed character.

$offset, // int offset - The position in string to start searching.
// If offset is given and is non-negative, then strcspn() will begin examining string at the offset'th position. For instance, in the string 'abcdef', the character at position 0 is 'a', the character at position 2 is 'c', and so forth.
// If offset is given and is negative, then strcspn() will begin examining string at the offset'th position from the end of string.

$length // int length - The length of the segment from string to examine.
// If length is given and is non-negative, then string will be examined for length characters after the starting position.
// If length is given and is negative, then string will be examined from the starting position up to length characters from the end of string.

); // Return Values
// Returns the length of the initial segment of string which consists entirely of characters not in characters.
// Note: When a offset parameter is set, the returned length is counted starting from this position, not from the beginning of string.
// 
// Changelog
// Version - Description
// 8.0.0   - length is nullable now.
// 
// [examples]
// Examples
// [example]
// Example #1 strcspn() example
// [php]
// $a = strcspn('abcd',  'apple');
// $b = strcspn('abcd',  'banana');
// $c = strcspn('hello', 'l');
// $d = strcspn('hello', 'world');
// $e = strcspn('abcdhelloabcd', 'abcd', -9);
// $f = strcspn('abcdhelloabcd', 'abcd', -9, -5);
// 
// var_dump($a);
// var_dump($b);
// var_dump($c);
// var_dump($d);
// var_dump($e);
// var_dump($f);
// [/php]
// The above example will output:
// [result]
// int(0)
// int(0)
// int(2)
// int(2)
// int(5)
// int(4)
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strcspn.php
// ========== STRCSPN - END

// SYNTAX:
// int strcspn(string $string, string $characters, int $offset = 0, int $length = null)

return $return_strcspn; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_STRCSPN    
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STRIP_TAGS  
// ============================== PUBLIC
// ============================== ABOUT
// Strip HTML and PHP tags from a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strip_tags() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strip_tags($string, $allowed_tags = null)
{
$return_strip_tags = null;

// ========== STRIP_TAGS - BEGIN
// ===== ABOUT
// Strip HTML and PHP tags from a string
// ===== DESCRIPTION
// This function tries to return a string with all NULL bytes, HTML and PHP tags stripped from a given string. It uses the same tag stripping state machine as the fgetss() function.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strip_tags(string $string, array|string|null $allowed_tags = null): string
// ===== CODE
$return_strip_tags = strip_tags(

$string, // string string - The input string.

$allowed_tags // array|string|null allowed_tags - You can use the optional second parameter to specify tags which should not be stripped. These are either given as string, or as of PHP 7.4.0, as array. Refer to the example below regarding the format of this parameter.
// Note: HTML comments and PHP tags are also stripped. This is hardcoded and can not be changed with allowed_tags.
//  Note:
//  Self-closing XHTML tags are ignored and only non-self-closing tags should be used in allowed_tags. For example, to allow both <br> and <br/>, you should use:
//  [example]
//  [php]
//  strip_tags($input, '<br>');
//  [/php]
//  [/example]

); // Return Values
// Returns the stripped string.
// 
// Changelog
// Version - Description
// 8.0.0   - allowed_tags is nullable now.
// 7.4.0   - The allowed_tags now alternatively accepts an array.
// 
// [examples]
// Examples
// [example]
// Example #1 strip_tags() example
// [php]
// $text = '<p>Test paragraph.</p><!-- Comment --> <a href="#fragment">Other text</a>';
// echo strip_tags($text);
// echo "\n";
// 
// // Allow <p> and <a>
// echo strip_tags($text, '<p><a>');
// 
// // as of PHP 7.4.0 the line above can be written as:
// // echo strip_tags($text, ['p', 'a']);
// [/php]
// The above example will output:
// [result]
// Test paragraph. Other text
// <p>Test paragraph.</p> <a href="#fragment">Other text</a>
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Warning: This function should not be used to try to prevent XSS attacks. Use more appropriate functions like htmlspecialchars() or other means depending on the context of the output.
// Warning: Because strip_tags() does not actually validate the HTML, partial or broken tags can result in the removal of more text/data than expected.
// Warning: This function does not modify any attributes on the tags that you allow using allowed_tags, including the style and onmouseover attributes that a mischievous user may abuse when posting text that will be shown to other users.
// Note: Tag names within the input HTML that are greater than 1023 bytes in length will be treated as though they are invalid, regardless of the allowed_tags parameter.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-21)
// URL: https://www.php.net/manual/en/function.strip-tags.php
// ========== STRIP_TAGS - END

// SYNTAX:
// string strip_tags(string $string, array|string|null $allowed_tags = null)

return $return_strip_tags; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_STRIP_TAGS  
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STRIPCSLASHES
// ============================== PUBLIC
// ============================== ABOUT
// Un-quote string quoted with addcslashes().
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// stripcslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_stripcslashes($string)
{
$return_stripcslashes = null;

// ========== STRIPCSLASHES - BEGIN
// ===== ABOUT
// Un-quote string quoted with addcslashes()
// ===== DESCRIPTION
// Returns a string with backslashes stripped off. Recognizes C-like \n, \r ..., octal and hexadecimal representation.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// stripcslashes(string $string): string
// ===== CODE
$return_stripcslashes = stripcslashes(

$string // string string - The string to be unescaped.

); // Return Values
// Returns the unescaped string.
// 
// [examples]
// Examples
// [example]
// Example #1 stripcslashes() example
// [php]
// 
// var_dump(stripcslashes('I\'d have a coffee.\nNot a problem.') === "I'd have a coffee.
// Not a problem."); // true
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.stripcslashes.php
// ========== STRIPCSLASHES - END

// SYNTAX:
// string stripcslashes(string $string)

return $return_stripcslashes; // string
}
// ============================== END
// PHP_TEXT_STRINGS_STRIPCSLASHES
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRIPOS    
// ============================== OFFLINE
// ============================== ABOUT
// Find the position of the first occurrence of a case-insensitive substring in a string.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// stripos() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_stripos($haystack, $needle, $offset = 0)
{
$return_stripos = false;

// ========== STRIPOS - BEGIN
// ===== ABOUT
// Find the position of the first occurrence of a case-insensitive substring in a string
// ===== DESCRIPTION
// Find the numeric position of the first occurrence of needle in the haystack string.
// Unlike the strpos(), stripos() is case-insensitive.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// stripos(string $haystack, string $needle, int $offset = 0): int|false
// ===== CODE
$return_stripos = stripos(

$haystack, // string haystack - The string to search in.

$needle, // string needle - The string to search for.
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

$offset // int offset - If specified, search will start this number of characters counted from the beginning of the string. If the offset is negative, the search will start this number of characters counted from the end of the string.

); // Return Values
// Returns the position of where the needle exists relative to the beginning of the haystack string (independent of offset). Also note that string positions start at 0, and not 1.
// Returns false if the needle was not found.
// Warning: This function may return Boolean false, but may also return a non-Boolean value which evaluates to false. Please read the section on Booleans for more information. Use the === operator for testing the return value of this function.
// 
// Changelog
// Version - Description
// 8.2.0   - Case folding no longer depends on the locale set with setlocale(). Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 7.1.0   - Support for negative offsets has been added.
// 
// [examples]
// Examples
// [example]
// Example #1 stripos() examples
// [php]
// $findme    = 'a';
// $mystring1 = 'xyz';
// $mystring2 = 'ABC';
// 
// $pos1 = stripos($mystring1, $findme);
// $pos2 = stripos($mystring2, $findme);
// 
// // Nope, 'a' is certainly not in 'xyz'
// if ($pos1 === false) {
//     echo "The string '$findme' was not found in the string '$mystring1'";
// }
// 
// // Note our use of ===.  Simply == would not work as expected
// // because the position of 'a' is the 0th (first) character.
// if ($pos2 !== false) {
//     echo "We found '$findme' in '$mystring2' at position $pos2";
// }
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.stripos.php
// ========== STRIPOS - END

// SYNTAX:
// int|false stripos(string $haystack, string $needle, int $offset = 0)

return $return_stripos; // int|false
}
*/
// ============================== END
//    PHP_TEXT_STRINGS_STRIPOS    
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STRIPSLASHES 
// ============================== PUBLIC
// ============================== ABOUT
// Un-quotes a quoted string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// stripslashes() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_stripslashes($string)
{
$return_stripslashes = null;

// ========== STRIPSLASHES - BEGIN
// ===== ABOUT
// Un-quotes a quoted string
// ===== DESCRIPTION
// Un-quotes a quoted string.
// stripslashes() can be used if you aren't inserting this data into a place (such as a database) that requires escaping. For example, if you're simply outputting data straight from an HTML form.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// stripslashes(string $string): string
// ===== CODE
$return_stripslashes = stripslashes(

$string // string string - The input string.

); // Return Values
// Returns a string with backslashes stripped off. (\' becomes ' and so on.) Double backslashes (\\) are made into a single backslash (\).
// 
// [examples]
// Examples
// [example]
// Example #1 A stripslashes() example
// [php]
// $str = "Is your name O\'reilly?";
// 
// // Outputs: Is your name O'reilly?
// echo stripslashes($str);
// [/php]
// Note: stripslashes() is not recursive. If you want to apply this function to a multi-dimensional array, you need to use a recursive function.
// [/example]
// [example]
// Example #2 Using stripslashes() on an array
// [php]
// function stripslashes_deep($value)
// {
//     $value = is_array($value) ?
//                 array_map('stripslashes_deep', $value) :
//                 stripslashes($value);
// 
//     return $value;
// }
// 
// // Example
// $array = array("f\\'oo", "b\\'ar", array("fo\\'o", "b\\'ar"));
// $array = stripslashes_deep($array);
// 
// // Output
// print_r($array);
// [/php]
// The above example will output:
// [result]
// Array
// (
//     [0] => f'oo
//     [1] => b'ar
//     [2] => Array
//         (
//             [0] => fo'o
//             [1] => b'ar
//         )
// 
// )
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-15)
// URL: https://www.php.net/manual/en/function.stripslashes.php
// ========== STRIPSLASHES - END

// SYNTAX:
// string stripslashes(string $string)

return $return_stripslashes; // string
}
// ============================== END
// PHP_TEXT_STRINGS_STRIPSLASHES 
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRISTR    
// ============================== PUBLIC
// ============================== ABOUT
// Case-insensitive strstr().
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// stristr() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_stristr($haystack, $needle, $before_needle = false)
{
$return_stristr = false;

// ========== STRISTR - BEGIN
// ===== ABOUT
// Case-insensitive strstr()
// ===== DESCRIPTION
// Returns all of haystack starting from and including the first occurrence of needle to the end.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// stristr(string $haystack, string $needle, bool $before_needle = false): string|false
// ===== CODE
$return_stristr = stristr(

$haystack, // string haystack - The string to search in

$needle, // string needle - The string to search for.
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

$before_needle // bool before_needle - If true, stristr() returns the part of the haystack before the first occurrence of the needle (excluding needle).

// needle and haystack are examined in a case-insensitive manner.

); // Return Values
// Returns the matched substring. If needle is not found, returns false.
// 
// Changelog
// Version - Description
// 8.2.0   - Case folding no longer depends on the locale set with setlocale(). Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 stristr() example
// [php]
//   $email = 'USER@EXAMPLE.com';
//   echo stristr($email, 'e'); // outputs ER@EXAMPLE.com
//   echo stristr($email, 'e', true); // outputs US
// [/php]
// [/example]
// [example]
// Example #2 Testing if a string is found or not
// [php]
//   $string = 'Hello World!';
//   if(stristr($string, 'earth') === FALSE) {
//     echo '"earth" not found in string';
//   }
// // outputs: "earth" not found in string
// [/php]
// [/example]
// [example]
// Example #3 Using a non "string" needle
// [php]
//   $string = 'APPLE';
//   echo stristr($string, 97); // 97 = lowercase a
// // outputs: APPLE
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.stristr.php
// ========== STRISTR - END

// SYNTAX:
// string|false stristr(string $haystack, string $needle, bool $before_needle = false)

return $return_stristr; // string|false
}
// ============================== END
//    PHP_TEXT_STRINGS_STRISTR    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRLEN    
// ============================== PUBLIC
// ============================== ABOUT
// Get string length.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strlen() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strlen($string)
{
$return_text_length = 0;

// ========== STRLEN - BEGIN
// ===== ABOUT
// Get string length
// ===== DESCRIPTION
// Returns the length of the given string.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strlen(string $string): int
// ===== CODE
$return_text_length = strlen(

$string // string string - The string being measured for length.

); // Return Values
// The length of the string in bytes.
// 
// [examples]
// Examples
// [example]
// Example #1 A strlen() example
// [php]
// $str = 'abcdef';
// echo strlen($str); // 6
// 
// $str = ' ab cd ';
// echo strlen($str); // 7
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: strlen() returns the number of bytes rather than the number of characters in a string.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strlen.php
// ========== STRLEN - END

// SYNTAX:
// int strlen(string $string)

return $return_text_length; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_STRLEN    
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_STRNATCASECMP
// ============================== PUBLIC
// ============================== ABOUT
// Case insensitive string comparisons using a "natural order" algorithm.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strnatcasecmp() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strnatcasecmp($string1, $string2)
{
$return_strnatcasecmp = 0;

// ========== STRNATCASECMP - BEGIN
// ===== ABOUT
// Case insensitive string comparisons using a "natural order" algorithm
// ===== DESCRIPTION
// This function implements a comparison algorithm that orders alphanumeric strings in the way a human being would. The behaviour of this function is similar to strnatcmp(), except that the comparison is not case sensitive. For more information see: Martin Pool's > Natural Order String Comparison page.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strnatcasecmp(string $string1, string $string2): int
// ===== CODE
$return_strnatcasecmp = strnatcasecmp(

$string1, // string string1 - The first string.

$string2 // string string2 - The second string.

); // Return Values
// Similar to other string comparison functions, this one returns -1 if string1 is less than string2 1 if string1 is greater than string2, and 0 if they are equal.
// 
// Changelog
// Version - Description
// 8.2.0   - This function now returns -1 or 1, where it previously returned a negative or positive number.
// 
// [examples]
// Examples
// [example]
// Example #1 strnatcasecmp() example
// [php]
// 
// var_dump(strnatcasecmp('Apple', 'Banana'));
// var_dump(strnatcasecmp('Banana', 'Apple'));
// var_dump(strnatcasecmp('apple', 'Apple'));
// [/php]
// The above example will output:
// [result]
// int(-1)
// int(1)
// int(0)
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strnatcasecmp.php
// ========== STRNATCASECMP - END

// SYNTAX:
// int strnatcasecmp(string $string1, string $string2)

return $return_strnatcasecmp; // int
}
// ============================== END
// PHP_TEXT_STRINGS_STRNATCASECMP
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_STRNATCMP   
// ============================== PUBLIC
// ============================== ABOUT
// String comparisons using a "natural order" algorithm.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strnatcmp() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strnatcmp($string1, $string2)
{
$return_strnatcmp = 0;

// ========== STRNATCMP - BEGIN
// ===== ABOUT
// String comparisons using a "natural order" algorithm
// ===== DESCRIPTION
// This function implements a comparison algorithm that orders alphanumeric strings in the way a human being would, this is described as a "natural ordering". Note that this comparison is case sensitive.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strnatcmp(string $string1, string $string2): int
// ===== CODE
$return_strnatcmp = strnatcmp(

$string1, // string string1 - The first string.

$string2 // string string2 - The second string.

); // Return Values
// Similar to other string comparison functions, this one returns -1 if string1 is less than string2; 1 if string1 is greater than string2, and 0 if they are equal.
// 
// Changelog
// Version - Description
// 8.2.0   - This function now returns -1 or 1, where it previously returned a negative or positive number.
// 
// [examples]
// Examples
// [example]
// An example of the difference between this algorithm and the regular computer string sorting algorithms (used in strcmp()) can be seen below:
// [php]
// $arr1 = $arr2 = array("img12.png", "img10.png", "img2.png", "img1.png");
// echo "Standard string comparison\n";
// usort($arr1, "strcmp");
// print_r($arr1);
// echo "\nNatural order string comparison\n";
// usort($arr2, "strnatcmp");
// print_r($arr2);
// [/php]
// The above example will output:
// [result]
// Standard string comparison
// Array
// (
//     [0] => img1.png
//     [1] => img10.png
//     [2] => img12.png
//     [3] => img2.png
// )
// 
// Natural order string comparison
// Array
// (
//     [0] => img1.png
//     [1] => img2.png
//     [2] => img10.png
//     [3] => img12.png
// )
// [/result]
// For more information see: Martin Pool's > Natural Order String Comparison page.
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strnatcmp.php
// ========== STRNATCMP - END

// SYNTAX:
// int strnatcmp(string $string1, string $string2)

return $return_strnatcmp; // int
}
// ============================== END
//   PHP_TEXT_STRINGS_STRNATCMP   
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STRNCASECMP  
// ============================== PUBLIC
// ============================== ABOUT
// Binary safe case-insensitive string comparison of the first n characters.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strncasecmp() - PHP_4 >= PHP_4_0_2, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strncasecmp($string1, $string2, $length)
{
$return_strncasecmp = 0;

// ========== STRNCASECMP - BEGIN
// ===== ABOUT
// Binary safe case-insensitive string comparison of the first n characters
// ===== DESCRIPTION
// This function is similar to strcasecmp(), with the difference that you can specify the (upper limit of the) number of characters from each string to be used in the comparison.
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_2, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strncasecmp(string $string1, string $string2, int $length): int
// ===== CODE
$return_strncasecmp = strncasecmp(

$string1, // string string1 - The first string.

$string2, // string string2 - The second string.

$length // int length - The length of strings to be used in the comparison.

); // Return Values
// Returns -1 if string1 is less than string2; 1 if string1 is greater than string2, and 0 if they are equal.
// 
// Changelog
// Version - Description
// 8.2.0   - This function now returns -1 or 1, where it previously returned a negative or positive number.
// 
// [examples]
// Examples
// [example]
// Example #1 strncasecmp() example
// [php]
// 
// $var1 = 'Hello John';
// $var2 = 'hello Doe';
// if (strncasecmp($var1, $var2, 5) === 0) {
//     echo 'First 5 characters of $var1 and $var2 are equals in a case-insensitive string comparison';
// }
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strncasecmp.php
// ========== STRNCASECMP - END

// SYNTAX:
// int strncasecmp(string $string1, string $string2, int $length)

return $return_strncasecmp; // int
}
// ============================== END
//  PHP_TEXT_STRINGS_STRNCASECMP  
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRNCMP    
// ============================== PUBLIC
// ============================== ABOUT
// Binary safe string comparison of the first n characters.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strncmp() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strncmp($string1, $string2, $length)
{
$return_strncmp = 0;

// ========== STRNCMP - BEGIN
// ===== ABOUT
// Binary safe string comparison of the first n characters
// ===== DESCRIPTION
// This function is similar to strcmp(), with the difference that you can specify the (upper limit of the) number of characters from each string to be used in the comparison.
// Note that this comparison is case sensitive.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strncmp(string $string1, string $string2, int $length): int
// ===== CODE
$return_strncmp = strncmp(

$string1, // string string1 - The first string.

$string2, // string string2 - The second string.

$length // int length - Number of characters to use in the comparison.

); // Return Values
// Returns -1 if string1 is less than string2; 1 if string1 is greater than string2, and 0 if they are equal.
// 
// Changelog
// Version - Description
// 8.2.0   - This function now returns -1 or 1, where it previously returned a negative or positive number.
// 
// [examples]
// Examples
// [example]
// Example #1 strncmp() example
// [php]
// 
// $var1 = 'Hello John';
// $var2 = 'Hello Doe';
// if (strncmp($var1, $var2, 5) === 0) {
//     echo 'First 5 characters of $var1 and $var2 are equals in a case-sensitive string comparison';
// }
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strncmp.php
// ========== STRNCMP - END

// SYNTAX:
// int strncmp(string $string1, string $string2, int $length)

return $return_strncmp; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_STRNCMP    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRPBRK    
// ============================== OFFLINE
// ============================== ABOUT
// Search a string for any of a set of characters.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// strpbrk() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_strpbrk($string, $characters)
{
$return_strpbrk = false;

// ========== STRPBRK - BEGIN
// ===== ABOUT
// Search a string for any of a set of characters
// ===== DESCRIPTION
// strpbrk() searches the string string for a characters.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strpbrk(string $string, string $characters): string|false
// ===== CODE
$return_strpbrk = strpbrk(

$string, // string string - The string where characters is looked for.

$characters // string characters - This parameter is case sensitive.

); // Return Values
// Returns a string starting from the character found, or false if it is not found.
// 
// [examples]
// Examples
// [example]
// Example #1 strpbrk() example
// [php]
// 
// $text = 'This is a Simple text.';
// 
// // this echoes "is is a Simple text." because 'i' is matched first
// echo strpbrk($text, 'mi');
// 
// // this echoes "Simple text." because chars are case sensitive
// echo strpbrk($text, 'S');
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.strpbrk.php
// ========== STRPBRK - END

// SYNTAX:
// string|false strpbrk(string $string, string $characters)

return $return_strpbrk; // string|false
}
*/
// ============================== END
//    PHP_TEXT_STRINGS_STRPBRK    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRPOS    
// ============================== PUBLIC
// ============================== ABOUT
// Find the position of the first occurrence of a substring in a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strpos() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strpos($haystack, $needle, $offset = 0)
{
$return_strpos = false;

// ========== STRPOS - BEGIN
// ===== ABOUT
// Find the position of the first occurrence of a substring in a string
// ===== DESCRIPTION
// Find the numeric position of the first occurrence of needle in the haystack string.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strpos(string $haystack, string $needle, int $offset = 0): int|false
// ===== CODE
$return_strpos = strpos(

$haystack, // string $haystack - The string to search in.

$needle, // string $needle - The string to search for.
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

$offset // int $offset - If specified, search will start this number of characters counted from the beginning of the string. If the offset is negative, the search will start this number of characters counted from the end of the string.

); // Return Values
// Returns the position of where the needle exists relative to the beginning of the haystack string (independent of offset). Also note that string positions start at 0, and not 1.
// Returns false if the needle was not found.
// Warning: This function may return Boolean false, but may also return a non-Boolean value which evaluates to false. Please read the section on Booleans for more information. Use the === operator for testing the return value of this function.
// 
// Changelog
// Version - Description
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 7.1.0   - Support for negative offsets has been added.
// 
// [examples]
// Examples
// [example]
// Example #1 Using ===
// [php]
// $mystring = 'abc';
// $findme   = 'a';
// $pos = strpos($mystring, $findme);
// 
// // Note our use of ===.  Simply == would not work as expected
// // because the position of 'a' was the 0th (first) character.
// if ($pos === false) {
//     echo "The string '$findme' was not found in the string '$mystring'";
// } else {
//     echo "The string '$findme' was found in the string '$mystring'";
//     echo " and exists at position $pos";
// }
// [/php]
// [/example]
// [example]
// Example #2 Using !==
// [php]
// $mystring = 'abc';
// $findme   = 'a';
// $pos = strpos($mystring, $findme);
// 
// // The !== operator can also be used.  Using != would not work as expected
// // because the position of 'a' is 0. The statement (0 != false) evaluates
// // to false.
// if ($pos !== false) {
//      echo "The string '$findme' was found in the string '$mystring'";
//          echo " and exists at position $pos";
// } else {
//      echo "The string '$findme' was not found in the string '$mystring'";
// }
// [/php]
// [/example]
// [example]
// Example #3 Using an offset
// [php]
// // We can search for the character, ignoring anything before the offset
// $newstring = 'abcdef abcdef';
// $pos = strpos($newstring, 'a', 1); // $pos = 7, not 0
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strpos.php
// ========== STRPOS - END

// SYNTAX:
// int|false strpos(string $haystack, string $needle, int $offset = 0)

return $return_strpos; // int|false
}
// ============================== END
//    PHP_TEXT_STRINGS_STRPOS    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRRCHR    
// ============================== PUBLIC
// ============================== ABOUT
// Find the last occurrence of a character in a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strrchr() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strrchr($haystack, $needle, $before_needle = false)
{
$return_strrchr = false;

// ========== STRRCHR - BEGIN
// ===== ABOUT
// Find the last occurrence of a character in a string
// ===== DESCRIPTION
// This function returns the portion of haystack which starts at the last occurrence of needle and goes until the end of haystack.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strrchr(string $haystack, string $needle, bool $before_needle = false): string|false
// ===== CODE
$return_strrchr = strrchr(

$haystack, // string haystack - The string to search in

$needle, // string needle - If needle contains more than one character, only the first is used. This behavior is different from that of strstr().
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

$before_needle // bool before_needle - If true, strrchr() returns the part of the haystack before the last occurrence of the needle (excluding the needle).

); // Return Values
// This function returns the portion of string, or false if needle is not found.
// 
// Changelog
// Version - Description
// 8.3.0   - The before_needle parameter was added.
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 strrchr() example
// [php]
// $ext = strrchr('somefile.txt', '.');
// echo "file extension: $ext \n";
// $ext = $ext ? strtolower(substr($ext, 1)) : '';
// echo "file extension: $ext";
// [/php]
// The above example will output something similar to:
// [result]
// file extension: .txt
// file extension: txt
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.strrchr.php
// ========== STRRCHR - END

// SYNTAX:
// string|false strrchr(string $haystack, string $needle, bool $before_needle = false)

return $return_strrchr; // string|false
}
// ============================== END
//    PHP_TEXT_STRINGS_STRRCHR    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRREV    
// ============================== PUBLIC
// ============================== ABOUT
// Reverse a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strrev() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strrev($string)
{
$return_strrev = null;

// ========== STRREV - BEGIN
// ===== ABOUT
// Reverse a string
// ===== DESCRIPTION
// Returns string, reversed.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strrev(string $string): string
// ===== CODE
$return_strrev = strrev(

$string // string string - The string to be reversed.

); // Return Values
// Returns the reversed string.
// 
// [examples]
// Examples
// [example]
// Example #1 Reversing a string with strrev()
// [php]
// echo strrev("Hello world!"); // outputs "!dlrow olleH"
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strrev.php
// ========== STRREV - END

// SYNTAX:
// string strrev(string $string)

return $return_strrev; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_STRREV    
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_STRRIPOS   
// ============================== OFFLINE
// ============================== ABOUT
// Find the position of the last occurrence of a case-insensitive substring in a string.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// strripos() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_strripos($haystack, $needle, $offset = 0)
{
$return_strripos = false;

// ========== STRRIPOS - BEGIN
// ===== ABOUT
// Find the position of the last occurrence of a case-insensitive substring in a string
// ===== DESCRIPTION
// Find the numeric position of the last occurrence of needle in the haystack string.
// Unlike the strrpos(), strripos() is case-insensitive.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strripos(string $haystack, string $needle, int $offset = 0): int|false
// ===== CODE
$return_strripos = strripos(

$haystack, // string haystack - The string to search in.

$needle, // string needle - The string to search for.
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

$offset // int offset - If zero or positive, the search is performed left to right skipping the first offset bytes of the haystack.
// If negative, the search is performed right to left skipping the last offset bytes of the haystack and searching for the first occurrence of needle.
// Note: This is effectively looking for the last occurrence of needle before the last offset bytes.

); // Return Values
// Returns the position where the needle exists relative to the beginnning of the haystack string (independent of search direction or offset).
// Note: String positions start at 0, and not 1.
// Returns false if the needle was not found.
// Warning: This function may return Boolean false, but may also return a non-Boolean value which evaluates to false. Please read the section on Booleans for more information. Use the === operator for testing the return value of this function.
// 
// Changelog
// Version - Description
// 8.2.0   - Case folding no longer depends on the locale set with setlocale(). Only ASCII case folding will be done. Non-ASCII bytes will be compared by their byte value.
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 A simple strripos() example
// [php]
// $haystack = 'ababcd';
// $needle   = 'aB';
// 
// $pos      = strripos($haystack, $needle);
// 
// if ($pos === false) {
//     echo "Sorry, we did not find ($needle) in ($haystack)";
// } else {
//     echo "Congratulations!\n";
//     echo "We found the last ($needle) in ($haystack) at position ($pos)";
// }
// [/php]
// The above example will output:
// [result]
//    Congratulations!
//    We found the last (aB) in (ababcd) at position (2)
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strripos.php
// ========== STRRIPOS - END

// SYNTAX:
// int|false strripos(string $haystack, string $needle, int $offset = 0)

return $return_strripos; // int|false
}
*/
// ============================== END
//   PHP_TEXT_STRINGS_STRRIPOS   
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRRPOS    
// ============================== PUBLIC
// ============================== ABOUT
// Find the position of the last occurrence of a substring in a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strrpos() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strrpos($haystack, $needle, $offset = 0)
{
$return_strrpos = false;

// ========== STRRPOS - BEGIN
// ===== ABOUT
// Find the position of the last occurrence of a substring in a string
// ===== DESCRIPTION
// Find the numeric position of the last occurrence of needle in the haystack string.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strrpos(string $haystack, string $needle, int $offset = 0): int|false
// ===== CODE
$return_strrpos = strrpos(

$haystack, // string haystack - The string to search in.

$needle, // string needle - The string to search for.
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

$offset // int offset - If zero or positive, the search is performed left to right skipping the first offset bytes of the haystack.
// If negative, the search starts offset bytes from the right instead of from the beginning of haystack. The search is performed right to left, searching for the first occurrence of needle from the selected byte.
// Note: This is effectively looking for the last occurrence of needle at or before the last offset bytes.

); // Return Values
// Returns the position where the needle exists relative to the beginning of the haystack string (independent of search direction or offset).
// Note: String positions start at 0, and not 1.
// Returns false if the needle was not found.
// Warning: This function may return Boolean false, but may also return a non-Boolean value which evaluates to false. Please read the section on Booleans for more information. Use the === operator for testing the return value of this function.
// 
// Changelog
// Version - Description
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 Checking if a needle is in the haystack
// It is easy to mistake the return values for "character found at position 0" and "character not found". Here's how to detect the difference:
// [php]
// 
// $pos = strrpos($mystring, "b");
// if ($pos === false) { // note: three equal signs
//     // not found...
// }
// 
// [/php]
// [/example]
// [example]
// Example #2 Searching with offsets
// [php]
// $foo = "0123456789a123456789b123456789c";
// 
// // Looking for '0' from the 0th byte (from the beginning)
// var_dump(strrpos($foo, '0', 0));
// 
// // Looking for '0' from the 1st byte (after byte "0")
// var_dump(strrpos($foo, '0', 1));
// 
// // Looking for '7' from the 21th byte (after byte 20)
// var_dump(strrpos($foo, '7', 20));
// 
// // Looking for '7' from the 29th byte (after byte 28)
// var_dump(strrpos($foo, '7', 28));
// 
// // Looking for '7' right to left from the 5th byte from the end
// var_dump(strrpos($foo, '7', -5));
// 
// // Looking for 'c' right to left from the 2nd byte from the end
// var_dump(strrpos($foo, 'c', -2));
// 
// // Looking for '9c' right to left from the 2nd byte from the end
// var_dump(strrpos($foo, '9c', -2));
// [/php]
// The above example will output:
// [result]
// int(0)
// bool(false)
// int(27)
// bool(false)
// int(17)
// bool(false)
// int(29)
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strrpos.php
// ========== STRRPOS - END

// SYNTAX:
// int|false strrpos(string $haystack, string $needle, int $offset = 0)

return $return_strrpos; // int|false
}
// ============================== END
//    PHP_TEXT_STRINGS_STRRPOS    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRSPN    
// ============================== PUBLIC
// ============================== ABOUT
// Finds the length of the initial segment of a string consisting entirely of characters contained within a given mask.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strspn() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strspn($string, $characters, $offset = 0, $length = null)
{
$return_strspn = 0;

// ========== STRSPN - BEGIN
// ===== ABOUT
// Finds the length of the initial segment of a string consisting entirely of characters contained within a given mask
// ===== DESCRIPTION
// Finds the length of the initial segment of string that contains only characters from characters.
// If offset and length are omitted, then all of string will be examined. If they are included, then the effect will be the same as calling strspn(substr($string, $offset, $length), $characters) (see substr for more information).
// The line of code:
// [php]
// $var = strspn("42 is the answer to the 128th question.", "1234567890");
// [/php]
// will assign 2 to $var, because the string "42" is the initial segment of string that consists only of characters contained within "1234567890".
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strspn(
//    string $string,
//    string $characters,
//    int $offset = 0,
//    ?int $length = null
// ): int
// ===== CODE
$return_strspn = strspn(

$string, // string string - The string to examine.

$characters, // string characters - The list of allowable characters.

$offset, // int offset - The position in string to start searching.
// If offset is given and is non-negative, then strspn() will begin examining string at the offset'th position. For instance, in the string 'abcdef', the character at position 0 is 'a', the character at position 2 is 'c', and so forth.
// If offset is given and is negative, then strspn() will begin examining string at the offset'th position from the end of string.

$length // int length - The length of the segment from string to examine.
// If length is given and is non-negative, then string will be examined for length characters after the starting position.
// If length is given and is negative, then string will be examined from the starting position up to length characters from the end of string.

); // Return Values
// Returns the length of the initial segment of string which consists entirely of characters in characters.
// Note: When a offset parameter is set, the returned length is counted starting from this position, not from the beginning of string.
// 
// Changelog
// Version - Description
// 8.0.0   - length is nullable now.
// 
// [examples]
// Examples
// [example]
// Example #1 strspn() example
// [php]
// // subject does not start with any characters from mask
// var_dump(strspn("foo", "o"));
// 
// // examine two characters from subject starting at offset 1
// var_dump(strspn("foo", "o", 1, 2));
// 
// // examine one character from subject starting at offset 1
// var_dump(strspn("foo", "o", 1, 1));
// [/php]
// The above example will output:
// [result]
// int(0)
// int(2)
// int(1)
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strspn.php
// ========== STRSPN - END

// SYNTAX:
// int strspn(string $string, string $characters, int $offset = 0, int $length = null)

return $return_strspn; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_STRSPN    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRSTR    
// ============================== PUBLIC
// ============================== ABOUT
// Find the first occurrence of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strstr() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strstr($haystack, $needle, $before_needle = false)
{
$return_strstr = false;

// ========== STRSTR - BEGIN
// ===== ABOUT
// Find the first occurrence of a string
// ===== DESCRIPTION
// Returns part of haystack string starting from and including the first occurrence of needle to the end of haystack.
// Note: This function is case-sensitive. For case-insensitive searches, use stristr().
// Note: If you only want to determine if a particular needle occurs within haystack, use the faster and less memory intensive function strpos() instead.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strstr(string $haystack, string $needle, bool $before_needle = false): string|false
// ===== CODE
$return_strstr = strstr(

$haystack, // string haystack - The input string.

$needle, // string needle - The string to search for.
// Prior to PHP 8.0.0, if needle is not a string, it is converted to an integer and applied as the ordinal value of a character. This behavior is deprecated as of PHP 7.3.0, and relying on it is highly discouraged. Depending on the intended behavior, the needle should either be explicitly cast to string, or an explicit call to chr() should be performed.

$before_needle // bool before_needle - If true, strstr() returns the part of the haystack before the first occurrence of the needle (excluding the needle).

); // Return Values
// Returns the portion of string, or false if needle is not found.
// 
// Changelog
// Version - Description
// 8.0.0   - needle now accepts an empty string.
// 8.0.0   - Passing an int as needle is no longer supported.
// 7.3.0   - Passing an int as needle has been deprecated.
// 
// [examples]
// Examples
// [example]
// Example #1 strstr() example
// [php]
// $email  = 'name@example.com';
// $domain = strstr($email, '@');
// echo $domain; // prints @example.com
// 
// $user = strstr($email, '@', true);
// echo $user; // prints name
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.strstr.php
// ========== STRSTR - END

// SYNTAX:
// string|false strstr(string $haystack, string $needle, bool $before_needle = false)

return $return_strstr; // string|false
}
// ============================== END
//    PHP_TEXT_STRINGS_STRSTR    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_STRTOK    
// ============================== PUBLIC
// ============================== ABOUT
// Tokenize string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strtok() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strtok($string, $token)
{
$return_strtok = false;

// ========== STRTOK - BEGIN
// ===== ABOUT
// Tokenize string
// ===== DESCRIPTION
// strtok() splits a string (string) into smaller strings (tokens), with each token being delimited by any character from token. That is, if you have a string like "This is an example string" you could tokenize this string into its individual words by using the space character as the token.
// Note that only the first call to strtok uses the string argument. Every subsequent call to strtok only needs the token to use, as it keeps track of where it is in the current string. To start over, or to tokenize a new string you simply call strtok with the string argument again to initialize it. Note that you may put multiple tokens in the token parameter. The string will be tokenized when any one of the characters in the token argument is found.
// Note: This function behaves slightly different from what one may expect being familiar with explode(). First, a sequence of two or more contiguous token characters in the parsed string is considered to be a single delimiter. Also, a token situated at the start or end of the string is ignored. For example, if a string ";aaa;;bbb;" is used, successive calls to strtok() with ";" as a token would return strings "aaa" and "bbb", and then false. As a result, the string will be split into only two elements, while explode(";", $string) would return an array of 5 elements.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strtok(string $string, string $token): string|false
// 
// Alternative signature (not supported with named arguments):
// strtok(string $token): string|false
// ===== CODE
$return_strtok = strtok(

$string, // string string - The string being split up into smaller strings (tokens).

$token // string token - The delimiter used when splitting up string.

); // Return Values
// A string token, or false if no more tokens are available.
// 
// Changelog
// Version - Description
// 8.3.0   - Now emits E_WARNING when token is not provided.
// 
// [examples]
// Examples
// [example]
// Example #1 strtok() example
// [php]
// $string = "This is\tan example\nstring";
// // Use tab and newline as tokenizing characters as well
// $tok = strtok($string, " \n\t");
// 
// while ($tok !== false) {
//     echo "Word=$tok<br />";
//     $tok = strtok(" \n\t");
// }
// [/php]
// [/example]
// [example]
// Example #2 strtok() behavior on empty part found
// [php]
// $first_token  = strtok('/something', '/');
// $second_token = strtok('/');
// var_dump($first_token, $second_token);
// [/php]
// The above example will output:
// [result]
//     string(9) "something"
//     bool(false)
// [/result]
// [/example]
// [example]
// Example #3 The difference between strtok() and explode()
// [php]
// $string = ";aaa;;bbb;";
// 
// $parts = [];
// $tok = strtok($string, ";");
// while ($tok !== false) {
//     $parts[] = $tok;
//     $tok = strtok(";");
// }
// echo json_encode($parts),"\n";
// 
// $parts = explode(";", $string);
// echo json_encode($parts),"\n";
// [/php]
// The above example will output:
// [result]
// ["aaa","bbb"]
// ["","aaa","","bbb",""]
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Warning: This function may return Boolean false, but may also return a non-Boolean value which evaluates to false. Please read the section on Booleans for more information. Use the === operator for testing the return value of this function.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.strtok.php
// ========== STRTOK - END

// SYNTAX:
// string|false strtok(string $string, string $token)

return $return_strtok; // string|false
}
// ============================== END
//    PHP_TEXT_STRINGS_STRTOK    
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STRTOLOWER  
// ============================== PUBLIC
// ============================== ABOUT
// Make a string lowercase.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strtolower() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strtolower($string)
{
$return_strtolower = null;

// ========== STRTOLOWER - BEGIN
// ===== ABOUT
// Make a string lowercase
// ===== DESCRIPTION
// Returns string with all ASCII alphabetic characters converted to lowercase.
// Bytes in the range "A" (0x41) to "Z" (0x5a) will be converted to the corresponding lowercase letter by adding 32 to each byte value.
// This can be used to convert ASCII characters within strings encoded with UTF-8, since multibyte UTF-8 characters will be ignored. To convert multibyte non-ASCII characters, use mb_strtolower().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strtolower(string $string): string
// ===== CODE
$return_strtolower = strtolower(

$string // string string - The input string.

); // Return Values
// Returns the lowercased string.
// 
// Changelog
// Version - Description
// 8.2.0   - Case conversion no longer depends on the locale set with setlocale(). Only ASCII characters will be converted.
// 
// [examples]
// Examples
// [example]
// Example #1 strtolower() example
// [php]
// $str = "Mary Had A Little Lamb and She LOVED It So";
// $str = strtolower($str);
// echo $str; // Prints mary had a little lamb and she loved it so
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-22)
// URL: https://www.php.net/manual/en/function.strtolower.php
// ========== STRTOLOWER - END

// SYNTAX:
// string strtolower(string $string)

return $return_strtolower; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_STRTOLOWER  
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_STRTOUPPER  
// ============================== PUBLIC
// ============================== ABOUT
// Make a string uppercase.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strtoupper() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strtoupper($string)
{
$return_strtoupper = null;

// ========== STRTOUPPER - BEGIN
// ===== ABOUT
// Make a string uppercase
// ===== DESCRIPTION
// Returns string with all ASCII alphabetic characters converted to uppercase.
// Bytes in the range "a" (0x61) to "z" (0x7a) will be converted to the corresponding uppercase letter by subtracting 32 from each byte value.
// This can be used to convert ASCII characters within strings encoded with UTF-8, since multibyte UTF-8 characters will be ignored. To convert multibyte non-ASCII characters, use mb_strtoupper().
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strtoupper(string $string): string
// ===== CODE
$return_strtoupper = strtoupper(

$string // string string - The input string.

); // Return Values
// Returns the uppercased string.
// 
// Changelog
// Version - Description
// 8.2.0   - Case conversion no longer depends on the locale set with setlocale(). Only ASCII characters will be converted.
// 
// [examples]
// Examples
// [example]
// Example #1 strtoupper() example
// [php]
// $str = "Mary Had A Little Lamb and She LOVED It So";
// $str = strtoupper($str);
// echo $str; // Prints MARY HAD A LITTLE LAMB AND SHE LOVED IT SO
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.strtoupper.php
// ========== STRTOUPPER - END

// SYNTAX:
// string strtoupper(string $string)

return $return_strtoupper; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_STRTOUPPER  
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_STRTR     
// ============================== PUBLIC
// ============================== ABOUT
// Translate characters or replace substrings.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// strtr() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_strtr($string, $from, $to)
{
$return_strtr = null;

// ========== STRTR - BEGIN
// ===== ABOUT
// Translate characters or replace substrings
// ===== DESCRIPTION
// If given three arguments, this function returns a copy of string where all occurrences of each (single-byte) character in from have been translated to the corresponding character in to, i.e., every occurrence of $from[$n] has been replaced with $to[$n], where $n is a valid offset in both arguments.
// If from and to have different lengths, the extra characters in the longer of the two are ignored. The length of string will be the same as the return value's.
// If given two arguments, the second should be an array in the form array('from' => 'to', ...). The return value is a string where all the occurrences of the array keys have been replaced by the corresponding values. The longest keys will be tried first. Once a substring has been replaced, its new value will not be searched again.
// In this case, the keys and the values may have any length, provided that there is no empty key; additionally, the length of the return value may differ from that of string. However, this function will be the most efficient when all the keys have the same size.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// strtr(string $string, string $from, string $to): string
// 
// Alternative signature (not supported with named arguments):
// strtr(string $string, array $replace_pairs): string
// ===== CODE
$return_strtr = strtr(

$string, // string string - The string being translated.

$from, // string from - The string being translated to to.

$to // string to - The string replacing from.

// array replace_pairs - The replace_pairs parameter may be used instead of to and from, in which case it's an array in the form array('from' => 'to', ...).
// If replace_pairs contains a key which is an empty string (""), the element is ignored; as of PHP 8.0.0 E_WARNING is raised in this case.

); // Return Values
// Returns the translated string.
// 
// [examples]
// Examples
// [example]
// Example #1 strtr() example
// [php]
// //In this form, strtr() does byte-by-byte translation
// //Therefore, we are assuming a single-byte encoding here:
// $addr = strtr($addr, "äåö", "aao");
// [/php]
// The next example shows the behavior of strtr() when called with only two arguments. Note the preference of the replacements ("h" is not picked because there are longer matches) and how replaced text was not searched again.
// [/example]
// [example]
// Example #2 strtr() example with two arguments
// [php]
// $trans = array("h" => "-", "hello" => "hi", "hi" => "hello");
// echo strtr("hi all, I said hello", $trans);
// [/php]
// The above example will output:
// [result]
// hello all, I said hi
// [/result]
// The two modes of behavior are substantially different. With three arguments, strtr() will replace bytes; with two, it may replace longer substrings.
// [/example]
// [example]
// Example #3 strtr() behavior comparison
// [php]
// echo strtr("baab", "ab", "01"),"\n";
// 
// $trans = array("ab" => "01");
// echo strtr("baab", $trans);
// [/php]
// The above example will output:
// [result]
// 1001
// ba01
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.strtr.php
// ========== STRTR - END

// SYNTAX:
// string strtr(string $string, string $from, string $to)

return $return_strtr; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_STRTR     
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_SUBSTR_COMPARE
// ============================== OFFLINE
// ============================== ABOUT
// Binary safe comparison of two strings from an offset, up to length characters.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// substr_compare() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_substr_compare($haystack, $needle, $offset, $length = null, $case_insensitive = false)
{
$return_substr_compare = 0;

// ========== SUBSTR_COMPARE - BEGIN
// ===== ABOUT
// Binary safe comparison of two strings from an offset, up to length characters
// ===== DESCRIPTION
// substr_compare() compares haystack from position offset with needle up to length characters.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// substr_compare(
//    string $haystack,
//    string $needle,
//    int $offset,
//    ?int $length = null,
//    bool $case_insensitive = false
// ): int
// ===== CODE
$return_substr_compare = substr_compare(

$haystack, // string haystack - The main string being compared.

$needle, // string needle - The secondary string being compared.

$offset, // int offset - The start position for the comparison. If negative, it starts counting from the end of the string.

$length, // int length - The length of the comparison. The default value is the largest of the length of the needle compared to the length of haystack minus the offset.

$case_insensitive // bool case_insensitive - If case_insensitive is true, comparison is case insensitive.

); // Return Values
// Returns -1 if haystack from position offset is less than needle, 1 if it is greater than needle, and 0 if they are equal. If offset is equal to (prior to PHP 7.2.18, 7.3.5) or greater than the length of haystack, or the length is set and is less than 0, substr_compare() prints a warning and returns false.
// 
// Changelog
// Version       - Description
// 8.2.0         - This function now returns -1 or 1, where it previously returned a negative or positive number.
// 8.0.0         - length is nullable now.
// 7.2.18, 7.3.5 - offset may now be equal to the length of haystack.
// 
// [examples]
// Examples
// [example]
// Example #1 A substr_compare() example
// [php]
// echo substr_compare("abcde", "bc", 1, 2); // 0
// echo substr_compare("abcde", "de", -2, 2); // 0
// echo substr_compare("abcde", "bcg", 1, 2); // 0
// echo substr_compare("abcde", "BC", 1, 2, true); // 0
// echo substr_compare("abcde", "bc", 1, 3); // 1
// echo substr_compare("abcde", "cd", 1, 2); // -1
// echo substr_compare("abcde", "abc", 5, 1); // warning
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.substr-compare.php
// ========== SUBSTR_COMPARE - END

// SYNTAX:
// int substr_compare(string $haystack, string $needle, int $offset, int $length = null, bool $case_insensitive = false)

return $return_substr_compare; // int
}
*/
// ============================== END
// PHP_TEXT_STRINGS_SUBSTR_COMPARE
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_SUBSTR_COUNT 
// ============================== PUBLIC
// ============================== ABOUT
// Returns number of substring occurrences.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// substr_count() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_substr_count($haystack, $needle, $offset = 0, $length = null)
{
$return_substr_count = 0;

// ========== SUBSTR_COUNT - BEGIN
// ===== ABOUT
// Count the number of substring occurrences
// ===== DESCRIPTION
// substr_count() returns the number of times the needle substring occurs in the haystack string. Please note that needle is case sensitive.
// Note: This function doesn't count overlapped substrings. See the example below!
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// substr_count(
//    string $haystack,
//    string $needle,
//    int $offset = 0,
//    ?int $length = null
// ): int
// ===== CODE
$return_substr_count = substr_count(

$haystack, // string haystack - The string to search in

$needle, // string needle - The substring to search for

$offset, // int offset - The offset where to start counting. If the offset is negative, counting starts from the end of the string.

$length // int length - The maximum length after the specified offset to search for the substring. It outputs a warning if the offset plus the length is greater than the haystack length. A negative length counts from the end of haystack.

); // Return Values
// This function returns an int.
// 
// Changelog
// Version - Description
// 8.0.0   - length is nullable now.
// 7.1.0   - Support for negative offsets and lengths has been added. length may also be 0 now.
// 
// [examples]
// Examples
// [example]
// Example #1 A substr_count() example
// [php]
// $text = 'This is a test';
// echo strlen($text); // 14
// 
// echo substr_count($text, 'is'); // 2
// 
// // the string is reduced to 's is a test', so it prints 1
// echo substr_count($text, 'is', 3);
// 
// // the text is reduced to 's i', so it prints 0
// echo substr_count($text, 'is', 3, 3);
// 
// // generates a warning because 5+10 > 14
// echo substr_count($text, 'is', 5, 10);
// 
// 
// // prints only 1, because it doesn't count overlapped substrings
// $text2 = 'gcdgcdgcd';
// echo substr_count($text2, 'gcdgcd');
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.substr-count.php
// ========== SUBSTR_COUNT - END

// SYNTAX:
// int substr_count(string $haystack, string $needle, int $offset = 0, int $length = null)

return $return_substr_count; // int
}
// ============================== END
// PHP_TEXT_STRINGS_SUBSTR_COUNT 
// ==============================


// ============================== BEGIN
// PHP_TEXT_STRINGS_SUBSTR_REPLACE
// ============================== PUBLIC
// ============================== ABOUT
// Replace text within a portion of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// substr_replace() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_substr_replace($string, $replace, $offset, $length = null)
{
$return_substr_replace = null;

// ========== SUBSTR_REPLACE - BEGIN
// ===== ABOUT
// Replace text within a portion of a string
// ===== DESCRIPTION
// substr_replace() replaces a copy of string delimited by the offset and (optionally) length parameters with the string given in replace.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// substr_replace(
//    array|string $string,
//    array|string $replace,
//    array|int $offset,
//    array|int|null $length = null
// ): string|array
// ===== CODE
$return_substr_replace = substr_replace(

$string, // array|string string - The input string.
// An array of strings can be provided, in which case the replacements will occur on each string in turn. In this case, the replace, offset and length parameters may be provided either as scalar values to be applied to each input string in turn, or as arrays, in which case the corresponding array element will be used for each input string.

$replace, // array|string replace - The replacement string.

$offset, // array|int offset - If offset is non-negative, the replacing will begin at the offset'th offset into string.
// If offset is negative, the replacing will begin at the offset'th character from the end of string.

$length // array|int|null length - If given and is positive, it represents the length of the portion of string which is to be replaced. If it is negative, it represents the number of characters from the end of string at which to stop replacing. If it is not given, then it will default to strlen( string ); i.e. end the replacing at the end of string. Of course, if length is zero then this function will have the effect of inserting replace into string at the given offset offset.

); // Return Values
// The result string is returned. If string is an array then array is returned.
// 
// Changelog
// Version - Description
// 8.0.0   - length is nullable now.
// 
// [examples]
// Examples
// [example]
// Example #1 Simple substr_replace() examples
// [php]
// $var = 'ABCDEFGH:/MNRPQR/';
// echo "Original: $var<hr />\n";
// 
// // These two examples replace all of $var with 'bob'.
// echo substr_replace($var, 'bob', 0) . "<br />\n";
// echo substr_replace($var, 'bob', 0, strlen($var)) . "<br />\n";
// 
// // Insert 'bob' right at the beginning of $var.
// echo substr_replace($var, 'bob', 0, 0) . "<br />\n";
// 
// // These next two replace 'MNRPQR' in $var with 'bob'.
// echo substr_replace($var, 'bob', 10, -1) . "<br />\n";
// echo substr_replace($var, 'bob', -7, -1) . "<br />\n";
// 
// // Delete 'MNRPQR' from $var.
// echo substr_replace($var, '', 10, -1) . "<br />\n";
// [/php]
// [/example]
// [example]
// Example #2 Using substr_replace() to replace multiple strings at once
// [php]
// $input = array('A: XXX', 'B: XXX', 'C: XXX');
// 
// // A simple case: replace XXX in each string with YYY.
// echo implode('; ', substr_replace($input, 'YYY', 3, 3))."\n";
// 
// // A more complicated case where each replacement is different.
// $replace = array('AAA', 'BBB', 'CCC');
// echo implode('; ', substr_replace($input, $replace, 3, 3))."\n";
// 
// // Replace a different number of characters each time.
// $length = array(1, 2, 3);
// echo implode('; ', substr_replace($input, $replace, 3, $length))."\n";
// [/php]
// The above example will output:
// [result]
// A: YYY; B: YYY; C: YYY
// A: AAA; B: BBB; C: CCC
// A: AAAXX; B: BBBX; C: CCC
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.substr-replace.php
// ========== SUBSTR_REPLACE - END

// SYNTAX:
// string|array substr_replace(array|string $string, array|string $replace, array|int $offset, array|int|null $length = null)

return $return_substr_replace; // string|array
}
// ============================== END
// PHP_TEXT_STRINGS_SUBSTR_REPLACE
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_SUBSTR    
// ============================== PUBLIC
// ============================== ABOUT
// Return part of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// substr() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_substr($string, $offset, $length = null)
{
$return_substr = null;

// ========== SUBSTR - BEGIN
// ===== ABOUT
// Return part of a string
// ===== DESCRIPTION
// Returns the portion of string specified by the offset and length parameters.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// substr(string $string, int $offset, ?int $length = null): string
// ===== CODE
$return_substr = substr(

$string, // string $string - The input string.

$offset, // int $offset - If offset is non-negative, the returned string will start at the offset'th position in string, counting from zero. For instance, in the string 'abcdef', the character at position 0 is 'a', the character at position 2 is 'c', and so forth.
// If offset is negative, the returned string will start at the offset'th character from the end of string.
// If string is less than offset characters long, an empty string will be returned.
// [example]
// Example #1 Using a negative offset
// [php]
// $rest = substr("abcdef", -1);    // returns "f"
// $rest = substr("abcdef", -2);    // returns "ef"
// $rest = substr("abcdef", -3, 1); // returns "d"
// [/php]
// [/example]

$length // int|null $length - If length is given and is positive, the string returned will contain at most length characters beginning from offset (depending on the length of string).
// If length is given and is negative, then that many characters will be omitted from the end of string (after the start position has been calculated when a offset is negative). If offset denotes the position of this truncation or beyond, an empty string will be returned.
// If length is given and is 0, an empty string will be returned.
// If length is omitted or null, the substring starting from offset until the end of the string will be returned.
// [example]
// Example #2 Using a negative length
// [php]
// $rest = substr("abcdef", 0, -1);  // returns "abcde"
// $rest = substr("abcdef", 2, -1);  // returns "cde"
// $rest = substr("abcdef", 4, -4);  // returns ""; prior to PHP 8.0.0, false was returned
// $rest = substr("abcdef", -3, -1); // returns "de"
// [/php]
// [/example]

); // Return Values
// Returns the extracted part of string, or an empty string.
// 
// Changelog
// Version - Description
// 8.0.0   - length is nullable now. When length is explicitly set to null, the function returns a substring finishing at the end of the string, when it previously returned an empty string.
// 8.0.0   - The function returns an empty string where it previously returned false.
// 
// [examples]
// Examples
// [example]
// Example #3 Basic substr() usage
// [php]
// echo substr('abcdef', 1);     // bcdef
// echo substr("abcdef", 1, null); // bcdef; prior to PHP 8.0.0, empty string was returned
// echo substr('abcdef', 1, 3);  // bcd
// echo substr('abcdef', 0, 4);  // abcd
// echo substr('abcdef', 0, 8);  // abcdef
// echo substr('abcdef', -1, 1); // f
// 
// // Accessing single characters in a string
// // can also be achieved using "square brackets"
// $string = 'abcdef';
// echo $string[0];                 // a
// echo $string[3];                 // d
// echo $string[strlen($string)-1]; // f
// 
// [/php]
// [/example]
// [example]
// Example #4 substr() casting behaviour
// [php]
// class apple {
//     public function __toString() {
//         return "green";
//     }
// }
// 
// echo "1) ".var_export(substr("pear", 0, 2), true).PHP_EOL;
// echo "2) ".var_export(substr(54321, 0, 2), true).PHP_EOL;
// echo "3) ".var_export(substr(new apple(), 0, 2), true).PHP_EOL;
// echo "4) ".var_export(substr(true, 0, 1), true).PHP_EOL;
// echo "5) ".var_export(substr(false, 0, 1), true).PHP_EOL;
// echo "6) ".var_export(substr("", 0, 1), true).PHP_EOL;
// echo "7) ".var_export(substr(1.2e3, 0, 4), true).PHP_EOL;
// [/php]
// The above example will output:
// [result]
// 1) 'pe'
// 2) '54'
// 3) 'gr'
// 4) '1'
// 5) ''
// 6) ''
// 7) '1200'
// [/result]
// [/example]
// [example]
// Example #5 Invalid Character Range
// If an invalid character range is requested, substr() returns an empty string as of PHP 8.0.0; previously, false was returned instead.
// [php]
// var_dump(substr('a', 2));
// [/php]
// Output of the above example in PHP 8:
// [result]
// string(0) ""
// [/result]
// Output of the above example in PHP 7:
// [result]
// bool(false)
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.substr.php
// ========== SUBSTR - END

// SYNTAX:
// string substr(string $string, int $offset, int $length = null)

return $return_substr; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_SUBSTR    
// ==============================


// ============================== BEGIN
//     PHP_TEXT_STRINGS_TRIM     
// ============================== PUBLIC
// ============================== ABOUT
// Strip whitespace (or other characters) from the beginning and end of a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// trim() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_trim($string, $characters = " \n\r\t\v\x00")
{
$return_trim = null;

// ========== TRIM - BEGIN
// ===== ABOUT
// Strip whitespace (or other characters) from the beginning and end of a string
// ===== DESCRIPTION
// This function returns a string with whitespace stripped from the beginning and end of string. Without the second parameter, trim() will strip these characters:
// * " "  (ASCII 32 (0x20)), an ordinary space.
// * "\t" (ASCII 9 (0x09)), a tab.
// * "\n" (ASCII 10 (0x0A)), a new line (line feed).
// * "\r" (ASCII 13 (0x0D)), a carriage return.
// * "\0" (ASCII 0 (0x00)), the NUL-byte.
// * "\v" (ASCII 11 (0x0B)), a vertical tab.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// trim(string $string, string $characters = " \n\r\t\v\x00"): string
// ===== CODE
$return_trim = trim(

$string, // string string - The string that will be trimmed.

$characters // string characters - Optionally, the stripped characters can also be specified using the characters parameter. Simply list all characters that you want to be stripped. With .. you can specify a range of characters.

); // Return Values
// The trimmed string.
// 
// [examples]
// Examples
// [example]
// Example #1 Usage example of trim()
// [php]
// 
// $text   = "\t\tThese are a few words :) ...  ";
// $binary = "\x09Example string\x0A";
// $hello  = "Hello World";
// var_dump($text, $binary, $hello);
// 
// print "\n";
// 
// $trimmed = trim($text);
// var_dump($trimmed);
// 
// $trimmed = trim($text, " \t.");
// var_dump($trimmed);
// 
// $trimmed = trim($hello, "Hdle");
// var_dump($trimmed);
// 
// $trimmed = trim($hello, 'HdWr');
// var_dump($trimmed);
// 
// // trim the ASCII control characters at the beginning and end of $binary
// // (from 0 to 31 inclusive)
// $clean = trim($binary, "\x00..\x1F");
// var_dump($clean);
// 
// [/php]
// The above example will output:
// [result]
// string(32) "        These are a few words :) ...  "
// string(16) "    Example string
// "
// string(11) "Hello World"
// 
// string(28) "These are a few words :) ..."
// string(24) "These are a few words :)"
// string(5) "o Wor"
// string(9) "ello Worl"
// string(14) "Example string"
// [/result]
// [/example]
// [example]
// Example #2 Trimming array values with trim()
// [php]
// function trim_value(&$value) 
// { 
//     $value = trim($value); 
// }
// 
// $fruit = array('apple','banana ', ' cranberry ');
// var_dump($fruit);
// 
// array_walk($fruit, 'trim_value');
// var_dump($fruit);
// 
// [/php]
// The above example will output:
// [result]
// array(3) {
//   [0]=>
//   string(5) "apple"
//   [1]=>
//   string(7) "banana "
//   [2]=>
//   string(11) " cranberry "
// }
// array(3) {
//   [0]=>
//   string(5) "apple"
//   [1]=>
//   string(6) "banana"
//   [2]=>
//   string(9) "cranberry"
// }
// 
// [/result]
// [/example]
// [/examples]
// 
// Notes
//  Note: Possible gotcha: removing middle characters
//  Because trim() trims characters from the beginning and end of a string, it may be confusing when characters are (or are not) removed from the middle. trim('abc', 'bad') removes both 'a' and 'b' because it trims 'a' thus moving 'b' to the beginning to also be trimmed. So, this is why it "works" whereas trim('abc', 'b') seemingly does not.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.trim.php
// ========== TRIM - END

// SYNTAX:
// string trim(string $string, string $characters = " \n\r\t\v\x00")

return $return_trim; // string
}
// ============================== END
//     PHP_TEXT_STRINGS_TRIM     
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_UCFIRST    
// ============================== PUBLIC
// ============================== ABOUT
// Make a string's first character uppercase.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// ucfirst() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_ucfirst($string)
{
$return_ucfirst = null;

// ========== UCFIRST - BEGIN
// ===== ABOUT
// Make a string's first character uppercase
// ===== DESCRIPTION
// Returns a string with the first character of string capitalized, if that character is an ASCII character in the range from "a" (0x61) to "z" (0x7a).
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// ucfirst(string $string): string
// ===== CODE
$return_ucfirst = ucfirst(

$string // string string - The input string.

); // Return Values
// Returns the resulting string.
// 
// Changelog
// Version - Description
// 8.2.0   - Case conversion no longer depends on the locale set with setlocale(). Only ASCII characters will be converted.
// 
// [examples]
// Examples
// [example]
// Example #1 ucfirst() example
// [php]
// $foo = 'hello world!';
// $foo = ucfirst($foo);             // Hello world!
// 
// $bar = 'HELLO WORLD!';
// $bar = ucfirst($bar);             // HELLO WORLD!
// $bar = ucfirst(strtolower($bar)); // Hello world!
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.ucfirst.php
// ========== UCFIRST - END

// SYNTAX:
// string ucfirst(string $string)

return $return_ucfirst; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_UCFIRST    
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_UCWORDS    
// ============================== PUBLIC
// ============================== ABOUT
// Uppercase the first character of each word in a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// ucwords() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_ucwords($string, $separators = " \t\r\n\f\v")
{
$return_ucwords = null;

// ========== UCWORDS - BEGIN
// ===== ABOUT
// Uppercase the first character of each word in a string
// ===== DESCRIPTION
// Returns a string with the first character of each word in string capitalized, if that character is an ASCII character between "a" (0x61) and "z" (0x7a).
// For this function, a word is a string of characters that are not listed in the separators parameter. By default, these are: space, horizontal tab, carriage return, newline, form-feed and vertical tab.
// To do a similar conversion on multibyte strings, use mb_convert_case() with the MB_CASE_TITLE mode.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// ucwords(string $string, string $separators = " \t\r\n\f\v"): string
// ===== CODE
$return_ucwords = ucwords(

$string, // string string - The input string.

$separators // string separators - The optional separators contains the word separator characters.

); // Return Values
// Returns the modified string.
// 
// Changelog
// Version - Description
// 8.2.0   - Case conversion no longer depends on the locale set with setlocale(). Only ASCII characters will be converted.
// 
// [examples]
// Examples
// [example]
// Example #1 ucwords() example
// [php]
// $foo = 'hello world!';
// $foo = ucwords($foo);             // Hello World!
// 
// $bar = 'HELLO WORLD!';
// $bar = ucwords($bar);             // HELLO WORLD!
// $bar = ucwords(strtolower($bar)); // Hello World!
// [/php]
// [/example]
// [example]
// Example #2 ucwords() example with custom delimiter
// [php]
// $foo = 'hello|world!';
// $bar = ucwords($foo);             // Hello|world!
// 
// $baz = ucwords($foo, "|");        // Hello|World!
// [/php]
// [/example]
// [example]
// Example #3 ucwords() example with additional delimiters
// [php]
// $foo = "mike o'hara";
// $bar = ucwords($foo);                 // Mike O'hara
// 
// $baz = ucwords($foo, " \t\r\n\f\v'"); // Mike O'Hara
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Note: This function is binary-safe.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.ucwords.php
// ========== UCWORDS - END

// SYNTAX:
// string ucwords(string $string, string $separators = " \t\r\n\f\v")

return $return_ucwords; // string
}
// ============================== END
//    PHP_TEXT_STRINGS_UCWORDS    
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_UTF8_DECODE  
// ============================== PUBLIC
// ============================== ABOUT
// Converts a string from UTF-8 to ISO-8859-1, replacing invalid or unrepresentable characters.
// 
// Warning: This function has been DEPRECATED as of PHP 8.2.0. Relying on this function is highly discouraged.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// utf8_decode() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_utf8_decode($string)
{
$return_utf8_decode = null;

// ========== UTF8_DECODE - BEGIN
// ===== ABOUT
// Converts a string from UTF-8 to ISO-8859-1, replacing invalid or unrepresentable characters
// Warning: This function has been DEPRECATED as of PHP 8.2.0. Relying on this function is highly discouraged.
// ===== DESCRIPTION
// This function converts the string string from the UTF-8 encoding to ISO-8859-1. Bytes in the string which are not valid UTF-8, and UTF-8 characters which do not exist in ISO-8859-1 (that is, code points above U+00FF) are replaced with ?.
// Note: Many web pages marked as using the ISO-8859-1 character encoding actually use the similar Windows-1252 encoding, and web browsers will interpret ISO-8859-1 web pages as Windows-1252. Windows-1252 features additional printable characters, such as the Euro sign (€) and curly quotes (“ ”), instead of certain ISO-8859-1 control characters. This function will not convert such Windows-1252 characters correctly. Use a different function if Windows-1252 conversion is required.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// utf8_decode(string $string): string
// ===== CODE
$return_utf8_decode = utf8_decode(

$string // string string - A UTF-8 encoded string.

); // Return Values
// Returns the ISO-8859-1 translation of string.
// 
// Changelog
// Version - Description
// 8.2.0   - This function has been deprecated.
// 7.2.0   - This function has been moved from the XML extension to the core of PHP. In previous versions, it was only available if the XML extension was installed.
// 
// [examples]
// Examples
// [example]
// Example #1 Basic examples
// [php]
// // Convert the string 'Zoë' from UTF-8 to ISO 8859-1
// $utf8_string = "\x5A\x6F\xC3\xAB";
// $iso8859_1_string = utf8_decode($utf8_string);
// echo bin2hex($iso8859_1_string), "\n";
// 
// // Invalid UTF-8 sequences are replaced with '?'
// $invalid_utf8_string = "\xC3";
// $iso8859_1_string = utf8_decode($invalid_utf8_string);
// var_dump($iso8859_1_string);
// 
// // Characters which don't exist in ISO 8859-1, such as
// // '€' (Euro Sign) are also replaced with '?'
// $utf8_string = "\xE2\x82\xAC";
// $iso8859_1_string = utf8_decode($utf8_string);
// var_dump($iso8859_1_string);
// [/php]
// The above example will output:
// [result]
// 5a6feb
// string(1) "?"
// string(1) "?"
// [/result]
// [/example]
// [/examples]
// 
// Notes
//  Note: Deprecation and alternatives
//  This function is deprecated as of PHP 8.2.0, and will be removed in a future version. Existing uses should be checked and replaced with appropriate alternatives.
//  Similar functionality can be achieved with mb_convert_encoding(), which supports ISO-8859-1 and many other character encodings.
//  [example]
//  [php]
//  $utf8_string = "\xC3\xAB"; // 'ë' (e with diaeresis) in UTF-8
//  $iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');
//  echo bin2hex($iso8859_1_string), "\n";
//  
//  $utf8_string = "\xCE\xBB"; // 'λ' (Greek lower-case lambda) in UTF-8
//  $iso8859_7_string = mb_convert_encoding($utf8_string, 'ISO-8859-7', 'UTF-8');
//  echo bin2hex($iso8859_7_string), "\n";
//  
//  $utf8_string = "\xE2\x82\xAC"; // '€' (Euro sign) in UTF-8 (not present in ISO-8859-1)
//  $windows_1252_string = mb_convert_encoding($utf8_string, 'Windows-1252', 'UTF-8');
//  echo bin2hex($windows_1252_string), "\n";
//  [/php]
//  The above example will output:
//  [result]
//  eb
//  eb
//  80
//  [/result]
//  [/example]
//  Other options which may be available depending on the extensions installed are UConverter::transcode() and iconv().
//  The following all give the same result:
//  [example]
//  [php]
//  $utf8_string = "\x5A\x6F\xC3\xAB"; // 'Zoë' in UTF-8
//  $iso8859_1_string = utf8_decode($utf8_string);
//  echo bin2hex($iso8859_1_string), "\n";
//  
//  $iso8859_1_string = mb_convert_encoding($utf8_string, 'ISO-8859-1', 'UTF-8');
//  echo bin2hex($iso8859_1_string), "\n";
//  
//  $iso8859_1_string = iconv('UTF-8', 'ISO-8859-1', $utf8_string);
//  echo bin2hex($iso8859_1_string), "\n";
//  
//  $iso8859_1_string = UConverter::transcode($utf8_string, 'ISO-8859-1', 'UTF8');
//  echo bin2hex($iso8859_1_string), "\n";
//  [/php]
//  The above example will output:
//  [result]
//  5a6feb
//  5a6feb
//  5a6feb
//  5a6feb
//  [/result]
//  [/example]
//  Specifying '?' as the 'to_subst' option to UConverter::transcode() gives the same result as utf8_decode() for strings which are invalid or which can not be represented in ISO 8859-1.
//  [example]
//  [php]
//  $utf8_string = "\xE2\x82\xAC"; // € (Euro Sign) does not exist in ISO 8859-1
//  $iso8859_1_string = UConverter::transcode(
//      $utf8_string, 'ISO-8859-1', 'UTF-8', ['to_subst' => '?']
//  );
//  var_dump($iso8859_1_string);
//  [/php]
//  The above example will output:
//  [result]
//  sring(1) "?"
//  [/result]
//  [/example]
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-22)
// URL: https://www.php.net/manual/en/function.utf8-decode.php
// ========== UTF8_DECODE - END

// SYNTAX:
// string utf8_decode(string $string)

return $return_utf8_decode; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_UTF8_DECODE  
// ==============================


// ============================== BEGIN
//  PHP_TEXT_STRINGS_UTF8_ENCODE  
// ============================== PUBLIC
// ============================== ABOUT
// Converts a string from ISO-8859-1 to UTF-8.
// 
// Warning: This function has been DEPRECATED as of PHP 8.2.0. Relying on this function is highly discouraged.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// utf8_encode() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_utf8_encode($string)
{
$return_utf8_encode = null;

// ========== UTF8_ENCODE - BEGIN
// ===== ABOUT
// Converts a string from ISO-8859-1 to UTF-8
// Warning: This function has been DEPRECATED as of PHP 8.2.0. Relying on this function is highly discouraged.
// ===== DESCRIPTION
// This function converts the string string from the ISO-8859-1 encoding to UTF-8.
//  Note:
//  This function does not attempt to guess the current encoding of the provided string, it assumes it is encoded as ISO-8859-1 (also known as "Latin 1") and converts to UTF-8. Since every sequence of bytes is a valid ISO-8859-1 string, this never results in an error, but will not result in a useful string if a different encoding was intended.
//  Many web pages marked as using the ISO-8859-1 character encoding actually use the similar Windows-1252 encoding, and web browsers will interpret ISO-8859-1 web pages as Windows-1252. Windows-1252 features additional printable characters, such as the Euro sign (€) and curly quotes (“ ”), instead of certain ISO-8859-1 control characters. This function will not convert such Windows-1252 characters correctly. Use a different function if Windows-1252 conversion is required.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// utf8_encode(string $string): string
// ===== CODE
$return_utf8_encode = utf8_encode(

$string // string string - An ISO-8859-1 string.

); // Return Values
// Returns the UTF-8 translation of string.
// 
// Changelog
// Version - Description
// 8.2.0   - This function has been deprecated.
// 7.2.0   - This function has been moved from the XML extension to the core of PHP. In previous versions, it was only available if the XML extension was installed.
// 
// [examples]
// Examples
// [example]
// Example #1 Basic example
// [php]
// // Convert the string 'Zoë' from ISO 8859-1 to UTF-8
// $iso8859_1_string = "\x5A\x6F\xEB";
// $utf8_string = utf8_encode($iso8859_1_string);
// echo bin2hex($utf8_string), "\n";
// [/php]
// The above example will output:
// [result]
// 5a6fc3ab
// [/result]
// [/example]
// [/examples]
// 
// Notes
//  Note: Deprecation and alternatives
//  This function is deprecated as of PHP 8.2.0, and will be removed in a future version. Existing uses should be checked and replaced with appropriate alternatives.
//  Similar functionality can be achieved with mb_convert_encoding(), which supports ISO-8859-1 and many other character encodings.
//  [example]
//  [php]
//  $iso8859_1_string = "\xEB"; // 'ë' (e with diaeresis) in ISO-8859-1
//  $utf8_string = mb_convert_encoding($iso8859_1_string, 'UTF-8', 'ISO-8859-1');
//  echo bin2hex($utf8_string), "\n";
//  
//  $iso8859_7_string = "\xEB"; // the same string in ISO-8859-7 represents 'λ' (Greek lower-case lambda)
//  $utf8_string = mb_convert_encoding($iso8859_7_string, 'UTF-8', 'ISO-8859-7');
//  echo bin2hex($utf8_string), "\n";
//  
//  $windows_1252_string = "\x80"; // '€' (Euro sign) in Windows-1252, but not in ISO-8859-1
//  $utf8_string = mb_convert_encoding($windows_1252_string, 'UTF-8', 'Windows-1252');
//  echo bin2hex($utf8_string), "\n";
//  [/php]
//  The above example will output:
//  [result]
//  c3ab
//  cebb
//  e282ac
//  [/result]
//  [/example]
//  Other options which may be available depending on the extensions installed are UConverter::transcode() and iconv().
//  The following all give the same result:
//  [example]
//  [php]
//  $iso8859_1_string = "\x5A\x6F\xEB"; // 'Zoë' in ISO-8859-1
//  
//  $utf8_string = utf8_encode($iso8859_1_string);
//  echo bin2hex($utf8_string), "\n";
//  
//  $utf8_string = mb_convert_encoding($iso8859_1_string, 'UTF-8', 'ISO-8859-1');
//  echo bin2hex($utf8_string), "\n";
//  
//  $utf8_string = UConverter::transcode($iso8859_1_string, 'UTF8', 'ISO-8859-1');
//  echo bin2hex($utf8_string), "\n";
//  
//  $utf8_string = iconv('ISO-8859-1', 'UTF-8', $iso8859_1_string);
//  echo bin2hex($utf8_string), "\n";
//  [/php]
//  The above example will output:
//  [result]
//  5a6fc3ab
//  5a6fc3ab
//  5a6fc3ab
//  5a6fc3ab
//  [/result]
//  [/example]
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-22)
// URL: https://www.php.net/manual/en/function.utf8-encode.php
// ========== UTF8_ENCODE - END

// SYNTAX:
// string utf8_encode(string $string)

return $return_utf8_encode; // string
}
// ============================== END
//  PHP_TEXT_STRINGS_UTF8_ENCODE  
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_VFPRINTF   
// ============================== OFFLINE
// ============================== ABOUT
// Write a formatted string to a stream.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// vfprintf() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_text_strings_vfprintf($stream, $format, $values)
{
$return_vfprintf = 0;

// ========== VFPRINTF - BEGIN
// ===== ABOUT
// Write a formatted string to a stream
// ===== DESCRIPTION
// Write a string produced according to format to the stream resource specified by stream.
// Operates as fprintf() but accepts an array of arguments, rather than a variable number of arguments.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// vfprintf(resource $stream, string $format, array $values): int
// ===== CODE
$return_vfprintf = vfprintf(

$stream, // resource stream

$format, // string format - The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.
// A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier.
// Argnum
// An integer followed by a dollar sign $, to specify which number argument to treat in the conversion.
// Flags
// Flag    - Description
// -       - Left-justify within the given field width; Right justification is the default
// +       - Prefix positive numbers with a plus sign +; Default only negative are prefixed with a negative sign.
// (space) - Pads the result with spaces. This is the default.
// 0       - Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros.
// '(char) - Pads the result with the character (char).
// Width
// Either an integer that says how many characters (minimum) this conversion should result in, or *. If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.
// Precision
// A period . optionally followed by either an integer or *, whose meaning depends on the specifier:
// * For e, E, f and F specifiers : this is the number of digits to be printed after the decimal point (by default, this is 6).
// * For g, G, h and H specifiers : this is the maximum number of significant digits to be printed.
// * For s specifier              : it acts as a cutoff point, setting a maximum character limit to the string.
// Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.
// Specifiers
// Specifier - Description
// %         - A literal percent character. No argument is required.
// b         - The argument is treated as an integer and presented as a binary number.
// c         - The argument is treated as an integer and presented as the character with that ASCII.
// d         - The argument is treated as an integer and presented as a (signed) decimal number.
// e         - The argument is treated as scientific notation (e.g. 1.2e+2).
// E         - Like the e specifier but uses uppercase letter (e.g. 1.2E+2).
// f         - The argument is treated as a float and presented as a floating-point number (locale aware).
// F         - The argument is treated as a float and presented as a floating-point number (non-locale aware).
// g         - General format.
//             Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
//             If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
// G         - Like the g specifier but uses E and f.
// h         - Like the g specifier but uses F. Available as of PHP 8.0.0.
// H         - Like the g specifier but uses E and F. Available as of PHP 8.0.0.
// o         - The argument is treated as an integer and presented as an octal number.
// s         - The argument is treated and presented as a string.
// u         - The argument is treated as an integer and presented as an unsigned decimal number.
// x         - The argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).
// X         - The argument is treated as an integer and presented as a hexadecimal number (with uppercase letters).
// Warning: The c type specifier ignores padding and width
// Warning: Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
// Variables will be co-erced to a suitable type for the specifier:
// Type Handling
// Type   - Specifiers
// string - s
// int    - d, u, c, o, x, X, b
// float  - e, E, f, F, g, G, h, H

$values //  array values

); // Return Values
// Returns the length of the outputted string.
// 
// Errors/Exceptions
// As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
// 
// Changelog
// Version - Description
// 8.0.0   - This function no longer returns false on failure.
// 8.0.0   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError when less arguments are given than required; previously this function emitted a E_WARNING instead.
// 
// [examples]
// Examples
// [example]
// Example #1 vfprintf(): zero-padded integers
// [php]
// if (!($fp = fopen('date.txt', 'w')))
//     return;
// 
// vfprintf($fp, "%04d-%02d-%02d", array($year, $month, $day));
// // will write the formatted ISO date to date.txt
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-17)
// URL: https://www.php.net/manual/en/function.vfprintf.php
// ========== VFPRINTF - END

// SYNTAX:
// int vfprintf(resource $stream, string $format, array $values)

return $return_vfprintf; // int
}
*/
// ============================== END
//   PHP_TEXT_STRINGS_VFPRINTF   
// ==============================


// ============================== BEGIN
//    PHP_TEXT_STRINGS_VPRINTF    
// ============================== PUBLIC
// ============================== ABOUT
// Output a formatted string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// vprintf() - PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_vprintf($format, $values)
{
$return_vprintf = 0;

// ========== VPRINTF - BEGIN
// ===== ABOUT
// Output a formatted string
// ===== DESCRIPTION
// Display array values as a formatted string according to format (which is described in the documentation for sprintf()).
// Operates as printf() but accepts an array of arguments, rather than a variable number of arguments.
// ===== SUPPORTED
// PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// vprintf(string $format, array $values): int
// ===== CODE
$return_vprintf = vprintf(

$format, // string format - The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.
// A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier.
// Argnum
// An integer followed by a dollar sign $, to specify which number argument to treat in the conversion.
// Flags
// Flag    - Description
// -       - Left-justify within the given field width; Right justification is the default
// +       - Prefix positive numbers with a plus sign +; Default only negative are prefixed with a negative sign.
// (space) - Pads the result with spaces. This is the default.
// 0       - Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros.
// '(char) - Pads the result with the character (char).
// Width
// Either an integer that says how many characters (minimum) this conversion should result in, or *. If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.
// Precision
// A period . optionally followed by either an integer or *, whose meaning depends on the specifier:
// * For e, E, f and F specifiers : this is the number of digits to be printed after the decimal point (by default, this is 6).
// * For g, G, h and H specifiers : this is the maximum number of significant digits to be printed.
// * For s specifier              : it acts as a cutoff point, setting a maximum character limit to the string.
// Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.
// Specifiers
// Specifier - Description
// %         - A literal percent character. No argument is required.
// b         - The argument is treated as an integer and presented as a binary number.
// c         - The argument is treated as an integer and presented as the character with that ASCII.
// d         - The argument is treated as an integer and presented as a (signed) decimal number.
// e         - The argument is treated as scientific notation (e.g. 1.2e+2).
// E         - Like the e specifier but uses uppercase letter (e.g. 1.2E+2).
// f         - The argument is treated as a float and presented as a floating-point number (locale aware).
// F         - The argument is treated as a float and presented as a floating-point number (non-locale aware).
// g         - General format.
//             Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
//             If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
// G         - Like the g specifier but uses E and f.
// h         - Like the g specifier but uses F. Available as of PHP 8.0.0.
// H         - Like the g specifier but uses E and F. Available as of PHP 8.0.0.
// o         - The argument is treated as an integer and presented as an octal number.
// s         - The argument is treated and presented as a string.
// u         - The argument is treated as an integer and presented as an unsigned decimal number.
// x         - The argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).
// X         - The argument is treated as an integer and presented as a hexadecimal number (with uppercase letters).
// Warning: The c type specifier ignores padding and width
// Warning: Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
// Variables will be co-erced to a suitable type for the specifier:
// Type Handling
// Type   - Specifiers
// string - s
// int    - d, u, c, o, x, X, b
// float  - e, E, f, F, g, G, h, H

$values //  array values

); // Return Values
// Returns the length of the outputted string.
// 
// Errors/Exceptions
// As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
// 
// Changelog
// Version - Description
// 8.0.0   - This function no longer returns false on failure.
// 8.0.0   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError when less arguments are given than required; previously this function emitted a E_WARNING instead.
// 
// [examples]
// Examples
// [example]
// Example #1 vprintf(): zero-padded integers
// [php]
// vprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
// [/php]
// The above example will output:
// [result]
// 1988-08-01
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.vprintf.php
// ========== VPRINTF - END

// SYNTAX:
// int vprintf(string $format, array $values)

return $return_vprintf; // int
}
// ============================== END
//    PHP_TEXT_STRINGS_VPRINTF    
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_VSPRINTF   
// ============================== PUBLIC
// ============================== ABOUT
// Return a formatted string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// vsprintf() - PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_vsprintf($format, $values)
{
$return_vsprintf = null;

// ========== VSPRINTF - BEGIN
// ===== ABOUT
// Return a formatted string
// ===== DESCRIPTION
// Operates as sprintf() but accepts an array of arguments, rather than a variable number of arguments.
// ===== SUPPORTED
// PHP_4 >= PHP_4_1_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// vsprintf(string $format, array $values): string
// ===== CODE
$return_vsprintf = vsprintf(

$format, // string format - The format string is composed of zero or more directives: ordinary characters (excluding %) that are copied directly to the result and conversion specifications, each of which results in fetching its own parameter.
// A conversion specification follows this prototype: %[argnum$][flags][width][.precision]specifier.
// Argnum
// An integer followed by a dollar sign $, to specify which number argument to treat in the conversion.
// Flags
// Flag    - Description
// -       - Left-justify within the given field width; Right justification is the default
// +       - Prefix positive numbers with a plus sign +; Default only negative are prefixed with a negative sign.
// (space) - Pads the result with spaces. This is the default.
// 0       - Only left-pads numbers with zeros. With s specifiers this can also right-pad with zeros.
// '(char) - Pads the result with the character (char).
// Width
// Either an integer that says how many characters (minimum) this conversion should result in, or *. If * is used, then the width is supplied as an additional integer value preceding the one formatted by the specifier.
// Precision
// A period . optionally followed by either an integer or *, whose meaning depends on the specifier:
// * For e, E, f and F specifiers: this is the number of digits to be printed after the decimal point (by default, this is 6).
// * For g, G, h and H specifiers: this is the maximum number of significant digits to be printed.
// * For s specifier: it acts as a cutoff point, setting a maximum character limit to the string.
// Note: If the period is specified without an explicit value for precision, 0 is assumed. If * is used, the precision is supplied as an additional integer value preceding the one formatted by the specifier.
// Specifiers
// Specifier - Description
// %         - A literal percent character. No argument is required.
// b         - The argument is treated as an integer and presented as a binary number.
// c         - The argument is treated as an integer and presented as the character with that ASCII.
// d         - The argument is treated as an integer and presented as a (signed) decimal number.
// e         - The argument is treated as scientific notation (e.g. 1.2e+2).
// E         - Like the e specifier but uses uppercase letter (e.g. 1.2E+2).
// f         - The argument is treated as a float and presented as a floating-point number (locale aware).
// F         - The argument is treated as a float and presented as a floating-point number (non-locale aware).
// g         - General format.
//             Let P equal the precision if nonzero, 6 if the precision is omitted, or 1 if the precision is zero. Then, if a conversion with style E would have an exponent of X:
//             If P > X ≥ −4, the conversion is with style f and precision P − (X + 1). Otherwise, the conversion is with style e and precision P − 1.
// G         - Like the g specifier but uses E and f.
// h         - Like the g specifier but uses F. Available as of PHP 8.0.0.
// H         - Like the g specifier but uses E and F. Available as of PHP 8.0.0.
// o         - The argument is treated as an integer and presented as an octal number.
// s         - The argument is treated and presented as a string.
// u         - The argument is treated as an integer and presented as an unsigned decimal number.
// x         - The argument is treated as an integer and presented as a hexadecimal number (with lowercase letters).
// X         - The argument is treated as an integer and presented as a hexadecimal number (with uppercase letters).
// Warning: The c type specifier ignores padding and width
// Warning: Attempting to use a combination of the string and width specifiers with character sets that require more than one byte per character may result in unexpected results
// Variables will be co-erced to a suitable type for the specifier:
// Type Handling
// Type   - Specifiers
// string - s
// int    - d, u, c, o, x, X, b
// float  - e, E, f, F, g, G, h, H

$values //  array values

); // Return Values
// Return array values as a formatted string according to format.
// 
// Errors/Exceptions
// As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX. Prior to PHP 8.0.0, a E_WARNING was emitted instead.
// As of PHP 8.0.0, a ValueError is thrown when less arguments are given than required. Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
// 
// Changelog
// Version - Description
// 8.0.0   - This function no longer returns false on failure.
// 8.0.0   - Throw a ValueError if the number of arguments is zero; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [width] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError if [precision] is less than zero or bigger than PHP_INT_MAX; previously this function emitted a E_WARNING instead.
// 8.0.0   - Throw a ValueError when less arguments are given than required; previously this function emitted a E_WARNING instead.
// 
// [examples]
// Examples
// [example]
// Example #1 vsprintf(): zero-padded integers
// [php]
// print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
// [/php]
// The above example will output:
// [result]
// 1988-08-01
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-16)
// URL: https://www.php.net/manual/en/function.vsprintf.php
// ========== VSPRINTF - END

// SYNTAX:
// string vsprintf(string $format, array $values)

return $return_vsprintf; // string
}
// ============================== END
//   PHP_TEXT_STRINGS_VSPRINTF   
// ==============================


// ============================== BEGIN
//   PHP_TEXT_STRINGS_WORDWRAP   
// ============================== PUBLIC
// ============================== ABOUT
// Wraps a string to a given number of characters.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// wordwrap() - PHP_4 >= PHP_4_0_2, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_text_strings_wordwrap($string, $width = 75, $break = "\n", $cut_long_words = false)
{
$return_wordwrap = null;

// ========== WORDWRAP - BEGIN
// ===== ABOUT
// Wraps a string to a given number of characters
// ===== DESCRIPTION
// Wraps a string to a given number of characters using a string break character.
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_2, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// wordwrap(
//    string $string,
//    int $width = 75,
//    string $break = "\n",
//    bool $cut_long_words = false
// ): string
// ===== CODE
$return_wordwrap = wordwrap(

$string, // string string - The input string.

$width, // int width - The number of characters at which the string will be wrapped.

$break, // string break - The line is broken using the optional break parameter.

$cut_long_words // bool cut_long_words - If the cut_long_words is set to true, the string is always wrapped at or before the specified width. So if you have a word that is larger than the given width, it is broken apart. (See second example). When false the function does not split the word even if the width is smaller than the word width.

); // Return Values
// Returns the given string wrapped at the specified length.
// 
// [examples]
// Examples
// [example]
// Example #1 wordwrap() example
// [php]
// $text = "The quick brown fox jumped over the lazy dog.";
// $newtext = wordwrap($text, 20, "<br />\n");
// 
// echo $newtext;
// [/php]
// The above example will output:
// [result]
// The quick brown fox<br />
// jumped over the lazy<br />
// dog.
// [/result]
// [/example]
// [example]
// Example #2 wordwrap() example
// [php]
// $text = "A very long woooooooooooord.";
// $newtext = wordwrap($text, 8, "\n", true);
// 
// echo "$newtext\n";
// [/php]
// The above example will output:
// [result]
// A very
// long
// wooooooo
// ooooord.
// [/result]
// [/example]
// [example]
// Example #3 wordwrap() example
// [php]
// $text = "A very long woooooooooooooooooord. and something";
// $newtext = wordwrap($text, 8, "\n", false);
// 
// echo "$newtext\n";
// [/php]
// The above example will output:
// [result]
// A very
// long
// woooooooooooooooooord.
// and
// something
// [/result]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-18)
// URL: https://www.php.net/manual/en/function.wordwrap.php
// ========== WORDWRAP - END

// SYNTAX:
// string wordwrap(string $string, int $width = 75, string $break = "\n", bool $cut_long_words = false)

return $return_wordwrap; // string
}
// ============================== END
//   PHP_TEXT_STRINGS_WORDWRAP   
// ==============================


// ============================== END
//        PHP_TEXT_STRINGS        
// ==============================
?>