cvs: /phpdoc/functions array.sgml misc.sgml

andrey Fri Jul 16 17:48:10 1999 EDT Modified files: /phpdoc/functions array.sgml misc.sgml Log: Move extract() function docs from misc.sgml to array.sgml Index: phpdoc/functions/array.sgml diff -u phpdoc/functions/array.sgml:1.11 phpdoc/functions/array.sgml:1.12 --- phpdoc/functions/array.sgml:1.11 Fri Jul 16 17:45:26 1999 +++ phpdoc/functions/array.sgml Fri Jul 16 17:48:10 1999 @@ -767,6 +767,111 @@ </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><optional>extract_type</optional></parameter></paramdef> + <paramdef>string <parameter><optional>prefix</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> + If <parameter>extract_type</parameter> is not specified, + it is assumed to be EXTR_OVERWRITE. + <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.in-array"> <refnamediv> <refname>in_array</refname> Index: phpdoc/functions/misc.sgml diff -u phpdoc/functions/misc.sgml:1.2 phpdoc/functions/misc.sgml:1.3 --- phpdoc/functions/misc.sgml:1.2 Sat Jun 19 23:04:56 1999 +++ phpdoc/functions/misc.sgml Fri Jul 16 17:48:10 1999 @@ -119,111 +119,6 @@ </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><optional>extract_type</optional></parameter></paramdef> - <paramdef>string <parameter><optional>prefix</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> - If <parameter>extract_type</parameter> is not specified, - it is assumed to be EXTR_OVERWRITE. - <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>