diff --git a/chapters/tutorial.xml b/chapters/tutorial.xml index d6cd931bfb..25927df15c 100644 --- a/chapters/tutorial.xml +++ b/chapters/tutorial.xml @@ -1,5 +1,5 @@ - + A simple tutorial @@ -322,7 +322,134 @@ if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) { if the string MSIE was found or not. + + + How to read a function definition (prototype) + + Each function is documented for quick reference, knowing how + to read and understand the manual will make using PHP + much easier. Rather than relying on examples or cut/paste, you want + to know how to read function definitions (prototypes). Let's begin: + + + + Prerequisite: Basic understanding of <link linkend="language.types">types</link> + + + Although PHP is a loosly typed language, it's important to have + a basic understanding of types as + they have important meaning. + + + + Function definitions tell us what + type of value is returned, + let's use the definition for strlen as our first example: + + + +strlen +(PHP 3, PHP 4 >= 4.0.0) +strlen -- Get string length + +Description +int strlen ( string str ) + +Returns the length of string. + + + + + Explanation of a function definition + + + + Part + Description + + + + + + strlen + + + The function name. + + + + + (PHP 3, PHP 4 >= 4.0.0) + + + strlen() has been around in both all of PHP 3 and PHP 4 + + + + + int + + + Type of value this function returns, which is an + integer + (i.e. The length of a string is measured in numbers). + + + + + ( string str ) + + + The first (and in this case the only) parameter/argument for the + function strlen is named str, and it's a + string. + + + + +
+ + + We could rewrite the above function definition in a generic way: + + + + returned type function name ( parameter type parameter name ) + + + + Many functions take on multiple parameters, such as in_array. + It's prototype is as follows: + + + + bool in_array ( mixed needle, array haystack [, bool strict]) + + + + What does this mean? in_array() returns a + boolean value, &true; on + success (the needle was found in the + haystack) or &false; on failure (the + needle was not found in the + haystack). The first parameter is named + needle and it can be many different + types, so we call it + "mixed". This mixed needle + (what we're looking for) can either be a scalar value (string, integer, + or float), or an + array. + haystack (the array we're searching in) is the + second parameter. The third optional parameter is + named strict. All optional parameters are seen + in [ brackets ]. The manual + states that the strict parameter defaults to + boolean &false;. See the manual page on each function for details on + how they work. + + + Dealing with Forms