svn: /phpdoc/en/trunk/reference/filesystem/functions/ pathinfo.xml

From: Date: Thu, 28 Jul 2011 15:09:43 +0000
Subject: svn: /phpdoc/en/trunk/reference/filesystem/functions/ pathinfo.xml
Groups: php.doc.cvs 
Request: Send a blank email to doc-cvs+get-8550@lists.php.net to get a copy of this message
mgf Thu, 28 Jul 2011 15:09:43 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=313876 Log: Clarify purpose of options parameter, be more explicit about return values; extra example; miscellaneous tidy ups. Changed paths: U phpdoc/en/trunk/reference/filesystem/functions/pathinfo.xml Modified: phpdoc/en/trunk/reference/filesystem/functions/pathinfo.xml =================================================================== --- phpdoc/en/trunk/reference/filesystem/functions/pathinfo.xml 2011-07-28 15:07:00 UTC (rev 313875) +++ phpdoc/en/trunk/reference/filesystem/functions/pathinfo.xml 2011-07-28 15:09:43 UTC (rev 313876) @@ -14,8 +14,9 @@ <methodparam choice="opt"><type>int</type><parameter>options</parameter><initializer>PATHINFO_DIRNAME | PATHINFO_BASENAME | PATHINFO_EXTENSION | PATHINFO_FILENAME</initializer></methodparam> </methodsynopsis> <para> - <function>pathinfo</function> returns an associative array - containing information about <parameter>path</parameter>. + <function>pathinfo</function> returns information about + <parameter>path</parameter>: either an associative array or a string, + depending on <parameter>options</parameter>. </para> </refsect1> @@ -27,7 +28,7 @@ <term><parameter>path</parameter></term> <listitem> <para> - The path being checked. + The path to be parsed. </para> </listitem> </varlistentry> @@ -35,14 +36,15 @@ <term><parameter>options</parameter></term> <listitem> <para> - You can specify which elements are returned with optional parameter - <parameter>options</parameter>. It composes from + If present, specifies a specific element to be returned; one of <constant>PATHINFO_DIRNAME</constant>, <constant>PATHINFO_BASENAME</constant>, - <constant>PATHINFO_EXTENSION</constant> and - <constant>PATHINFO_FILENAME</constant>. It - defaults to return all elements. + <constant>PATHINFO_EXTENSION</constant> or + <constant>PATHINFO_FILENAME</constant>. </para> + <para>If <parameter>options</parameter> is not specified, returns all + available elements. + </para> </listitem> </varlistentry> </variablelist> @@ -52,13 +54,22 @@ <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - The following associative <type>array</type> elements are returned: + If the <parameter>options</parameter> parameter is not passed, an + associative <type>array</type> containing the following elements is + returned: <literal>dirname</literal>, <literal>basename</literal>, <literal>extension</literal> (if any), and <literal>filename</literal>. </para> + <note> + <para> + If the <parameter>path</parameter> does not have an extension, no + <literal>extension</literal> element will be returned + (see second example below). + </para> + </note> <para> - If <parameter>options</parameter> is used, this function will return a - <type>string</type> if not all elements are requested. + If <parameter>options</parameter> is present, returns a + <type>string</type> containing the requested element. </para> </refsect1> @@ -114,6 +125,30 @@ </screen> </example> </para> + <para> + <example> + <title><function>pathinfo</function> example showing difference between null and no extension</title> + <programlisting role="php"> +<![CDATA[ +<?php +$path_parts = pathinfo('/path/nullextension.'); +var_dump($path_parts['extension']); + +$path_parts = pathinfo('/path/noextension'); +var_dump($path_parts['extension']); +?> +]]> + </programlisting> + &example.outputs.similar; + <screen> +<![CDATA[ +string(0) "" + +Notice: Undefined index: extension in /test.php on line 6 +]]> + </screen> + </example> + </para> </refsect1> <refsect1 role="notes"> @@ -127,8 +162,8 @@ </note> <note> <para> - <function>pathinfo</function> is locale aware, so for it to parse the path - correctly with multibyte character, the matching locale must be set using + <function>pathinfo</function> is locale aware, so for it to parse a path + containing multibyte characters correctly, the matching locale must be set using the <function>setlocale</function> function. </para> </note>

« previous php.doc.cvs (#8550) next »