Moving section on "How to read a function definition" here from tutorial.xml

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@97337 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2002-09-29 03:39:23 +00:00
parent 152b6ee663
commit 244993c775

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- $Revision: 1.17 $ -->
<!--
TODO: add manual conventions section (eg. how to read
@ -111,6 +111,133 @@
</para>
</note>
</sect1>
<sect1 id="about.prototypes">
<title>How to read a function definition (prototype)</title>
<para>
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:
</para>
<note>
<title>
Prerequisite: Basic understanding of <link linkend="language.types">types</link>
</title>
<para>
Although PHP is a loosly typed language, it's important to have
a basic understanding of <link linkend="language.types">types</link> as
they have important meaning.
</para>
</note>
<para>
Function definitions tell us what
type of value is <link linkend="functions.returning-values">returned</link>,
let's use the definition for <function>strlen</function> as our first example:
</para>
<para>
<screen role="html">
strlen
(PHP 3, PHP 4 >= 4.0.0)
strlen -- Get string length
Description
int strlen ( string str )
Returns the length of string.
</screen>
</para>
<para>
<table>
<title>Explanation of a function definition</title>
<tgroup cols="2">
<thead>
<row>
<entry>Part</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>
strlen
</entry>
<entry>
The function name.
</entry>
</row>
<row>
<entry>
(PHP 3, PHP 4 >= 4.0.0)
</entry>
<entry>
strlen() has been around in both all of PHP 3 and PHP 4
</entry>
</row>
<row>
<entry>
int
</entry>
<entry>
Type of value this function returns, which is an
<link linkend="language.types.integer">integer</link>
(i.e. The length of a string is measured in numbers).
</entry>
</row>
<row>
<entry>
( string str )
</entry>
<entry>
The first (and in this case the only) parameter/argument for the
function strlen() is named <parameter>str</parameter>, and it's a
<link linkend="language.types.string">string</link>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
We could rewrite the above function definition in a generic way:
</para>
<para>
<screen role="html">
returned type function name ( parameter type parameter name )
</screen>
</para>
<para>
Many functions take on multiple parameters, such as <function>in_array</function>.
It's prototype is as follows:
</para>
<para>
<screen role="html">
bool in_array ( mixed needle, array haystack [, bool strict])
</screen>
</para>
<para>
What does this mean? in_array() returns a
<link linkend="language.types.boolean">boolean</link> value, &true; on
success (the <parameter>needle</parameter> was found in the
<parameter>haystack</parameter>) or &false; on failure (the
<parameter>needle</parameter> was not found in the
<parameter>haystack</parameter>). The first parameter is named
<parameter>needle</parameter> and it can be many different
<link linkend="language.types">types</link>, so we call it
"<emphasis>mixed</emphasis>". This mixed <parameter>needle</parameter>
(what we're looking for) can either be a scalar value (string, integer,
or <link linkend="language.types.float">float</link>), or an
<link linkend="language.types.array">array</link>.
<parameter>haystack</parameter> (the array we're searching in) is the
second parameter. The third <emphasis>optional</emphasis> parameter is
named <parameter>strict</parameter>. All optional parameters are seen
in <emphasis>[</emphasis> brackets <emphasis>]</emphasis>. The manual
states that the <parameter>strict</parameter> parameter defaults to
boolean &false;. See the manual page on each function for details on
how they work.
</para>
</sect1>
<sect1 id="about.more">
<title>How to find more information about PHP</title>