4c60a42003-11-07Martin Nilsson <!doctype html><html><head><title>Pike Reference Manual</title> <meta charset='utf-8'></head>
7393ca2019-08-17Henrik Grubbström (Grubba) <body><dl><dt><h1 class='header'>21. The rest</h1></dt><dd><dl><dt><h2 class='header'>Namespace <b class='ms datatype'>cpp::</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Pike has a builtin C-style preprocessor. It works similar to the ANSI-C preprocessor but has a few extra features. These and the default set of preprocessor macros are described here.</p> <p> The preprocessor is usually accessed via <code>MasterObject-&gt;compile_file()</code> or <code>MasterObject-&gt;compile_string()</code>, but may be accessed directly by calling <code>cpp()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>compile()</code>, <code>cpp()</code>, <code>CompilerEnvironment.CPP</code></p> </dd></dl></dd></dl><dl><dt><h2 class='header'>Namespace <b class='ms datatype'>predef::</b></h2>
47a29e2020-05-24Stephen R. van den Berg </dt><dd>
7393ca2019-08-17Henrik Grubbström (Grubba)  <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>FUSE_MAJOR_VERSION</b></span><br> <span class='homogen--type'>Constant</span> <span class='homogen--name'><b>FUSE_MINOR_VERSION</b></span><br> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>FUSE_MAJOR_VERSION</code></code><br> <code><code class='datatype'>constant</code> <code class='constant'>FUSE_MINOR_VERSION</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>The version of FUSE</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>HKEY_CLASSES_ROOT</b></span><br> <span class='homogen--type'>Constant</span> <span class='homogen--name'><b>HKEY_LOCAL_MACHINE</b></span><br> <span class='homogen--type'>Constant</span> <span class='homogen--name'><b>HKEY_CURRENT_USER</b></span><br> <span class='homogen--type'>Constant</span> <span class='homogen--name'><b>HKEY_USERS</b></span><br> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>HKEY_CLASSES_ROOT</code></code><br> <code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>HKEY_LOCAL_MACHINE</code></code><br> <code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>HKEY_CURRENT_USER</code></code><br> <code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>HKEY_USERS</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Root handles in the Windows registry.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>These constants are only available on Win32 systems.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>RegGetValue()</code>, <code>RegGetValues()</code>, <code>RegGetKeyNames()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>ProxyFactory</b></span> </dt> <dd><p><code><code class='datatype'>program</code> <b><span class='method'>ProxyFactory</span>(</b><code class='datatype'>program</code> <code class='argument'>p</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Create a class that acts as a proxy for the specified program.</p> </dd> <dt class='head--doc'><span id='p-p'></span>Parameter <code class='parameter'>p</code></dt> <dd></dd><dd class='body--doc'><p>Program to generate a proxy for.</p> <p> The generated class will have the same symbols (public and private) with the same types as in <code>p</code>, where accesses to these will proxy the access to the same symbol in the proxied (aka wrapped) object. With the following exceptions:</p> <dl class='group--doc'><dt><p><code class='expr'>protected&nbsp;void&nbsp;create(object(p)&nbsp;obj)</code></p> </dt><dd><p>Initialize the object to act as a proxy for <code class='expr'>obj</code>.</p> </dd> <dt><p><code class='expr'>_sprintf(int&nbsp;c,&nbsp;mapping|void&nbsp;params)</code></p> </dt><dd><p>Special case for <code class='expr'>c</code> == <code class='expr'>'O'</code>, where it will return <code class='expr'>sprintf("%O(%O)",&nbsp;this_program,&nbsp;obj)</code>, and otherwise proxy the call.</p> </dd> <dt><p><code class='expr'>void&nbsp;_destruct()</code>/<code class='expr'>void&nbsp;destroy()</code></p> </dt><dd><p>These lfuns will not be present as the act of them being proxied would likely confuse the proxied object.</p> </dd> </dl> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The same proxy class will be returned if this function is called with the same program multiple times.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>RegGetKeyNames</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>RegGetKeyNames</span>(</b><code class='datatype'>int</code> <code class='argument'>hkey</code>, <code class='datatype'>string</code> <code class='argument'>key</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get a list of value key names from the register.</p> </dd> <dt class='head--doc'><span id='p-hkey'></span>Parameter <code class='parameter'>hkey</code></dt> <dd></dd><dd class='body--doc'><p>One of the following:</p> <table class='box'><tr><td><code><code class='key'>HKEY_CLASSES_ROOT</code></code></td></tr> <tr><td><code><code class='key'>HKEY_LOCAL_MACHINE</code></code></td></tr> <tr><td><code><code class='key'>HKEY_CURRENT_USER</code></code></td></tr> <tr><td><code><code class='key'>HKEY_USERS</code></code></td></tr> </table> </dd> <dt class='head--doc'><span id='p-key'></span>Parameter <code class='parameter'>key</code></dt> <dd></dd><dd class='body--doc'><p>A registry key.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns an array of value keys stored at the specified location if any. Returns <code class='expr'>UNDEFINED</code> on missing <code>key</code>. Throws errors on other failures.</p> </dd> <dt class='head--doc'>Example</dt> <dd class='example'><pre><p>&gt; RegGetKeyNames(HKEY_CURRENT_USER, "Keyboard Layout"); (1) Result: ({ "IMEtoggle", "Preload", "Substitutes", "Toggle" })</p> </pre></dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is only available on Win32 systems.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>RegGetValue()</code>, <code>RegGetValues()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>RegGetValue</b></span> </dt> <dd><p><code><code class='datatype'>string</code>|<code class='datatype'>int</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>RegGetValue</span>(</b><code class='datatype'>int</code> <code class='argument'>hkey</code>, <code class='datatype'>string</code> <code class='argument'>key</code>, <code class='datatype'>string</code> <code class='argument'>index</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get a single value from the register.</p> </dd> <dt class='head--doc'><span id='p-hkey'></span>Parameter <code class='parameter'>hkey</code></dt> <dd></dd><dd class='body--doc'><p>One of the following:</p> <table class='box'><tr><td><code><code class='key'>HKEY_CLASSES_ROOT</code></code></td></tr> <tr><td><code><code class='key'>HKEY_LOCAL_MACHINE</code></code></td></tr> <tr><td><code><code class='key'>HKEY_CURRENT_USER</code></code></td></tr> <tr><td><code><code class='key'>HKEY_USERS</code></code></td></tr> </table> </dd> <dt class='head--doc'><span id='p-key'></span>Parameter <code class='parameter'>key</code></dt> <dd></dd><dd class='body--doc'><p>Registry key.</p> </dd> <dt class='head--doc'><span id='p-index'></span>Parameter <code class='parameter'>index</code></dt> <dd></dd><dd class='body--doc'><p>Value name.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the value stored at the specified location in the register if any. Returns <code class='expr'>UNDEFINED</code> on missing keys, throws errors on other failures.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is only available on Win32 systems.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>RegGetValues()</code>, <code>RegGetKeyNames()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>RegGetValues</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>|<code class='datatype'>int</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <b><span class='method'>RegGetValues</span>(</b><code class='datatype'>int</code> <code class='argument'>hkey</code>, <code class='datatype'>string</code> <code class='argument'>key</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get multiple values from the register.</p> </dd> <dt class='head--doc'><span id='p-hkey'></span>Parameter <code class='parameter'>hkey</code></dt> <dd></dd><dd class='body--doc'><p>One of the following:</p> <table class='box'><tr><td><code><code class='key'>HKEY_CLASSES_ROOT</code></code></td></tr> <tr><td><code><code class='key'>HKEY_LOCAL_MACHINE</code></code></td></tr> <tr><td><code><code class='key'>HKEY_CURRENT_USER</code></code></td></tr> <tr><td><code><code class='key'>HKEY_USERS</code></code></td></tr> </table> </dd> <dt class='head--doc'><span id='p-key'></span>Parameter <code class='parameter'>key</code></dt> <dd></dd><dd class='body--doc'><p>Registry key.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns a mapping with all the values stored at the specified location in the register if any. Returns <code class='expr'>UNDEFINED</code> on missing <code>key</code>. Throws errors on other failures.</p> </dd> <dt class='head--doc'>Example</dt> <dd class='example'><pre><p>&gt; RegGetValues(HKEY_CURRENT_USER, "Keyboard Layout\\Preload"); (5) Result: ([ "1":"0000041d" ])</p> </pre></dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is only available on Win32 systems.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>RegGetValue()</code>, <code>RegGetKeyNames()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>TOKENIZE_KEEP_ESCAPES</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>TOKENIZE_KEEP_ESCAPES</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Don't unquote backslash-sequences in quoted strings during tokenizing. This is used for bug-compatibility with Microsoft...</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>tokenize()</code>, <code>tokenize_labled()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>UNDEFINED</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>UNDEFINED</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>The undefined value; ie a zero for which <code>zero_type()</code> returns 1.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>_Static_assert</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>_Static_assert</span>(</b><code class='datatype'>int</code> <code class='argument'>constant_expression</code>, <code class='datatype'>string</code> <code class='argument'>constant_message</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Perform a compile-time assertion check.</p> <p> If <code>constant_expression</code> is false, a compiler error message containing <code>constant_message</code> will be generated.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that the function call compiles to the null statement, and thus does not affect the run-time.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>cpp::static_assert</code></p> </dd></dl>
4a0b9d2019-08-28Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>__automap__</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>__automap__</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>fun</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Automap execution function.</p> </dd> <dt class='head--doc'><span id='p-fun'></span>Parameter <code class='parameter'>fun</code></dt> <dd></dd><dd class='body--doc'><p>Function to call for each of the mapped arguments.</p> </dd> <dt class='head--doc'><span id='p-args'></span>Parameter <code class='parameter'>args</code></dt> <dd></dd><dd class='body--doc'><p>Arguments for <code>fun</code>. Either</p> <table class='box'><tr><td><code><code class='object unresolved'>Builtin.automap_marker</code></code></td><td><p>Wrapper for an array to loop over. All of the arrays will be looped over in parallel.</p> </td></tr> <tr><td><code><code class='datatype'>mixed</code></code></td><td><p>All other arguments will be held constant during the automap, and sent as is to <code>fun</code>.</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is used by the compiler to implement the automap syntax, and should in normal circumstances never be used directly.</p> <p> It may however show up during module dumping and in backtraces.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>It is an error not to have any <code>Builtin.automap_marker</code>s in <code>args</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Builtin.automap_marker</code>, <code>map()</code></p> </dd></dl>
7393ca2019-08-17Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>__empty_program</b></span> </dt> <dd><p><code><code class='datatype'>program</code> <b><span class='method'>__empty_program</span>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>line</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>file</code><b>)</b></code></p></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>__handle_sprintf_format</b></span> </dt> <dd><p><code><code class='type'>type</code> <b><span class='method'>__handle_sprintf_format</span>(</b><code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>fmt</code>, <code class='type'>type</code> <code class='argument'>arg_type</code>, <code class='type'>type</code> <code class='argument'>cont_type</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Type attribute handler for <code class='expr'>"sprintf_format"</code>.</p> </dd> <dt class='head--doc'><span id='p-attr'></span>Parameter <code class='parameter'>attr</code></dt> <dd></dd><dd class='body--doc'><p>Attribute to handle, either <code class='expr'>"sprintf_format"</code> or <code class='expr'>"strict_sprintf_format"</code>.</p> </dd> <dt class='head--doc'><span id='p-fmt'></span>Parameter <code class='parameter'>fmt</code></dt> <dd></dd><dd class='body--doc'><p>Sprintf-style formatting string to generate type information from.</p> </dd> <dt class='head--doc'><span id='p-arg_type'></span>Parameter <code class='parameter'>arg_type</code></dt> <dd></dd><dd class='body--doc'><p>Declared type of the <code>fmt</code> argument (typically <code class='expr'>string</code>).</p> </dd> <dt class='head--doc'><span id='p-cont_type'></span>Parameter <code class='parameter'>cont_type</code></dt> <dd></dd><dd class='body--doc'><p>Continuation function type after the <code>fmt</code> argument. This is scanned for the type attribute <code class='expr'>"sprintf_args"</code> to determine where the remaining arguments to <code>sprintf()</code> will come from.</p> <p> This function is typically called from <code>PikeCompiler()-&gt;apply_attribute_constant()</code> and is used to perform stricter compile-time argument checking of <code>sprintf()</code>-style functions.</p> <p> It currently implements two operating modes depending on the value of <code>attr</code>:</p> <table class='box'><tr><td><code><code class='key'>"strict_sprintf_format"</code></code></td><td><p>The formatting string <code>fmt</code> is known to always be passed to <code>sprintf()</code>.</p> </td></tr> <tr><td><code><code class='key'>"sprintf_format"</code></code></td><td><p>The formatting string <code>fmt</code> is passed to <code>sprintf()</code> only if there are <code class='expr'>"sprintf_args"</code>.</p> </td></tr> </table> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns <code>cont_type</code> with <code class='expr'>"sprintf_args"</code> replaced by the arguments required by the <code>fmt</code> formatting string, and <code class='expr'>"sprintf_result"</code> replaced by the resulting string type.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>PikeCompiler()-&gt;apply_attribute_constant()</code>, <code>sprintf()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>__null_program</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>__null_program</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Program used internally by the compiler to create objects that are later modified into instances of the compiled program by the compiler.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>__placeholder_object</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>__parse_pike_type</b></span> </dt> <dd><p><code><code class='datatype'>string(8bit)</code> <b><span class='method'>__parse_pike_type</span>(</b><code class='datatype'>string(8bit)</code> <code class='argument'>t</code><b>)</b></code></p></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>__placeholder_object</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>__placeholder_object</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Object used internally by the compiler.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>__null_program</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>call_out</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>_do_call_outs</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>find_call_out</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>remove_call_out</b></span><br> <span class='homogen--type'>Method</span> <span class='homogen--name'><b>call_out_info</b></span><br> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>call_out</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>float</code>|<code class='datatype'>int</code> <code class='argument'>delay</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code><b>)</b></code><br> <code><code class='datatype'>void</code> <b><span class='method'>_do_call_outs</span>(</b><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>find_call_out</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>find_call_out</span>(</b><code class='datatype'>mixed</code> <code class='argument'>id</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>remove_call_out</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>remove_call_out</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>id</code><b>)</b></code><br> <code><code class='datatype'>array</code>(<code class='datatype'>array</code>) <b><span class='method'>call_out_info</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>These are aliases for the corresponding functions in <code>Pike.DefaultBackend</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Pike.Backend()-&gt;call_out()</code>, <code>Pike.Backend()-&gt;_do_call_outs()</code>, <code>Pike.Backend()-&gt;find_call_out()</code>, <code>Pike.Backend()-&gt;remove_call_out()</code>, <code>Pike.Backend()-&gt;call_out_info()</code></p> </dd></dl>
9b13162019-11-02Tobias S. Josefowitz <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>_equal</b></span> </dt> <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>_equal</span>(</b><code class='datatype'>mixed</code> <code class='argument'>o</code><b>)</b></code></p></dd> </dl>
7393ca2019-08-17Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>_exit</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>_exit</span>(</b><code class='datatype'>int</code> <code class='argument'>returncode</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function does the same as <code>exit</code>, but doesn't bother to clean up the Pike interpreter before exiting. This means that no destructors will be called, caches will not be flushed, file locks might not be released, and databases might not be closed properly.</p> <p> Use with extreme caution.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>exit()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>_gdb_breakpoint</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>_gdb_breakpoint</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function only exists so that it is possible to set a gdb breakpoint on the function pike_gdb_breakpoint.</p> </dd></dl>
9b13162019-11-02Tobias S. Josefowitz <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>_m_delete</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>_m_delete</span>(</b><code class='datatype'>mixed</code> <code class='argument'>key</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>m_delete callback.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>_random</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>_random</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>random_string</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>random</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get a random entry.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>An array <code class='expr'>({&nbsp;key,&nbsp;value&nbsp;})</code>.</p> </dd></dl>
7393ca2019-08-17Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Variable</span> <span class='homogen--name'><b>_static_modules</b></span> </dt> <dd><p><code><code class='datatype'>object</code> <b><span class='variable'>_static_modules</span></b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This is an object containing the classes for all static (ie non-dynamic) C-modules.</p> <p> In a typic Pike with support for dynamic modules the contained module classes are:</p> <dl class='group--doc'><dt><p><code>Builtin</code></p> </dt><dt><p><code>Gmp</code></p> </dt><dt><p><code>_Stdio</code></p> </dt><dt><p><code>_math</code></p> </dt><dt><p><code>_system</code></p> </dt></dl><p>If the Pike binary lacks support for dynamic modules, all C-modules will show up here.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>abs</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>abs</span>(</b><code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>abs</span>(</b><code class='datatype'>int</code> <code class='argument'>f</code><b>)</b></code><br> <code><code class='datatype'>object</code> <b><span class='method'>abs</span>(</b><code class='datatype'>object</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the absolute value for <code>f</code>. If <code>f</code> is an object it must implement <code>lfun::`&lt;</code> and unary <code>lfun::`-</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>acos</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>acos</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the arcus cosine value for <code>f</code>. The result will be in radians.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>cos()</code>, <code>asin()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>acosh</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>acosh</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the hyperbolic arcus cosine value for <code>f</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>cosh()</code>, <code>asinh()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>add_constant</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>add_constant</span>(</b><code class='datatype'>string</code> <code class='argument'>name</code>, <code class='datatype'>mixed</code> <code class='argument'>value</code><b>)</b></code><br> <code><code class='datatype'>void</code> <b><span class='method'>add_constant</span>(</b><code class='datatype'>string</code> <code class='argument'>name</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Add a new predefined constant.</p> <p> This function is often used to add builtin functions. All programs compiled after the <code>add_constant()</code> function has been called can access <code>value</code> by the name <code>name</code>.</p> <p> If there is a constant called <code>name</code> already, it will be replaced by by the new definition. This will not affect already compiled programs.</p> <p> Calling <code>add_constant()</code> without a value will remove that name from the list of constants. As with replacing, this will not affect already compiled programs.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>all_constants()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>aggregate</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>aggregate</span>(</b><code class='datatype'>mixed</code> ... <code class='argument'>elements</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Construct an array with the arguments as indices.</p> <p> This function could be written in Pike as:</p> <pre><code><span class='type'>array</span> aggregate<span class='delim'>(</span><span class='type'>mixed</span> ... elems<span class='delim'>)</span> <span class='delim'>{</span> <span class='lang'>return</span> elems<span class='delim'>;</span> <span class='delim'>}</span> </code></pre> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Arrays are dynamically allocated there is no need to declare them like <code class='expr'>int&nbsp;a[10]=allocate(10);</code> (and it isn't possible either) like in C, just <code class='expr'>array(int)&nbsp;a=allocate(10);</code> will do.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sizeof()</code>, <code>arrayp()</code>, <code>allocate()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>aggregate_mapping</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code> <b><span class='method'>aggregate_mapping</span>(</b><code class='datatype'>mixed</code> ... <code class='argument'>elems</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Construct a mapping.</p> <p> Groups the arguments together two and two in key-index pairs and creates a mapping of those pairs. Generally, the mapping literal syntax is handier: <code class='expr'>([&nbsp;key1:val1,&nbsp;key2:val2,&nbsp;...&nbsp;])</code></p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sizeof()</code>, <code>mappingp()</code>, <code>mkmapping()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>aggregate_multiset</b></span> </dt> <dd><p><code><code class='datatype'>multiset</code> <b><span class='method'>aggregate_multiset</span>(</b><code class='datatype'>mixed</code> ... <code class='argument'>elems</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Construct a multiset with the arguments as indices. The multiset will not contain any values. This method is most useful when constructing multisets with <code>map</code> or similar; generally, the multiset literal syntax is handier: <code class='expr'>(&lt;elem1,&nbsp;elem2,&nbsp;...&gt;)</code> With it, it's also possible to construct a multiset with values: <code class='expr'>(&lt;index1:&nbsp;value1,&nbsp;index2:&nbsp;value2,&nbsp;...&gt;)</code></p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sizeof()</code>, <code>multisetp()</code>, <code>mkmultiset()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>alarm</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>alarm</span>(</b><code class='datatype'>int</code> <code class='argument'>seconds</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Set an alarm clock for delivery of a signal.</p> <p> <code>alarm()</code> arranges for a SIGALRM signal to be delivered to the process in <code>seconds</code> seconds.</p> <p> If <code>seconds</code> is <code class='expr'>0</code> (zero), no new alarm will be scheduled.</p> <p> Any previous alarms will in any case be canceled.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the number of seconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is only available on platforms that support signals.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>ualarm()</code>, <code>signal()</code>, <code>call_out()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>all_constants</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>) <b><span class='method'>all_constants</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns a mapping containing all global constants, indexed on the name of the constant, and with the value of the constant as value.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>add_constant()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>allocate</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>allocate</span>(</b><code class='datatype'>int</code> <code class='argument'>size</code><b>)</b></code><br> <code><code class='datatype'>array</code> <b><span class='method'>allocate</span>(</b><code class='datatype'>int</code> <code class='argument'>size</code>, <code class='datatype'>mixed</code> <code class='argument'>init</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Allocate an array of <code>size</code> elements. If <code>init</code> is specified then each element is initialized by copying that value recursively.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sizeof()</code>, <code>aggregate()</code>, <code>arrayp()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>array_sscanf</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>array_sscanf</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>string</code> <code class='argument'>format</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function works just like <code>sscanf()</code>, but returns the matched results in an array instead of assigning them to lvalues. This is often useful for user-defined sscanf strings.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sscanf()</code>, <code>`/()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>asin</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>asin</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the arcus sine value for <code>f</code>. The result will be in radians.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sin()</code>, <code>acos()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>asinh</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>asinh</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the hyperbolic arcus sine value for <code>f</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sinh()</code>, <code>acosh()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>atan</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>atan</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the arcus tangent value for <code>f</code>. The result will be in radians.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>tan()</code>, <code>asin()</code>, <code>acos()</code>, <code>atan2()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>atan2</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>atan2</span>(</b><code class='datatype'>float</code> <code class='argument'>f1</code>, <code class='datatype'>float</code> <code class='argument'>f2</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the arcus tangent value for <code>f1</code>/<code>f2</code>, and uses the signs of <code>f1</code> and <code>f2</code> to determine the quadrant. The result will be in radians.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>tan()</code>, <code>asin()</code>, <code>acos()</code>, <code>atan()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>atanh</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>atanh</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the hyperbolic arcus tangent value for <code>f</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>tanh()</code>, <code>asinh()</code>, <code>acosh()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>atexit</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>atexit</span>(</b><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>callback</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function puts the <code>callback</code> in a queue of callbacks to call when pike exits. The call order is reversed, i.e. callbacks that have been added earlier are called after <code>callback</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Please note that <code>atexit</code> callbacks are not called if Pike exits abnormally.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>exit()</code>, <code>_exit()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>backtrace</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='object unresolved'>Pike.BacktraceFrame</code>) <b><span class='method'>backtrace</span>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>flags</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get a description of the current call stack.</p> </dd> <dt class='head--doc'><span id='p-flags'></span>Parameter <code class='parameter'>flags</code></dt> <dd></dd><dd class='body--doc'><p>A bit mask of flags affecting generation of the backtrace.</p> <p> Currently a single flag is defined:</p> <table class='box'><tr><td><code><code class='key'>1</code></code></td><td><p>Return <code>LiveBacktraceFrame</code>s. This flag causes the frame objects to track changes (as long as they are in use), and makes eg local variables for functions available for inspection or change.</p> <p> Note that since these values are "live", they may change or dissapear at any time unless the corresponding thread has been halted or similar.</p> </td></tr> </table> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The description is returned as an array with one entry for each call frame on the stack.</p> <p> The entries are represented by <code>Pike.BacktraceFrame</code> objects.</p> <p> The current call frame will be last in the array.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Please note that the frame order may be reversed in a later version of Pike to accommodate for deferred backtraces.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that the arguments reported in the backtrace are the current values of the variables, and not the ones that were at call-time. This can be used to hide sensitive information from backtraces (eg passwords).</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>In old versions of Pike the entries used to be represented by arrays of the following format:</p> <table class='box'><tr><td colspan='2'>Array</td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>file</code></code></td><td><p>A string with the filename if known, else zero.</p> </td></tr> <tr><td><code><code class='datatype'>int</code> <code class='key'>line</code></code></td><td><p>An integer containing the linenumber if known, else zero.</p> </td></tr> <tr><td><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='key'>fun</code></code></td><td><p>The function that was called at this level.</p> </td></tr> <tr><td><code><code class='datatype'>mixed</code>|<code class='datatype'>void</code> ... <code class='key'>args</code></code></td><td><p>The arguments that the function was called with.</p> </td></tr> </table><p>The above format is still supported by eg <code>describe_backtrace()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>catch()</code>, <code>throw()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>basetype</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>basetype</span>(</b><code class='datatype'>mixed</code> <code class='argument'>x</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Same as sprintf("%t",x);</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sprintf()</code></p> </dd></dl>
9b13162019-11-02Tobias S. Josefowitz <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>bkey</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>bkey</span>(</b><code class='datatype'>mixed</code> <code class='argument'>key</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Render the internally used binary representation of the key into a string as a strings of '0's and '1's.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>cast</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code> <b><span class='method'>cast</span>(</b><code class='datatype'>string</code> <code class='argument'>type</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Cast callback. Supports only cast to mapping and behaves as the inverse of create().</p> </dd></dl>
7393ca2019-08-17Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>ceil</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>ceil</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the closest integer value greater or equal to <code>f</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p><code>ceil()</code> does <b>not</b> return an <code class='expr'>int</code>, merely an integer value stored in a <code class='expr'>float</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>floor()</code>, <code>round()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>column</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>column</span>(</b><code class='datatype'>array</code> <code class='argument'>data</code>, <code class='datatype'>mixed</code> <code class='argument'>index</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Extract a column from a two-dimensional array.</p> <p> This function is exactly equivalent to:</p> <pre><code>map<span class='delim'>(</span>data<span class='delim'>,</span> <span class='lang'>lambda</span><span class='delim'>(</span><span class='type'>mixed</span> x<span class='delim'>,</span><span class='type'>mixed</span> y<span class='delim'>)</span> <span class='delim'>{</span> <span class='lang'>return</span> x<span class='delim'>[</span>y<span class='delim'>]</span><span class='delim'>;</span> <span class='delim'>}</span><span class='delim'>,</span> index<span class='delim'>)</span> </code></pre><p>Except of course it is a lot shorter and faster. That is, it indices every index in the array data on the value of the argument index and returns an array with the results.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>rows()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>compile</b></span> </dt> <dd><p><code><code class='datatype'>program</code> <b><span class='method'>compile</span>(</b><code class='datatype'>string</code> <code class='argument'>source</code>, <code class='object unresolved'>CompilationHandler</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>major</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>minor</code>, <code class='datatype'>program</code>|<code class='datatype'>void</code> <code class='argument'>target</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>placeholder</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Compile a string to a program.</p> <p> This function takes a piece of Pike code as a string and compiles it into a clonable program.</p> <p> The optional argument <code>handler</code> is used to specify an alternative error handler. If it is not specified the current master object will be used.</p> <p> The optional arguments <code>major</code> and <code>minor</code> are used to tell the compiler to attempt to be compatible with Pike <code>major</code>.<code>minor</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that <code>source</code> must contain the complete source for a program. It is not possible to compile a single expression or statement.</p> <p> Also note that <code>compile()</code> does not preprocess the program. To preprocess the program you can use <code>compile_string()</code> or call the preprocessor manually by calling <code>cpp()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>compile_string()</code>, <code>compile_file()</code>, <code>cpp()</code>, <code>master()</code>, <code>CompilationHandler</code>, <code>DefaultCompilerEnvironment</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>copy_value</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>copy_value</span>(</b><code class='datatype'>mixed</code> <code class='argument'>value</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Copy a value recursively.</p> <p> If the result value is changed destructively (only possible for multisets, arrays and mappings) the copied value will not be changed.</p> <p> The resulting value will always be equal to the copied (as tested with the function <code>equal()</code>), but they may not the the same value (as tested with <code>`==()</code>).</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>equal()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>cos</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>cos</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the cosine value for <code>f</code>. <code>f</code> should be specified in radians.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>acos()</code>, <code>sin()</code>, <code>tan()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>cosh</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>cosh</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the hyperbolic cosine value for <code>f</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>acosh()</code>, <code>sinh()</code>, <code>tanh()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>cpp</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>cpp</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>mapping</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>current_file</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>charset</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>compat_major</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>compat_minor</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>picky_cpp</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Run a string through the preprocessor.</p> <p> Preprocesses the string <code>data</code> with Pike's builtin ANSI-C look-alike preprocessor. If the <code>current_file</code> argument has not been specified, it will default to <code class='expr'>"-"</code>. <code>charset</code> defaults to <code class='expr'>"ISO-10646"</code>.</p> <p> If the second argument is a mapping, no other arguments may follow. Instead, they have to be given as members of the mapping (if wanted). The following members are recognized:</p> <table class='box'><tr><td><code><code class='key'>"current_file"</code> : <code class='datatype'>string</code></code></td><td><p>Name of the current file. It is used for generating #line directives and for locating include files.</p> </td></tr> <tr><td><code><code class='key'>"charset"</code> : <code class='datatype'>int</code>|<code class='datatype'>string</code></code></td><td><p>Charset to use when processing <code class='expr'>data</code>.</p> </td></tr> <tr><td><code><code class='key'>"handler"</code> : <code class='datatype'>object</code></code></td><td><p>Compilation handler.</p> </td></tr> <tr><td><code><code class='key'>"compat_major"</code> : <code class='datatype'>int</code></code></td><td><p>Sets the major pike version used for compat handling.</p> </td></tr> <tr><td><code><code class='key'>"compat_minor"</code> : <code class='datatype'>int</code></code></td><td><p>Sets the minor pike version used for compat handling.</p> </td></tr> <tr><td><code><code class='key'>"picky_cpp"</code> : <code class='datatype'>int</code></code></td><td><p>Generate more warnings.</p> </td></tr> <tr><td><code><code class='key'>"keep_comments"</code> : <code class='datatype'>int</code></code></td><td><p>This option keeps <code>cpp()</code> from removing comments. Useful in combination with the prefix feature below.</p> </td></tr> <tr><td><code><code class='key'>"prefix"</code> : <code class='datatype'>string</code></code></td><td><p>If a prefix is given, only prefixed directives will be processed. For example, if the prefix is <code class='expr'>"foo"</code>, then <code class='expr'>#foo_ifdef&nbsp;COND</code> and <code class='expr'>foo___LINE__</code> would be processed, <code class='expr'>#ifdef&nbsp;COND</code> and <code class='expr'>__LINE__</code> would not.</p> </td></tr> <tr><td><code><code class='key'>"predefines"</code> : <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>)</code></td><td><p>Mapping of predefined macros in addition to those returned by <code>CPP()-&gt;get_predefines()</code>.</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>compile()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>ctime</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>ctime</span>(</b><code class='datatype'>int</code> <code class='argument'>timestamp</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Convert the output from a previous call to <code>time()</code> into a readable string containing the current year, month, day and time.</p> <p> Like <code>localtime</code>, this function might throw an error if the ctime(2) call failed on the system. It's platform dependent what time ranges that function can handle, e.g. Windows doesn't handle a negative <code>timestamp</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>strftime()</code>, <code>time()</code>, <code>localtime()</code>, <code>gmtime()</code>, <code>mktime()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>decode_value</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>decode_value</span>(</b><code class='datatype'>string</code> <code class='argument'>coded_value</code>, <code class='datatype'>void</code>|<code class='object unresolved'>Codec</code> <code class='argument'>codec</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Decode a value from the string <code>coded_value</code>.</p> <p> This function takes a string created with <code>encode_value()</code> or <code>encode_value_canonic()</code> and converts it back to the value that was coded.</p> <p> If <code>codec</code> is specified, it's used as the codec for the decode. If none is specified, then one is instantiated through <code class='expr'>master()-&gt;Decoder()</code>. As a compatibility fallback, the master itself is used if it has no <code class='expr'>Decoder</code> class.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>encode_value()</code>, <code>encode_value_canonic()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>delay</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>delay</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>s</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function makes the thread stop for <code>s</code> seconds.</p> <p> Only signal handlers can interrupt the sleep. Other callbacks are not called during delay. Beware that this function uses busy-waiting to achieve the highest possible accuracy.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>signal()</code>, <code>sleep()</code></p> </dd></dl>
9b13162019-11-02Tobias S. Josefowitz <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>depth</b></span> </dt> <dd><p><code><code class='datatype'>int(0..)</code> <b><span class='method'>depth</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Calculate the depth of the tree.</p> </dd></dl>
7393ca2019-08-17Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>destruct</b></span> </dt> <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>destruct</span>(</b><code class='datatype'>void</code>|<code class='datatype'>object</code> <code class='argument'>o</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Mark an object as destructed.</p> <p> Calls <code class='expr'>o-&gt;_destruct()</code>, and then clears all variables in the object. If no argument is given, the current object is destructed.</p> <p> All pointers and function pointers to this object will become zero. The destructed object will be freed from memory as soon as possible.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if <code>o</code> has an <code>lfun::_destruct()</code> that returned <code class='expr'>1</code> and inhibited destruction.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>encode_value</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>encode_value</span>(</b><code class='datatype'>mixed</code> <code class='argument'>value</code>, <code class='object unresolved'>Codec</code>|<code class='datatype'>void</code> <code class='argument'>codec</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Code a value into a string.</p> <p> This function takes a value, and converts it to a string. This string can then be saved, sent to another Pike process, packed or used in any way you like. When you want your value back you simply send this string to <code>decode_value()</code> and it will return the value you encoded.</p> <p> Almost any value can be coded, mappings, floats, arrays, circular structures etc.</p> <p> If <code>codec</code> is specified, it's used as the codec for the encode. If none is specified, then one is instantiated through <code class='expr'>master()-&gt;Encoder()</code>. As a compatibility fallback, the master itself is used if it has no <code class='expr'>Encoder</code> class.</p> <p> If <code class='expr'><code>codec</code>-&gt;nameof(o)</code> returns <tt>UNDEFINED</tt> for an object, <code class='expr'>val&nbsp;=&nbsp;o-&gt;encode_object(o)</code> will be called. The returned value will be passed to <code class='expr'>o-&gt;decode_object(o,&nbsp;val)</code> when the object is decoded.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>When only simple types like int, floats, strings, mappings, multisets and arrays are encoded, the produced string is very portable between pike versions. It can at least be read by any later version.</p> <p> The portability when objects, programs and functions are involved depends mostly on the codec. If the byte code is encoded, i.e. when Pike programs are actually dumped in full, then the string can probably only be read by the same pike version.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>decode_value()</code>, <code>sprintf()</code>, <code>encode_value_canonic()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>encode_value_canonic</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>encode_value_canonic</span>(</b><code class='datatype'>mixed</code> <code class='argument'>value</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>codec</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Code a value into a string on canonical form.</p> <p> Takes a value and converts it to a string on canonical form, much like <code>encode_value()</code>. The canonical form means that if an identical value is encoded, it will produce exactly the same string again, even if it's done at a later time and/or in another Pike process. The produced string is compatible with <code>decode_value()</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that this function is more restrictive than <code>encode_value()</code> with respect to the types of values it can encode. It will throw an error if it can't encode to a canonical form.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>encode_value()</code>, <code>decode_value()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>enumerate</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) <b><span class='method'>enumerate</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code><b>)</b></code><br> <code><code class='datatype'>array</code> <b><span class='method'>enumerate</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>void</code>|<code class='datatype'>mixed</code> <code class='argument'>step</code>, <code class='datatype'>void</code>|<code class='datatype'>mixed</code> <code class='argument'>start</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>operator</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Create an array with an enumeration, useful for initializing arrays or as first argument to <code>map()</code> or <code>foreach()</code>.</p> <p> The defaults are: <code>step</code> = 1, <code>start</code> = 0, <code>operator</code> = <code>`+</code></p> <h1>Advanced use</h1> <p>The resulting array is calculated like this:</p> <pre><code><span class='type'>array</span> enumerate<span class='delim'>(</span><span class='type'>int</span> n<span class='delim'>,</span> <span class='type'>mixed</span> step<span class='delim'>,</span> <span class='type'>mixed</span> start<span class='delim'>,</span> <span class='type'>function</span> operator<span class='delim'>)</span> <span class='delim'>{</span> <span class='type'>array</span> res <span class='delim'>=</span> allocate<span class='delim'>(</span>n<span class='delim'>)</span><span class='delim'>;</span> <span class='lang'>for</span> <span class='delim'>(</span><span class='type'>int</span> i<span class='delim'>=</span>0<span class='delim'>;</span> i <span class='delim'>&lt;</span> n<span class='delim'>;</span> i++<span class='delim'>)</span> <span class='delim'>{</span> res<span class='delim'>[</span>i<span class='delim'>]</span> <span class='delim'>=</span> start<span class='delim'>;</span> start <span class='delim'>=</span> operator<span class='delim'>(</span>start<span class='delim'>,</span> step<span class='delim'>)</span><span class='delim'>;</span> <span class='delim'>}</span> <span class='lang'>return</span> res<span class='delim'>;</span> <span class='delim'>}</span> </code></pre> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>map()</code>, <code>foreach()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>equal</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>equal</span>(</b><code class='datatype'>mixed</code> <code class='argument'>a</code>, <code class='datatype'>mixed</code> <code class='argument'>b</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function checks if the values <code>a</code> and <code>b</code> are equivalent.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>If either of the values is an object the (normalized) result of calling <code>lfun::_equal()</code> will be returned.</p> <p> Returns <code class='expr'>1</code> if both values are false (zero, destructed objects, prototype functions, etc).</p> <p> Returns <code class='expr'>0</code> (zero) if the values have different types.</p> <p> Otherwise depending on the type of the values:</p> <table class='box'><tr><td><code><code class='datatype'>int</code></code></td><td><p>Returns the same as <code class='expr'>a&nbsp;==&nbsp;b</code>.</p> </td></tr> <tr><td><code><code class='datatype'>array</code></code></td><td><p>The contents of <code>a</code> and <code>b</code> are checked recursively, and if all their contents are <code>equal</code> and in the same place, they are considered equal.</p> <p> Note that for objects this case is only reached if neither <code>a</code> nor <code>b</code> implements <code>lfun::_equal()</code>.</p> </td></tr> <tr><td><code><code class='type'>type</code></code></td><td><p>Returns <code class='expr'>(a&nbsp;&lt;=&nbsp;b)&nbsp;&amp;&amp;&nbsp;(b&nbsp;&lt;=&nbsp;a)</code>.</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>copy_value()</code>, <code>`==()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>is_gssapi_error</b></span><br> <span class='homogen--type'>Constant</span> <span class='homogen--name'><b>error_type</b></span><br> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>is_gssapi_error</code></code><br> <code><code class='datatype'>constant</code> <code class='datatype'>string</code> <code class='constant'>error_type</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Object recognition constants.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>is_gssapi_missing_services_error</b></span><br> <span class='homogen--type'>Constant</span> <span class='homogen--name'><b>error_type</b></span><br> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>is_gssapi_missing_services_error</code></code><br> <code><code class='datatype'>constant</code> <code class='datatype'>string</code> <code class='constant'>error_type</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Object recognition constants.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>exece</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>exece</span>(</b><code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>args</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>exece</span>(</b><code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>args</code>, <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>env</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function transforms the Pike process into a process running the program specified in the argument <code>file</code> with the arguments <code>args</code>.</p> <p> If the mapping <code>env</code> is present, it will completely replace all environment variables before the new program is executed.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>This function only returns if something went wrong during <tt>exece(2)</tt>, and in that case it returns <code class='expr'>0</code> (zero).</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The Pike driver _dies_ when this function is called. You must either use <code>fork()</code> or <code>Process.create_process()</code> if you wish to execute a program and still run the Pike runtime.</p> <p> This function is not available on all platforms.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Process.create_process()</code>, <code>fork()</code>, <code>Stdio.File-&gt;pipe()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>exit</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>exit</span>(</b><code class='datatype'>int</code> <code class='argument'>returncode</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>fmt</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Exit the whole Pike program with the given <code>returncode</code>.</p> <p> Using <code>exit()</code> with any other value than <code class='expr'>0</code> (zero) indicates that something went wrong during execution. See your system manuals for more information about return codes.</p> <p> The arguments after the <code>returncode</code> will be used for a call to <code>werror</code> to output a message on stderr.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>_exit()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>exp</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>exp</span>(</b><code class='datatype'>float</code>|<code class='datatype'>int</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the natural exponential of <code>f</code>. <code class='expr'>log(&nbsp;exp(&nbsp;x&nbsp;)&nbsp;)&nbsp;==&nbsp;x</code> as long as exp(x) doesn't overflow an int.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>pow()</code>, <code>log()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>filter</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>filter</span>(</b><code class='datatype'>mixed</code> <code class='argument'>arr</code>, <code class='datatype'>void</code>|<code class='datatype'>mixed</code> <code class='argument'>fun</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Filters the elements in <code>arr</code> through <code>fun</code>.</p> <p> <code>arr</code> is treated as a set of elements to be filtered, as follows:</p> <dl class='group--doc'><dt>array</dt> <dt>multiset</dt> <dt>string</dt> <dd><p>Each element is filtered with <code>fun</code>. The return value is of the same type as <code>arr</code> and it contains the elements that <code>fun</code> accepted. <code>fun</code> is applied in order to each element, and that order is retained between the kept elements.</p> <p> If <code>fun</code> is an array, it should have the same length as <code>arr</code>. In this case, the elements in <code>arr</code> are kept where the corresponding positions in <code>fun</code> are nonzero. Otherwise <code>fun</code> is used as described below.</p> </dd> <dt>mapping</dt> <dd><p>The values are filtered with <code>fun</code>, and the index/value pairs it accepts are kept in the returned mapping.</p> </dd> <dt>program</dt> <dd><p>The program is treated as a mapping containing the identifiers that are indexable from it and their values.</p> </dd> <dt>object</dt> <dd><p>If there is a <code>lfun::cast</code> method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then filtered as described above.</p> </dd> </dl><p>Unless something else is mentioned above, <code>fun</code> is used as filter like this:</p> <dl class='group--doc'><dt>function</dt> <dd><p><code>fun</code> is called for each element. It gets the current element as the first argument and <code>extra</code> as the rest. The element is kept if it returns true, otherwise it's filtered out.</p> </dd> <dt>object</dt> <dd><p>The object is used as a function like above, i.e. the <code>lfun::`()</code> method in it is called.</p> </dd> <dt>multiset</dt> <dt>mapping</dt> <dd><p><code>fun</code> is indexed with each element. The element is kept if the result is nonzero, otherwise it's filtered out.</p> </dd> <dt>"zero or left out"</dt> <dd><p>Each element that is callable is called with <code>extra</code> as arguments. The element is kept if the result of the call is nonzero, otherwise it's filtered out. Elements that aren't callable are also filtered out.</p> </dd> <dt>string</dt> <dd><p>Each element is indexed with the given string. If the result of that is zero then the element is filtered out, otherwise the result is called with <code>extra</code> as arguments. The element is kept if the return value is nonzero, otherwise it's filtered out.</p> <p> This is typically used when <code>arr</code> is a collection of objects, and <code>fun</code> is the name of some predicate function in them.</p> </dd> </dl> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The function is never destructive on <code>arr</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>map()</code>, <code>foreach()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>floor</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>floor</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the closest integer value less or equal to <code>f</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p><code>floor()</code> does <b>not</b> return an <code class='expr'>int</code>, merely an integer value stored in a <code class='expr'>float</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>ceil()</code>, <code>round()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>fork</b></span> </dt> <dd><p><code><code class='datatype'>object</code> <b><span class='method'>fork</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Fork the process in two.</p> <p> Fork splits the process in two, and for the parent it returns a pid object for the child. Refer to your Unix manual for further details.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function can cause endless bugs if used without proper care.</p> <p> This function is disabled when using threads.</p> <p> This function is not available on all platforms.</p> <p> The most common use for fork is to start sub programs, which is better done with <code>Process.create_process()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Process.create_process()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>gc</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>gc</span>(</b><code class='datatype'>mapping</code>|<code class='datatype'>array</code>|<code class='datatype'>void</code> <code class='argument'>quick</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Force garbage collection.</p> </dd> <dt class='head--doc'><span id='p-quick'></span>Parameter <code class='parameter'>quick</code></dt> <dd></dd><dd class='body--doc'><p>Perform a quick garbage collection on just this value, which must have been made weak by <code>set_weak_flag()</code>. All values that only have a single reference from <code>quick</code> will then be freed.</p> <p> When <code>quick</code> hasn't been specified or is <code>UNDEFINED</code>, this function checks all the memory for cyclic structures such as arrays containing themselves and frees them if appropriate. It also frees up destructed objects and things with only weak references.</p> <p> Normally there is no need to call this function since Pike will call it by itself every now and then. (Pike will try to predict when 20% of all arrays/object/programs in memory is 'garbage' and call this routine then.)</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The amount of garbage is returned. This is the number of arrays, mappings, multisets, objects and programs that had no nonweak external references during the garbage collection. It's normally the same as the number of freed things, but there might be some difference since _destruct() functions are called during freeing, which can cause more things to be freed or allocated.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Pike.gc_parameters</code>, <code>Debug.gc_status</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_active_compiler</b></span> </dt> <dd><p><code><code class='object unresolved'>CompilerEnvironment.PikeCompiler</code> <b><span class='method'>get_active_compiler</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the most recent of the currently active pike compilers, or <code>UNDEFINED</code> if none is active.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function should only be used during a call of <code>compile()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>get_active_error_handler()</code>, <code>compile()</code>, <code>master()-&gt;get_compilation_handler()</code>, <code>CompilationHandler</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_all_groups</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>))) <b><span class='method'>get_all_groups</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns an array of arrays with all groups in the system groups source. Each element in the returned array has the same structure as in <code>getgrent</code> function.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The groups source is system dependant. Refer to your system manuals for information about how to set the source.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><table class='box'><tr><td colspan='2'>Array</td></tr> <tr><td><code><code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <code class='key'>0..</code></code></td><td><p>Array with info about the group</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>getgrent()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_all_users</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>)) <b><span class='method'>get_all_users</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns an array with all users in the system.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>An array with arrays of userinfo as in <code>getpwent</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>getpwent()</code> <code>getpwnam()</code> <code>getpwuid()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_groups_for_user</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) <b><span class='method'>get_groups_for_user</span>(</b><code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>user</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Gets all groups which a given user is a member of.</p> </dd> <dt class='head--doc'><span id='p-user'></span>Parameter <code class='parameter'>user</code></dt> <dd></dd><dd class='body--doc'><p>UID or loginname of the user</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><table class='box'><tr><td colspan='2'>Array</td></tr> <tr><td><code><code class='datatype'>array</code> <code class='key'>0..</code></code></td><td><p>Information about all the users groups</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>get_all_groups()</code> <code>getgrgid()</code> <code>getgrnam()</code> <code>getpwuid()</code> <code>getpwnam()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_iterator</b></span> </dt> <dd><p><code><code class='object unresolved'>Iterator</code> <b><span class='method'>get_iterator</span>(</b><code class='datatype'>object</code>|<code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code>|<code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Creates and returns a canonical iterator for <code>data</code>.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><code>data</code> can have any of the following types:<br /><table class='box'><tr><td><code><code class='datatype'>object</code></code></td><td><p>If <code>data</code> is an object with <code>lfun::_get_iterator</code> defined then it's called in it with the arguments <code>args</code> to create the iterator.</p> <p> If <code>data</code> is an object that lacks <code>lfun::_get_iterator</code> then it's assumed to already be an iterator object, and is simply returned.</p> </td></tr> <tr><td><code><code class='datatype'>array</code></code></td><td><p>If <code>data</code> is an array, an <code>Array.Iterator</code> object will be returned.</p> </td></tr> <tr><td><code><code class='datatype'>mapping</code></code></td><td><p>If <code>data</code> is a mapping, a <code>Mapping.Iterator</code> object will be returned</p> </td></tr> <tr><td><code><code class='datatype'>multiset</code></code></td><td><p>If <code>data</code> is a multiset, a <code>Multiset.Iterator</code> object will be returned</p> </td></tr> <tr><td><code><code class='datatype'>string</code></code></td><td><p>If <code>data</code> is a string, a <code>String.Iterator</code> object will be returned</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is used by <code>foreach</code> to get an iterator for an object.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Iterator</code>, <code>lfun::_get_iterator</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>getgrgid</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <b><span class='method'>getgrgid</span>(</b><code class='datatype'>int</code> <code class='argument'>gid</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the group entry for the group with the id <code>gid</code> using the systemfunction <tt>getgrid(3)</tt>.</p> </dd> <dt class='head--doc'><span id='p-gid'></span>Parameter <code class='parameter'>gid</code></dt> <dd></dd><dd class='body--doc'><p>The id of the group</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>An array with the information about the group</p> <table class='box'><tr><td colspan='2'>Array</td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>0</code></code></td><td><p>Group name</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>1</code></code></td><td><p>Group password (encrypted)</p> </td></tr> <tr><td><code><code class='datatype'>int</code> <code class='key'>2</code></code></td><td><p>ID of the group</p> </td></tr> <tr><td><code><code class='datatype'>array</code> <code class='key'>3..</code></code></td><td><p>Array with UIDs of group members</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>getgrent()</code> <code>getgrnam()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>getgrnam</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <b><span class='method'>getgrnam</span>(</b><code class='datatype'>string</code> <code class='argument'>str</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the group entry for the group with the name <code>str</code> using the systemfunction <tt>getgrnam(3)</tt>.</p> </dd> <dt class='head--doc'><span id='p-str'></span>Parameter <code class='parameter'>str</code></dt> <dd></dd><dd class='body--doc'><p>The name of the group</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>An array with the information about the group</p> <table class='box'><tr><td colspan='2'>Array</td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>0</code></code></td><td><p>Group name</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>1</code></code></td><td><p>Group password (encrypted)</p> </td></tr> <tr><td><code><code class='datatype'>int</code> <code class='key'>2</code></code></td><td><p>ID of the group</p> </td></tr> <tr><td><code><code class='datatype'>array</code> <code class='key'>3..</code></code></td><td><p>Array with UIDs of group members</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>getgrent()</code> <code>getgrgid()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>gethrdtime</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>gethrdtime</span>(</b><code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>nsec</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the high resolution real time spent with threads disabled since the Pike interpreter was started. The time is normally returned in microseconds, but if the optional argument <code>nsec</code> is nonzero it's returned in nanoseconds.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See <code>System.REAL_TIME_RESOLUTION</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>_disable_threads()</code>, <code>gethrtime()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>gethrtime</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>gethrtime</span>(</b><code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>nsec</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the high resolution real time since some arbitrary event in the past. The time is normally returned in microseconds, but if the optional argument <code>nsec</code> is nonzero it's returned in nanoseconds.</p> <p> It's system dependent whether or not this time is monotonic, i.e. if it's unaffected by adjustments of the calendaric clock in the system. <code>System.REAL_TIME_IS_MONOTONIC</code> tells what it is. Pike tries to use monotonic time for this function if it's available.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See <code>System.REAL_TIME_RESOLUTION</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>System.REAL_TIME_IS_MONOTONIC</code>, <code>System.REAL_TIME_RESOLUTION</code>, <code>time()</code>, <code>System.gettimeofday()</code>, <code>gethrvtime()</code>, <code>Pike.implicit_gc_real_time</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>gethrvtime</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>gethrvtime</span>(</b><code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>nsec</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the CPU time that has been consumed by this process or thread. -1 is returned if the system couldn't determine it. The time is normally returned in microseconds, but if the optional argument <code>nsec</code> is nonzero it's returned in nanoseconds.</p> <p> The CPU time includes both user and system time, i.e. it's approximately the same thing you would get by adding together the "utime" and "stime" fields returned by <code>System.getrusage</code> (but perhaps with better accuracy).</p> <p> It's however system dependent whether or not it's the time consumed in all threads or in the current one only; <code>System.CPU_TIME_IS_THREAD_LOCAL</code> tells which. If both types are available then thread local time is preferred.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The actual accuracy on many systems is significantly less than microseconds or nanoseconds. See <code>System.CPU_TIME_RESOLUTION</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The garbage collector might run automatically at any time. The time it takes is not included in the figure returned by this function, so that normal measurements aren't randomly clobbered by it. Explicit calls to <code>gc</code> are still included, though.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The special function <code>gauge</code> is implemented with this function.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>System.CPU_TIME_IS_THREAD_LOCAL</code>, <code>System.CPU_TIME_RESOLUTION</code>, <code>gauge()</code>, <code>System.getrusage()</code>, <code>gethrtime()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>getpid</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>getpid</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the process ID of this process.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>System.getppid()</code>, <code>System.getpgrp()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>getpwnam</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>) <b><span class='method'>getpwnam</span>(</b><code class='datatype'>string</code> <code class='argument'>str</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the user entry for login <code>str</code> using the systemfunction <tt>getpwnam(3)</tt>.</p> </dd> <dt class='head--doc'><span id='p-str'></span>Parameter <code class='parameter'>str</code></dt> <dd></dd><dd class='body--doc'><p>The login name of the user whos userrecord is requested.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>An array with the information about the user</p> <table class='box'><tr><td colspan='2'>Array</td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>0</code></code></td><td><p>Users username (loginname)</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>1</code></code></td><td><p>User password (encrypted)</p> </td></tr> <tr><td><code><code class='datatype'>int</code> <code class='key'>2</code></code></td><td><p>Users ID</p> </td></tr> <tr><td><code><code class='datatype'>int</code> <code class='key'>3</code></code></td><td><p>Users primary group ID</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>4</code></code></td><td><p>Users real name an possibly some other info</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>5</code></code></td><td><p>Users home directory</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>6</code></code></td><td><p>Users shell</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>getpwuid()</code> <code>getpwent()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>getpwuid</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>int</code>|<code class='datatype'>string</code>) <b><span class='method'>getpwuid</span>(</b><code class='datatype'>int</code> <code class='argument'>uid</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the user entry for UID <code>uid</code> using the systemfunction <tt>getpwuid(3)</tt>.</p> </dd> <dt class='head--doc'><span id='p-uid'></span>Parameter <code class='parameter'>uid</code></dt> <dd></dd><dd class='body--doc'><p>The uid of the user whos userrecord is requested.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>An array with the information about the user</p> <table class='box'><tr><td colspan='2'>Array</td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>0</code></code></td><td><p>Users username (loginname)</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>1</code></code></td><td><p>User password (encrypted)</p> </td></tr> <tr><td><code><code class='datatype'>int</code> <code class='key'>2</code></code></td><td><p>Users ID</p> </td></tr> <tr><td><code><code class='datatype'>int</code> <code class='key'>3</code></code></td><td><p>Users primary group ID</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>4</code></code></td><td><p>Users real name an possibly some other info</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>5</code></code></td><td><p>Users home directory</p> </td></tr> <tr><td><code><code class='datatype'>string</code> <code class='key'>6</code></code></td><td><p>Users shell</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>getpwnam()</code> <code>getpwent()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>getxattr</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>getxattr</span>(</b><code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the value of a specified attribute, or 0 if it does not exist.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>glob</b></span> </dt> <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>glob</span>(</b><code class='datatype'>string</code> <code class='argument'>glob</code>, <code class='datatype'>string</code> <code class='argument'>str</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>glob</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>glob</code>, <code class='datatype'>string</code> <code class='argument'>str</code><b>)</b></code><br> <code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>glob</span>(</b><code class='datatype'>string</code> <code class='argument'>glob</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>str</code><b>)</b></code><br> <code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>glob</span>(</b><code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>glob</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>str</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Match strings against a glob pattern.</p> </dd> <dt class='head--doc'><span id='p-glob'></span>Parameter <code class='parameter'>glob</code></dt> <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='datatype'>string</code></code></td><td><p>The glob pattern. A question sign ('?') matches any character and an asterisk ('*') matches a string of arbitrary length. All other characters only match themselves.</p> </td></tr> <tr><td><code><code class='datatype'>array</code>(<code class='datatype'>string</code>)</code></td><td><p>the function returns the matching glob if any of the given patterns match. Otherwise 0. If the second argument is an array it will behave as if the first argument is a string (see below)</p> </td></tr> </table> </dd> <dt class='head--doc'><span id='p-str'></span>Parameter <code class='parameter'>str</code></dt> <dd></dd><dd class='body--doc'><table class='box'><tr><td><code><code class='datatype'>string</code></code></td><td><p><code class='expr'>1</code> is returned if the string <code>str</code> matches <code>glob</code>, <code class='expr'>0</code> (zero) otherwise.</p> </td></tr> <tr><td><code><code class='datatype'>array</code>(<code class='datatype'>string</code>)</code></td><td><p>All strings in the array <code>str</code> are matched against <code>glob</code>, and those that match are returned in an array (in the same order).</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sscanf()</code>, <code>Regexp</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>gmtime</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>) <b><span class='method'>gmtime</span>(</b><code class='datatype'>int</code> <code class='argument'>timestamp</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Convert seconds since 00:00:00 UTC, Jan 1, 1970 into components.</p> <p> This function works like <code>localtime()</code> but the result is not adjusted for the local time zone.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>localtime()</code>, <code>time()</code>, <code>ctime()</code>, <code>mktime()</code>, <code>strptime()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>has_index</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>has_index</span>(</b><code class='datatype'>string</code> <code class='argument'>haystack</code>, <code class='datatype'>int</code> <code class='argument'>index</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>has_index</span>(</b><code class='datatype'>array</code> <code class='argument'>haystack</code>, <code class='datatype'>int</code> <code class='argument'>index</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>has_index</span>(</b><code class='datatype'>mapping</code>|<code class='datatype'>multiset</code>|<code class='datatype'>object</code>|<code class='datatype'>program</code> <code class='argument'>haystack</code>, <code class='datatype'>mixed</code> <code class='argument'>index</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Search for <code>index</code> in <code>haystack</code>.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if <code>index</code> is in the index domain of <code>haystack</code>, or <code class='expr'>0</code> (zero) if not found.</p> <p> This function is equivalent to (but sometimes faster than):</p> <pre><code>search(indices(haystack), index) != -1</code></pre> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>A negative index in strings and arrays as recognized by the index operators <code class='expr'>`[]()</code> and <code class='expr'>`[]=()</code> is not considered a proper index by <code>has_index()</code></p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>has_value()</code>, <code>has_prefix()</code>, <code>has_suffix()</code>, <code>indices()</code>, <code>search()</code>, <code>values()</code>, <code>zero_type()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>has_prefix</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>has_prefix</span>(</b><code class='datatype'>string</code>|<code class='datatype'>object</code> <code class='argument'>s</code>, <code class='datatype'>string</code> <code class='argument'>prefix</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if the string <code>s</code> starts with <code>prefix</code>, returns <code class='expr'>0</code> (zero) otherwise.</p> <p> When <code>s</code> is an object, it needs to implement <code>lfun::_sizeof()</code> and <code>lfun::`[]</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>has_suffix()</code>, <code>has_value()</code>, <code>search()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>has_suffix</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>has_suffix</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>string</code> <code class='argument'>suffix</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if the string <code>s</code> ends with <code>suffix</code>, returns <code class='expr'>0</code> (zero) otherwise.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>has_prefix()</code>, <code>has_value()</code>, <code>search()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>has_value</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>has_value</span>(</b><code class='datatype'>string</code> <code class='argument'>haystack</code>, <code class='datatype'>string</code> <code class='argument'>value</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>has_value</span>(</b><code class='datatype'>string</code> <code class='argument'>haystack</code>, <code class='datatype'>int</code> <code class='argument'>value</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>has_value</span>(</b><code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>object</code>|<code class='datatype'>program</code> <code class='argument'>haystack</code>, <code class='datatype'>mixed</code> <code class='argument'>value</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Search for <code>value</code> in <code>haystack</code>.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if <code>value</code> is in the value domain of <code>haystack</code>, or <code class='expr'>0</code> (zero) if not found.</p> <p> This function is in all cases except when both arguments are strings equivalent to (but sometimes faster than):</p> <pre><code>search(values(haystack), value) != -1</code></pre><p>If both arguments are strings, <code>has_value()</code> is equivalent to:</p> <pre><code>search(haystack, value) != -1</code></pre> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>has_index()</code>, <code>indices()</code>, <code>search()</code>, <code>has_prefix()</code>, <code>has_suffix()</code>, <code>values()</code>, <code>zero_type()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>hash</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>hash</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>hash</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>max</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return an integer derived from the string <code>s</code>. The same string always hashes to the same value, also between processes, architectures, and Pike versions (see compatibility notes below, though).</p> <p> If <code>max</code> is given, the result will be &gt;= 0 and &lt; <code>max</code>, otherwise the result will be &gt;= 0 and &lt;= 0x7fffffff.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The hash algorithm was changed in Pike 8.1. If you want a hash that is compatible with Pike 8.0 and earlier, use <code>hash_8_0()</code>.</p> <p> The hash algorithm was also changed in Pike 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use <code>hash_7_4()</code>. The difference with regards to <code>hash_8_0()</code> only affects wide strings.</p> <p> The hash algorithm was also changed in Pike 7.1. If you want a hash that is compatible with Pike 7.0 and earlier, use <code>hash_7_0()</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This hash function differs from the one provided by <code>hash_value()</code>, in that <code>hash_value()</code> returns a process specific value.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>hash_7_0()</code>, <code>hash_7_4()</code>, <code>hash_8_0()</code>, <code>hash_value</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>hash_7_0</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>hash_7_0</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>hash_7_0</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>max</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return an integer derived from the string <code>s</code>. The same string always hashes to the same value, also between processes.</p> <p> If <code>max</code> is given, the result will be &gt;= 0 and &lt; <code>max</code>, otherwise the result will be &gt;= 0 and &lt;= 0x7fffffff.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is provided for backward compatibility with code written for Pike up and including version 7.0.</p> <p> This function is not NUL-safe, and is byte-order dependant.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>hash()</code>, <code>hash_7_4</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>hash_7_4</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>hash_7_4</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>hash_7_4</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>max</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return an integer derived from the string <code>s</code>. The same string always hashes to the same value, also between processes.</p> <p> If <code>max</code> is given, the result will be &gt;= 0 and &lt; <code>max</code>, otherwise the result will be &gt;= 0 and &lt;= 0x7fffffff.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is provided for backward compatibility with code written for Pike up and including version 7.4.</p> <p> This function is byte-order dependant for wide strings.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>hash_7_6()</code>, <code>hash_7_0</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>hash_8_0</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>hash_8_0</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>hash_8_0</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>max</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return an integer derived from the string <code>s</code>. The same string always hashes to the same value, also between processes, architectures, and Pike versions (see compatibility notes below, though).</p> <p> If <code>max</code> is given, the result will be &gt;= 0 and &lt; <code>max</code>, otherwise the result will be &gt;= 0 and &lt;= 0x7fffffff.</p> </dd> <dt class='head--doc'>Deprecated</dt> <dd class='body--doc'><p>Use <code>hash_value()</code> for in-process hashing (eg, for implementing <code>lfun::_hash()</code>) or one of the cryptographic hash functions.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is really bad at hashing strings. Similar string often return similar hash values.</p> <p> It is especially bad for url:s, paths and similarly formatted strings.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The hash algorithm was changed in Pike 7.5. If you want a hash that is compatible with Pike 7.4 and earlier, use <code>hash_7_4()</code>. The difference only affects wide strings.</p> <p> The hash algorithm was also changed in Pike 7.1. If you want a hash that is compatible with Pike 7.0 and earlier, use <code>hash_7_0()</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This hash function differs from the one provided by <code>hash_value()</code>, in that <code>hash_value()</code> returns a process specific value.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>hash()</code>, <code>hash_7_0()</code>, <code>hash_7_4()</code>, <code>hash_value</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>hash_value</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>hash_value</span>(</b><code class='datatype'>mixed</code> <code class='argument'>value</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return a hash value for the argument. It's an integer in the native integer range.</p> <p> The hash will be the same for the same value in the running process only (the memory address is typically used as the basis for the hash value).</p> <p> If the value is an object with an <code>lfun::__hash</code>, that function is called and its result returned.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This is the hashing method used by mappings.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>lfun::__hash()</code></p> </dd></dl>
4a0b9d2019-08-28Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>is_sql_null</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>is_sql_null</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>SQL Null marker.</p> </dd> <dt class='head--doc'>Deprecated</dt> <dd class='body--doc'><p>Replaced by <code>is_val_null</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>is_val_null</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='datatype'>int</code> <code class='constant'>is_val_null</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Nonzero recognition constant.</p> </dd></dl>
7393ca2019-08-17Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>kill</b></span> </dt> <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>kill</span>(</b><code class='datatype'>int</code> <code class='argument'>pid</code>, <code class='datatype'>int</code> <code class='argument'>signal</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Send a signal to another process.</p> <p> Some signals and their supposed purpose:</p> <table class='box'><tr><td><code><code class='key'>SIGHUP</code></code></td><td><p>Hang-up, sent to process when user logs out.</p> </td></tr> <tr><td><code><code class='key'>SIGINT</code></code></td><td><p>Interrupt, normally sent by ctrl-c.</p> </td></tr> <tr><td><code><code class='key'>SIGQUIT</code></code></td><td><p>Quit, sent by ctrl-\.</p> </td></tr> <tr><td><code><code class='key'>SIGILL</code></code></td><td><p>Illegal instruction.</p> </td></tr> <tr><td><code><code class='key'>SIGTRAP</code></code></td><td><p>Trap, mostly used by debuggers.</p> </td></tr> <tr><td><code><code class='key'>SIGABRT</code></code></td><td><p>Aborts process, can be caught, used by Pike whenever something goes seriously wrong.</p> </td></tr> <tr><td><code><code class='key'>SIGEMT</code></code></td><td><p>Emulation trap.</p> </td></tr> <tr><td><code><code class='key'>SIGFPE</code></code></td><td><p>Floating point error (such as division by zero).</p> </td></tr> <tr><td><code><code class='key'>SIGKILL</code></code></td><td><p>Really kill a process, cannot be caught.</p> </td></tr> <tr><td><code><code class='key'>SIGBUS</code></code></td><td><p>Bus error.</p> </td></tr> <tr><td><code><code class='key'>SIGSEGV</code></code></td><td><p>Segmentation fault, caused by accessing memory where you shouldn't. Should never happen to Pike.</p> </td></tr> <tr><td><code><code class='key'>SIGSYS</code></code></td><td><p>Bad system call. Should never happen to Pike.</p> </td></tr> <tr><td><code><code class='key'>SIGPIPE</code></code></td><td><p>Broken pipe.</p> </td></tr> <tr><td><code><code class='key'>SIGALRM</code></code></td><td><p>Signal used for timer interrupts.</p> </td></tr> <tr><td><code><code class='key'>SIGTERM</code></code></td><td><p>Termination signal.</p> </td></tr> <tr><td><code><code class='key'>SIGUSR1</code></code></td><td><p>Signal reserved for whatever you want to use it for. Note that some OSs reserve this signal for the thread library.</p> </td></tr> <tr><td><code><code class='key'>SIGUSR2</code></code></td><td><p>Signal reserved for whatever you want to use it for. Note that some OSs reserve this signal for the thread library.</p> </td></tr> <tr><td><code><code class='key'>SIGCHLD</code></code></td><td><p>Child process died. This signal is reserved for internal use by the Pike run-time.</p> </td></tr> <tr><td><code><code class='key'>SIGPWR</code></code></td><td><p>Power failure or restart.</p> </td></tr> <tr><td><code><code class='key'>SIGWINCH</code></code></td><td><p>Window change signal.</p> </td></tr> <tr><td><code><code class='key'>SIGURG</code></code></td><td><p>Urgent socket data.</p> </td></tr> <tr><td><code><code class='key'>SIGIO</code></code></td><td><p>Pollable event.</p> </td></tr> <tr><td><code><code class='key'>SIGSTOP</code></code></td><td><p>Stop (suspend) process.</p> </td></tr> <tr><td><code><code class='key'>SIGTSTP</code></code></td><td><p>Stop (suspend) process. Sent by ctrl-z.</p> </td></tr> <tr><td><code><code class='key'>SIGCONT</code></code></td><td><p>Continue suspended.</p> </td></tr> <tr><td><code><code class='key'>SIGTTIN</code></code></td><td><p>TTY input for background process.</p> </td></tr> <tr><td><code><code class='key'>SIGTTOU</code></code></td><td><p>TTY output for background process.</p> </td></tr> <tr><td><code><code class='key'>SIGVTALRM</code></code></td><td><p>Virtual timer expired.</p> </td></tr> <tr><td><code><code class='key'>SIGPROF</code></code></td><td><p>Profiling trap.</p> </td></tr> <tr><td><code><code class='key'>SIGXCPU</code></code></td><td><p>Out of CPU.</p> </td></tr> <tr><td><code><code class='key'>SIGXFSZ</code></code></td><td><p>File size limit exceeded.</p> </td></tr> <tr><td><code><code class='key'>SIGSTKFLT</code></code></td><td><p>Stack fault</p> </td></tr> </table> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>1</code></code></td><td><p>Success.</p> </td></tr> <tr><td><code><code class='key'>0</code></code></td><td><p>Failure. <code>errno()</code> is set to EINVAL, EPERM or ESRCH.</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that you have to use signame to translate the name of a signal to its number.</p> <p> Note that the kill function is not available on platforms that do not support signals. Some platforms may also have signals not listed here.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>signal()</code>, <code>signum()</code>, <code>signame()</code>, <code>fork()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>limit</b></span> </dt> <dd><p><code><code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> <b><span class='method'>limit</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> <code class='argument'>minval</code>, <code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> <code class='argument'>x</code>, <code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> <code class='argument'>maxval</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Limits the value <code>x</code> so that it's between <code>minval</code> and <code>maxval</code>. If <code>x</code> is an object, it must implement the <code>lfun::`&lt;</code> method.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>max()</code> and <code>min()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>listxattr</b></span> </dt> <dd><p><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) <b><span class='method'>listxattr</span>(</b><code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return an array of all extended attributes set on the file</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>load_module</b></span> </dt> <dd><p><code><code class='datatype'>program</code> <b><span class='method'>load_module</span>(</b><code class='datatype'>string</code> <code class='argument'>module_name</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Load a binary module.</p> <p> This function loads a module written in C or some other language into Pike. The module is initialized and any programs or constants defined will immediately be available.</p> <p> When a module is loaded the C function <tt>pike_module_init()</tt> will be called to initialize it. When Pike exits <tt>pike_module_exit()</tt> will be called. These two functions <b>must</b> be available in the module.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The current working directory is normally not searched for dynamic modules. Please use <code class='expr'>"./name.so"</code> instead of just <code class='expr'>"name.so"</code> to load modules from the current directory.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>localtime</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>) <b><span class='method'>localtime</span>(</b><code class='datatype'>int</code> <code class='argument'>timestamp</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Convert seconds since 00:00:00 UTC, 1 Jan 1970 into components.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>This function returns a mapping with the following components:</p> <table class='box'><tr><td><code><code class='key'>"sec"</code> : <code class='datatype'>int(0..60)</code></code></td><td><p>Seconds over the minute.</p> </td></tr> <tr><td><code><code class='key'>"min"</code> : <code class='datatype'>int(0..59)</code></code></td><td><p>Minutes over the hour.</p> </td></tr> <tr><td><code><code class='key'>"hour"</code> : <code class='datatype'>int(0..23)</code></code></td><td><p>Hour of the day.</p> </td></tr> <tr><td><code><code class='key'>"mday"</code> : <code class='datatype'>int(1..31)</code></code></td><td><p>Day of the month.</p> </td></tr> <tr><td><code><code class='key'>"mon"</code> : <code class='datatype'>int(0..11)</code></code></td><td><p>Month of the year.</p> </td></tr> <tr><td><code><code class='key'>"year"</code> : <code class='datatype'>int(0..)</code></code></td><td><p>Year since 1900.</p> </td></tr> <tr><td><code><code class='key'>"wday"</code> : <code class='datatype'>int(0..6)</code></code></td><td><p>Day of week (0 = Sunday).</p> </td></tr> <tr><td><code><code class='key'>"yday"</code> : <code class='datatype'>int(0..365)</code></code></td><td><p>Day of the year.</p> </td></tr> <tr><td><code><code class='key'>"isdst"</code> : <code class='datatype'>bool</code></code></td><td><p>Is daylight-saving time active.</p> </td></tr> <tr><td><code><code class='key'>"timezone"</code> : <code class='datatype'>int</code></code></td><td><p>Offset from UTC, including daylight-saving time adjustment.</p> </td></tr> </table><p>An error is thrown if the localtime(2) call failed on the system. It's platform dependent what time ranges that function can handle, e.g. Windows doesn't handle a negative <code>timestamp</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Prior to Pike 7.5 the field <code class='expr'>"timezone"</code> was sometimes not present, and was sometimes not adjusted for daylight-saving time.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Calendar</code>, <code>gmtime()</code>, <code>time()</code>, <code>ctime()</code>, <code>mktime()</code>, <code>strptime()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>log</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>log</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the natural logarithm of <code>f</code>. <code class='expr'>exp(&nbsp;log(x)&nbsp;)&nbsp;==&nbsp;x</code> for x &gt; 0.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>pow()</code>, <code>exp()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>lower_case</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>lower_case</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>lower_case</span>(</b><code class='datatype'>int</code> <code class='argument'>c</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Convert a string or character to lower case.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns a copy of the string <code>s</code> with all upper case characters converted to lower case, or the character <code>c</code> converted to lower case.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, <code>Charset.decoder</code> can do the initial conversion for you.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Prior to Pike 7.5 this function only accepted strings.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>upper_case()</code>, <code>Charset.decoder</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>m_add</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>m_add</span>(</b><code class='datatype'>multiset</code>|<code class='datatype'>object</code> <code class='argument'>l</code>, <code class='datatype'>mixed</code> <code class='argument'>val</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Add a member to a multiset.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>m_delete()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>m_clear</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>m_clear</span>(</b><code class='datatype'>mapping</code>|<code class='datatype'>multiset</code>|<code class='datatype'>object</code> <code class='argument'>map</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Clear the contents of a mapping or multiset.</p> <p> This function clears the content of the mapping or multiset <code>map</code> so that it becomes empty. This is an atomic operation.</p> <p> If <code>map</code> is an object <code>lfun::_m_clear()</code> will be called in it.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>m_delete()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>m_delete</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>m_delete</span>(</b><code class='datatype'>object</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code> <code class='argument'>map</code>, <code class='datatype'>mixed</code> <code class='argument'>index</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>If <code>map</code> is an object that implements <code>lfun::_m_delete()</code>, that function will be called with <code>index</code> as its single argument.</p> <p> Otherwise if <code>map</code> is a mapping or multiset the entry with index <code>index</code> will be removed from <code>map</code> destructively.</p> <p> If the mapping or multiset does not have an entry with index <code>index</code>, nothing is done.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The value that was removed will be returned, and <code class='expr'>UNDEFINED</code> otherwise.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that <code>m_delete()</code> changes <code>map</code> destructively.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>mappingp()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>map</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>map</span>(</b><code class='datatype'>mixed</code> <code class='argument'>arr</code>, <code class='datatype'>void</code>|<code class='datatype'>mixed</code> <code class='argument'>fun</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Applies <code>fun</code> to the elements in <code>arr</code> and collects the results.</p> <p> <code>arr</code> is treated as a set of elements, as follows:</p> <dl class='group--doc'><dt>array</dt> <dt>multiset</dt> <dt>string</dt> <dd><p><code>fun</code> is applied in order to each element. The results are collected, also in order, to a value of the same type as <code>arr</code>, which is returned.</p> </dd> <dt>mapping</dt> <dd><p><code>fun</code> is applied to the values, and each result is assigned to the same index in a new mapping, which is returned.</p> </dd> <dt>program</dt> <dd><p>The program is treated as a mapping containing the identifiers that are indexable from it and their values.</p> </dd> <dt>object</dt> <dd><p>If there is a <code>lfun::cast</code> method in the object, it's called to try to cast the object to an array, a mapping, or a multiset, in that order, which is then handled as described above.</p> </dd> </dl><p><code>fun</code> is applied in different ways depending on its type:</p> <dl class='group--doc'><dt>function</dt> <dd><p><code>fun</code> is called for each element. It gets the current element as the first argument and <code>extra</code> as the rest. The result of the call is collected.</p> </dd> <dt>object</dt> <dd><p><code>fun</code> is used as a function like above, i.e. the <code>lfun::`()</code> method in it is called.</p> </dd> <dt>array</dt> <dd><p>Each element of the <code>fun</code> array will be called for each element of <code>arr</code>.</p> </dd> <dt>multiset</dt> <dt>mapping</dt> <dd><p><code>fun</code> is indexed with each element. The result of that is collected.</p> </dd> <dt>"zero or left out"</dt> <dd><p>Each element that is callable is called with <code>extra</code> as arguments. The result of the calls are collected. Elements that aren't callable gets zero as result.</p> </dd> <dt>string</dt> <dd><p>Each element is indexed with the given string. If the result of that is zero then a zero is collected, otherwise it's called with <code>extra</code> as arguments and the result of that call is collected.</p> <p> This is typically used when <code>arr</code> is a collection of objects, and <code>fun</code> is the name of some function in them.</p> </dd> </dl> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The function is never destructive on <code>arr</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>filter()</code>, <code>enumerate()</code>, <code>foreach()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>master</b></span> </dt> <dd><p><code><code class='datatype'>object</code> <b><span class='method'>master</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the current master object.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>May return <code>UNDEFINED</code> if no master has been loaded yet.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>replace_master()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>max</b></span> </dt> <dd><p><code><code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> <b><span class='method'>max</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code>, <code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> ... <code class='argument'>args</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>max</span>(</b><code class='datatype'>string</code>, <code class='datatype'>string</code> ... <code class='argument'>args</code><b>)</b></code><br> <code><code class='datatype'>int(0..0)</code> <b><span class='method'>max</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the largest value among <code>args</code>. Compared objects must implement the <code>lfun::`&lt;</code> method.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>min()</code> and <code>limit()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>min</b></span> </dt> <dd><p><code><code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> <b><span class='method'>min</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code>, <code class='datatype'>int</code>|<code class='datatype'>float</code>|<code class='datatype'>object</code> ... <code class='argument'>args</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>min</span>(</b><code class='datatype'>string</code>, <code class='datatype'>string</code> ... <code class='argument'>args</code><b>)</b></code><br> <code><code class='datatype'>int(0..0)</code> <b><span class='method'>min</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the smallest value among <code>args</code>. Compared objects must implement the <code>lfun::`&lt;</code> method.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>max()</code> and <code>limit()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>mkmapping</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code> <b><span class='method'>mkmapping</span>(</b><code class='datatype'>array</code> <code class='argument'>ind</code>, <code class='datatype'>array</code> <code class='argument'>val</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Make a mapping from two arrays.</p> <p> Makes a mapping <code>ind[x]</code>:<code>val[x]</code>, <tt>0 &lt;= x &lt; sizeof(ind)</tt>.</p> <p> <code>ind</code> and <code>val</code> must have the same size.</p> <p> This is the inverse operation of <code>indices()</code> and <code>values()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>indices()</code>, <code>values()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>mkmultiset</b></span> </dt> <dd><p><code><code class='datatype'>multiset</code> <b><span class='method'>mkmultiset</span>(</b><code class='datatype'>array</code> <code class='argument'>a</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function creates a multiset from an array.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>aggregate_multiset()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>mktime</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>mktime</span>(</b><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>tm</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>mktime</span>(</b><code class='datatype'>int</code> <code class='argument'>sec</code>, <code class='datatype'>int</code> <code class='argument'>min</code>, <code class='datatype'>int</code> <code class='argument'>hour</code>, <code class='datatype'>int</code> <code class='argument'>mday</code>, <code class='datatype'>int</code> <code class='argument'>mon</code>, <code class='datatype'>int</code> <code class='argument'>year</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>isdst</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>tz</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function converts information about date and time into an integer which contains the number of seconds since 00:00:00 UTC, Jan 1, 1970.</p> <p> You can either call this function with a mapping containing the following elements:</p> <table class='box'><tr><td><code><code class='key'>"sec"</code> : <code class='datatype'>int(0..60)</code></code></td><td><p>Seconds over the minute.</p> </td></tr> <tr><td><code><code class='key'>"min"</code> : <code class='datatype'>int(0..59)</code></code></td><td><p>Minutes over the hour.</p> </td></tr> <tr><td><code><code class='key'>"hour"</code> : <code class='datatype'>int(0..23)</code></code></td><td><p>Hour of the day.</p> </td></tr> <tr><td><code><code class='key'>"mday"</code> : <code class='datatype'>int(1..31)</code></code></td><td><p>Day of the month.</p> </td></tr> <tr><td><code><code class='key'>"mon"</code> : <code class='datatype'>int(0..11)</code></code></td><td><p>Month of the year.</p> </td></tr> <tr><td><code><code class='key'>"year"</code> : <code class='datatype'>int(0..)</code></code></td><td><p>Year since 1900.</p> </td></tr> <tr><td><code><code class='key'>"isdst"</code> : <code class='datatype'>int(-1..1)</code></code></td><td><p>Is daylight-saving time active. If omitted or set to <code class='expr'>-1</code>, it means that the information is not available.</p> </td></tr> <tr><td><code><code class='key'>"timezone"</code> : <code class='datatype'>int</code></code></td><td><p>The timezone offset from UTC in seconds. If omitted, the time will be calculated in the local timezone.</p> </td></tr> </table><p>Or you can just send them all on one line as the second syntax suggests.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>For proper UTC calculations ensure that <code class='expr'>isdst&nbsp;=&nbsp;0</code> <b>and</b> <code class='expr'>timezone&nbsp;=&nbsp;0</code>; omitting either one of these parameters <b>will</b> mess up the UTC calculation.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>On some operating systems (notably AIX and Win32), dates before 00:00:00 UTC, Jan 1, 1970 are not supported.</p> <p> On most 32-bit systems, the supported range of dates is from Dec 13, 1901 20:45:52 UTC through to Jan 19, 2038 03:14:07 UTC (inclusive).</p> <p> On most 64-bit systems, the supported range of dates is expressed in 56 bits and is thus practically unlimited (at least up to 1141 milion years in the past and into the future).</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>time()</code>, <code>ctime()</code>, <code>localtime()</code>, <code>gmtime()</code>, <code>strftime()</code></p> </dd></dl>
9b13162019-11-02Tobias S. Josefowitz <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>nth</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>nth</span>(</b><code class='datatype'>int(0..)</code> <code class='argument'>n</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the <code class='expr'>n</code>th entry in order.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>An array <code class='expr'>({&nbsp;key,&nbsp;value&nbsp;})</code>.</p> </dd></dl>
7393ca2019-08-17Henrik Grubbström (Grubba) <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>object_variablep</b></span> </dt> <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>object_variablep</span>(</b><code class='datatype'>object</code> <code class='argument'>o</code>, <code class='datatype'>string</code> <code class='argument'>var</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Find out if an object identifier is a variable.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>This function returns <code class='expr'>1</code> if <code>var</code> exists as a non-protected variable in <code>o</code>, and returns <code class='expr'>0</code> (zero) otherwise.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>indices()</code>, <code>values()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>objectp</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>objectp</span>(</b><code class='datatype'>mixed</code> <code class='argument'>arg</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if <code>arg</code> is an object, <code class='expr'>0</code> (zero) otherwise.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>mappingp()</code>, <code>programp()</code>, <code>arrayp()</code>, <code>stringp()</code>, <code>functionp()</code>, <code>multisetp()</code>, <code>floatp()</code>, <code>intp()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>pow</b></span> </dt> <dd><p><code><code class='datatype'>int</code>|<code class='datatype'>float</code> <b><span class='method'>pow</span>(</b><code class='datatype'>float</code>|<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>float</code>|<code class='datatype'>int</code> <code class='argument'>x</code><b>)</b></code><br> <code><code class='datatype'>mixed</code> <b><span class='method'>pow</span>(</b><code class='datatype'>object</code> <code class='argument'>n</code>, <code class='datatype'>float</code>|<code class='datatype'>int</code>|<code class='datatype'>object</code> <code class='argument'>x</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return <code>n</code> raised to the power of <code>x</code>. If both <code>n</code> and <code>x</code> are integers the result will be an integer. If <code>n</code> is an object its pow method will be called with <code>x</code> as argument.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>exp()</code>, <code>log()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>query_num_arg</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>query_num_arg</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the number of arguments given when the previous function was called.</p> <p> This is useful for functions that take a variable number of arguments.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>call_function()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>random_seed</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>random_seed</span>(</b><code class='datatype'>int</code> <code class='argument'>seed</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function sets the initial value for the random generator.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>random()</code></p> </dd> <dt class='head--doc'>Deprecated</dt> <dd class='body--doc'><p><code>Random.Deterministic</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
47a29e2020-05-24Stephen R. van den Berg <span class='homogen--name'><b>removexattr</b></span>
7393ca2019-08-17Henrik Grubbström (Grubba) </dt>
47a29e2020-05-24Stephen R. van den Berg <dd><p><code><code class='datatype'>void</code> <b><span class='method'>removexattr</span>(</b><code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code><b>)</b></code></p></dd>
7393ca2019-08-17Henrik Grubbström (Grubba)  <dt class='head--doc'>Description</dt>
47a29e2020-05-24Stephen R. van den Berg <dd class='body--doc'><p>Remove the specified extended attribute.</p>
7393ca2019-08-17Henrik Grubbström (Grubba) </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span>
47a29e2020-05-24Stephen R. van den Berg <span class='homogen--name'><b>replace</b></span>
7393ca2019-08-17Henrik Grubbström (Grubba) </dt>
47a29e2020-05-24Stephen R. van den Berg <dd><p><code><code class='datatype'>string</code> <b><span class='method'>replace</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>string</code> <code class='argument'>from</code>, <code class='datatype'>string</code> <code class='argument'>to</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>replace</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>from</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>to</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>replace</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>from</code>, <code class='datatype'>string</code> <code class='argument'>to</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>replace</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>replacements</code><b>)</b></code><br> <code><code class='datatype'>array</code> <b><span class='method'>replace</span>(</b><code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>mixed</code> <code class='argument'>from</code>, <code class='datatype'>mixed</code> <code class='argument'>to</code><b>)</b></code><br> <code><code class='datatype'>mapping</code> <b><span class='method'>replace</span>(</b><code class='datatype'>mapping</code> <code class='argument'>a</code>, <code class='datatype'>mixed</code> <code class='argument'>from</code>, <code class='datatype'>mixed</code> <code class='argument'>to</code><b>)</b></code></p></dd>
7393ca2019-08-17Henrik Grubbström (Grubba)  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Generic replace function.</p> <p> This function can do several kinds replacement operations, the different syntaxes do different things as follows:</p> <p> If all the arguments are strings, a copy of <code>s</code> with every occurrence of <code>from</code> replaced with <code>to</code> will be returned. Special case: <code>to</code> will be inserted between every character in <code>s</code> if <code>from</code> is the empty string.</p> <p> If the first argument is a string, and the others array(string), a string with every occurrance of <code>from</code>[<i>i</i>] in <code>s</code> replaced with <code>to</code>[<i>i</i>] will be returned. Instead of the arrays <code>from</code> and <code>to</code> a mapping equivalent to <code class='expr'><code>mkmapping</code>(<code>from</code>,&nbsp;<code>to</code>)</code> can be used.</p> <p> If the first argument is an array or mapping, the values of <code>a</code> which are <code>`==()</code> with <code>from</code> will be replaced with <code>to</code> destructively. <code>a</code> will then be returned.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that <code>replace()</code> on arrays and mappings is a destructive operation.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>replace_master</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>replace_master</span>(</b><code class='datatype'>object</code> <code class='argument'>o</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Replace the master object with <code>o</code>.</p> <p> This will let you control many aspects of how Pike works, but beware that <tt>master.pike</tt> may be required to fill certain functions, so it is usually a good idea to have your master inherit the original master and only re-define certain functions.</p> <p> FIXME: Tell how to inherit the master.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>master()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>reverse</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>reverse</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code><b>)</b></code><br> <code><code class='datatype'>array</code> <b><span class='method'>reverse</span>(</b><code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code><b>)</b></code><br>
abd0692019-11-20Henrik Grubbström (Grubba) <code><code class='datatype'>int</code> <b><span class='method'>reverse</span>(</b><code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code><b>)</b></code><br> <code><code class='datatype'>mixed</code> <b><span class='method'>reverse</span>(</b><code class='datatype'>object</code> <code class='argument'>o</code>, <code class='datatype'>mixed</code> ... <code class='argument'>options</code><b>)</b></code></p></dd>
7393ca2019-08-17Henrik Grubbström (Grubba)  <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Reverses a string, array or int.</p> </dd> <dt class='head--doc'><span id='p-s'></span>Parameter <code class='parameter'>s</code></dt> <dd></dd><dd class='body--doc'><p>String to reverse.</p> </dd> <dt class='head--doc'><span id='p-a'></span>Parameter <code class='parameter'>a</code></dt> <dd></dd><dd class='body--doc'><p>Array to reverse.</p> </dd> <dt class='head--doc'><span id='p-i'></span>Parameter <code class='parameter'>i</code></dt> <dd></dd><dd class='body--doc'><p>Integer to reverse.</p> </dd>
abd0692019-11-20Henrik Grubbström (Grubba) <dt class='head--doc'><span id='p-o'></span>Parameter <code class='parameter'>o</code></dt> <dd></dd><dd class='body--doc'><p>Object to reverse.</p> </dd>
7393ca2019-08-17Henrik Grubbström (Grubba) <dt class='head--doc'><span id='p-start'></span>Parameter <code class='parameter'>start</code></dt> <dd></dd><dd class='body--doc'><p>Optional start index of the range to reverse. Default: <code class='expr'>0</code> (zero).</p> </dd> <dt class='head--doc'><span id='p-end'></span>Parameter <code class='parameter'>end</code></dt> <dd></dd><dd class='body--doc'><p>Optional end index of the range to reverse. Default for strings: <code class='expr'>sizeof(s)-1</code>. Default for arrays: <code class='expr'>sizeof(a)-1</code>. Default for integers: <code class='expr'>Pike.get_runtime_info()-&gt;int_size&nbsp;-&nbsp;1</code>.</p>
abd0692019-11-20Henrik Grubbström (Grubba) </dd> <dt class='head--doc'><span id='p-options'></span>Parameter <code class='parameter'>options</code></dt> <dd></dd><dd class='body--doc'><p>Optional arguments that are to be passed to <code>lfun::_reverse()</code>.</p>
7393ca2019-08-17Henrik Grubbström (Grubba) <p> This function reverses a string, char by char, an array, value by value or an int, bit by bit and returns the result. It's not
abd0692019-11-20Henrik Grubbström (Grubba)  destructive on the input value. For objects it simply calls <code>lfun::_reverse()</code> in the object, and returns the result.</p>
7393ca2019-08-17Henrik Grubbström (Grubba) <p> Reversing strings can be particularly useful for parsing difficult syntaxes which require scanning backwards.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sscanf()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>round</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>round</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Return the closest integer value to <code>f</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p><code>round()</code> does <b>not</b> return an <code class='expr'>int</code>, merely an integer value stored in a <code class='expr'>float</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>floor()</code>, <code>ceil()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>rows</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>rows</span>(</b><code class='datatype'>mixed</code> <code class='argument'>data</code>, <code class='datatype'>array</code> <code class='argument'>index</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Select a set of rows from an array.</p> <p> This function is en optimized equivalent to:</p> <pre><code>map<span class='delim'>(</span>index<span class='delim'>,</span> <span class='lang'>lambda</span><span class='delim'>(</span><span class='type'>mixed</span> x<span class='delim'>)</span> <span class='delim'>{</span> <span class='lang'>return</span> data<span class='delim'>[</span>x<span class='delim'>]</span><span class='delim'>;</span> <span class='delim'>}</span><span class='delim'>)</span> </code></pre><p>That is, it indices data on every index in the array index and returns an array with the results.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>column()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>search</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>search</span>(</b><code class='datatype'>string</code> <code class='argument'>haystack</code>, <code class='datatype'>string</code>|<code class='datatype'>int</code> <code class='argument'>needle</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>search</span>(</b><code class='datatype'>array</code> <code class='argument'>haystack</code>, <code class='datatype'>mixed</code> <code class='argument'>needle</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>end</code><b>)</b></code><br> <code><code class='datatype'>mixed</code> <b><span class='method'>search</span>(</b><code class='datatype'>mapping</code> <code class='argument'>haystack</code>, <code class='datatype'>mixed</code> <code class='argument'>needle</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> <code class='argument'>start</code><b>)</b></code><br> <code><code class='datatype'>mixed</code> <b><span class='method'>search</span>(</b><code class='datatype'>object</code> <code class='argument'>haystack</code>, <code class='datatype'>mixed</code> <code class='argument'>needle</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> <code class='argument'>start</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Search for <code>needle</code> in <code>haystack</code>.</p> </dd> <dt class='head--doc'><span id='p-haystack'></span>Parameter <code class='parameter'>haystack</code></dt> <dd></dd><dd class='body--doc'><p>Item to search in. This can be one of:</p> <table class='box'><tr><td><code><code class='datatype'>string</code></code></td><td><p>When <code>haystack</code> is a string <code>needle</code> must be a string or an int, and the first occurrence of the string or int is returned.</p> </td></tr> <tr><td><code><code class='datatype'>array</code></code></td><td><p>When <code>haystack</code> is an array, <code>needle</code> is compared only to one value at a time in <code>haystack</code>.</p> </td></tr> <tr><td><code><code class='datatype'>mapping</code></code></td><td><p>When <code>haystack</code> is a mapping, <code>search()</code> tries to find the index connected to the data <code>needle</code>. That is, it tries to lookup the mapping backwards.</p> </td></tr> <tr><td><code><code class='datatype'>object</code></code></td><td><p>When <code>haystack</code> is an object implementing <code>lfun::_search()</code>, the result of calling <code>lfun::_search()</code> with <code>needle</code>, <code>start</code> and any <code>extra_args</code> will be returned.</p> <p> If <code>haystack</code> is an object that doesn't implement <code>lfun::_search()</code> it is assumed to be an <code>Iterator</code>, and implement <code>Iterator()-&gt;index()</code>, <code>Iterator()-&gt;value()</code>, and <code>Iterator()-&gt;next()</code>. <code>search()</code> will then start comparing elements with <code>`==()</code> until a match with <code>needle</code> is found. If <code>needle</code> is found <code>haystack</code> will be advanced to the element, and the iterator index will be returned. If <code>needle</code> is not found, <code>haystack</code> will be advanced to the end.</p> </td></tr> </table> </dd> <dt class='head--doc'><span id='p-start'></span>Parameter <code class='parameter'>start</code></dt> <dd></dd><dd class='body--doc'><p>If the optional argument <code>start</code> is present search is started at this position. This has no effect on mappings.</p> </dd> <dt class='head--doc'><span id='p-end'></span>Parameter <code class='parameter'>end</code></dt> <dd></dd><dd class='body--doc'><p>If the optional argument <code>end</code> is present, the search will terminate at this position (exclusive) if not found earlier.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the position of <code>needle</code> in <code>haystack</code> if found.</p> <p> If not found the returned value depends on the type of <code>haystack</code>:</p> <table class='box'><tr><td><code><code class='datatype'>string</code>|<code class='datatype'>array</code></code></td><td><p><code class='expr'>-1</code>.</p> </td></tr> <tr><td><code><code class='datatype'>mapping</code>|<code class='object unresolved'>Iterator</code></code></td><td><p><code>UNDEFINED</code>.</p> </td></tr> <tr><td><code><code class='datatype'>object</code></code></td><td><p>The value returned by <code>lfun::_search()</code>.</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>If <code>start</code> is supplied to an iterator object without an <code>lfun::_search()</code>, <code>haystack</code> will need to implement <code>Iterator()-&gt;set_index()</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>For mappings and object <code>UNDEFINED</code> will be returned when not found. In all other cases <code class='expr'>-1</code> will be returned when not found.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>indices()</code>, <code>values()</code>, <code>zero_type()</code>, <code>has_value()</code>, <code>has_prefix()</code>, <code>has_suffix()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_priority</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>set_priority</span>(</b><code class='datatype'>string</code> <code class='argument'>level</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>void</code> <code class='argument'>pid</code><b>)</b></code></p></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>set_weak_flag</b></span> </dt> <dd><p><code><code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code> <b><span class='method'>set_weak_flag</span>(</b><code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code> <code class='argument'>m</code>, <code class='datatype'>int</code> <code class='argument'>state</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Set the value <code>m</code> to use weak or normal references in its indices and/or values (whatever is applicable). <code>state</code> is a bitfield built by using <code class='expr'>|</code> between the following flags:</p> <table class='box'><tr><td><code><code class='key'>Pike.WEAK_INDICES</code></code></td><td><p>Use weak references for indices. Only applicable for multisets and mappings.</p> </td></tr> <tr><td><code><code class='key'>Pike.WEAK_VALUES</code></code></td><td><p>Use weak references for values. Only applicable for arrays and mappings.</p> </td></tr> <tr><td><code><code class='key'>Pike.WEAK</code></code></td><td><p>Shorthand for <code class='expr'>Pike.WEAK_INDICES|Pike.WEAK_VALUES</code>.</p> </td></tr> </table><p>If a flag is absent, the corresponding field will use normal references. <code>state</code> can also be <code class='expr'>1</code> as a compatibility measure; it's treated like <code>Pike.WEAK</code>.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p><code>m</code> will be returned.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>setxattr</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>setxattr</span>(</b><code class='datatype'>string</code> <code class='argument'>file</code>, <code class='datatype'>string</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>value</code>, <code class='datatype'>int</code> <code class='argument'>flags</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>symlink</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Set the attribute <code>attr</code> to the value <code>value</code>.</p> <p> The flags parameter can be used to refine the semantics of the operation.</p> <p> <code>Stdio.XATTR_CREATE</code> specifies a pure create, which fails if the named attribute exists already.</p> <p> <code>Stdio.XATTR_REPLACE</code> specifies a pure replace operation, which fails if the named attribute does not already exist.</p> <p> By default (no flags), the extended attribute will be created if need be, or will simply replace the value if the attribute exists.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>1 if successful, 0 otherwise, setting errno.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sgn</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>sgn</span>(</b><code class='datatype'>mixed</code> <code class='argument'>value</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>sgn</span>(</b><code class='datatype'>mixed</code> <code class='argument'>value</code>, <code class='datatype'>mixed</code> <code class='argument'>zero</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Check the sign of a value.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns <code class='expr'>-1</code> if <code>value</code> is less than <code>zero</code>, <code class='expr'>1</code> if <code>value</code> is greater than <code>zero</code> and <code class='expr'>0</code> (zero) otherwise.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>abs()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>signal</b></span> </dt> <dd><p><code><code class='datatype'>function</code>(<code class='datatype'>int</code>|<code class='datatype'>void</code>:<code class='datatype'>void</code>) <b><span class='method'>signal</span>(</b><code class='datatype'>int</code> <code class='argument'>sig</code>, <code class='datatype'>function</code>(<code class='datatype'>int</code>|<code class='datatype'>void</code>:<code class='datatype'>void</code>) <code class='argument'>callback</code><b>)</b></code><br> <code><code class='datatype'>function</code>(<code class='datatype'>int</code>|<code class='datatype'>void</code>:<code class='datatype'>void</code>) <b><span class='method'>signal</span>(</b><code class='datatype'>int</code> <code class='argument'>sig</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Trap signals.</p> <p> This function allows you to trap a signal and have a function called when the process receives a signal. Although it IS possible to trap SIGBUS, SIGSEGV etc, I advise you not to; Pike should not receive any such signals, and if it does, it is because of bugs in the Pike interpreter. And all bugs should be reported, no matter how trifle.</p> <p> The callback will receive the signal number as its only argument.</p> <p> See the documentation for <code>kill()</code> for a list of signals.</p> <p> If no second argument is given, the signal handler for that signal is restored to the default handler.</p> <p> If the second argument is zero, the signal will be completely ignored.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the previous signal function, or 0 if none had been registered.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>kill()</code>, <code>signame()</code>, <code>signum()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>signame</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>signame</span>(</b><code class='datatype'>int</code> <code class='argument'>sig</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns a string describing the signal <code>sig</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>kill()</code>, <code>signum()</code>, <code>signal()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>signum</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>signum</span>(</b><code class='datatype'>string</code> <code class='argument'>sig</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get a signal number given a descriptive string.</p> <p> This function is the inverse of <code>signame()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>signame()</code>, <code>kill()</code>, <code>signal()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sin</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>sin</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the sine value for <code>f</code>. <code>f</code> should be specified in radians.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>asin()</code>, <code>cos()</code>, <code>tan()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sinh</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>sinh</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the hyperbolic sine value for <code>f</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>asinh()</code>, <code>cosh()</code>, <code>tanh()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sizeof</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>sizeof</span>(</b><code class='datatype'>string</code> <code class='argument'>arg</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>sizeof</span>(</b><code class='datatype'>array</code> <code class='argument'>arg</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>sizeof</span>(</b><code class='datatype'>mapping</code> <code class='argument'>arg</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>sizeof</span>(</b><code class='datatype'>multiset</code> <code class='argument'>arg</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>sizeof</span>(</b><code class='datatype'>object</code> <code class='argument'>arg</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Size query.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The result will be as follows:</p> <code>arg</code> can have any of the following types:<br /><table class='box'><tr><td><code><code class='datatype'>string</code></code></td><td><p>The number of characters in <code>arg</code> will be returned.</p> </td></tr> <tr><td><code><code class='datatype'>array</code>|<code class='datatype'>multiset</code></code></td><td><p>The number of elements in <code>arg</code> will be returned.</p> </td></tr> <tr><td><code><code class='datatype'>mapping</code></code></td><td><p>The number of key-value pairs in <code>arg</code> will be returned.</p> </td></tr> <tr><td><code><code class='datatype'>object</code></code></td><td><p>If <code>arg</code> implements <code>lfun::_sizeof()</code>, that function will be called. Otherwise the number of non-protected (ie public) symbols in <code>arg</code> will be returned.</p> </td></tr> </table> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>lfun::_sizeof()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sleep</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>sleep</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>s</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>abort_on_signal</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function makes the thread stop for <code>s</code> seconds.</p> <p> Only signal handlers can interrupt the sleep, and only when <code>abort_on_signal</code> is set. If more than one thread is running the signal must be sent to the sleeping thread. Other callbacks are not called during sleep.</p> <p> If <code>s</code> is zero then this thread will yield to other threads but not sleep otherwise. Note that Pike yields internally at regular intervals so it's normally not necessary to do this.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>signal()</code>, <code>delay()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sort</b></span> </dt> <dd><p><code><code class='datatype'>array</code> <b><span class='method'>sort</span>(</b><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>index</code>, <code class='datatype'>array</code>(<code class='datatype'>mixed</code>) ... <code class='argument'>data</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Sort arrays destructively.</p> <p> This function sorts the array <code>index</code> destructively. That means that the array itself is changed and returned, no copy is created.</p> <p> If extra arguments are given, they are supposed to be arrays of the same size as <code>index</code>. Each of these arrays will be modified in the same way as <code>index</code>. I.e. if index 3 is moved to position 0 in <code>index</code> index 3 will be moved to position 0 in all the other arrays as well.</p> <p> The sort order is as follows:</p> <ul> <li><p>Integers and floats are sorted in ascending order.</p> </li><li><p>Strings are sorted primarily on the first characters that are different, and secondarily with shorter strings before longer. Different characters are sorted in ascending order on the character value. Thus the sort order is not locale dependent.</p> </li><li><p>Arrays are sorted recursively on the first element. Empty arrays are sorted before nonempty ones.</p> </li><li><p>Multisets are sorted recursively on the first index. Empty multisets are sorted before nonempty ones.</p> </li><li><p>Objects are sorted in ascending order according to <code>`&lt;()</code>, <code>`&gt;()</code> and <code>`==()</code>.</p> </li><li><p>Other types aren't reordered.</p> </li><li><p>Different types are sorted in this order: Arrays, mappings, multisets, objects, functions, programs, strings, types, integers and floats. Note however that objects can control their ordering wrt other types with <code>`&lt;</code>, <code>`&gt;</code> and <code>`==</code>, so this ordering of types only applies to objects without those functions.</p> </li></ul> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The first argument is returned.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The sort is stable, i.e. elements that are compare-wise equal aren't reordered.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Array.sort_array</code>, <code>reverse()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sprintf</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>sprintf</span>(</b><code class='object unresolved'>strict_sprintf_format</code> <code class='argument'>format</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Print formated output to string.</p> <p> The <code>format</code> string is a string containing a description of how to output the data in <code>args</code>. This string should generally speaking have one <tt>%<i>&lt;modifiers&gt;</i><i>&lt;operator&gt;</i></tt> format specifier (examples: <tt>%s</tt>, <tt>%0d</tt>, <tt>%-=20s</tt>) for each of the arguments.</p> <p> The following modifiers are supported:</p> <table class='box'><tr><td><code><code class='key'>'0'</code></code></td><td><p>Zero pad numbers (implies right justification).</p> </td></tr> <tr><td><code><code class='key'>'!'</code></code></td><td><p>Toggle truncation.</p> </td></tr> <tr><td><code><code class='key'>' '</code></code></td><td><p>Pad positive integers with a space.</p> </td></tr> <tr><td><code><code class='key'>'+'</code></code></td><td><p>Pad positive integers with a plus sign.</p> </td></tr> <tr><td><code><code class='key'>'-'</code></code></td><td><p>Left adjust within field size (default is right).</p> </td></tr> <tr><td><code><code class='key'>'|'</code></code></td><td><p>Centered within field size.</p> </td></tr>
d928cf2019-09-26Henrik Grubbström (Grubba) <tr><td><code><code class='key'>'='</code></code></td><td><p>Column mode if strings are greater than field width. Breaks
7393ca2019-08-17Henrik Grubbström (Grubba)  between words (possibly skipping or adding spaces). Can not be used together with <code class='expr'>'/'</code>.</p> </td></tr>
d928cf2019-09-26Henrik Grubbström (Grubba) <tr><td><code><code class='key'>'/'</code></code></td><td><p>Column mode with rough line break (break at exactly field width
7393ca2019-08-17Henrik Grubbström (Grubba)  instead of between words). Can not be used together with <code class='expr'>'='</code>.</p> </td></tr> <tr><td><code><code class='key'>'#'</code></code></td><td><p>Table mode, print a list of <code class='expr'>'\n'</code> separated words (top-to-bottom order).</p> </td></tr> <tr><td><code><code class='key'>'$'</code></code></td><td><p>Inverse table mode (left-to-right order).</p> </td></tr> <tr><td><code><code class='key'>'n'</code></code></td><td rowspan='2'><p>(Where n is a number or *) field width specifier.</p> </td></tr> <tr><td><code><code class='key'>':n'</code></code></td></tr> <tr><td><code><code class='key'>'.n'</code></code></td><td><p>Precision specifier.</p> </td></tr> <tr><td><code><code class='key'>';n'</code></code></td><td><p>Column width specifier.</p> </td></tr> <tr><td><code><code class='key'>'*'</code></code></td><td><p>If n is a <tt>*</tt> then next argument is used for precision/field size. The argument may either be an integer, or a modifier mapping as received by <code>lfun::_sprintf()</code>:</p> <table class='box'><tr><td><code><code class='key'>"precision"</code> : <code class='datatype'>int</code>|<code class='datatype'>void</code></code></td><td><p>Precision.</p> </td></tr> <tr><td><code><code class='key'>"width"</code> : <code class='datatype'>int(0..)</code>|<code class='datatype'>void</code></code></td><td><p>Field width.</p> </td></tr> <tr><td><code><code class='key'>"flag_left"</code> : <code class='datatype'>bool</code>|<code class='datatype'>void</code></code></td><td><p>Indicates that the output should be left-aligned.</p> </td></tr> <tr><td><code><code class='key'>"indent"</code> : <code class='datatype'>int(0..)</code>|<code class='datatype'>void</code></code></td><td><p>Indentation level in <tt>%O</tt>-mode.</p> </td></tr> </table></td></tr> <tr><td><code><code class='key'>"'"</code></code></td><td><p>Set a pad string. <tt>'</tt> cannot be a part of the pad string (yet).</p> </td></tr> <tr><td><code><code class='key'>'~'</code></code></td><td><p>Get pad string from argument list.</p> </td></tr> <tr><td><code><code class='key'>'&lt;'</code></code></td><td><p>Use same argument again.</p> </td></tr> <tr><td><code><code class='key'>'^'</code></code></td><td><p>Repeat this on every line produced.</p> </td></tr> <tr><td><code><code class='key'>'@'</code></code></td><td><p>Repeat this format for each element in the argument array.</p> </td></tr> <tr><td><code><code class='key'>'&gt;'</code></code></td><td><p>Put the string at the bottom end of column instead of top.</p> </td></tr> <tr><td><code><code class='key'>'_'</code></code></td><td><p>Set width to the length of data.</p> </td></tr> <tr><td><code><code class='key'>'[n]'</code></code></td><td><p>Select argument number <tt><i>n</i></tt>. Use <tt>*</tt> to use the next argument as selector. The arguments are numbered starting from <code class='expr'>0</code> (zero) for the first argument after the <code>format</code>. Note that this only affects where the current operand is fetched.</p> </td></tr> </table><p>The following operators are supported:</p> <table class='box'><tr><td><code><code class='key'>'%'</code></code></td><td><p>Percent.</p> </td></tr> <tr><td><code><code class='key'>'b'</code></code></td><td><p>Signed binary integer.</p> </td></tr> <tr><td><code><code class='key'>'d'</code></code></td><td><p>Signed decimal integer.</p> </td></tr> <tr><td><code><code class='key'>'u'</code></code></td><td><p>Unsigned decimal integer.</p> </td></tr> <tr><td><code><code class='key'>'o'</code></code></td><td><p>Signed octal integer.</p> </td></tr> <tr><td><code><code class='key'>'x'</code></code></td><td><p>Lowercase signed hexadecimal integer.</p> </td></tr> <tr><td><code><code class='key'>'X'</code></code></td><td><p>Uppercase signed hexadecimal integer.</p> </td></tr> <tr><td><code><code class='key'>'c'</code></code></td><td><p>Character. If a fieldsize has been specified this will output the low-order bytes of the integer in network (big endian) byte order. To get little endian byte order, negate the field size.</p> </td></tr> <tr><td><code><code class='key'>'f'</code></code></td><td><p>Float. (Locale dependent formatting.)</p> </td></tr> <tr><td><code><code class='key'>'g'</code></code></td><td><p>Heuristically chosen representation of float. (Locale dependent formatting.)</p> </td></tr> <tr><td><code><code class='key'>'G'</code></code></td><td><p>Like <tt>%g</tt>, but uses uppercase <tt>E</tt> for exponent.</p> </td></tr> <tr><td><code><code class='key'>'e'</code></code></td><td><p>Exponential notation float. (Locale dependent output.)</p> </td></tr> <tr><td><code><code class='key'>'E'</code></code></td><td><p>Like <tt>%e</tt>, but uses uppercase <tt>E</tt> for exponent.</p> </td></tr> <tr><td><code><code class='key'>'F'</code></code></td><td><p>Binary IEEE representation of float (<tt>%4F</tt> gives single precision, <tt>%8F</tt> gives double precision) in network (big endian) byte order. To get little endian byte order, negate the field size.</p> </td></tr> <tr><td><code><code class='key'>'s'</code></code></td><td><p>String.</p> </td></tr> <tr><td><code><code class='key'>'q'</code></code></td><td><p>Quoted string. Escapes all control and non-8-bit characters, as well as the quote characters <tt>'\\'</tt> and <tt>'\"'</tt>.</p> </td></tr> <tr><td><code><code class='key'>'O'</code></code></td><td><p>Any value, debug style. Do not rely on the exact formatting; how the result looks can vary depending on locale, phase of the moon or anything else the <code>lfun::_sprintf()</code> method implementor wanted for debugging.</p> </td></tr> <tr><td><code><code class='key'>'p'</code></code></td><td><p>Hexadecimal representation of the memory address of the object. Integers and floats have no address, and are printed as themselves.</p> </td></tr> <tr><td><code><code class='key'>'H'</code></code></td><td><p>Binary Hollerith string. Equivalent to <code class='expr'>sprintf("%c%s", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;strlen(str),&nbsp;str)</code>. Arguments (such as width etc) adjust the length-part of the format. Requires 8-bit strings.</p> </td></tr> <tr><td><code><code class='key'>'n'</code></code></td><td><p>No argument. Same as <code class='expr'>"%s"</code> with an empty string as argument. Note: Does take an argument array (but ignores its content) if the modifier <code class='expr'>'@'</code> is active.</p> </td></tr> <tr><td><code><code class='key'>'t'</code></code></td><td><p>Type of the argument.</p> </td></tr> <tr><td><code><code class='key'>'{'</code></code></td><td rowspan='2'><p>Perform the enclosed format for every element of the argument array.</p> </td></tr> <tr><td><code><code class='key'>'}'</code></code></td></tr> </table><p>Most modifiers and operators are combinable in any fashion, but some combinations may render strange results.</p> <p> If an argument is an object that implements <code>lfun::_sprintf()</code>, that callback will be called with the operator as the first argument, and the current modifiers as the second. The callback is expected to return a string.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>sprintf-style formatting is applied by many formatting functions, such <code>write()</code> and <code>werror()</code>. It is also possible to get sprintf-style compile-time argument checking by using the type-attributes <code>sprintf_format</code> or <code>strict_sprintf_format</code> in combination with <code>sprintf_args</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>The <code class='expr'>'q'</code> operator was added in Pike 7.7.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Support for specifying modifiers via a mapping was added in Pike 7.8. This support can be tested for with the constant <code>String.__HAVE_SPRINTF_STAR_MAPPING__</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Support for specifying little endian byte order to <code class='expr'>'F'</code> was added in Pike 7.8. This support can be tested for with the constant <code>String.__HAVE_SPRINTF_NEGATIVE_F__</code>.</p> </dd> <dt class='head--doc'>Example</dt>
ecb4b22020-05-20Stephen R. van den Berg <dd class='example'><pre><pre><code><span class='ns'>Pike</span> v7.8 release 263 running Hilfe v3.5 <span class='delim'>(</span>Incremental <span class='ns'>Pike</span> Frontend<span class='delim'>)</span>
7393ca2019-08-17Henrik Grubbström (Grubba) <span class='delim'>&gt;</span> sprintf<span class='delim'>(</span><span class='string'>"The unicode character %c has character code %04X."</span><span class='delim'>,</span> <span class='string'>'A'</span><span class='delim'>,</span> <span class='string'>'A'</span><span class='delim'>)</span><span class='delim'>;</span> <span class='delim'>(</span>1<span class='delim'>)</span> Result<span class='delim'>:</span> <span class='string'>"The unicode character A has character code 0041."</span> <span class='delim'>&gt;</span> sprintf<span class='delim'>(</span><span class='string'>"#%@02X is the HTML code for purple."</span><span class='delim'>,</span> <span class='ns'>Image</span><span class='delim'>.</span>Color<span class='delim'>.</span>purple-&gt;rgb<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>)</span><span class='delim'>;</span> <span class='delim'>(</span>2<span class='delim'>)</span> Result<span class='delim'>:</span> <span class='string'>"#A020F0 is the HTML code for purple."</span> <span class='delim'>&gt;</span> <span class='type'>int</span> n<span class='delim'>=</span>4711<span class='delim'>;</span> <span class='delim'>&gt;</span> sprintf<span class='delim'>(</span><span class='string'>"%d = hexadecimal %x = octal %o = %b binary"</span><span class='delim'>,</span> n<span class='delim'>,</span> n<span class='delim'>,</span> n<span class='delim'>,</span> n<span class='delim'>)</span><span class='delim'>;</span> <span class='delim'>(</span>3<span class='delim'>)</span> Result<span class='delim'>:</span> <span class='string'>"4711 = hexadecimal 1267 = octal 11147 = 1001001100111 binary"</span> <span class='delim'>&gt;</span> write<span class='delim'>(</span><span class='string'>#"Formatting examples: Left adjusted [%-10d] Centered [%|10d] Right adjusted [%10d] Zero padded [%010d] "</span><span class='delim'>,</span> n<span class='delim'>,</span> n<span class='delim'>,</span> n<span class='delim'>,</span> n<span class='delim'>)</span><span class='delim'>;</span> Formatting examples<span class='delim'>:</span> Left adjusted <span class='delim'>[</span>4711 <span class='delim'>]</span> Centered <span class='delim'>[</span> 4711 <span class='delim'>]</span> Right adjusted <span class='delim'>[</span> 4711<span class='delim'>]</span> Zero padded <span class='delim'>[</span>0000004711<span class='delim'>]</span> <span class='delim'>(</span>5<span class='delim'>)</span> Result<span class='delim'>:</span> 142 <span class='type'>int</span> screen_width<span class='delim'>=</span>70<span class='delim'>;</span> <span class='delim'>&gt;</span> write<span class='delim'>(</span><span class='string'>"%-=*s\n"</span><span class='delim'>,</span> screen_width<span class='delim'>,</span> &gt;&gt; <span class='string'>"This will wordwrap the specified string within the "</span><span class='delim'>+</span> &gt;&gt; <span class='string'>"specified field size, this is useful say, if you let "</span><span class='delim'>+</span> &gt;&gt; <span class='string'>"users specify their screen size, then the room "</span><span class='delim'>+</span> &gt;&gt; <span class='string'>"descriptions will automagically word-wrap as appropriate.\n"</span><span class='delim'>+</span> &gt;&gt; <span class='string'>"slosh-n's will of course force a new-line when needed.\n"</span><span class='delim'>)</span><span class='delim'>;</span> This will wordwrap the specified <span class='type'>string</span> within the specified field size<span class='delim'>,</span> <span class='const'>this</span> is useful say<span class='delim'>,</span> <span class='lang'>if</span> you let users specify their screen size<span class='delim'>,</span> then the room descriptions will automagically word<span class='delim'>-</span>wrap as appropriate<span class='delim'>.</span> slosh<span class='delim'>-</span>n<span class='string'>'s will of course force a new-line when needed. (6) Result: 355 &gt; write("%-=*s %-=*s\n", screen_width/2, &gt;&gt; "Two columns next to each other (any number of columns will "+ &gt;&gt; "of course work) independantly word-wrapped, can be useful.", &gt;&gt; screen_width/2-1, &gt;&gt; "The - is to specify justification, this is in addherence "+ &gt;&gt; "to std sprintf which defaults to right-justification, "+ &gt;&gt; "this version also supports centre and right justification."); Two columns next to each other (any The - is to specify justification, number of columns will of course this is in addherence to std work) independantly word-wrapped, sprintf which defaults to can be useful. right-justification, this version also supports centre and right justification. (7) Result: 426 &gt; write("%-$*s\n", screen_width, &gt;&gt; "Given a\nlist of\nslosh-n\nseparated\n'</span>words<span class='string'>',\nthis option\n"+ &gt;&gt; "creates a\ntable out\nof them\nthe number of\ncolumns\n"+ &gt;&gt; "be forced\nby specifying a\npresision.\nThe most obvious\n"+ &gt;&gt; "use is for\nformatted\nls output."); Given a list of slosh-n separated '</span>words<span class='string'>', this option creates a table out of them the number of columns be forced by specifying a presision. The most obvious use is for formatted ls output. (8) Result: 312 &gt; write("%-#*s\n", screen_width, &gt;&gt; "Given a\nlist of\nslosh-n\nseparated\n'</span>words<span class='string'>',\nthis option\n"+ &gt;&gt; "creates a\ntable out\nof them\nthe number of\ncolumns\n"+ &gt;&gt; "be forced\nby specifying a\npresision.\nThe most obvious\n"+ &gt;&gt; "use is for\nformatted\nls output."); Given a creates a by specifying a list of table out presision. slosh-n of them The most obvious separated the number of use is for '</span>words<span class='string'>', columns formatted this option be forced ls output. (9) Result: 312 &gt; sample = ([ "align":"left", "valign":"middle" ]); (10) Result: ([ /* 2 elements */ "align":"left", "valign":"middle" ]) &gt; write("&lt;td%{ %s='</span><span class='delim'>%</span>s<span class='string'>'%}&gt;\n", (array)sample); &lt;td valign='</span>middle<span class='string'>' align='</span>left </code></pre> </pre></dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>lfun::_sprintf()</code>, <code>strict_sprintf_format</code>, <code>sprintf_format</code>, <code>sprintf_args</code>, <code>String.__HAVE_SPRINTF_STAR_MAPPING__</code>, <code>String.__HAVE_SPRINTF_NEGATIVE_F__</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>sprintf_args</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>sprintf_args</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Type constant used for typing extra arguments that are sent to <code>sprintf()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>strict_sprintf_format</code>, <code>sprintf_format</code>, <code>sprintf()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>sprintf_format</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>sprintf_format</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Type constant used for typing arguments that are optionally sent to <code>sprintf()</code> depending on the presence of extra arguments.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>strict_sprintf_format</code>, <code>sprintf_args</code>, <code>sprintf()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>sprintf_result</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>sprintf_result</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Type constant used for typing the return value from <code>sprintf()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>strict_sprintf_format</code>, <code>sprintf_format</code>, <code>sprintf()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sqrt</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>sqrt</span>(</b><code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>sqrt</span>(</b><code class='datatype'>int</code> <code class='argument'>i</code><b>)</b></code><br> <code><code class='datatype'>mixed</code> <b><span class='method'>sqrt</span>(</b><code class='datatype'>object</code> <code class='argument'>o</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the square root of <code>f</code>, or in the integer case, the square root truncated to the closest lower integer. If the argument is an object, the lfun _sqrt in the object will be called.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>pow()</code>, <code>log()</code>, <code>exp()</code>, <code>floor()</code>, <code>lfun::_sqrt</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>sscanf</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>sscanf</span>(</b><code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>lvalues</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>The purpose of sscanf is to match a string <code>data</code> against a <code>format</code> string and place the matching results into a list of variables. The list of <code>lvalues</code> are destructively modified (which is only possible because sscanf really is a special form, rather than a pike function) with the values extracted from the <code>data</code> according to the <code>format</code> specification. Only the variables up to the last matching directive of the format string are touched.</p> <p> The <code>format</code> string may contain strings separated by special matching directives like <tt>%d</tt>, <tt>%s</tt> <tt>%c</tt> and <tt>%f</tt>. Every such directive corresponds to one of the <code>lvalues</code>, in the order they are listed. An lvalue is the name of a variable, a name of a local variable, an index into an array, mapping or object. It is because of these lvalues that sscanf can not be implemented as a normal function.</p> <p> Whenever a percent character is found in the format string, a match is performed, according to which operator and modifiers follow it:</p> <table class='box'><tr><td><code><code class='key'>"%b"</code></code></td><td><p>Reads a binary integer (<code class='expr'>"0101"</code> makes <code class='expr'>5</code>)</p> </td></tr> <tr><td><code><code class='key'>"%d"</code></code></td><td><p>Reads a decimal integer (<code class='expr'>"0101"</code> makes <code class='expr'>101</code>).</p> </td></tr> <tr><td><code><code class='key'>"%o"</code></code></td><td><p>Reads an octal integer (<code class='expr'>"0101"</code> makes <code class='expr'>65</code>).</p> </td></tr> <tr><td><code><code class='key'>"%x"</code></code></td><td><p>Reads a hexadecimal integer (<code class='expr'>"0101"</code> makes <code class='expr'>257</code>).</p> </td></tr> <tr><td><code><code class='key'>"%D"</code></code></td><td><p>Reads an integer that is either octal (leading zero), hexadecimal (leading <code class='expr'>0x</code>) or decimal. (<code class='expr'>"0101"</code> makes <code class='expr'>65</code>).</p> </td></tr> <tr><td><code><code class='key'>"%c"</code></code></td><td><p>Reads one character and returns it as an integer (<code class='expr'>"0101"</code> makes <code class='expr'>48</code>, or <code class='expr'>'0'</code>, leaving <code class='expr'>"101"</code> for later directives). Using the field width and endianness modifiers, you can decode integers of any size and endianness. For example <code class='expr'>"%-2c"</code> decodes <code class='expr'>"0101"</code> into <code class='expr'>12592</code>, leaving <code class='expr'>"01"</code> for later directives. The sign modifiers can be used to modify the signature of the data, making <code class='expr'>"%+1c"</code> decode <code class='expr'>"ä"</code> into <code class='expr'>-28</code>.</p> </td></tr> <tr><td><code><code class='key'>"%n"</code></code></td><td><p>Returns the current character offset in <code>data</code>. Note that any characters matching fields scanned with the <code class='expr'>"!"</code>-modifier are removed from the count (see below).</p> </td></tr> <tr><td><code><code class='key'>"%f"</code></code></td><td><p>Reads a float ("0101" makes 101.0).</p> </td></tr> <tr><td><code><code class='key'>"%F"</code></code></td><td><p>Reads a float encoded according to the IEEE single precision binary format (<code class='expr'>"0101"</code> makes <code class='expr'>6.45e-10</code>, approximately). Given a field width modifier of 8 (4 is the default), the data will be decoded according to the IEEE double precision binary format instead. (You will however still get a float, unless your pike was compiled with the configure argument <tt>--with-double-precision</tt>.)</p> </td></tr> <tr><td><code><code class='key'>"%s"</code></code></td><td><p>Reads a string. If followed by %d, %s will only read non-numerical characters. If followed by a %[], %s will only read characters not present in the set. If followed by normal text, %s will match all characters up to but not including the first occurrence of that text.</p> </td></tr> <tr><td><code><code class='key'>"%H"</code></code></td><td><p>Reads a Hollerith-encoded string, i.e. first reads the length of the string and then that number of characters. The size and byte order of the length descriptor can be modified in the same way as <tt>%c</tt>. As an example <code class='expr'>"%2H"</code> first reads <code class='expr'>"%2c"</code> and then the resulting number of characters.</p> </td></tr> <tr><td><code><code class='key'>"%[set]"</code></code></td><td><p>Matches a string containing a given set of characters (those given inside the brackets). Ranges of characters can be defined by using a minus character between the first and the last character to be included in the range. Example: <code class='expr'>%[0-9H]</code> means any number or 'H'. Note that sets that includes the character '-' must have it first (not possible in complemented sets, see below) or last in the brackets to avoid having a range defined. Sets including the character ']' must list this first too. If both '-' and ']' should be included then put ']' first and '-' last. It is not possible to make a range that ends with ']'; make the range end with '\' instead and put ']' at the beginning of the set. Likewise it is generally not possible to have a range start with '-'; make the range start with '.' instead and put '-' at the end of the set. If the first character after the [ bracket is '^' (%[^set]), and this character does not begin a range, it means that the set is complemented, which is to say that any character except those inside brackets is matched. To include '-' in a complemented set, it must be put last, not first. To include '^' in a non-complemented set, it can be put anywhere but first, or be specified as a range ("^-^").</p> </td></tr> <tr><td><code><code class='key'>"%{format%}"</code></code></td><td><p>Repeatedly matches 'format' as many times as possible and assigns an array of arrays with the results to the lvalue.</p> </td></tr> <tr><td><code><code class='key'>"%O"</code></code></td><td><p>Match a Pike constant, such as string or integer (currently only integer, string and character constants are functional).</p> </td></tr> <tr><td><code><code class='key'>"%%"</code></code></td><td><p>Match a single percent character (hence this is how you quote the % character to just match, and not start an lvalue matcher directive).</p> </td></tr> </table><p>Similar to <code>sprintf</code>, you may supply modifiers between the % character and the operator, to slightly change its behaviour from the default:</p> <table class='box'><tr><td><code><code class='key'>"*"</code></code></td><td><p>The operator will only match its argument, without assigning any variable.</p> </td></tr> <tr><td><code><code class='key'>number</code></code></td><td><p>You may define a field width by supplying a numeric modifier. This means that the format should match that number of characters in the input data; be it a <i>number</i> characters long string, integer or otherwise (<code class='expr'>"0101"</code> using the format %2c would read an unsigned short <code class='expr'>12337</code>, leaving the final <code class='expr'>"01"</code> for later operators, for instance).</p> </td></tr> <tr><td><code><code class='key'>"-"</code></code></td><td><p>Supplying a minus sign toggles the decoding to read the data encoded in little-endian byte order, rather than the default network (big-endian) byte order.</p> </td></tr> <tr><td><code><code class='key'>"+"</code></code></td><td><p>Interpret the data as a signed entity. In other words, <code class='expr'>"%+1c"</code> will read <code class='expr'>"\xFF"</code> as <code class='expr'>-1</code> instead of <code class='expr'>255</code>, as <code class='expr'>"%1c"</code> would have.</p> </td></tr> <tr><td><code><code class='key'>"!"</code></code></td><td><p>Ignore the matched characters with respect to any following <code class='expr'>"%n"</code>.</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Sscanf does not use backtracking. Sscanf simply looks at the format string up to the next % and tries to match that with the string. It then proceeds to look at the next part. If a part does not match, sscanf immediately returns how many % were matched. If this happens, the lvalues for % that were not matched will not be changed.</p> </dd> <dt class='head--doc'>Example</dt> <dd class='example'><pre><pre><code><span class='comment'>// a will be assigned "oo" and 1 will be returned</span> sscanf<span class='delim'>(</span><span class='string'>"foo"</span><span class='delim'>,</span> <span class='string'>"f%s"</span><span class='delim'>,</span> a<span class='delim'>)</span><span class='delim'>;</span> <span class='comment'>// a will be 4711 and b will be "bar", 2 will be returned</span> sscanf<span class='delim'>(</span><span class='string'>"4711bar"</span><span class='delim'>,</span> <span class='string'>"%d%s"</span><span class='delim'>,</span> a<span class='delim'>,</span> b<span class='delim'>)</span><span class='delim'>;</span> <span class='comment'>// a will be 4711, 2 will be returned</span> sscanf<span class='delim'>(</span><span class='string'>"bar4711foo"</span><span class='delim'>,</span> <span class='string'>"%*s%d"</span><span class='delim'>,</span> a<span class='delim'>)</span><span class='delim'>;</span> <span class='comment'>// a will become "test", 2 will be returned</span> sscanf<span class='delim'>(</span><span class='string'>" \t test"</span><span class='delim'>,</span> <span class='string'>"%*[ \t]%s"</span><span class='delim'>,</span> a<span class='delim'>)</span><span class='delim'>;</span> <span class='comment'>// Remove "the " from the beginning of a string</span> <span class='comment'>// If 'str' does not begin with "the " it will not be changed</span> sscanf<span class='delim'>(</span>str<span class='delim'>,</span> <span class='string'>"the %s"</span><span class='delim'>,</span> str<span class='delim'>)</span><span class='delim'>;</span> <span class='comment'>// It is also possible to declare a variable directly in the sscanf call;</span> <span class='comment'>// another reason for sscanf not to be an ordinary function:</span> sscanf<span class='delim'>(</span><span class='string'>"abc def"</span><span class='delim'>,</span> <span class='string'>"%s %s"</span><span class='delim'>,</span> <span class='type'>string</span> a<span class='delim'>,</span> <span class='type'>string</span> b<span class='delim'>)</span><span class='delim'>;</span> </code></pre> </pre></dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The number of directives matched in the format string. Note that a string directive (%s or %[]) counts as a match even when matching just the empty string (which either may do).</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sprintf</code>, <code>array_sscanf</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>strftime</b></span> </dt> <dd><p><code><code class='datatype'>string(1..255)</code> <b><span class='method'>strftime</span>(</b><code class='datatype'>string(1..255)</code> <code class='argument'>format</code>, <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>tm</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Convert the structure to a string.</p> <dl class='group--doc'><dt>%a</dt> <dd><p>The abbreviated weekday name according to the current locale</p> </dd> <dt>%A</dt> <dd><p>The full weekday name according to the current locale.</p> </dd> <dt>%b</dt> <dd><p>The abbreviated month name according to the current locale.</p> </dd> <dt>%B</dt> <dd><p>The full month name according to the current locale.</p> </dd> <dt>%c</dt> <dd><p>The preferred date and time representation for the current locale.</p> </dd> <dt>%C</dt> <dd><p>The century number (year/100) as a 2-digit integer.</p> </dd> <dt>%d</dt> <dd><p>The day of the month as a decimal number (range 01 to 31).</p> </dd> <dt>%D</dt> <dd><p>Equivalent to <code class='expr'>%m/%d/%y</code>. (for Americans only. Americans should note that in other countries <code class='expr'>%d/%m/%y</code> is rather common. This means that in international context this format is ambiguous and should not be used.)</p> </dd> <dt>%e</dt> <dd><p>Like <code class='expr'>%d</code>, the day of the month as a decimal number, but a leading zero is replaced by a space.</p> </dd> <dt>%E</dt> <dd><p>Modifier: use alternative format, see below.</p> </dd> <dt>%F</dt> <dd><p>Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)</p> </dd> <dt>%G</dt> <dd><p>The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see <code class='expr'>%V</code>). This has the same format and value as <code class='expr'>%Y</code>, except that if the ISO week number belongs to the previous or next year, that year is used instead.</p> </dd> <dt>%g</dt> <dd><p>Like <code class='expr'>%G</code>, but without century, that is, with a 2-digit year (00-99). (TZ)</p> </dd> <dt>%h</dt> <dd><p>Equivalent to %b.</p> </dd> <dt>%H</dt> <dd><p>The hour as a decimal number using a 24-hour clock (range 00 to 23).</p> </dd> <dt>%I</dt> <dd><p>The hour as a decimal number using a 12-hour clock (range 01 to 12).</p> </dd> <dt>%j</dt> <dd><p>The day of the year as a decimal number (range 001 to 366).</p> </dd> <dt>%k</dt> <dd><p>The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. (See also <code class='expr'>%H</code>.)</p> </dd> <dt>%l</dt> <dd><p>The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. (See also <code class='expr'>%I</code>.)</p> </dd> <dt>%m</dt> <dd><p>The month as a decimal number (range 01 to 12).</p> </dd> <dt>%M</dt> <dd><p>The minute as a decimal number (range 00 to 59).</p> </dd> <dt>%n</dt> <dd><p>A newline character. (SU)</p> </dd> <dt>%O</dt> <dd><p>Modifier: use alternative format, see below. (SU)</p> </dd> <dt>%p</dt> <dd><p>Either <code class='expr'>"AM"</code> or <code class='expr'>"PM"</code> according to the given time value, or the corresponding strings for the current locale. Noon is treated as <code class='expr'>"PM"</code> and midnight as <code class='expr'>"AM"</code>.</p> </dd> <dt>%P</dt> <dd><p>Like <code class='expr'>%p</code> but in lowercase: <code class='expr'>"am"</code> or <code class='expr'>"pm"</code> or a corresponding string for the current locale.</p> </dd> <dt>%r</dt> <dd><p>The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to <code class='expr'>%I:%M:%S&nbsp;%p</code>.</p> </dd> <dt>%R</dt> <dd><p>The time in 24-hour notation (<code class='expr'>%H:%M</code>). (SU) For a version including the seconds, see <code class='expr'>%T</code> below.</p> </dd> <dt>%s</dt> <dd><p>The number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). (TZ)</p> </dd> <dt>%S</dt> <dd><p>The second as a decimal number (range 00 to 60). (The range is up to 60 to allow for occasional leap seconds.)</p> </dd> <dt>%t</dt> <dd><p>A tab character. (SU)</p> </dd> <dt>%T</dt> <dd><p>The time in 24-hour notation (<code class='expr'>%H:%M:%S</code>). (SU)</p> </dd> <dt>%u</dt> <dd><p>The day of the week as a decimal, range 1 to 7, Monday being 1. See also <code class='expr'>%w</code>. (SU)</p> </dd> <dt>%U</dt> <dd><p>The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. See also <code class='expr'>%V</code> and <code class='expr'>%W</code>.</p> </dd> <dt>%V</dt> <dd><p>The ISO 8601 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also <code class='expr'>%U</code> and <code class='expr'>%W</code>.</p> </dd> <dt>%w</dt> <dd><p>The day of the week as a decimal, range 0 to 6, Sunday being 0. See also <code class='expr'>%u</code>.</p> </dd> </dl> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>ctime()</code>, <code>mktime()</code>, <code>strptime()</code>, <code>Gettext.setlocale</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>strict_sprintf_format</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>strict_sprintf_format</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Type constant used for typing arguments that are always sent to <code>sprintf()</code> regardless of the presence of extra arguments.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>sprintf_format</code>, <code>sprintf_args</code>, <code>sprintf()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>string_filter_non_unicode</b></span> </dt> <dd><p><code><code class='datatype'>string(1..)</code> <b><span class='method'>string_filter_non_unicode</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Replace the most obviously non-unicode characters from <code>s</code> with the unicode replacement character.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This will replace characters outside the ranges <code class='expr'>0x00000000-0x0000d7ff</code> and <code class='expr'>0x0000e000-0x0010ffff</code> with 0xffea (the replacement character).</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Charset.encoder()</code>, <code>string_to_unicode()</code>, <code>unicode_to_string()</code>, <code>utf8_to_string()</code>, <code>string_to_utf8()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>string_to_unicode</b></span> </dt> <dd><p><code><code class='datatype'>string(8bit)</code> <b><span class='method'>string_to_unicode</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int(0..2)</code>|<code class='datatype'>void</code> <code class='argument'>byteorder</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Converts a string into an UTF16 compliant byte-stream.</p> </dd> <dt class='head--doc'><span id='p-s'></span>Parameter <code class='parameter'>s</code></dt> <dd></dd><dd class='body--doc'><p>String to convert to UTF16.</p> </dd> <dt class='head--doc'><span id='p-byteorder'></span>Parameter <code class='parameter'>byteorder</code></dt> <dd></dd><dd class='body--doc'><p>Byte-order for the output. One of:</p> <table class='box'><tr><td><code><code class='key'>0</code></code></td><td><p>Network (aka big-endian) byte-order (default).</p> </td></tr> <tr><td><code><code class='key'>1</code></code></td><td><p>Little-endian byte-order.</p> </td></tr> <tr><td><code><code class='key'>2</code></code></td><td><p>Native byte-order.</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Throws an error if characters not legal in an UTF16 stream are encountered. Valid characters are in the range 0x00000 - 0x10ffff, except for characters 0xfffe and 0xffff.</p> <p> Characters in range 0x010000 - 0x10ffff are encoded using surrogates.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Charset.decoder()</code>, <code>string_to_utf8()</code>, <code>unicode_to_string()</code>, <code>utf8_to_string()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>string_to_utf8</b></span> </dt> <dd><p><code><code class='object unresolved'>utf8_string</code> <b><span class='method'>string_to_utf8</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='object unresolved'>utf8_string</code> <b><span class='method'>string_to_utf8</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>extended</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Convert a string into a UTF-8 compliant byte-stream.</p> </dd> <dt class='head--doc'><span id='p-s'></span>Parameter <code class='parameter'>s</code></dt> <dd></dd><dd class='body--doc'><p>String to encode into UTF-8.</p> </dd> <dt class='head--doc'><span id='p-extended'></span>Parameter <code class='parameter'>extended</code></dt> <dd></dd><dd class='body--doc'><p>Bitmask with extension options.</p> <table class='box'><tr><td><code><code class='key'>1</code></code></td><td><p>Accept and encode the characters outside the valid ranges using the same algorithm. Such encoded characters are however not UTF-8 compliant.</p> </td></tr> <tr><td><code><code class='key'>2</code></code></td><td><p>Encode characters outside the BMP with UTF-8 encoded UTF-16 (ie split them into surrogate pairs and encode).</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Throws an error if characters not valid in an UTF-8 stream are encountered. Valid characters are in the ranges <code class='expr'>0x00000000-0x0000d7ff</code> and <code class='expr'>0x0000e000-0x0010ffff</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Charset.encoder()</code>, <code>string_to_unicode()</code>, <code>unicode_to_string()</code>, <code>utf8_to_string()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>stringp</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>stringp</span>(</b><code class='datatype'>mixed</code> <code class='argument'>arg</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns <code class='expr'>1</code> if <code>arg</code> is a string, <code class='expr'>0</code> (zero) otherwise.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>intp()</code>, <code>programp()</code>, <code>arrayp()</code>, <code>multisetp()</code>, <code>objectp()</code>, <code>mappingp()</code>, <code>floatp()</code>, <code>functionp()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>strptime</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>) <b><span class='method'>strptime</span>(</b><code class='datatype'>string(1..255)</code> <code class='argument'>data</code>, <code class='datatype'>string(1..255)</code> <code class='argument'>format</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Parse the given <code>data</code> using the format in <code>format</code> as a date.</p> <dl class='group--doc'><dt>%%</dt> <dd><p>The % character.</p> </dd> <dt>%a or %A</dt> <dd><p>The weekday name according to the C locale, in abbreviated form or the full name.</p> </dd> <dt>%b or %B or %h</dt> <dd><p>The month name according to the C locale, in abbreviated form or the full name.</p> </dd> <dt>%c</dt> <dd><p>The date and time representation for the C locale.</p> </dd> <dt>%C</dt> <dd><p>The century number (0-99).</p> </dd> <dt>%d or %e</dt> <dd><p>The day of month (1-31).</p> </dd> <dt>%D</dt> <dd><p>Equivalent to %m/%d/%y.</p> </dd> <dt>%H</dt> <dd><p>The hour (0-23).</p> </dd> <dt>%I</dt> <dd><p>The hour on a 12-hour clock (1-12).</p> </dd> <dt>%j</dt> <dd><p>The day number in the year (1-366).</p> </dd> <dt>%m</dt> <dd><p>The month number (1-12).</p> </dd> <dt>%M</dt> <dd><p>The minute (0-59).</p> </dd> <dt>%n</dt> <dd><p>Arbitrary whitespace.</p> </dd> <dt>%p</dt> <dd><p>The C locale's equivalent of AM or PM.</p> </dd> <dt>%R</dt> <dd><p>Equivalent to %H:%M.</p> </dd> <dt>%S</dt> <dd><p>The second (0-60; 60 may occur for leap seconds; earlier also 61 was allowed).</p> </dd> <dt>%t</dt> <dd><p>Arbitrary whitespace.</p> </dd> <dt>%T</dt> <dd><p>Equivalent to %H:%M:%S.</p> </dd> <dt>%U</dt> <dd><p>The week number with Sunday the first day of the week (0-53).</p> </dd> <dt>%w</dt> <dd><p>The weekday number (0-6) with Sunday = 0.</p> </dd> <dt>%W</dt> <dd><p>The week number with Monday the first day of the week (0-53).</p> </dd> <dt>%x</dt> <dd><p>The date, using the C locale's date format.</p> </dd> <dt>%X</dt> <dd><p>The time, using the C locale's time format.</p> </dd> <dt>%y</dt> <dd><p>The year within century (0-99). When a century is not otherwise specified, values in the range 69-99 refer to years in the twentieth century (1969-1999); values in the range 00-68 refer to years in the twenty-first century (2000-2068).</p> </dd> <dt>%Y</dt> <dd><p>The year, including century (for example, 1991).</p> </dd> </dl> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>localtime()</code>, <code>gmtime()</code>, <code>strftime()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>tan</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>tan</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the tangent value for <code>f</code>. <code>f</code> should be specified in radians.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>atan()</code>, <code>sin()</code>, <code>cos()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>tanh</b></span> </dt> <dd><p><code><code class='datatype'>float</code> <b><span class='method'>tanh</span>(</b><code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>f</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the hyperbolic tangent value for <code>f</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>atanh()</code>, <code>sinh()</code>, <code>cosh()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>this</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>this</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Builtin read only variable that evaluates to the current object.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>this_program</code>, <code>this_object()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>this_function</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>this_function</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Builtin constant that evaluates to the current function.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>this</code>, <code>this_object()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>this_object</b></span> </dt> <dd><p><code><code class='datatype'>object</code> <b><span class='method'>this_object</span>(</b><code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>level</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the object we are currently evaluating in.</p> </dd> <dt class='head--doc'><span id='p-level'></span>Parameter <code class='parameter'>level</code></dt> <dd></dd><dd class='body--doc'><p><code>level</code> may be used to access the object of a surrounding class: The object at level 0 is the current object, the object at level 1 is the one belonging to the class that surrounds the class that the object comes from, and so on.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>As opposed to a qualified <code class='expr'>this</code> reference such as <code class='expr'>global::this</code>, this function doesn't always access the objects belonging to the lexically surrounding classes. If the class containing the call has been inherited then the objects surrounding the inheriting class are accessed.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Constant</span> <span class='homogen--name'><b>this_program</b></span> </dt> <dd><p><code><code class='datatype'>constant</code> <code class='constant'>this_program</code></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Builtin constant that evaluates to the current program.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>this</code>, <code>this_object()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>throw</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code>|<code class='datatype'>void</code> <b><span class='method'>throw</span>(</b><code class='datatype'>mixed</code> <code class='argument'>value</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Throw <code>value</code> to a waiting <code>catch</code>.</p> <p> If no <code>catch</code> is waiting the global error handling will send the value to <code>master()-&gt;handle_error()</code>.</p> <p> If you throw an array with where the first index contains an error message and the second index is a backtrace, (the output from <code>backtrace()</code>) then it will be treated exactly like a real error by overlying functions.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>catch</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>time</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>time</span>(</b><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>time</span>(</b><code class='datatype'>int(1..1)</code> <code class='argument'>one</code><b>)</b></code><br> <code><code class='datatype'>float</code> <b><span class='method'>time</span>(</b><code class='datatype'>int(2..)</code> <code class='argument'>t</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function returns the number of seconds since 00:00:00 UTC, 1 Jan 1970.</p> <p> The second syntax does not query the system for the current time, instead the last time value used by the pike process is returned again. It avoids a system call, and thus is slightly faster, but can be wildly inaccurate. Pike queries the time internally when a thread has waited for something, typically in <code>sleep</code> or in a backend (see <code>Pike.Backend</code>).</p> <p> The third syntax can be used to measure time more precisely than one second. It returns how many seconds have passed since <code>t</code>. The precision of this function varies from system to system.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>ctime()</code>, <code>localtime()</code>, <code>mktime()</code>, <code>gmtime()</code>, <code>System.gettimeofday()</code>, <code>gethrtime()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>trace</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>trace</span>(</b><code class='datatype'>int</code> <code class='argument'>level</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>facility</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>all_threads</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>This function changes the trace level for the subsystem identified by <code>facility</code> to <code>level</code>. If <code>facility</code> is zero or left out, it changes the global trace level which affects all subsystems.</p> <p> Enabling tracing causes messages to be printed to stderr. A higher trace level includes the output from all lower levels. The lowest level is zero which disables all trace messages.</p> <p> See the <tt>-t</tt> command-line option for more information.</p> </dd> <dt class='head--doc'><span id='p-level'></span>Parameter <code class='parameter'>level</code></dt> <dd></dd><dd class='body--doc'><p>If <code>facility</code> is specified then there is typically only one trace level for it, i.e. it's an on-or-off toggle. The global trace levels, when <code>facility</code> isn't specified, are:</p> <table class='box'><tr><td><code><code class='key'>1</code></code></td><td><p>Trace calls to Pike functions and garbage collector runs.</p> </td></tr> <tr><td><code><code class='key'>2</code></code></td><td><p>Trace calls to builtin functions.</p> </td></tr> <tr><td><code><code class='key'>3</code></code></td><td><p>Trace every interpreted opcode.</p> </td></tr> <tr><td><code><code class='key'>4</code></code></td><td><p>Also trace the opcode arguments.</p> </td></tr> </table> </dd> <dt class='head--doc'><span id='p-facility'></span>Parameter <code class='parameter'>facility</code></dt> <dd></dd><dd class='body--doc'><p>Valid facilities are:</p> <table class='box'><tr><td><code><code class='key'>"gc"</code></code></td><td><p>Trace the doings of the garbage collector. The setting is never thread local. <code>level</code> has two different meanings:</p> <dl class='group--doc'><dt>1..2</dt> <dd><p>Trace the start and end of each gc run.</p> </dd> <dt>3..</dt> <dd><p>Additionally show info about the collected garbage, to aid hunting down garbage problems. This currently shows gc'd trampolines. Note that the output can be very bulky and is somewhat low-level technical. Also note that pike currently has to be configured with <code class='expr'>--with-rtldebug</code> to enable this.</p> </dd> </dl></td></tr> </table> </dd> <dt class='head--doc'><span id='p-all_threads'></span>Parameter <code class='parameter'>all_threads</code></dt> <dd></dd><dd class='body--doc'><p>Trace levels are normally thread local, so changes affect only the current thread. To change the level in all threads, pass a nonzero value in this argument.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>The old trace level in the current thread is returned.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>ualarm</b></span> </dt> <dd><p><code><code class='datatype'>int</code> <b><span class='method'>ualarm</span>(</b><code class='datatype'>int</code> <code class='argument'>useconds</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Set an alarm clock for delivery of a signal.</p> <p> <code>alarm()</code> arranges for a SIGALRM signal to be delivered to the process in <code>useconds</code> microseconds.</p> <p> If <code>useconds</code> is <code class='expr'>0</code> (zero), no new alarm will be scheduled.</p> <p> Any previous alarms will in any case be canceled.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the number of microseconds remaining until any previously scheduled alarm was due to be delivered, or zero if there was no previously scheduled alarm.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is only available on platforms that support signals.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>alarm()</code>, <code>signal()</code>, <code>call_out()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>unicode_to_string</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>unicode_to_string</span>(</b><code class='datatype'>string(8bit)</code> <code class='argument'>s</code>, <code class='datatype'>int(0..2)</code>|<code class='datatype'>void</code> <code class='argument'>byteorder</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Converts an UTF16 byte-stream into a string.</p> </dd> <dt class='head--doc'><span id='p-s'></span>Parameter <code class='parameter'>s</code></dt> <dd></dd><dd class='body--doc'><p>String to convert to UTF16.</p> </dd> <dt class='head--doc'><span id='p-byteorder'></span>Parameter <code class='parameter'>byteorder</code></dt> <dd></dd><dd class='body--doc'><p>Default input byte-order. One of:</p> <table class='box'><tr><td><code><code class='key'>0</code></code></td><td><p>Network (aka big-endian) byte-order (default).</p> </td></tr> <tr><td><code><code class='key'>1</code></code></td><td><p>Little-endian byte-order.</p> </td></tr> <tr><td><code><code class='key'>2</code></code></td><td><p>Native byte-order.</p> </td></tr> </table><p>Note that this argument is disregarded if <code>s</code> starts with a BOM.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Charset.decoder()</code>, <code>string_to_unicode()</code>, <code>string_to_utf8()</code>, <code>utf8_to_string()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>upper_case</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>upper_case</span>(</b><code class='datatype'>string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>int</code> <b><span class='method'>upper_case</span>(</b><code class='datatype'>int</code> <code class='argument'>c</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Convert a string or character to upper case.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns a copy of the string <code>s</code> with all lower case characters converted to upper case, or the character <code>c</code> converted to upper case.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Assumes the string or character to be coded according to ISO-10646 (aka Unicode). If they are not, <code>Charset.decoder</code> can do the initial conversion for you.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Prior to Pike 7.5 this function only accepted strings.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>lower_case()</code>, <code>Charset.decoder</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>utf8_to_string</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>utf8_to_string</span>(</b><code class='object unresolved'>utf8_string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>utf8_to_string</span>(</b><code class='object unresolved'>utf8_string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>extended</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Converts an UTF-8 byte-stream into a string.</p> </dd> <dt class='head--doc'><span id='p-s'></span>Parameter <code class='parameter'>s</code></dt> <dd></dd><dd class='body--doc'><p>String of UTF-8 encoded data to decode.</p> </dd> <dt class='head--doc'><span id='p-extended'></span>Parameter <code class='parameter'>extended</code></dt> <dd></dd><dd class='body--doc'><p>Bitmask with extension options.</p> <table class='box'><tr><td><code><code class='key'>1</code></code></td><td><p>Accept and decode the extension used by <code>string_to_utf8()</code>.</p> </td></tr> <tr><td><code><code class='key'>2</code></code></td><td><p>Accept and decode UTF-8 encoded UTF-16 (ie accept and decode valid surrogates).</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Throws an error if the stream is not a legal UTF-8 byte-stream.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>In conformance with <b><a href='http://pike.lysator.liu.se/rfc3629.xml'>RFC 3629</a></b> and Unicode 3.1 and later, non-shortest forms are not decoded. An error is thrown instead.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Charset.encoder()</code>, <code>string_to_unicode()</code>, <code>string_to_utf8()</code>, <code>unicode_to_string()</code>, <code>validate_utf8()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>validate_utf8</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>validate_utf8</span>(</b><code class='object unresolved'>utf8_string</code> <code class='argument'>s</code><b>)</b></code><br> <code><code class='datatype'>string</code> <b><span class='method'>validate_utf8</span>(</b><code class='object unresolved'>utf8_string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>extended</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Checks whether a string is a valid UTF-8 byte-stream.</p> </dd> <dt class='head--doc'><span id='p-s'></span>Parameter <code class='parameter'>s</code></dt> <dd></dd><dd class='body--doc'><p>String of UTF-8 encoded data to validate.</p> </dd> <dt class='head--doc'><span id='p-extended'></span>Parameter <code class='parameter'>extended</code></dt> <dd></dd><dd class='body--doc'><p>Bitmask with extension options.</p> <table class='box'><tr><td><code><code class='key'>1</code></code></td><td><p>Accept the extension used by <code>string_to_utf8()</code>, including lone UTF-16 surrogates.</p> </td></tr> <tr><td><code><code class='key'>2</code></code></td><td><p>Accept UTF-8 encoded UTF-16 (ie accept valid surrogate-pairs).</p> </td></tr> </table> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns <code class='expr'>0</code> (zero) if the stream is not a legal UTF-8 byte-stream, and <code class='expr'>1</code> if it is.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>In conformance with <b><a href='http://pike.lysator.liu.se/rfc3629.xml'>RFC 3629</a></b> and Unicode 3.1 and later, non-shortest forms are considered invalid.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>Charset.encoder()</code>, <code>string_to_unicode()</code>, <code>string_to_utf8()</code>, <code>unicode_to_string()</code>, <code>utf8_to_string()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>version</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>version</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Report the version of Pike. Does the same as</p> <pre><code>sprintf<span class='delim'>(</span><span class='string'>"Pike v%d.%d release %d"</span><span class='delim'>,</span> <span class='const'>__REAL_VERSION__</span><span class='delim'>,</span> <span class='const'>__REAL_MINOR__</span><span class='delim'>,</span> <span class='const'>__REAL_BUILD__</span><span class='delim'>)</span><span class='delim'>;</span> </code></pre> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>__VERSION__</code>, <code>__MINOR__</code>, <code>__BUILD__</code>, <code>__REAL_VERSION__</code>, <code>__REAL_MINOR__</code>, <code>__REAL_BUILD__</code>,</p> </dd></dl>
47a29e2020-05-24Stephen R. van den Berg <dl><dt><h2 class='header'>Class <b class='ms datatype'>Codec</b></h2>
7393ca2019-08-17Henrik Grubbström (Grubba) </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>An <code>Encoder</code> and a <code>Decoder</code> lumped into a single instance which can be used for both encoding and decoding.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>Decoder</b></span> </dt> <dd><p><code><span class='datatype'>inherit Decoder</span> : <span class='inherit'>Decoder</span></code></p></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>Encoder</b></span> </dt> <dd><p><code><span class='datatype'>inherit Encoder</span> : <span class='inherit'>Encoder</span></code></p></dd> </dl> </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>CompilationHandler</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Objects used by the compiler to handle references to global symbols, modules, external files, etc.</p> <p> There can be up to three compilation handlers active at the same time during a compilation. They are in order of precedence:</p> <ol> <li><p>The error handler</p> <p> This is the object passed to <code>compile()</code> as the second argument (if any). This object is returned by <code>get_active_error_handler()</code> during a compilation.</p> </li><li><p>The compatibility handler</p> <p> This is the object returned by <code>master()-&gt;get_compilation_handler()</code> (if any), which the compiler calls when it sees <tt>#pike</tt>-directives, or expressions using the version scope (eg <code class='expr'>7.4::rusage</code>). This object is returned by <code>get_active_compilation_handler()</code> during a compilation.</p> </li><li><p>The master object.</p> <p> This is returned by <code>master()</code> at any time.</p> </li></ol><p>Any of the objects may implement a subset of the <code>CompilationHandler</code> functions, and the first object that implements a function will be used. The error handler object can thus be used to block certain functionality (eg to restrict the number of available functions).</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>master()-&gt;get_compilation_handler()</code>, <code>get_active_error_handler()</code>, <code>get_active_compilation_handler()</code>, <code>compile()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>compile_error</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>compile_error</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>int</code> <code class='argument'>line</code>, <code class='datatype'>string</code> <code class='argument'>msg</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>compile()</code> and <code>cpp()</code> when they encounter errors in the code they compile.</p> </dd> <dt class='head--doc'><span id='p-filename'></span>Parameter <code class='parameter'>filename</code></dt> <dd></dd><dd class='body--doc'><p>File where the error was detected.</p> </dd> <dt class='head--doc'><span id='p-line'></span>Parameter <code class='parameter'>line</code></dt> <dd></dd><dd class='body--doc'><p>Line where the error was detected.</p> </dd> <dt class='head--doc'><span id='p-msg'></span>Parameter <code class='parameter'>msg</code></dt> <dd></dd><dd class='body--doc'><p>Description of error.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>compile_warning()</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>compile_exception</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>compile_exception</span>(</b><code class='datatype'>mixed</code> <code class='argument'>exception</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>compile()</code> and <code>cpp()</code> if they trigger exceptions.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>compile_warning</b></span> </dt> <dd><p><code><code class='datatype'>void</code> <b><span class='method'>compile_warning</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>int</code> <code class='argument'>line</code>, <code class='datatype'>string</code> <code class='argument'>msg</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>compile()</code> to report warnings.</p> </dd> <dt class='head--doc'><span id='p-filename'></span>Parameter <code class='parameter'>filename</code></dt> <dd></dd><dd class='body--doc'><p>File which triggered the warning.</p> </dd> <dt class='head--doc'><span id='p-line'></span>Parameter <code class='parameter'>line</code></dt> <dd></dd><dd class='body--doc'><p>Line which triggered the warning.</p> </dd> <dt class='head--doc'><span id='p-msg'></span>Parameter <code class='parameter'>msg</code></dt> <dd></dd><dd class='body--doc'><p>Warning message.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>compile_error()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_default_module</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>)|<code class='datatype'>object</code> <b><span class='method'>get_default_module</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Returns the default module from which global symbols will be fetched.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the default module, or <code class='expr'>0</code> (zero).</p> <p> If <code class='expr'>0</code> (zero) is returned the compiler use the mapping returned by <code>all_constants()</code> as fallback.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>get_predefines()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_predefines</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>) <b><span class='method'>get_predefines</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>cpp()</code> to get the set of global symbols.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns a mapping from symbol name to symbol value. Returns zero on failure.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>resolv()</code>, <code>get_default_module()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>handle_import</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>handle_import</span>(</b><code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='object unresolved'>CompilationHandler</code> <code class='argument'>handler</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>compile()</code> and <code>cpp()</code> to handle import directives specifying specific paths.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the resolved value, or <code>UNDEFINED</code> on failure.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>handle_include</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>handle_include</span>(</b><code class='datatype'>string</code> <code class='argument'>header_file</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>bool</code> <code class='argument'>is_local_ref</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>cpp()</code> to resolv <code class='expr'>#include</code> and <code class='expr'>#string</code> directives.</p> </dd> <dt class='head--doc'><span id='p-header_file'></span>Parameter <code class='parameter'>header_file</code></dt> <dd></dd><dd class='body--doc'><p>File that was requested for inclusion.</p> </dd> <dt class='head--doc'><span id='p-current_file'></span>Parameter <code class='parameter'>current_file</code></dt> <dd></dd><dd class='body--doc'><p>File where the directive was found.</p> </dd> <dt class='head--doc'><span id='p-is_local_ref'></span>Parameter <code class='parameter'>is_local_ref</code></dt> <dd></dd><dd class='body--doc'><p>Specifies reference method.</p> <table class='box'><tr><td><code><code class='key'>0</code></code></td><td><p>Directive was <code class='expr'>#include&nbsp;&lt;header_file&gt;</code>.</p> </td></tr> <tr><td><code><code class='key'>1</code></code></td><td><p>Directive was <code class='expr'>#include&nbsp;"header_file"</code>.</p> </td></tr> </table> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the filename to pass to <code>read_include()</code> if found, and <code class='expr'>0</code> (zero) on failure.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>read_include()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>read_include</b></span> </dt> <dd><p><code><code class='datatype'>string</code> <b><span class='method'>read_include</span>(</b><code class='datatype'>string</code> <code class='argument'>filename</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>cpp()</code> to read included files.</p> </dd> <dt class='head--doc'><span id='p-filename'></span>Parameter <code class='parameter'>filename</code></dt> <dd></dd><dd class='body--doc'><p>Filename as returned by <code>handle_include()</code>.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns a string with the content of the header file on success, and <code class='expr'>0</code> (zero) on failure.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>handle_include()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>resolv</b></span> </dt> <dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>resolv</span>(</b><code class='datatype'>string</code> <code class='argument'>symbol</code>, <code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='object unresolved'>CompilationHandler</code> <code class='argument'>handler</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Called by <code>compile()</code> and <code>cpp()</code> to resolv module references.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><p>Returns the resolved value, or <code>UNDEFINED</code> on failure.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>get_predefines()</code></p> </dd></dl> </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>CompilerEnvironment</b></h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt>
47a29e2020-05-24Stephen R. van den Berg <dd class='body--doc'><p>The compiler environment.</p>
7393ca2019-08-17Henrik Grubbström (Grubba) <p> By inheriting this class and overloading the functions, it is possible to make a custom Pike compiler.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Prior to Pike 7.8 this sort of customization has to be done either via custom master objects, or via <code>CompilationHandler</code>s.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>CompilationHandler</code>, <code>MasterObject</code>, <code>master()</code>, <code>replace_master()</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>compile</b></span> </dt> <dd><p><code><code class='datatype'>program</code> <b><span class='method'>compile</span>(</b><code class='datatype'>string</code> <code class='argument'>source</code>, <code class='object unresolved'>CompilationHandler</code>|<code class='datatype'>void</code> <code class='argument'>handler</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>major</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>minor</code>, <code class='datatype'>program</code>|<code class='datatype'>void</code> <code class='argument'>target</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>placeholder</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Compile a string to a program.</p> <p> This function takes a piece of Pike code as a string and compiles it into a clonable program.</p> <p> The optional argument <code>handler</code> is used to specify an alternative error handler. If it is not specified the current master object will be used.</p> <p> The optional arguments <code>major</code> and <code>minor</code> are used to tell the compiler to attempt to be compatible with Pike <code>major</code>.<code>minor</code>.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function essentially performs</p> <pre><code><span class='type'>program</span> compile<span class='delim'>(</span><span class='type'>mixed</span> ... args<span class='delim'>)</span> <span class='delim'>{</span> <span class='lang'>return</span> PikeCompiler<span class='delim'>(</span>@args<span class='delim'>)</span>-&gt;compile<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span> <span class='delim'>}</span> </code></pre> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>Note that <code>source</code> must contain the complete source for a program. It is not possible to compile a single expression or statement.</p> <p> Also note that <code>compile()</code> does not preprocess the program. To preprocess the program you can use <code>compile_string()</code> or call the preprocessor manually by calling <code>cpp()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>compile_string()</code>, <code>compile_file()</code>, <code>cpp()</code>, <code>master()</code>, <code>CompilationHandler</code></p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_compilation_handler</b></span> </dt> <dd><p><code><code class='datatype'>object</code> <b><span class='method'>get_compilation_handler</span>(</b><code class='datatype'>int</code> <code class='argument'>major</code>, <code class='datatype'>int</code> <code class='argument'>minor</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get compatibility handler for Pike <code>major</code>.<code>minor</code>.</p> <p> The default implementation calls the corresponding function in the master object.</p> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is typically called by <code>PikeCompiler()-&gt;get_compilation_handler()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>MasterObject()-&gt;get_compilation_handler()</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>get_default_module</b></span> </dt> <dd><p><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>)|<code class='datatype'>object</code> <b><span class='method'>get_default_module</span>(</b><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Get the default module for the current compatibility level (ie typically the value returned by <code>predef::all_constants()</code>).</p> <p> The default implementation calls the corresponding function in the master object.</p> </dd> <dt class='head--doc'>Returns</dt> <dd class='body--doc'><table class='box'><tr><td><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>mixed</code>)|<code class='datatype'>object</code></code></td><td><p>Constant table to use.</p> </td></tr> <tr><td><code><code class='datatype'>int(0..0)</code></code></td><td><p>Use the builtin constant table.</p> </td></tr> </table> </dd> <dt class='head--doc'>Note</dt> <dd class='body--doc'><p>This function is typically called by <code>Pike_compiler()-&gt;get_default_module()</code>.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>MasterObject()-&gt;get_default_module()</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>handle_import</b></span> </dt> <dd><p><code><code class='datatype'>program</code> <b><span class='method'>handle_import</span>(</b><code class='datatype'>string</code> <code class='argument'>module</code>, <code class='datatype'>string</code> <code class='argument'>current_file</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>handler</code><b>)</b></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Look up an import <code>module</code>.</p> <p> The default implementation calls the corresponding function in the master object.</p> </dd> <dt class='head--doc'>See also</dt> <dd class='body--doc'><p><code>MasterObject()-&gt;handle_import()</code>.</p> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Method</span> <span class='homogen--name'><b>handle_inherit</b>&l