sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-17 01:18:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
php-doc-en/functions/funchand.xml
Hartmut Holzgraefe 7839d91186 added DO NOT EDIT noctice to old english functions files, 
removing the others


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@78562 c90b9560-bf6c-de11-be94-00142212c4b1
2002-04-17 19:58:46 +00:00

638 lines
19 KiB
XML
Executable file
Raw Blame History

<!-- D O N O T E D I T T H I S F I L E ! ! !
it is still here for historical reasons only
(as translators may need to check old revision diffs)
if you want to change things documented in this file
you should now edit the files found under en/reference
instead -->
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.30 $ -->
<reference id="ref.funchand">
<title>Function Handling functions</title>
<titleabbrev>Functions</titleabbrev>
<partintro>
<para>
These functions all handle various operations involved in working
with functions.
</para>
</partintro>
<refentry id="function.call-user-func-array">
<refnamediv>
<refname>call_user_func_array</refname>
<refpurpose>
Call a user function given with an array of parameters
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>call_user_func_array</methodname>
<methodparam><type>string</type><parameter>function_name</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>paramarr</parameter></methodparam>
</methodsynopsis>
<para>
Call a user defined function given by
<parameter>function_name</parameter>, with
the parameters in <parameter>paramarr</parameter>.
For example:
<informalexample>
<programlisting role="php">
<![CDATA[
function debug($var, $val)
echo "***DEBUGGING\nVARIABLE: $var\nVALUE:";
if (is_array($val) || is_object($val) || is_resource($val))
print_r($val);
else
echo "\n$val\n";
echo "***\n";
}
$c = mysql_connect();
$host = $HTTP_SERVER_VARS["SERVER_NAME"];
call_user_func_array ('debug', array("host", $host));
call_user_func_array ('debug', array("c", $c));
call_user_func_array ('debug', array("HTTP_POST_VARS", $HTTP_POST_VARS));
]]>
</programlisting>
</informalexample>
</para>
<para>
See also:
<function>call_user_func</function>,
<function>call_user_method</function>,
<function>call_user_method_array</function>.
</para>
<note>
<para>
This function was added to the CVS code after release of PHP 4.0.4pl1
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.call-user-func">
<refnamediv>
<refname>call_user_func</refname>
<refpurpose>
Call a user function given by the first parameter
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>call_user_func</methodname>
<methodparam><type>string</type><parameter>function_name</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>parameter</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>...</parameter></methodparam>
</methodsynopsis>
<para>
Call a user defined function given by the
<parameter>function_name</parameter> parameter. Take the
following:
<informalexample>
<programlisting role="php">
<![CDATA[
function barber ($type) {
print "You wanted a $type haircut, no problem";
}
call_user_func ('barber', "mushroom");
call_user_func ('barber', "shave");
]]>
</programlisting>
</informalexample>
</para>
<para>
See also:
<function>call_user_func_array</function>,
<function>call_user_method</function>,
<function>call_user_method_array</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.create-function">
<refnamediv>
<refname>create_function</refname>
<refpurpose>Create an anonymous (lambda-style) function</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>string</type><methodname>create_function</methodname>
<methodparam><type>string</type><parameter>args</parameter></methodparam>
<methodparam><type>string</type><parameter>code</parameter></methodparam>
</methodsynopsis>
<para>
Creates an anonymous function from the parameters passed, and
returns a unique name for it. Usually the
<parameter>args</parameter> will be passed as a single quote
delimited string, and this is also recommended for the
<parameter>code</parameter>. The reason for using single quoted
strings, is to protect
the variable names from parsing, otherwise, if you use double
quotes there will be a need to escape the variable names, e.g.
<literal>\$avar</literal>.
</para>
<para>
You can use this function, to (for example) create a function
from information gathered at run time:
<example>
<title>
Creating an anonymous function with <function>create_function</function>
</title>
<programlisting role="php">
<![CDATA[
$newfunc = create_function('$a,$b','return "ln($a) + ln($b) = ".log($a * $b);');
echo "New anonymous function: $newfunc\n";
echo $newfunc(2,M_E)."\n";
// outputs
// New anonymous function: lambda_1
// ln(2) + ln(2.718281828459) = 1.6931471805599
]]>
</programlisting>
</example>
Or, perhaps to have general handler function that can apply a set
of operations to a list of parameters:
<example>
<title>
Making a general processing function with
<function>create_function</function>
</title>
<programlisting role="php">
<![CDATA[
function process($var1, $var2, $farr) {
for ($f=0; $f < count($farr); $f++)
echo $farr[$f]($var1,$var2)."\n";
}
// create a bunch of math functions
$f1 = 'if ($a >=0) {return "b*a^2 = ".$b*sqrt($a);} else {return false;}';
$f2 = "return \"min(b^2+a, a^2,b) = \".min(\$a*\$a+\$b,\$b*\$b+\$a);";
$f3 = 'if ($a > 0 && $b != 0) {return "ln(a)/b = ".log($a)/$b; } else { return false; }';
$farr = array(
create_function('$x,$y', 'return "some trig: ".(sin($x) + $x*cos($y));'),
create_function('$x,$y', 'return "a hypotenuse: ".sqrt($x*$x + $y*$y);'),
create_function('$a,$b', $f1),
create_function('$a,$b', $f2),
create_function('$a,$b', $f3)
);
echo "\nUsing the first array of anonymous functions\n";
echo "parameters: 2.3445, M_PI\n";
process(2.3445, M_PI, $farr);
// now make a bunch of string processing functions
$garr = array(
create_function('$b,$a','if (strncmp($a,$b,3) == 0) return "** \"$a\" '.
'and \"$b\"\n** Look the same to me! (looking at the first 3 chars)";'),
create_function('$a,$b','; return "CRCs: ".crc32($a)." , ".crc32(b);'),
create_function('$a,$b','; return "similar(a,b) = ".similar_text($a,$b,&$p)."($p%)";')
);
echo "\nUsing the second array of anonymous functions\n";
process("Twas brilling and the slithy toves", "Twas the night", $garr);
]]>
</programlisting>
</example>
and when you run the code above, the output will be:
<informalexample>
<programlisting>
<![CDATA[
Using the first array of anonymous functions
parameters: 2.3445, M_PI
some trig: -1.6291725057799
a hypotenuse: 3.9199852871011
b*a^2 = 4.8103313314525
min(b^2+a, a^2,b) = 8.6382729035898
ln(a/b) = 0.27122299212594
Using the second array of anonymous functions
** "Twas the night" and "Twas brilling and the slithy toves"
** Look the same to me! (looking at the first 3 chars)
CRCs: -725381282 , 1908338681
similar(a,b) = 11(45.833333333333%)
]]>
</programlisting>
</informalexample>
But perhaps the most common use for of lambda-style (anonymous) functions
is to create callback functions, for example when using
<function>array_walk</function> or <function>usort</function>
<example>
<title>Using anonymous functions as callback functions</title>
<programlisting role="php">
<![CDATA[
$av = array("the ","a ","that ","this ");
array_walk($av, create_function('&$v,$k','$v = $v."mango";'));
print_r($av); // for PHP 3 use var_dump()
// outputs:
// Array
// (
// [0] => the mango
// [1] => a mango
// [2] => that mango
// [3] => this mango
// )
// an array of strings ordered from shorter to longer
$sv = array("small","larger","a big string","it is a string thing");
print_r($sv);
// outputs:
// Array
// (
// [0] => small
// [1] => larger
// [2] => a big string
// [3] => it is a string thing
// )
// sort it from longer to shorter
usort($sv, create_function('$a,$b','return strlen($b) - strlen($a);'));
print_r($sv);
// outputs:
// Array
// (
// [0] => it is a string thing
// [1] => a big string
// [2] => larger
// [3] => small
// )
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.func-get-arg">
<refnamediv>
<refname>func_get_arg</refname>
<refpurpose>Return an item from the argument list</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>mixed</type><methodname>func_get_arg</methodname>
<methodparam><type>int</type><parameter>arg_num</parameter></methodparam>
</methodsynopsis>
<simpara>
Returns the argument which is at the
<parameter>arg_num</parameter>'th offset into a user-defined
function's argument list. Function arguments are counted starting
from zero. <function>func_get_arg</function> will generate a
warning if called from outside of a function definition.
</simpara>
<simpara>
If <parameter>arg_num</parameter> is greater than the number of
arguments actually passed, a warning will be generated and
<function>func_get_arg</function> will return &false;.
</simpara>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
function foo() {
$numargs = func_num_args();
echo "Number of arguments: $numargs<br>\n";
if ($numargs >= 2) {
echo "Second argument is: " . func_get_arg (1) . "<br>\n";
}
}
foo (1, 2, 3);
?>
]]>
</programlisting>
</informalexample>
</para>
<simpara>
<function>func_get_arg</function> may be used in conjunction with
<function>func_num_args</function> and
<function>func_get_args</function> to allow user-defined
functions to accept variable-length argument lists.
</simpara>
<note>
<simpara>
This function was added in PHP 4.
</simpara>
</note>
</refsect1>
</refentry>
<refentry id="function.func-get-args">
<refnamediv>
<refname>func_get_args</refname>
<refpurpose>
Returns an array comprising a function's argument list
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>func_get_args</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns an array in which each element is the corresponding
member of the current user-defined function's argument
list. <function>func_get_args</function> will generate a warning
if called from outside of a function definition.
</simpara>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
function foo() {
$numargs = func_num_args();
echo "Number of arguments: $numargs<br>\n";
if ($numargs >= 2) {
echo "Second argument is: " . func_get_arg (1) . "<br>\n";
}
$arg_list = func_get_args();
for ($i = 0; $i < $numargs; $i++) {
echo "Argument $i is: " . $arg_list[$i] . "<br>\n";
}
}
foo (1, 2, 3);
?>
]]>
</programlisting>
</informalexample>
</para>
<simpara>
<function>func_get_args</function> may be used in conjunction
with <function>func_num_args</function> and
<function>func_get_arg</function> to allow user-defined functions
to accept variable-length argument lists.
</simpara>
<note>
<simpara>
This function was added in PHP 4.
</simpara>
</note>
</refsect1>
</refentry>
<refentry id="function.func-num-args">
<refnamediv>
<refname>func_num_args</refname>
<refpurpose>
Returns the number of arguments passed to the function
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>func_num_args</methodname>
<void/>
</methodsynopsis>
<simpara>
Returns the number of arguments passed into the current
user-defined function. <function>func_num_args</function> will
generate a warning if called from outside of a user-defined function.
</simpara>
<para>
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
function foo() {
$numargs = func_num_args();
echo "Number of arguments: $numargs\n";
}
foo (1, 2, 3); // Prints 'Number of arguments: 3'
?>
]]>
</programlisting>
</informalexample>
</para>
<simpara>
<function>func_num_args</function> may be used in conjunction
with <function>func_get_arg</function> and
<function>func_get_args</function> to allow user-defined
functions to accept variable-length argument lists.
</simpara>
</refsect1>
</refentry>
<refentry id="function.function-exists">
<refnamediv>
<refname>function_exists</refname>
<refpurpose>
Return &true; if the given function has been defined
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>bool</type><methodname>function_exists</methodname>
<methodparam><type>string</type><parameter>function_name</parameter></methodparam>
</methodsynopsis>
<para>
Checks the list of defined functions, both built-in (internal) and
user-defined, for <parameter>function_name</parameter>. &return.success;
<informalexample>
<programlisting role="php">
<![CDATA[
if (function_exists('imap_open')) {
echo "IMAP functions are available.<br>\n";
} else {
echo "IMAP functions are not available.<br>\n";
}
]]>
</programlisting>
</informalexample>
Note that a function name may exist even if the function itself
is unusable due to configuration or compiling options (with the
<link linkend="ref.image">image</link> functions being an example).
Also note that <function>function_exists</function> will return
&false; for constructs, such as <function>include_once</function>
and <function>echo</function>.
</para>
<para>
See also <function>method_exists</function> and
<function>get_defined_functions</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.get-defined-functions">
<refnamediv>
<refname>get_defined_functions</refname>
<refpurpose>
Returns an array of all defined functions
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>array</type><methodname>get_defined_functions</methodname>
<void/>
</methodsynopsis>
<para>
This function returns an multidimensional array containing a list of
all defined functions, both built-in (internal) and user-defined. The
internal functions will be accessible via
<varname>$arr["internal"]</varname>, and the user defined ones using
<varname>$arr["user"]</varname> (see example below).
<informalexample>
<programlisting role="php">
<![CDATA[
function myrow($id, $data) {
return "<tr><th>$id</th><td>$data</td></tr>\n";
}
$arr = get_defined_functions();
print_r($arr);
]]>
</programlisting>
</informalexample>
</para>
<para>
Will output something along the lines of:
<informalexample>
<programlisting>
<![CDATA[
Array
(
[internal] => Array
(
[0] => zend_version
[1] => func_num_args
[2] => func_get_arg
[3] => func_get_args
[4] => strlen
[5] => strcmp
[6] => strncmp
...
[750] => bcscale
[751] => bccomp
)
[user] => Array
(
[0] => myrow
)
)
]]>
</programlisting>
</informalexample>
</para>
<para>
See also <function>get_defined_vars</function> and
<function>get_defined_constants</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.register-shutdown-function">
<refnamediv>
<refname>register_shutdown_function</refname>
<refpurpose>
Register a function for execution on shutdown
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>register_shutdown_function</methodname>
<methodparam><type>string</type><parameter>func</parameter></methodparam>
</methodsynopsis>
<simpara>
Registers the function named by <parameter>func</parameter> to be
executed when script processing is complete.
</simpara>
<para>
Multiple calls to <function>register_shutdown_function</function> can be
made, and each will be called in the same order as they were registered.
If you call <function>exit</function> within one registered shutdown
function, processing will stop completely and no other registered
shutdown functions will be called.
</para>
<para>
The registered shutdown functions are called after the request has been
completed (including sending any output buffers), so it is not possible
to send output to the browser using <function>echo</function> or
<function>print</function>, or retrieve the contents of any output
buffers using <function>ob_get_contents</function>.
</para>
&note.func-callback;
</refsect1>
</refentry>
<refentry id="function.register-tick-function">
<refnamediv>
<refname>register_tick_function</refname>
<refpurpose>
Register a function for execution on each tick
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>void</type><methodname>register_tick_function</methodname>
<methodparam><type>string</type><parameter>func</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
</methodsynopsis>
<simpara>
Registers the function named by <parameter>func</parameter> to be
executed when a <link
linkend="control-structures.declare">tick</link> is
called.</simpara>
</refsect1>
</refentry>
<refentry id="function.unregister-tick-function">
<refnamediv>
<refname>unregister_tick_function</refname>
<refpurpose>
De-register a function for execution on each tick
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
<type>void</type><methodname>unregister_tick_function</methodname>
<methodparam><type>string</type><parameter>func</parameter></methodparam>
<methodparam choice="opt"><type>mixed</type><parameter>arg</parameter></methodparam>
</methodsynopsis>
<simpara>
De-registers the function named by <parameter>func</parameter> so it is
no longer executed when a <link
linkend="control-structures.declare">tick</link> is
called.</simpara>
</refsect1>
</refentry>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Reference in a new issue View git blame Copy permalink