Doc #72271 [NEW]: Collator::getSortKey() doc page is out of date, incomplete, inaccurate

From: pleasestand at live dot com Operating system: PHP version: master-Git-2016-05-26 (Git) Package: intl Bug Type: Documentation Problem Bug description:Collator::getSortKey() doc page is out of date, incomplete, inaccurate 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 bug report at https://bugs.php.net/bug.php?id=72271&edit=1 -- Try a snapshot (PHP 5.4): https://bugs.php.net/fix.php?id=72271&r=trysnapshot54 Try a snapshot (PHP 5.5): https://bugs.php.net/fix.php?id=72271&r=trysnapshot55 Try a snapshot (trunk): https://bugs.php.net/fix.php?id=72271&r=trysnapshottrunk Fixed in SVN: https://bugs.php.net/fix.php?id=72271&r=fixed Fixed in release: https://bugs.php.net/fix.php?id=72271&r=alreadyfixed Need backtrace: https://bugs.php.net/fix.php?id=72271&r=needtrace Need Reproduce Script: https://bugs.php.net/fix.php?id=72271&r=needscript Try newer version: https://bugs.php.net/fix.php?id=72271&r=oldversion Not developer issue: https://bugs.php.net/fix.php?id=72271&r=support Expected behavior: https://bugs.php.net/fix.php?id=72271&r=notwrong Not enough info: https://bugs.php.net/fix.php?id=72271&r=notenoughinfo Submitted twice: https://bugs.php.net/fix.php?id=72271&r=submittedtwice register_globals: https://bugs.php.net/fix.php?id=72271&r=globals PHP 4 support discontinued: https://bugs.php.net/fix.php?id=72271&r=php4 Daylight Savings: https://bugs.php.net/fix.php?id=72271&r=dst IIS Stability: https://bugs.php.net/fix.php?id=72271&r=isapi Install GNU Sed: https://bugs.php.net/fix.php?id=72271&r=gnused Floating point limitations: https://bugs.php.net/fix.php?id=72271&r=float No Zend Extensions: https://bugs.php.net/fix.php?id=72271&r=nozend MySQL Configuration Error: https://bugs.php.net/fix.php?id=72271&r=mysqlcfg