From e4a006c351d09dfdb5faf5f271c5e14ef66a25d7 Mon Sep 17 00:00:00 2001
From: Philip Olson <philip@php.net>
Date: Fri, 27 Sep 2002 20:18:30 +0000
Subject: [PATCH] Added section on "How to read a function definition
(prototype)" # One day this will go in "About the manual", when the PDF is
fixed ;)
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@97165 c90b9560-bf6c-de11-be94-00142212c4b1
---
chapters/tutorial.xml | 129 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 128 insertions(+), 1 deletion(-)
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 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
<chapter id="tutorial">
<title>A simple tutorial</title>
@@ -322,7 +322,134 @@ if (strstr($_SERVER["HTTP_USER_AGENT"], "MSIE")) {
if the string <literal>MSIE</literal> was found or not.
</para>
</sect1>
+
+ <sect1 id="tutorial.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="tutorial.forms">
<title>Dealing with Forms</title>
<para>