cvs: phpdoc-ru /appendices about.xml
| From: | Alexander Voytsekhovskyy | Date: | Tue, 01 Jun 2004 14:50:16 +0000 |
| Subject: | cvs: phpdoc-ru /appendices about.xml | ||
| Groups: | php.doc.ru | ||
| Request: | Send a blank email to doc-ru+get-353@lists.php.net to get a copy of this message | ||
young Tue Jun 1 10:50:16 2004 EDT
Modified files:
/phpdoc-ru/appendices about.xml
Log:
Add two lost chapters to Appendix O. It will be translated soon.
http://cvs.php.net/diff.php/phpdoc-ru/appendices/about.xml?r1=1.3&r2=1.4&ty=u
Index: phpdoc-ru/appendices/about.xml
diff -u phpdoc-ru/appendices/about.xml:1.3 phpdoc-ru/appendices/about.xml:1.4
--- phpdoc-ru/appendices/about.xml:1.3 Wed Sep 4 15:20:38 2002
+++ phpdoc-ru/appendices/about.xml Tue Jun 1 10:50:16 2004
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="windows-1251"?>
<!-- EN-Revision: 1.16 Maintainer: tronic Status: ready -->
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!--
TODO: add manual conventions section (eg. how to read
@@ -119,6 +119,174 @@
</note>
</sect1>
+ <sect1 id="about.prototypes">
+ <title>How to read a function definition (prototype)</title>
+ <para>
+ Each function in the manual is documented for quick reference. Knowing how
+ to read and understand the text will make learning PHP
+ much easier. Rather than relying on examples or cut/paste, you will 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 loosely 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>
+strlen
+
+(PHP 3, PHP 4, PHP 5)
+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, PHP 5)
+ </entry>
+ <entry>
+ strlen() has been around in all versions of PHP 3, PHP 4 and PHP 5
+ </entry>
+ </row>
+ <row>
+ <entry>
+ int
+ </entry>
+ <entry>
+ Type of value this function returns, which is an
+ <type>integer</type> (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 this
+ function is named <parameter>str</parameter>, and it's a
+ <type>string</type>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ We could rewrite the above function definition in a generic way:
+ </para>
+ <para>
+ <screen>
+ returned type function name ( parameter type parameter name )
+ </screen>
+ </para>
+ <para>
+ Many functions take on multiple parameters, such as <function>in_array</function>.
+ Its prototype is as follows:
+ </para>
+ <para>
+ <screen>
+ 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 (if the <parameter>needle</parameter> was found in the
+ <parameter>haystack</parameter>) or &false; on failure (if the
+ <parameter>needle</parameter> was not found in the
+ <parameter>haystack</parameter>). The first parameter is named
+ <parameter>needle</parameter> and it can be of 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 be either 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>
+ <para>
+ There are also functions with more complex PHP version information. Take
+ <function>html_entity_decode</function> as an example:
+ </para>
+ <para>
+ <screen>
+ (PHP 4 >= 4.3.0, PHP 5)
+ </screen>
+ </para>
+ <para>
+ This means that this function was not available in PHP 3, and is only
+ available in a released version since PHP 4.3.0.
+ </para>
+ </sect1>
+
+ <sect1 id="about.phpversions">
+ <title>PHP versions documented in this manual</title>
+ <para>
+ This documentation contains information about bot PHP 4 and PHP 5, with
+ some added migration and compatibility notes regarding PHP 3. Behaviour,
+ parameter, return value and other changes between different PHP
+ versions are documented in notes and inline text in the manual.
+ </para>
+ <para>
+ You may find documentation pieces for the CVS version of PHP, which
+ always means the very latest development version available through
+ the CVS version handling system. If you are not a developer of PHP
+ itself, and you are not keen on using the very latest development
+ version of PHP, features marked with the "available in CVS" wording
+ are not accessible to you. These features, though, will probably be
+ available in the next stable version of PHP. If you would like to
+ download the CVS version, see the <ulink url="&url.php.anoncvs;">anonymous
+ CVS access page</ulink>.
+ </para>
+ <para>
+ You may also encounter documentation for a PHP version which is
+ not released (something like PHP 5.0.0 while the latest stable version
+ is 4.3.x). Most of the time, this is not an error in the documentation.
+ Explanation is often added for features not available in the current
+ PHP release, but which will be available in a known future PHP version.
+ </para>
+ </sect1>
+
<sect1 id="about.more">
<title>Êàê óçíàòü áîëüøå î PHP</title>
<para>