extract() doc updates

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@68661 c90b9560-bf6c-de11-be94-00142212c4b1

functions/array.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.153 $ -->
+<!-- $Revision: 1.154 $ -->
  <reference id="ref.array">
   <title>Array Functions</title>
   <titleabbrev>Arrays</titleabbrev>
@@ -2693,7 +2693,7 @@ while (list ($key, $val) = each ($HTTP_POST_VARS)) {
    <refnamediv>
     <refname>extract</refname>
     <refpurpose>
-     Import variables into the symbol table from an array
+     Import variables into the current symbol table from an array
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -2712,7 +2712,7 @@ while (list ($key, $val) = each ($HTTP_POST_VARS)) {
     </funcsynopsis>
     <para>
      This function is used to import variables from an array into the
-     current symbol table.  It takes associative array
+     current symbol table.  It takes an associative array
      <parameter>var_array</parameter> and treats keys as variable
      names and values as variable values.  For each key/value pair it
      will create a variable in the current symbol table, subject to
@@ -2725,8 +2725,14 @@ while (list ($key, $val) = each ($HTTP_POST_VARS)) {
       variables extracted.
      </para>
     </note>
+    <note>
+     <para>
+      EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS was introduced in version 4.2.0.
+      variables extracted.
+     </para>
+    </note>
     <para>
-     <function>extract</function> checks each key to see whether if
+     <function>extract</function> checks each key to see whether it
      constitutes a valid variable name and also for collisions with
      existing variables in the symbol table. The way invalid/numeric
      keys and collisions are treated is determined by
@@ -2773,11 +2779,33 @@ while (list ($key, $val) = each ($HTTP_POST_VARS)) {
        <listitem>
         <simpara>
          Only prefix invalid/numeric variable names with
-         <parameter>prefix</parameter>. This flag has been added in
+         <parameter>prefix</parameter>. This flag was added in
          PHP 4.0.5.
         </simpara>
        </listitem>
       </varlistentry>
+      <varlistentry>
+       <term>EXTR_IF_EXISTS</term>
+       <listitem>
+        <simpara>
+         Only overwrite the variable if it already exists in the
+         current symbol table, otherwise do nothing.  This is useful
+         for defining a list of valid variables and then extracting
+         only those variables you have defined out of $_REQUEST, for
+         example.  This flag was added in PHP 4.2.0.
+        </simpara>
+       </listitem>
+      </varlistentry>
+      <varlistentry>
+       <term>EXTR_PREFIX_IF_EXISTS</term>
+       <listitem>
+        <simpara>
+         Only create prefixed variable names if the non-prefixed version
+         of the same variable exists in the current symbol table.  This
+         flag was added in PHP 4.2.0.
+        </simpara>
+       </listitem>
+      </varlistentry>
      </variablelist>
     </para>
     <para>
@@ -2787,16 +2815,16 @@ while (list ($key, $val) = each ($HTTP_POST_VARS)) {
     <para>
      Note that <parameter>prefix</parameter> is only required if
      <parameter>extract_type</parameter> is EXTR_PREFIX_SAME,
-     EXTR_PREFIX_ALL, or EXTR_PREFIX_INVALID. If the prefixed result
-     is not a valid variable name, it is not imported into the symbol
-     table.
+     EXTR_PREFIX_ALL, EXTR_PREFIX_INVALID or EXTR_PREFIX_IF_EXISTS. If 
+     the prefixed result is not a valid variable name, it is not 
+     imported into the symbol table.
     </para>
     <para>
      <function>extract</function> returns the number of variables
      successfully imported into the symbol table.
     </para>
     <para>
-     A possible use for extract is to import into symbol table
+     A possible use for extract is to import into the symbol table
      variables contained in an associative array returned by
      <function>wddx_deserialize</function>.
     </para>
@@ -2836,7 +2864,7 @@ blue, large, sphere, medium
      specified EXTR_PREFIX_SAME, which resulted in
      <varname>$wddx_size</varname> being created.  If EXTR_SKIP was
      specified, then $wddx_size wouldn't even have been created.
-     EXTR_OVERWRITE would have cause <varname>$size</varname> to have
+     EXTR_OVERWRITE would have caused <varname>$size</varname> to have
      value "medium", and EXTR_PREFIX_ALL would result in new variables
      being named <varname>$wddx_color</varname>,
      <varname>$wddx_size</varname>, and
@@ -2844,7 +2872,8 @@ blue, large, sphere, medium
     </para>
     <para>
      You must use an associative array, a numerically indexed array
-     will not produce results.
+     will not produce results unless you use EXTR_PREFIX_ALL or 
+     EXTR_PREFIX_INVALID.
     </para>
     <para>
      See also <function>compact</function>.