php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #78393 Incorrectly specified behavior
Submitted: 2019-08-09 14:53 UTC Modified: 2020-03-15 22:27 UTC
Votes:2
Avg. Score:4.0 ± 1.0
Reproduced:2 of 2 (100.0%)
Same Version:2 (100.0%)
Same OS:2 (100.0%)
From: dmorgan at adobe dot com Assigned:
Status: Open Package: Strings related
PHP Version: Irrelevant OS: n/a
Private report: No CVE-ID: None
 [2019-08-09 14:53 UTC] dmorgan at adobe dot com
Description:
------------
The documentation describes the operation of the method as follows:
"Returns a string with the first character of each word in str capitalized, if that character is alphabetic."

The documentation describes a word as follows:

"The definition of a word is any string of characters that is immediately after any character listed in the delimiters parameter (By default these are: space, form-feed, newline, carriage return, horizontal tab, and vertical tab)."

It should probably read more like:
"The definition of a word is any string of characters that is EITHER AT THE START OF STR, OR immediately after any character listed in the delimiters parameter (By default these are: space, form-feed, newline, carriage return, horizontal tab, and vertical tab)."

Alternatively, the first line could be changed to read something like:
"Returns a string with the first character of STR, AND THE FIRST CHARACTER OF each SUBSEQUENT word in str capitalized, if that character is alphabetic."

I would recommend, while you're in there, clarifying the first line by adding something like "All characters in the remainder of word are left unchanged." - many are caught out by interpreting this as a TitleCase method, so try to use this function to Title Case an UPPER CASE string, without first lowercasing it. You can see at least one such victim in the comments on the page.

Finally, I'd also recommend rigorously clarifying what's meant by "alphabetic", and how that definition might change with localization; and/or giving a clear pointer to a page where such a clarification is made (not just in the "see also" section!)

Test script:
---------------
php -r 'echo ucwords("foo_bar_BAZ", "_") . "\n";

Expected result:
----------------
If a word were indeed "any string of characters that is immediately after any character listed in the delimiters parameter", you'd expect the output of the above to be "foo_Bar_BAZ", or possibly "foo_Bar_Baz" without the optional clarification.

Actual result:
--------------
The output is instead "Foo_Bar_BAZ".

Note how the first character of the string is capitalized, even though it is NOT immediately after the delimiter '_' as stated in the documentation.

Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2020-03-15 22:27 UTC] cmb@php.net
-Summary: Incorrectly specified behavior. +Summary: Incorrectly specified behavior -Package: PHP Language Specification +Package: PDF related
 [2020-03-15 22:27 UTC] cmb@php.net
-Package: PDF related +Package: Strings related
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Wed Dec 04 22:01:29 2024 UTC