Do you feel bad because of the Python docs?

[Steven D'Aprano]

On Tue, 26 Feb 2013 17:48:27 +0000, MRAB wrote:

> On 2013-02-26 14:26, Chris Angelico wrote:
>> On Wed, Feb 27, 2013 at 12:56 AM, Roy Smith <roy at panix.com> wrote:
>>> When people ask PHP questions, the questions tend to be phrased as
>>> "what do I type to get X", and the answers come back that way too. 
>>> The forums are full of, "I had the same problem.  Somebody told me to
>>> do this.  I don't really understand it, but it worked for me and maybe
>>> it'll work for you too".
>>
>> A problem that's majorly exacerbated by the myriad ways of doing some
>> things, with some of those ways deprecated and others theoretically
>> plausible but hopelessly impractical.
>>
>> Here's an actual example that came up today at work. Suppose you have a
>> user-provided string that's supposed to contain a URL, and you need to
>> ensure that it doesn't have a trailing slash, so you can later add
>> "/foo" or "/bar". (Or alternatively, ensure that it DOES have a
>> trailing slash. Either works.) Start the timer, go find out how to do
>> it. Assume you are broadly familiar with PHP, and know how to do the
>> basics of string handling, and are competent at searching the web.
>> Ready? Go!
>>
>> I'll wait for you to come back.
>>
>> ... Okay, some of you are back now. Just giving the stragglers time to
>> finish losing their marbles...
>>
>> Alright. Here's what I found in a recreation of today's search. Google
>> search: php last character of string
>>
>> http://php.net/manual/en/function.substr.php -- okay, so I can use
>> substr, but not string indexing, to find out what the last character is
>> -- "Returns the extracted part of string; or FALSE on failure, or an
>> empty string." What kind of failures result in FALSE, and what kind in
>> an empty string?
>>
> [snip]
> The page http://php.net/manual/en/function.substr.php says:
> 
>      Description
>          string substr ( string $string , int $start [, int $length ] )
> 
> OK. It then goes on to say:
> 
>      Parameters
>          string
>              The input string. Must be one character or longer.
> 
> What? The input string can't be an empty string?

Huh, this is PHP. You're lucky it doesn't say:

"The input string. Must be one character or longer, except for the case-
insensitive string 'something-magical-happens-here'."

*wink*


-- 
Steven