php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #65566 document default value of $length in substr()
Submitted: 2013-08-27 20:15 UTC Modified: 2013-08-27 20:25 UTC
From: matteosistisette at gmail dot com Assigned:
Status: Wont fix Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2013-08-27 20:15 UTC] 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).


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2013-08-27 20:25 UTC] aharvey@php.net
-Status: Open +Status: Wont fix
 [2013-08-27 20:25 UTC] aharvey@php.net
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.
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Mon May 20 00:01:31 2024 UTC