rasmus Fri Jan 25 04:26:58 2002 EDT
Modified files:
/phpdoc/en/functions array.xml
Log:
extract() doc updates
Index: phpdoc/en/functions/array.xml
diff -u phpdoc/en/functions/array.xml:1.153 phpdoc/en/functions/array.xml:1.154
--- phpdoc/en/functions/array.xml:1.153 Sat Jan 19 17:02:15 2002
+++ phpdoc/en/functions/array.xml Fri Jan 25 04:26:58 2002
@@ -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 @@
<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 @@
</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 @@
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 @@
<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 @@
<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 @@
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 @@
</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>.
