|
HTML clipboard
The php manual
Finding a function description
How to read a function description
Function description for sort ()
1. The php manual
On the official homepage of php you get besides the source code and downloads of
php so the manual of php. It contains some basic information about php like
installation and security but also a list of all functions which exists in php.
These functions are grouped together in groups like String or MySQL.
2. Finding a function description
There are a lot of function descriptions in the manual, however you must find
the right one for you. First you should check the whole function reference,
specially in the function groups. A function which should sort an array would be
found in the group arrays, a function to change a text in a string would be
found in the group strings. In such a group there is a list of all functions
which belongs to it. Each function got a short description what they do. As an
example you will find the group inside the function array sort with the short
description Sort an array A click on this function gets you the description.
The easiest way for beginners (and the most annoying way for any forum
moderators or helpers) is to simply ask in a forum or chat.
<user> I have a problem, I have an array in php but the values are not sorted in
any way.
How can I sort the array?
<helper> sort
<helper2> with usort
<helper3> www.php.net do you know?
<helber4> try it with sort ()
You have ben kicked from # helpchannel by operator3 (sort (), and next time
check the manual at www.php.net / manual)
In most cases its just a function name. There are several ways to get the
function description out of the manual.
On the homepage there is a link documentation in the upper manual which gets you
to the manual. As the manual is translated into several language alyways you
should use the english version, as this is the most up to date version. Inside
the english version is a chapter called Function Reference. As the function may
be a function for array the function may be in the arrays "section. At the
bottom of this there is a sorted list of functions in this group. There you find
the function sort with the description Sort an array Click on it and you get to
the detailed description.
On the homepage is an input field in the top right corner which allow you to
search on the homepage. It searches in the reference function by default but can
also be changed to search in the bug database or on the whole site. You can
enter the function name inside the search function and get the description or a
search result list with functions which sounds similar to the one entered.
The simpliest way is to open the url http://www.php.net/FUNCTIONNAME where
FUNCTIONNAME is the function to search for. This call automatically starts the
search and redirects you to the function description.
3. How to read a function description
As you may want to read the function description in your native language you
should however read it in english to get the most up to date version of the
description. This can be done in English by selecting the drop down list in the
top of the page.
After the name of the function there is an expression which shows php version in
which this function exists and a short description of the function.
Now the detailed function description is followed. It starts with the function
signature. It contains the return value, name of the function and the parameter
list. The return value shows what kind of data the function is returning. The
value void means no value is returned. The parameter list shows which parameters
can be used. Every parameter syntax got the type $name $ type $name or $ type
&$name & type &$name The type which shows the parameter type should be. There
are some special types which does not exists in php like number for a float or
int number. A list of all pseudo-types can be found at Pseudo-types and
variables used in this documenation. After the type there is the name of the
parameter. This name is also used in the function description itself. If there
is a and the parameter is used as a reference. If this is the case the parameter
must be a variable (and can not be a static value) and the function changes the
content of the variable. Without the & just a copy of the parameter is send to
the function. If a parameter is written in brackets the parameter is optional.
After the function signature there is the description about the function and its
parameters. It use the same parameter names as in the parameter list above.
These parameters are written in a monospace italic font. The detailed function
description so contains some examples how to use the function and a detailed
list of all parameters and how they work.
The return value is explained in a separate section. For a return value of void
this section is omitted, for a return value of mixed there is a lot of text
which descripe when which type is returned by this function.
There is also a changelog which explains which parameters are implemented since
which php version and how a function worked before or after a given php version.
The most functions got cross references to other similar functions. Maybe you
read a function description which is not exactly what you want but may find the
right function in the cross reference.
At the end there are user comments for each function. These explain some hints
how to use the function and provides you with a lot of examples and experiance.
4. Function description for sort ()
As an example we explain the function description for sort. This function exists
in the php php4 and php5 versions and according to the short description This
function is used to sort an array.
The function signature explain this function returns a boolean value, the first
parameter must be an array and the second parameter must be an integer value, if
given. Independent how the function works program following all lines are
possible.
<? php
$ a = array (4, 6, 10, - 4);
$ ret = sort ($ a);
$ ret = sort ($ a, 4);
$ ret = sort ($ a, 0);
sort ($ a, - 400);
sort ($ a, 9 * 30-5);
sort ($ a, $ a [0]); / / possible as $ a [0] got the value int (4)
?>
The function got a text description which explains what the function do. In this
case the array it sorts ascending. Further it says it returns true if the array
is sorted or false if there was an error.
Since the second parameter can be any integer value only some of them makes
sense. The description explains that you should use the values SORT_REGULAR,
SORT_NUMERIC, SORT_STRING or SORT_LOCALE_STRING to get the given behavior of the
function. It looks like these values are strings and the function should be
called with sort($a, "SORT_NUMERIC"); ($ sort($a, "SORT_NUMERIC"); "SORT_NUMERIC"),
but thats not true. First, the second parameter must be an integer, not a second
string, parameters or values written in uppercase are normally constants in php.
If you check the group arrays again you see a list of predefined constants which
got the constants mentioned above. So you can use this function constants for
your call.
<? php
sort ($ a, SORT_STRING);
sort ($ a, SORT_NUMERIC);
?>
|
