svn: /phpdoc/en/trunk/reference/filesystem/functions/ pathinfo.xml
| From: | Mike Ford | 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>