mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-16 00:48:54 +00:00
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
parent
152b6ee663
commit
244993c775
1 changed files with 128 additions and 1 deletions
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue