cvs: phpdoc /en/functions array.xml

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>.