CVS update: php3/doc/functions

Date: Thursday February 11, 1999 @ 1:23 Author: andrey Update of /repository/php3/doc/functions In directory asf:/u/temp/cvs-serv1088/doc/functions Modified Files: misc.sgml Log Message: Added extract() fucntion and docs for it. Feel free to suggest a different name for it. Index: php3/doc/functions/misc.sgml diff -c php3/doc/functions/misc.sgml:1.19 php3/doc/functions/misc.sgml:1.20 *** php3/doc/functions/misc.sgml:1.19 Wed Feb 3 22:34:52 1999 --- php3/doc/functions/misc.sgml Thu Feb 11 01:23:39 1999 *************** *** 119,124 **** --- 119,226 ---- </refsect1> </refentry> + <refentry id="function.extract"> + <refnamediv> + <refname>extract</refname> + <refpurpose>Import variables into the symbol table from an array</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcdef>void <function>extract</function></funcdef> + <paramdef>array <parameter>var_array</parameter></paramdef> + <paramdef>int <parameter>extract_type</parameter></paramdef> + <paramdef>string <parameter><optional>var_array</optional></parameter></paramdef> + </funcsynopsis> + <para> + This function is used to import variables from an array into the + current symbol table. It takes 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 + <parameter>extract_type</parameter> and + <parameter>prefix</parameter> parameters. + <para> + <function>extract</function> checks for colissions with existing variables. + The way collisions are treated is determined by + <parameter>extract_type</parameter>. It can be one of the + following values: + <variablelist> + <varlistentry> + <term>EXTR_OVERWRITE</term> + <listitem> + <simpara>If there is a collision, overwrite the existing variable.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_SKIP</term> + <listitem> + <simpara>If there is a collision, don't overwrite the existing variable.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_SAME</term> + <listitem> + <simpara>If there is a collision, prefix the new variable with + <parameter>prefix</parameter>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>EXTR_PREFIX_ALL</term> + <listitem> + <simpara>Prefix all variables with <parameter>prefix</parameter>.</simpara> + </listitem> + </varlistentry> + </variablelist> + <para> + Note that <parameter>prefix</parameter> is only required if + <parameter>extract_type</parameter> is EXTR_PREFIX_SAME or + EXTR_PREFIX_ALL. + <para> + <function>extract</function> checks each key to see if it + constitues a valid variable name, and if it does only then does + it proceed to import it. + <para> + A possible use for extract is to import into symbol table + variables contained in an associative array returned by + <function>wddx_deserialize</function>. + <para> + <example> + <title>extract example</title> + <programlisting> + &lt;? + + /* Suppose that $var_array is an array returned from + wddx_deserialize */ + $size = "large"; + $var_array = array("color" => "blue", + "size" => "medium", + "shape" => "sphere"); + extract($var_array, EXTR_PREFIX_SAME, "wddx"); + + print "$color, $size, $shape, $wddx_size\n"; + + ?> + </programlisting> + </example> + + <para> + The above example will produce: + <programlisting> + blue, large, sphere, medium + </programlisting> + + <para> + The $size wasn't overwritten, becaus we specified + EXTR_PREFIX_SAME, which resulted in $wddx_size being created. + If EXTR_SKIP was specified, then $wddx_size wouldn't even have + been created. EXTR_OVERWRITE would have cause $size to have + value "medium", and EXTR_PREFIX_ALL would result in new + variables being named $wddx_color, $wddx_size, and $wddx_shape. + </refsect1> + </refentry> + <refentry id="function.die"> <refnamediv> <refname>die</refname> -- PHP Development Mailing List http://www.php.net/ To unsubscribe send an empty message to php-dev-unsubscribe@lists.php.net For help: php-dev-help@lists.php.net