Doc #72271 [Opn->Csd]: Collator::getSortKey() doc page is out of date, incomplete, inaccurate

Edit report at https://bugs.php.net/bug.php?id=72271&edit=1 ID: 72271 Updated by: cmb@php.net Reported by: pleasestand at live dot com Summary: Collator::getSortKey() doc page is out of date, incomplete, inaccurate -Status: Open +Status: Closed Type: Documentation Problem Package: intl PHP Version: master-Git-2016-05-26 (Git) -Assigned To: +Assigned To: cmb Block user comment: N Private report: N New Comment: This bug has been fixed in the documentation's XML sources. Since the online and downloadable versions of the documentation need some time to get updated, we would like to ask you to be a bit patient. Thank you for the report, and for helping us make our documentation better. Previous Comments: ------------------------------------------------------------------------ [2020-04-10 12:42:06] cmb@php.net Automatic comment from SVN on behalf of cmb Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=349647 Log: Fix #72271: Collator::getSortKey() doc page is out of date, incomplete, inaccurate ------------------------------------------------------------------------ [2016-05-26 20:29:14] pleasestand at live dot com Description: ------------ I noticed some problems with the documentation for Collator::getSortKey() and collator_get_sort_key() at <https://secure.php.net/manual/en/collator.getsortkey.php>: 1. The function was not added in 5.3.11 but rather in 5.3.2, according to the changelog. 2. Example #1 shows a URL-encoded return value of "71%3F%3FE%01%09%01%8F%08%00". According to <http://userguide.icu-project.org/collation/api#TOC-GetSortKey>, there is no stability guarantee for sort keys. Recent ICU versions return a different value, so it is not necessarily true that "The above example will output" that value. Instead, the implementation-specific nature of sort keys should be noted. For example, the "Return Values" section could state, "Collation keys can be compared directly instead of strings, though are implementation specific and change between ICU library versions." Then the Example #1 section could state, "The above example will output (for ICU x.x):", where x.x is the version of ICU matching the example output (which can be changed). The version of ICU is available as INTL_ICU_VERSION (currently not documented at <https://secure.php.net/manual/en/intl.constants.php>). 3. Any version of PHP 5.3.15 or newer, or 5.4.5 or newer, or PECL intl 2.0.1 or newer, is not going to output that exact value, even when used with the same old version of ICU. The null byte at the end was the result of bug #62070, which was fixed in those PHP versions. The "%00" should be removed from the example output, and the behavior change introduced by the bug fix should be noted: now, returned sort keys will not contain *any* null bytes. While at it, it may also make sense to change from urlencode() to bin2hex(). 4. The "Return Values" section, in addition to the existing warning, should note that FALSE is returned if an error occurred. 5. For Example #1, there should be a space between the ")" and "example", and whitespace appears to be used inconsistently in the code. ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=72271&edit=1