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
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: matteosistisette at gmail dot com
New email:
PHP Version: OS:

 

 [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 Jun 24 22:01:28 2024 UTC