[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-doc-cvs
Subject:    [DOC-CVS] =?utf-8?q?svn:_/phpdoc/en/trunk/reference/filesystem/functions/_pathinfo.xml?=
From:       Mike_Ford <mgf () php ! net>
Date:       2011-07-28 15:09:43
Message-ID: svn-mgf-1311865783-313876-1851189182 () svn ! php ! net
[Download RAW message or body]

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>



-- 
PHP Documentation Commits Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]