Sophie: php-manual-en-4.3.0-2mdk noarch

php-manual-en-4.3.0-2mdk.noarch.rpm

<HTML
><HEAD
><TITLE
>extract</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
REL="HOME"
TITLE="PHP Manual"
HREF="index.html"><LINK
REL="UP"
TITLE="Array Functions"
HREF="ref.array.html"><LINK
REL="PREVIOUS"
TITLE="end"
HREF="function.end.html"><LINK
REL="NEXT"
TITLE="in_array"
HREF="function.in-array.html"><META
HTTP-EQUIV="Content-type"
CONTENT="text/html; charset=ISO-8859-1"></HEAD
><BODY
CLASS="refentry"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PHP Manual</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="function.end.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="function.in-array.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="function.extract"
></A
>extract</H1
><DIV
CLASS="refnamediv"
><A
NAME="AEN8679"
></A
><P
>    (PHP 3&#62;= 3.0.7, PHP 4 )</P
>extract&nbsp;--&nbsp;
     Import variables into the current symbol table from an array
    </DIV
><DIV
CLASS="refsect1"
><A
NAME="AEN8682"
></A
><H2
>Description</H2
>int <B
CLASS="methodname"
>extract</B
> ( array var_array [, int extract_type [, string prefix]])<BR
></BR
><P
>&#13;     This function is used to import variables from an array into the
     current symbol table.  It takes an associative array
     <TT
CLASS="parameter"
><I
>var_array</I
></TT
> 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
     <TT
CLASS="parameter"
><I
>extract_type</I
></TT
> and
     <TT
CLASS="parameter"
><I
>prefix</I
></TT
> parameters.
    </P
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
      Beginning with version 4.0.5, this function returns the number of
      variables extracted.
     </P
></BLOCKQUOTE
></DIV
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
      EXTR_IF_EXISTS and EXTR_PREFIX_IF_EXISTS was introduced in version 4.2.0.
     </P
></BLOCKQUOTE
></DIV
><DIV
CLASS="note"
><BLOCKQUOTE
CLASS="note"
><P
><B
>Note: </B
>
      EXTR_REFS was introduced in version 4.3.0.
     </P
></BLOCKQUOTE
></DIV
><P
>&#13;     <B
CLASS="function"
>extract()</B
> checks each key to see whether it
     has a valid variable name. It also checks for collisions with
     existing variables in the symbol table. The way invalid/numeric
     keys and collisions are treated is determined by the
     <TT
CLASS="parameter"
><I
>extract_type</I
></TT
>. It can be one of the
     following values:
     <P
></P
><DIV
CLASS="variablelist"
><DL
><DT
>EXTR_OVERWRITE</DT
><DD
><P
>&#13;         If there is a collision, overwrite the existing variable.
        </P
></DD
><DT
>EXTR_SKIP</DT
><DD
><P
>&#13;         If there is a collision, don't overwrite the existing
         variable.
        </P
></DD
><DT
>EXTR_PREFIX_SAME</DT
><DD
><P
>If there is a collision, prefix the variable name with
        <TT
CLASS="parameter"
><I
>prefix</I
></TT
>.
        </P
></DD
><DT
>EXTR_PREFIX_ALL</DT
><DD
><P
>&#13;         Prefix all variable names with
         <TT
CLASS="parameter"
><I
>prefix</I
></TT
>. Beginning with PHP 4.0.5, this includes
         numeric variables as well.
        </P
></DD
><DT
>EXTR_PREFIX_INVALID</DT
><DD
><P
>&#13;         Only prefix invalid/numeric variable names with
         <TT
CLASS="parameter"
><I
>prefix</I
></TT
>. This flag was added in
         PHP 4.0.5.
        </P
></DD
><DT
>EXTR_IF_EXISTS</DT
><DD
><P
>&#13;         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.
        </P
></DD
><DT
>EXTR_PREFIX_IF_EXISTS</DT
><DD
><P
>&#13;         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.
        </P
></DD
><DT
>EXTR_REFS</DT
><DD
><P
>&#13;         Extracts variables as references. This effectively means that the
         values of the imported variables are still referencing the values of
         the <TT
CLASS="parameter"
><I
>var_array</I
></TT
> parameter. You can use this flag
         on its own or combine it with any other flag by OR'ing the
         <TT
CLASS="parameter"
><I
>extract_type</I
></TT
>. This flag was added in PHP
         4.3.0.
        </P
></DD
></DL
></DIV
>
    </P
><P
>&#13;     If <TT
CLASS="parameter"
><I
>extract_type</I
></TT
> is not specified, it is
     assumed to be EXTR_OVERWRITE.
    </P
><P
>&#13;     Note that <TT
CLASS="parameter"
><I
>prefix</I
></TT
> is only required if
     <TT
CLASS="parameter"
><I
>extract_type</I
></TT
> is EXTR_PREFIX_SAME,
     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.
    </P
><P
>&#13;     <B
CLASS="function"
>extract()</B
> returns the number of variables
     successfully imported into the symbol table.
    </P
><P
>&#13;     A possible use for <B
CLASS="function"
>extract()</B
> is to import into the
     symbol table variables contained in an associative array returned by
     <A
HREF="function.wddx-deserialize.html"
><B
CLASS="function"
>wddx_deserialize()</B
></A
>.
    </P
><P
>&#13;     <TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
CLASS="EXAMPLE"
><TR
><TD
><DIV
CLASS="example"
><A
NAME="AEN8758"
></A
><P
><B
>Example 1. <B
CLASS="function"
>extract()</B
> example</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="php"
>&#60;?php

/* Suppose that $var_array is an array returned from
   wddx_deserialize */

$size = "large";
$var_array = array ("color" =&#62; "blue",
                    "size"  =&#62; "medium",
                    "shape" =&#62; "sphere");
extract ($var_array, EXTR_PREFIX_SAME, "wddx");

print "$color, $size, $shape, $wddx_size\n";

?&#62;</PRE
></TD
></TR
></TABLE
></DIV
></TD
></TR
></TABLE
>
    </P
><P
>&#13;     The above example will produce:
     <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
CELLPADDING="5"
><TR
><TD
><PRE
CLASS="programlisting"
>blue, large, sphere, medium</PRE
></TD
></TR
></TABLE
>
    </P
><P
>&#13;     The <TT
CLASS="varname"
>$size</TT
> wasn't overwritten, because we
     specified EXTR_PREFIX_SAME, which resulted in
     <TT
CLASS="varname"
>$wddx_size</TT
> being created.  If EXTR_SKIP was
     specified, then $wddx_size wouldn't even have been created.
     EXTR_OVERWRITE would have caused <TT
CLASS="varname"
>$size</TT
> to have
     value "medium", and EXTR_PREFIX_ALL would result in new variables
     being named <TT
CLASS="varname"
>$wddx_color</TT
>,
     <TT
CLASS="varname"
>$wddx_size</TT
>, and
     <TT
CLASS="varname"
>$wddx_shape</TT
>.
    </P
><P
>&#13;     You must use an associative array, a numerically indexed array
     will not produce results unless you use EXTR_PREFIX_ALL or 
     EXTR_PREFIX_INVALID.
    </P
><P
>&#13;     See also <A
HREF="function.compact.html"
><B
CLASS="function"
>compact()</B
></A
>.
    </P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="function.end.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="function.in-array.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>end</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="ref.array.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>in_array</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>