php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #72271 Collator::getSortKey() doc page is out of date, incomplete, inaccurate
Submitted: 2016-05-26 20:29 UTC Modified: 2020-04-10 12:42 UTC
From: pleasestand at live dot com Assigned: cmb (profile)
Status: Closed Package: intl (PECL)
PHP Version: master-Git-2016-05-26 (Git) OS:
Private report: No CVE-ID: None
Welcome back! If you're the original bug submitter, here's where you can edit the bug or add additional notes.
If this is not your bug, you can add a comment by following this link.
If this is your bug, but you forgot your password, you can retrieve your password here.
Password:
Status:
Package:
Bug Type:
Summary:
From: pleasestand at live dot com
New email:
PHP Version: OS:

 

 [2016-05-26 20:29 UTC] 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.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2020-04-10 12:42 UTC] 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
 [2020-04-10 12:42 UTC] cmb@php.net
-Status: Open +Status: Closed -Assigned To: +Assigned To: cmb
 [2020-04-10 12:42 UTC] cmb@php.net
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.
 [2020-04-10 12:44 UTC] phpdocbot@php.net
Automatic comment on behalf of cmb
Revision: http://git.php.net/?p=doc/en.git;a=commit;h=90d4bd6eaa6c9330ba6375b39852ab8eec58a80c
Log: Fix #72271: Collator::getSortKey() doc page is out of date, incomplete, inaccurate
 [2020-04-12 10:58 UTC] mumumu@php.net
Automatic comment from SVN on behalf of mumumu
Revision: http://svn.php.net/viewvc/?view=revision&amp;revision=349652
Log: Fix #72271: Collator::getSortKey() doc page is out of date, incomplete, inaccurate
 [2020-04-12 11:00 UTC] phpdocbot@php.net
Automatic comment on behalf of mumumu
Revision: http://git.php.net/?p=doc/ja.git;a=commit;h=aa5bb54df1ce8e8d986fcec8126b08de726e5374
Log: Fix #72271: Collator::getSortKey() doc page is out of date, incomplete, inaccurate
 
PHP Copyright © 2001-2020 The PHP Group
All rights reserved.
Last updated: Tue Nov 24 01:01:24 2020 UTC