Doc #65566 [Opn->Wfx]: document default value of $length in substr()
Edit report at https://bugs.php.net/bug.php?id=65566&edit=1
ID: 65566
Updated by: aharvey@php.net
Reported by: matteosistisette at gmail dot com
Summary: document default value of $length in substr()
-Status: Open
+Status: Wont fix
Type: Documentation Problem
Package: Documentation problem
PHP Version: Irrelevant
Block user comment: N
Private report: N
New Comment:
There are cases in PHP where the behaviour of a function is actually dependent
on the number of parameters passed in, rather than an optional parameter having
a simple default, and this is one of them.
The implementation of substr() is here: https://github.com/php/php-src/blob/php-
5.5.3/ext/standard/string.c#L2233 â if the length parameter is omitted, then the
default effectively becomes strlen($string). In theory, we could put this into
the function prototype as the default value, but I think that's going to be more
confusing than what's currently there.
If there's an obvious, constant default, then I agree that we should document
it, but there isn't in this case.
Previous Comments:
------------------------------------------------------------------------
[2013-08-27 20:15:46] matteosistisette at gmail dot com
Description:
------------
---
From manual page: http://www.php.net/function.substr#refsect1-function.substr-
parameters
---
"""
If length is given and is positive, the string returned will contain at most
length characters beginning from start (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
start is negative). If start denotes the position of this truncation or beyond,
false will be returned.
If length is given and is 0, FALSE or NULL an empty string will be returned.
If length is omitted, the substring starting from start until the end of the
string will be returned.
"""
And what if one needs to specify a value for length and obtain the last
behavior??
That is:
if (/*whatever*/) $length=/*something*/;
else if (/*whatever_else*/) $length=/*something else*/;
else if.....
//...
echo substr ($string, $start, $length);
I guess the solution is to set $length=PHP_INT_MAX.
But then it needs to be better documented by declaring it as the default value
for $length:
replace this:
string substr ( string $string , int $start [, int $length ] )
with this:
string substr ( string $string , int $start, int $length=PHP_INT_MAX )
Default values for all parameters must ALWAYS be documented, so that one can
ALWAYS know what value to pass to a function when one has to specify a value and
one wants the default behavior.
I have found the same problem in various pages of php's docs.
Actually there are cases worst than this (in this case, one can guess it).
------------------------------------------------------------------------
--
Edit this bug report at https://bugs.php.net/bug.php?id=65566&edit=1
Thread (2 messages)