[Tutor] string.search [Documentation conventions]

[Danny Yoo]

On Wed, 5 Dec 2001, john public wrote:

> weeks ago. I have lived with many programmers in the past and I am
> realizing I learned some BASIC by osmosis. Once I find the right tool
> for the job, is there some online documentation that has a real
> example for everything. I checked Guido's tutorial and the Python
> reference library but could only find examples in the abstract.
>
> such as string.search(string,[,pos[,endpos]]) 

Ah!  I understand now.  It's a UNIX convention that when we describe
functions list this, we just braces to tell the user what parts are
optional.  One problem with a convention, though, is that it's not obvious
unless one hears about it.  *grin*

In an example like this, the braces are there to show that pos and endpos
are optional parameters --- you don't need to put braces in yourself.  
Let's take a look at the description of the string.find() function:

"""
find(s, sub[, start[,end]])

Return the lowest index in s where the substring sub is found such that
sub is wholly contained in s[start:end]. Return -1 on failure. Defaults
for start and end and interpretation of negative values is the same as for
slices.
"""

In this case, we don't have to feed in the last two parameters until we
want to.

###
>>> yourname = "john public"
>>> string.find(yourname, "public")
5
>>> string.find(yourname, "john")
0
>>> string.find(yourname, "john", 0)    ## Let's tell it to search from 0
0
>>> string.find(yourname, "john", 1)    ## Another search starting from 1.
-1
>>> string.find(yourname, "public", 0, -1)
-1
>>> string.find(yourname, "publi", 0, -1)
5
###


The last few examples show how we can fill in 'start' and 'end' so that
string.find() limits itself to the grounds we tell it.  In the last case,
we've told it: "You can start searching from the 0th position of yourname,
but only up to (and not including!) the very last -1th position."


Hope this helps!