Log of autodoc.git/traditional_manual/chapter

2017-07-10

2017-07-10 10:30:01 by Henrik Grubbström (Grubba) <grubba@grubba.org>

f6a422df4113bcaa37e83b5e8e4d7c90e43af2e1 (10036 lines) (+5482/-4554) ^{[

Show
| Annotate

]}
Branch: master

Manual: Extended the data types chapter with void & mixed.

Added some elaboration on the difference between compile-time
and run-time types, as well as some about the types void & mixed
and how they are used.

Fixes [bug 1656 (#1656)].

1: <!doctype html><html><head><title>Pike Reference Manual</title> <meta charset='utf-8'></head> - <body><dl><dt><h1 class='header'>9. I/O</h1></dt><dd><dl><dt><h2 class='header'>Class Stdio.File</h2> - </dt><dd><dl class='group--doc'> + <body><dl><dt><h1 class='header'>9. Specific Datatype Modules</h1></dt><dd><dl><dt><h2 class='header'>Module String</h2> + </dt><dd> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __HAVE_SPRINTF_NEGATIVE_F__ + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> String.<code class='constant'>__HAVE_SPRINTF_NEGATIVE_F__</code></code></dd> + <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This is the basic I/O object, it provides socket and pipe - communication as well as file access. It does not buffer reads and - writes by default, and provides no line-by-line reading, that is done - with <code>Stdio.FILE</code> object. + <dd class='body--doc'>Presence of this symbol indicates that <code>sprintf()</code> supports + little endian output for the <tt>'F'</tt>-format specifier. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The file or stream will normally be closed when this object is - destructed (unless there are more objects that refer to the same - file through use of <code>assign</code> or <code>dup</code>). Objects do not contain - cyclic references in themselves, so they will be destructed timely - when they run out of references. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>sprintf()</code>, <code>lfun::_sprintf()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + __HAVE_SPRINTF_STAR_MAPPING__ + </dt> + <dd><code><code class='datatype'>constant</code> <code class='datatype'>int</code> String.<code class='constant'>__HAVE_SPRINTF_STAR_MAPPING__</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Presence of this symbol indicates that <code>sprintf()</code> supports + mappings for the <tt>'*'</tt>-modifier syntax. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.FILE</code> + <dd class='body--doc'><code>sprintf()</code>, <code>lfun::_sprintf()</code> </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - assign + capitalize </dt> - <dd><code><code class='datatype'>int</code> assign(<code class='object unresolved'>File</code>|<code class='object unresolved'>Fd</code> <code class='argument'>o</code>)</code></dd> + <dd><code><code class='datatype'>string</code> capitalize(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function takes a clone of Stdio.File and assigns all - variables of this file from it. It can be used together with <code>dup()</code> - to move files around. + <dd class='body--doc'>Convert the first character in <code>str</code> to upper case, and return the + new string. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>dup()</code> + <dd class='body--doc'><code>lower_case()</code>, <code>upper_case()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - async_connect + common_prefix </dt> - <dd><code><code class='datatype'>int</code> async_connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>void</code>) <code class='argument'>callback</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> + <dd><code><code class='datatype'>string</code> common_prefix(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>strs</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a TCP/IP connection asynchronously. - This function is similar to <code>connect()</code>, but works asynchronously. + <dd class='body--doc'>Find the longest common prefix from an array of strings. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + count + </dt> + <dd><code><code class='datatype'>int</code> count(<code class='datatype'>string</code> <code class='argument'>haystack</code>, <code class='datatype'>string</code> <code class='argument'>needle</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Count the number of non-overlapping times the string <code>needle</code> + occurs in the string <code>haystack</code>. The special cases for the needle + <code class='expr'>""</code> is that it occurs one time in the empty string, zero + times in a one character string and between every character + (length-1) in any other string. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>host</code></dt> - <dd></dd><dd class='body--doc'>Hostname or IP to connect to. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>search()</code>, <code>`/()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + expand_tabs + </dt> + <dd><code><code class='datatype'>string</code> expand_tabs(<code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>tab_width</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>substitute_tab</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>substitute_space</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>substitute_newline</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Expands tabs in a string to ordinary spaces, according to common + tabulation rules. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + fuzzymatch + </dt> + <dd><code><code class='datatype'>int(0..100)</code> fuzzymatch(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function compares two strings using a fuzzy matching + routine. The higher the resulting value, the better the strings match. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> - <dd></dd><dd class='body--doc'>Port number or service name to connect to. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>callback</code></dt> - <dd></dd><dd class='body--doc'>Function to be called on completion. - The first argument will be <code class='expr'>1</code> if a connection was - successfully established, and <code class='expr'>0</code> (zero) on failure. - The rest of the arguments to <code>callback</code> are passed - verbatim from <code>args</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>args</code></dt> - <dd></dd><dd class='body--doc'>Extra arguments to pass to <code>callback</code>. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>0</code> on failure to open a socket, and <code class='expr'>1</code> - if <code>callback</code> will be used. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The socket may be opened with <code>open_socket()</code> ahead of - the call to this function, but it is not required. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This object is put in callback mode by this function. For - <code>callback</code> to be called, the backend must be active. See e.g. - <code>set_read_callback</code> for more details about backends and - callback mode. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The socket will be in nonblocking state if the connection is - successful, and any callbacks will be cleared. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>connect()</code>, <code>open_socket()</code>, <code>set_nonblocking()</code> + <dd class='body--doc'><code>Array.diff()</code>, <code>Array.diff_compare_table()</code> + <code>Array.diff_longest_sequence()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - close + hex2string </dt> - <dd><code><code class='datatype'>int</code> close()</code> - <code><code class='datatype'>int</code> close(<code class='datatype'>string</code> <code class='argument'>direction</code>)</code></dd> + <dd><code><code class='datatype'>string(8bit)</code> hex2string(<code class='datatype'>string(8bit)</code> <code class='argument'>hex</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Close the file. Optionally, specify "r", "w" or "rw" to close just - the read, just the write or both read and write directions of the file - respectively. - An exception is thrown if an I/O error occurs. + <dd class='body--doc'>Convert a string of hexadecimal digits to binary + data. Non-hexadecimal characters will be ignored when between + tuples. Eg. "00 00" is ok, but "0 000" isn't. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Nonzero is returned if the file wasn't open in the specified - direction, zero otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function will not call the <tt>close_callback</tt>. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open</code>, <code>open_socket</code> + <dd class='body--doc'><code>string2hex()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - connect + implode_nicely </dt> - <dd><code><code class='modifier'>variant</code> <code class='datatype'>int</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>)</code> - <code><code class='modifier'>variant</code> <code class='datatype'>int</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>client</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>client_port</code>)</code> - <code><code class='modifier'>variant</code> <code class='datatype'>string</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>data</code>)</code> - <code><code class='modifier'>variant</code> <code class='datatype'>string</code> connect(<code class='datatype'>string</code> <code class='argument'>host</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>int(0..0)</code>|<code class='datatype'>string</code> <code class='argument'>client</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>string</code> <code class='argument'>client_port</code>, <code class='datatype'>string</code> <code class='argument'>data</code>)</code></dd> + <dd><code><code class='datatype'>string</code> implode_nicely(<code class='datatype'>array</code>(<code class='datatype'>string</code>|<code class='datatype'>int</code>|<code class='datatype'>float</code>) <code class='argument'>foo</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>separator</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a TCP/IP connection to the specified destination. - In nonblocking mode, success is indicated with the write-callback, - and failure with the close-callback or the read_oob-callback. - The <code>host</code> argument is the hostname or IP number of the remote - machine. - A local IP and port can be explicitly bound by specifying - <code>client</code> and <code>client_port</code>. - If the <code>data</code> argument is included the socket will use - TCP_FAST_OPEN if posible. In this mode the the function will - return the part of the data that has not been sent to the remote - server yet instead of 1 (you will have to use <code>write</code> to send - this data). - Note that TCP_FAST_OPEN requires server support, the connection - might fail even though the remote server exists. It might be - advisable to retry without TCP_FAST_OPEN (and remember this - fact) + <dd class='body--doc'>This function implodes a list of words to a readable string, e.g. + <code class='expr'>({"straw","berry","pie"})</code> becomes + <code class='expr'>"straw, berry and pie"</code>. If the separator is omitted, the + default is <code class='expr'>"and"</code>. If the words are numbers they are + converted to strings first. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns 1 or the remaining <code>data</code> for success, 0 - otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In nonblocking mode <code class='expr'>0</code> (zero) may be returned and - <code>errno()</code> set to <code class='expr'>EWOULDBLOCK</code> or <code class='expr'>WSAEWOULDBLOCK</code>. - This should not be regarded as a - connection failure. In nonblocking mode you need to wait for a - write or close callback before you know if the connection failed - or not. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_address()</code>, <code>async_connect()</code>, <code>connect_unix()</code> + <dd class='body--doc'><code>`*()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - connect_unix + int2char </dt> - <dd><code><code class='datatype'>int</code> connect_unix(<code class='datatype'>string</code> <code class='argument'>path</code>)</code></dd> + <dd><code><code class='datatype'>string</code> int2char(<code class='datatype'>int</code> <code class='argument'>x</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a UNIX domain socket connection to the specified destination. + <dd class='body--doc'>Same as sprintf("%c",x); </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, and <code class='expr'>0</code> on failure. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Nonblocking mode is not supported while connecting + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>sprintf()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + int2hex </dt> - <dd><code>Stdio.File Stdio.File()</code> - <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code> - <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code> - <code>Stdio.File Stdio.File(<code class='datatype'>string</code> <code class='argument'>descriptorname</code>)</code> - <code>Stdio.File Stdio.File(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code> - <code>Stdio.File Stdio.File(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + <dd><code><code class='datatype'>string</code> int2hex(<code class='datatype'>int</code> <code class='argument'>x</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>There are four basic ways to create a Stdio.File object. - The first is calling it without any arguments, in which case the you'd - have to call <code>open()</code>, <code>connect()</code> or some other method which connects - the File object with a stream. - The second way is calling it with a <code>filename</code> and open <code>mode</code>. This is - the same thing as cloning and then calling <code>open()</code>, except shorter and - faster. - The third way is to call it with <code>descriptorname</code> of <code class='expr'>"stdin"</code>, - <code class='expr'>"stdout"</code> or <code class='expr'>"stderr"</code>. This will open the specified - standard stream. - For the advanced users, you can use the file descriptors of the - systems (note: emulated by pike on some systems - like NT). This is - only useful for streaming purposes on unix systems. This is not - recommended at all if you don't know what you're into. Default - <code>mode</code> for this is <code class='expr'>"rw"</code>. + <dd class='body--doc'>Same as <code class='expr'>sprintf("%x",x);</code>, i.e. returns the integer <code>x</code> in + hexadecimal base using lower cased symbols. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Open mode will be filtered through the system UMASK. You - might need to use <code>chmod()</code> later. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open()</code>, <code>connect()</code>, <code>Stdio.FILE</code>, + <dd class='body--doc'><code>sprintf()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - dup + int2roman </dt> - <dd><code><code class='object unresolved'>File</code> dup()</code></dd> + <dd><code><code class='datatype'>string</code> int2roman(<code class='datatype'>int</code> <code class='argument'>m</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function returns a clone of Stdio.File with all variables - copied from this file. + <dd class='body--doc'>Converts the provided integer to a roman integer (i.e. a string). </dd> - + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>Throws an error if <code>m</code> is outside the range 0 to 10000. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + int2size + </dt> + <dd><code><code class='datatype'>string</code> int2size(<code class='datatype'>int</code> <code class='argument'>size</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the size as a memory size string with suffix, + e.g. 43210 is converted into "42.2 kB". To be correct + to the latest standards it should really read "42.2 KiB", + but we have chosen to keep the old notation for a while. + The function knows about the quantifiers kilo, mega, giga, + tera, peta, exa, zetta and yotta. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + levenshtein_distance + </dt> + <dd><code><code class='datatype'>int</code> levenshtein_distance(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function calculates the Levenshtein distance between two strings a + and b. The Levenshtein distance describes the minimal number of character + additions, removals or substitutions to apply to convert a to b. + Mathematically, the Levenshtein distance between two strings a, b is given + by lev_a,b(|a|,|b|) where + lev_a,b(i, j) == max(i, j), if min(i, j) == 0 + lev_a,b(i, j) == min( lev_a,b(i, j-1)+1, + lev_a,b(i-1, j)+1, + lev_a,b(i-1, j-1) + a_i!=b_j ), else + Note that the first element in the minimum corresponds to inserting a + character to a (or deleting a character from b), the second to deleting a + character from a and the third to match or mismatch, depending on whether + the respective characters are equal. + Example: For example, the Levenshtein distance between "pike" and + "bikes" is 2, since the following two edits change one into the other, + and there is no way to do it with fewer than two edits: + - "pike" -> "bike" (substitute "p" with "b") + - "bike" -> "bikes" (add "s" at the end) + Note that the cost to compute the Levenshtein distance is roughly + proportional to the product of the two string lengths. So this function + is usually used to aid in fuzzy string matching, when at least one of the + strings is short. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + normalize_space + </dt> + <dd><code><code class='datatype'>string</code> normalize_space(<code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>whitespace</code>)</code></dd> + + <dt class='head--doc'>Parameter <code class='parameter'>s</code></dt> + <dd></dd><dd class='body--doc'>Is returned after white space in it has been normalised. + White space is normalised by stripping leading and trailing white space + and replacing sequences of white space characters with a single space. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>whitespace</code></dt> + <dd></dd><dd class='body--doc'>Defines what is considered to be white space eligible for normalisation. + It has a default value that starts with <code class='expr'>" \t\r\n\v\f"</code> and in + addition to that contains all whitespace characters part of Unicode. + The first character denotes the character for replacing whitespace + sequences. + </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>All variables, even <tt>id</tt>, are copied. + <dd class='body--doc'>Trailing and leading whitespace around \r and \n characters + is stripped as well (only useful if they're not in the <code>whitespace</code> set). </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>assign()</code> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function is a lot faster with just one argument (i.e. the builtin + whitespace set has an optimised code path). </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - errno + range </dt> - <dd><code><code class='datatype'>int</code> errno()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) range(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the error code for the last command on this file. - Error code is normally cleared when a command is successful. + <dd class='body--doc'>Returns the character range of a string in an array of two + elements. The first element contains the lower bound and the + second the upper. The precision is only 8 bits, so for wide + strings only character blocks are known. </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Inherit - Fd + <dt class='head--type'>Method + secure </dt> - <dd><code><code class='modifier'>optional</code> inherit Fd : Fd</code></dd> - </dl> + <dd><code><code class='datatype'>string</code> secure(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Marks the string as secure, which will clear the memory area + before freeing the string. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Object.secure()</code> + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - line_iterator + sillycaps </dt> - <dd><code><code class='object unresolved'>String.SplitIterator</code>|<code class='object unresolved'>LineIterator</code> line_iterator(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>trim</code>)</code></dd> + <dd><code><code class='datatype'>string</code> sillycaps(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an iterator that will loop over the lines in this file. - If trim is true, all <tt>'\r'</tt> characters will be removed from - the input. + <dd class='body--doc'>Convert the first character in each word (separated by spaces) in + <code>str</code> to upper case, and return the new string. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - open + soundex </dt> - <dd><code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='datatype'>int</code> open(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code></dd> + <dd><code><code class='datatype'>string</code> soundex(<code class='datatype'>string</code> <code class='argument'>word</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a file for read, write or append. The parameter <code>mode</code> should - contain one or more of the following letters: - <table class='box'><tr><td><code><code class='key'>"r"</code></code></td><td>Open file for reading. - </td></tr> - <tr><td><code><code class='key'>"w"</code></code></td><td>Open file for writing. - </td></tr> - <tr><td><code><code class='key'>"a"</code></code></td><td>Open file for append (use with <code class='expr'>"w"</code>). - </td></tr> - <tr><td><code><code class='key'>"t"</code></code></td><td>Truncate file at open (use with <code class='expr'>"w"</code>). - </td></tr> - <tr><td><code><code class='key'>"c"</code></code></td><td>Create file if it doesn't exist (use with <code class='expr'>"w"</code>). - </td></tr> - <tr><td><code><code class='key'>"x"</code></code></td><td>Fail if file already exists (use with <code class='expr'>"c"</code>). - </td></tr> - </table><code>mode</code> should always contain at least one of the letters - <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. - The parameter <code>mask</code> is protection bits to use if the file is - created. Default is <code class='expr'>0666</code> (read+write for all in octal - notation). + <dd class='body--doc'>Returns the soundex value of <code>word</code> according to + the original Soundex algorithm, patented by Margaret O´Dell + and Robert C. Russel in 1918. The method is based on the phonetic + classification of sounds by how they are made. It was only intended + for hashing of english surnames, and even at that it isn't that + much of a help. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + status + </dt> + <dd><code><code class='datatype'>string</code> status(<code class='datatype'>int</code> <code class='argument'>verbose</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Get string table statistics. </dd> <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns <code class='expr'>1</code> for success, <code class='expr'>0</code> otherwise. + <dd class='body--doc'>Returns a string with an ASCII table containing + the current string table statistics. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>close()</code>, <code>create()</code> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Currently returns the empty string (<code class='expr'>""</code>) + if <code>verbose</code> is zero. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The formatting and contents of the result + may vary between different versions of Pike. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - open_socket + string2hex </dt> - <dd><code><code class='datatype'>int</code> open_socket(<code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>address</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>family_hint</code>)</code></dd> + <dd><code><code class='datatype'>string</code> string2hex(<code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>uppercase</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This makes this file into a socket ready for connections. The reason - for this function is so that you can set the socket to nonblocking - or blocking (default is blocking) before you call <code>connect()</code>. + <dd class='body--doc'>Convert a string of binary data to a hexadecimal string. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> - <dd></dd><dd class='body--doc'>If you give a port number to this function, the socket will be - bound to this port locally before connecting anywhere. This is - only useful for some silly protocols like FTP. The port can - also be specified as a string, giving the name of the service - associated with the port. Pass -1 to not specify a port (eg to - bind only to an address). + <dt class='head--doc'>Parameter <code class='parameter'>uppercase</code></dt> + <dd></dd><dd class='body--doc'>If set, the string will use upper cased characters. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> - <dd></dd><dd class='body--doc'>You may specify an address to bind to if your machine has many IP - numbers. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>family_hint</code></dt> - <dd></dd><dd class='body--doc'>A protocol family for the socket can be specified. If no family is - specified, one which is appropriate for the address is automatically - selected. Thus, there is normally no need to specify it. If you - do not want to specify a bind address, you can provide the address - as a hint here instead, to allow the automatic selection to work - anyway. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns 1 for success, 0 otherwise. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>connect()</code>, <code>set_nonblocking()</code>, <code>set_blocking()</code> + <dd class='body--doc'><code>hex2string()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - openat + trim </dt> - <dd><code><code class='object unresolved'>File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='object unresolved'>File</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code></dd> + <dd><code><code class='datatype'>string</code> trim(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open a file relative to an open directory. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>File.statat()</code>, <code>File.unlinkat()</code> + <dd class='body--doc'>Trim leading and trailing white spaces characters (space, tab, + newline, carriage return, form feed, vertical tab and all the + white spaces defined in Unicode) from the string <code>s</code>. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - openpt + trim_whites </dt> - <dd><code><code class='datatype'>int</code> openpt(<code class='datatype'>string</code> <code class='argument'>mode</code>)</code></dd> + <dd><code><code class='datatype'>string</code> trim_whites(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Open the master end of a pseudo-terminal pair. The parameter - <code>mode</code> should contain one or more of the following letters: - <table class='box'><tr><td><code><code class='key'>"r"</code></code></td><td>Open terminal for reading. - </td></tr> - <tr><td><code><code class='key'>"w"</code></code></td><td>Open terminal for writing. - </td></tr> - </table><code>mode</code> should always contain at least one of the letters - <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>grantpt()</code> + <dd class='body--doc'>Trim leading and trailing spaces and tabs from the string <code>s</code>. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - pipe + width </dt> - <dd><code><code class='object unresolved'>File</code> pipe(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>required_properties</code>)</code></dd> + <dd><code><code class='datatype'>int(8..8)</code>|<code class='datatype'>int(16..16)</code>|<code class='datatype'>int(32..32)</code> width(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function creates a pipe between the object it was called in - and an object that is returned. + <dd class='body--doc'>Returns the width of a string. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>required_properties</code></dt> - <dd></dd><dd class='body--doc'>Binary or (<code>predef::`|()</code>) of required <code class='expr'>PROP_</code> properties. - <table class='box'><tr><td><code><code class='key'>PROP_IPC</code></code></td><td>The resulting pipe may be used for inter process communication. + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Three return values are currently possible: + <table class='box'><tr><td><code><code class='key'>8</code></code></td><td>The string <code>s</code> only contains characters <= 255. </td></tr> - <tr><td><code><code class='key'>PROP_NONBLOCK</code></code></td><td>The resulting pipe supports nonblocking I/O. + <tr><td><code><code class='key'>16</code></code></td><td>The string <code>s</code> only contains characters <= 65535. </td></tr> - <tr><td><code><code class='key'>PROP_SHUTDOWN</code></code></td><td>The resulting pipe supports shutting down transmission in either - direction (see <code>close()</code>). + <tr><td><code><code class='key'>32</code></code></td><td>The string <code>s</code> contains characters >= 65536. </td></tr> - <tr><td><code><code class='key'>PROP_BUFFERED</code></code></td><td>The resulting pipe is buffered (usually 4KB). - </td></tr> - <tr><td><code><code class='key'>PROP_BIDIRECTIONAL</code></code></td><td>The resulting pipe is bi-directional. - </td></tr> - <tr><td><code><code class='key'>PROP_SEND_FD</code></code></td><td>The resulting pipe might support sending of file descriptors - (see <code>send_fd()</code> and <code>receive_fd()</code> for details). - </td></tr> - <tr><td><code><code class='key'>PROP_REVERSE</code></code></td><td>The resulting pipe supports communication "backwards" (but - not necessarily "forwards", see <code>PROP_BIDIRECTIONAL</code>). - </td></tr> - </table>The default is <code class='expr'>PROP_NONBLOCK|PROP_BIDIRECTIONAL</code>. - If <code>PROP_BIDIRECTIONAL</code> isn't specified, the read-end is this - object, and the write-end is the returned object (unless - <code>PROP_REVERSE</code> has been specified, in which case it is the other - way around). - The two ends of a bi-directional pipe are indistinguishable. - If the File object this function is called in was open to begin with, - it will be closed before the pipe is created. + </table> </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Calling this function with an argument of <tt>0</tt> is not the - same as calling it with no arguments. + <dd class='body--doc'>It is possible that a future version of Pike may return + further values. In particular the width <code class='expr'>7</code> seems + like it could be useful. + </dd></dl> + <dl><dt><h2 class='header'>Class String.Bootstring</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This class implements the "Bootstring" string transcoder described in + <a href='ftp://ftp.rfc-editor.org/in-notes/rfc3492.txt'>ftp://ftp.rfc-editor.org/in-notes/rfc3492.txt</a>. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>String.Bootstring String.Bootstring(<code class='datatype'>int</code> <code class='argument'>base</code>, <code class='datatype'>int</code> <code class='argument'>tmin</code>, <code class='datatype'>int</code> <code class='argument'>tmax</code>, <code class='datatype'>int</code> <code class='argument'>skew</code>, <code class='datatype'>int</code> <code class='argument'>damp</code>, <code class='datatype'>int</code> <code class='argument'>initial_bias</code>, <code class='datatype'>int</code> <code class='argument'>initial_n</code>, <code class='datatype'>int</code> <code class='argument'>delim</code>, <code class='datatype'>string</code> <code class='argument'>digits</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Creates a Bootstring transcoder instance using the specified parameters. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Process.create_process()</code>, <code>send_fd()</code>, <code>receive_fd()</code>, - <code>PROP_IPC</code>, <code>PROP_NONBLOCK</code>, <code>PROP_SEND_FD</code>, - <code>PROP_SHUTDOWN</code>, <code>PROP_BUFFERED</code>, <code>PROP_REVERSE</code>, - <code>PROP_BIDIRECTIONAL</code> + <dt class='head--doc'>Parameter <code class='parameter'>base</code></dt> + <dd></dd><dd class='body--doc'>The base used by the variable-length integers. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>tmin</code></dt> + <dd></dd><dd class='body--doc'>The minimum threshold digit value for the variable-length integers. + Must be >=0 and <= tmax. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>tmax</code></dt> + <dd></dd><dd class='body--doc'>The maximum threshold digit value for the variable-length integers. + Must be <= base-1. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>skew</code></dt> + <dd></dd><dd class='body--doc'>The skew term for the bias adapation. Must be >= 1. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>damp</code></dt> + <dd></dd><dd class='body--doc'>The damping factor for the bias adaption. Must be >= 2. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>initial_bias</code></dt> + <dd></dd><dd class='body--doc'>The initial bias for the variable-length integer thresholding. + initial_bias % base must be <= base - tmin. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>initial_n</code></dt> + <dd></dd><dd class='body--doc'>The first code point outside the "basic" set of code points. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>delim</code></dt> + <dd></dd><dd class='body--doc'>The "basic" code point used as the delimiter. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>digits</code></dt> + <dd></dd><dd class='body--doc'>The "basic" code points used as digits. The length of the string + should be the same as the base parameter. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_buffer_mode + decode </dt> - <dd><code><code class='datatype'>array</code>(<code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code>) query_buffer_mode()</code></dd> + <dd><code><code class='datatype'>string</code> decode(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the active input and output buffers that have been - set with <code>set_buffer_mode()</code> (if any). + <dd class='body--doc'>Decodes a Bootstring encoded string of "basic" code points back + to the original string space. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + encode + </dt> + <dd><code><code class='datatype'>string</code> encode(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Encodes a string using Bootstring encoding into a string constisting + only of "basic" code points (< initial_n). + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class String.Buffer</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>A buffer, used for building strings. It's + conceptually similar to a string, but you can only <code>add</code> + strings to it, and you can only <code>get</code> the value from it once. + There is a reason for those seemingly rather odd limitations, + it makes it possible to do some optimizations that really speed + things up. + You do not need to use this class unless you add very many + strings together, or very large strings. </dd> - + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>For the fastest possible operation, write your code like this: + <pre><code>String.Buffer b = String.Buffer( ); + + function add = b->add; + + .. call add several times in code ... + + string result = b->get(); // also clears the buffer + </code></pre></pre></dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _search + </dt> + <dd><code><code class='datatype'>int(0..)</code> search(String.Buffer from, <code class='datatype'>int</code> <code class='argument'>character</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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Search for a <code>character</code> in the buffer, starting the scan + from <code>start</code> and ending at <code>end</code> (inclusive). + </dd> <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns an array with two elements: - <table class='box'><tr><td colspan='2'>Array</td></tr> - <tr><td><code><code class='object unresolved'>Stdio.Buffer</code> <code class='key'>0</code></code></td><td>The current input buffer. - </td></tr> - <tr><td><code><code class='object unresolved'>Stdio.Buffer</code> <code class='key'>1</code></code></td><td>The current output buffer. - </td></tr> - </table> + <dd class='body--doc'>Returns to position in the buffer where the character was found + on success, and <code>UNDEFINED</code> on failure. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_buffer_mode()</code> + <dd class='body--doc'><code>Stdio.Buffer()->_search()</code>, <code>search()</code>, <code>lfun::_search()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_read_callback - Method - query_write_callback - Method - query_read_oob_callback - Method - query_write_oob_callback - Method - query_close_callback - Method - query_callbacks + _search </dt> - <dd><code><code class='object unresolved'>read_callback_t</code> query_read_callback()</code> - <code><code class='object unresolved'>write_callback_t</code> query_write_callback()</code> - <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) query_read_oob_callback()</code> - <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) query_write_oob_callback()</code> - <code><code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) query_close_callback()</code> - <code><code class='datatype'>array</code>(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code>:<code class='datatype'>int</code>)) query_callbacks()</code></dd> + <dd><code><code class='datatype'>int(0..)</code> search(String.Buffer from, <code class='datatype'>string</code> <code class='argument'>substring</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>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>These functions return the currently installed callbacks for the - respective events. - <code>query_callbacks</code> returns the callbacks in the same order as - <code>set_callbacks</code> and <code>set_nonblocking</code> expect them. + <dd class='body--doc'>Search for a <code>substring</code> in the buffer, starting the scan + from <code>start</code> and ending at <code>end</code> (inclusive). </dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns to position in the buffer where the substring was found + on success, and <code>UNDEFINED</code> on failure. + </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_nonblocking()</code>, <code>set_read_callback</code>, - <code>set_write_callback</code>, <code>set_read_oob_callback</code>, - <code>set_write_oob_callback</code>, <code>set_close_callback</code>, - <code>set_callbacks</code> + <dd class='body--doc'><code>Stdio.Buffer()->_search()</code>, <code>search()</code>, <code>lfun::_search()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_id + _sizeof </dt> - <dd><code><code class='datatype'>mixed</code> query_id()</code></dd> + <dd><code><code class='datatype'>int</code> sizeof( String.Buffer arg )</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function returns the <tt>id</tt> that has been set with <code>set_id()</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_id()</code> + <dd class='body--doc'>Returns the size of the buffer. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - read + _sprintf </dt> - <dd><code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>, <code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code>)</code></dd> + <dd><code>string sprintf(string format, ... String.Buffer arg ... )</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read (optionally buffered) data from a file or a stream. - Proxy function for <code>Fd::read()</code>, that adds support for - the buffering configured by <code>set_buffer_mode()</code> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read_function()</code>, <code>write()</code>, <code>Fd::read()</code> + <dd class='body--doc'>It is possible to <code>sprintf</code> a String.Buffer object + as <tt>%s</tt> just as if it was a string. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - read_function + `+ </dt> - <dd><code><code class='datatype'>function</code>(:<code class='datatype'>string</code>) read_function(<code class='datatype'>int</code> <code class='argument'>nbytes</code>)</code></dd> + <dd><code><code class='object unresolved'>String.Buffer</code> res = <code class='class'>String.Buffer()</code> + <code class='class'>what</code></code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + `+= + </dt> + <dd><code><code class='class'>String.Buffer()</code> += <code class='class'>what</code></code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add + </dt> + <dd><code><code class='datatype'>int</code> add(<code class='datatype'>string</code>|<code class='object unresolved'>String.Buffer</code> ... <code class='argument'>data</code>)</code></dd> + <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns a function that when called will call <code>read</code> with - nbytes as argument. Can be used to get various callback - functions, eg for the fourth argument to - <code>String.SplitIterator</code>. + <dd class='body--doc'>Adds <code>data</code> to the buffer. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the size of the buffer. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Pike 7.8 and earlier did not support adding <code>String.Buffer</code>s + directly. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - send_fd + cast </dt> - <dd><code><code class='datatype'>void</code> send_fd(<code class='object unresolved'>File</code>|<code class='object unresolved'>Fd</code> <code class='argument'>file</code>)</code></dd> - </dl> + <dd><code>(int)String.Buffer() (float)String.Buffer() (string)String.Buffer() (array)String.Buffer() (mapping)String.Buffer() (multiset)String.Buffer()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>It is possible to cast a String.Buffer object to + a <code class='expr'>string</code> and an <code class='expr'>int</code>. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_blocking + clear </dt> - <dd><code><code class='datatype'>void</code> set_blocking()</code></dd> + <dd><code><code class='datatype'>void</code> clear()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function clears all callbacks and sets a stream to blocking - mode. i.e. reading, writing and closing will wait until data has - been transferred before returning. + <dd class='body--doc'>Empty the buffer, and don't care about the old content. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The callbacks are cleared and blocking mode is set in one atomic - operation, so no callback gets called in between if the backend - is running in another thread. - Even so, if the stream is in callback mode (i.e. if any - callbacks are installed) then only the backend thread can use - this function reliably; it might otherwise already be running in - a callback which is about to call e.g. <code>write</code> when the stream - becomes blocking. + <dd class='body--doc'>This function was not available in Pike 7.8 and earlier. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_nonblocking()</code>, <code>set_nonblocking_keep_callbacks()</code>, - <code>set_blocking_keep_callbacks()</code> + <dd class='body--doc'><code>get()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_nonblocking_keep_callbacks - Method - set_blocking_keep_callbacks + create </dt> - <dd><code><code class='datatype'>void</code> set_nonblocking_keep_callbacks()</code> - <code><code class='datatype'>void</code> set_blocking_keep_callbacks()</code></dd> + <dd><code>String.Buffer String.Buffer(<code class='datatype'>int</code> <code class='argument'>initial_size</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Toggle between blocking and nonblocking, - without changing the callbacks. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_nonblocking()</code>, <code>set_blocking()</code> + <dd class='body--doc'>Initializes a new buffer. + If no <code>initial_size</code> is specified, 256 is used. If you + know approximately how big the buffer will be, you can optimize + the operation of <code>add()</code> (slightly) by passing the size to this + function. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_buffer_mode + get </dt> - <dd><code><code class='datatype'>void</code> set_buffer_mode(<code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>in</code>, <code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>out</code>)</code></dd> + <dd><code><code class='datatype'>string</code> get()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Toggle the file to Buffer mode. - In this mode reading and writing will be done via Buffer - objects, in the directions you included buffers. + <dd class='body--doc'>Get the data from the buffer. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>in</code></dt> - <dd></dd><dd class='body--doc'>Input buffer. If this buffer is non-empty, its contents - will be returned after any already received data. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>out</code></dt> - <dd></dd><dd class='body--doc'>Output buffer. If this buffer is non-empty, its contents - will be sent after any data already queued for sending. - </dd> + <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Normally you call <code>write</code> to re-trigger the write callback if - you do not output anything in it (which will stop it from - re-occuring again). - This will work with buffered output mode as well, but simply - adding more data to the output buffer will work as well. + <dd class='body--doc'>This will clear the data in the buffer </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_buffer_mode()</code> + <dd class='body--doc'><code>get_copy()</code>, <code>clear()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_callbacks + get_copy </dt> - <dd><code><code class='datatype'>void</code> set_callbacks(<code class='object unresolved'>read_callback_t</code>|<code class='datatype'>void</code> <code class='argument'>read_cb</code>, <code class='object unresolved'>write_callback_t</code>|<code class='datatype'>void</code> <code class='argument'>write_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code>)</code></dd> + <dd><code><code class='datatype'>string</code> get_copy()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Installs all the specified callbacks at once. Use <code>UNDEFINED</code> - to keep the current setting for a callback. - Like <code>set_nonblocking</code>, the callbacks are installed atomically. - As opposed to <code>set_nonblocking</code>, this function does not do - anything with the stream, and it doesn't even have to be open. + <dd class='body--doc'>Get the data from the buffer. Significantly slower than <code>get</code>, + but does not clear the buffer. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_read_callback</code>, <code>set_write_callback</code>, - <code>set_read_oob_callback</code>, <code>set_write_oob_callback</code>, - <code>set_close_callback</code>, <code>query_callbacks</code> + <dd class='body--doc'><code>get()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_read_callback - Method - set_write_callback - Method - set_read_oob_callback - Method - set_write_oob_callback - Method - set_close_callback - Method - set_fs_event_callback + putchar </dt> - <dd><code><code class='datatype'>void</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>)</code> - <code><code class='datatype'>void</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>)</code> - <code><code class='datatype'>void</code> set_write_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>)</code> - <code><code class='datatype'>void</code> set_write_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>)</code> - <code><code class='datatype'>void</code> set_read_oob_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code>)</code> - <code><code class='datatype'>void</code> set_write_oob_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code>)</code> - <code><code class='datatype'>void</code> set_close_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>)</code> - <code><code class='datatype'>void</code> set_fs_event_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>int</code>:<code class='datatype'>int</code>) <code class='argument'>fs_event_cb</code>, <code class='datatype'>int</code> <code class='argument'>event_mask</code>)</code></dd> + <dd><code><code class='datatype'>void</code> putchar(<code class='datatype'>int</code> <code class='argument'>c</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>These functions set the various callbacks, which will be called - when various events occur on the stream. A zero as argument will - remove the callback. - A <code>Pike.Backend</code> object is responsible for calling the - callbacks. It requires a thread to be waiting in it to execute - the calls. That means that only one of the callbacks will be - running at a time, so you don't need mutexes between them. - Unless you've specified otherwise with the <code>set_backend</code> - function, the default backend <code>Pike.DefaultBackend</code> will be - used. It's normally activated by returning <code class='expr'>-1</code> from the - <tt>main</tt> function and will then execute in the main thread. - <ul> - <li>When data arrives on the stream, <code>read_cb</code> will be called with - some or all of that data as the second argument. - If the file is in buffer mode, the second argument will be a Buffer. - This will always be the same buffer, so data you do not use in - one read callback can be simply left in the buffer, when new - data arrives it will be appended - </li><li>When the stream has buffer space over for writing, <code>write_cb</code> - will be called so that you can write more data to it. - This callback is also called after the remote end of a socket - connection has closed the write direction. An attempt to write - data to it in that case will generate a <code>System.EPIPE</code> errno. - If the remote end has closed both directions simultaneously - (the usual case), Pike will first attempt to call <code>close_cb</code>, - then this callback (unless <code>close_cb</code> has closed the stream). - If the file is in buffer mode, the second argument will be a Buffer. - You should add data to write to this buffer. - </li><li>When out-of-band data arrives on the stream, <code>read_oob_cb</code> - will be called with some or all of that data as the second - argument. - </li><li>When the stream allows out-of-band data to be sent, - <code>write_oob_cb</code> will be called so that you can write more - out-of-band data to it. - If the OS doesn't separate the write events for normal and - out-of-band data, Pike will try to call <code>write_oob_cb</code> first. - If it doesn't write anything, then <code>write_cb</code> will be tried. - This also means that <code>write_oob_cb</code> might get called when the - remote end of a connection has closed the write direction. - </li><li>When an error or an end-of-stream in the read direction - occurs, <code>close_cb</code> will be called. <code>errno</code> will return the - error, or zero in the case of an end-of-stream. - The name of this callback is rather unfortunate since it - really has nothing to do with a close: The stream is still - open when <code>close_cb</code> is called (you might not be able to read - and/or write to it, but you can still use things like - <code>query_address</code>, and the underlying file descriptor is still - allocated). Also, this callback will not be called for a local - close, neither by a call to <code>close</code> or by destructing this - object. - Also, <code>close_cb</code> will not be called if a remote close only - occurs in the write direction; that is handled by <code>write_cb</code> - (or possibly <code>write_oob_cb</code>). - Events to <code>read_cb</code> and <code>close_cb</code> will be automatically - deregistered if an end-of-stream occurs, and all events in the - case of an error. I.e. there won't be any more calls to the - callbacks unless they are reinstalled. This doesn't affect the - callback settings - <code>query_read_callback</code> et al will still - return the installed callbacks. - </li></ul>If the stream is a socket performing a nonblocking connect (see - <code>open_socket</code> and <code>connect</code>), a connection failure will call - <code>close_cb</code>, and a successful connect will call either - <code>read_cb</code> or <code>write_cb</code> as above. - All callbacks will receive the <tt>id</tt> set by <code>set_id</code> as - first argument. - If a callback returns <code class='expr'>-1</code>, no other callback or call out - will be called by the backend in that round. I.e. the caller of - the backend will get control back right away. For the default - backend that means it will immediately start another round and - check files and call outs anew. + <dd class='body--doc'>Appends the character <code>c</code> at the end of the string. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + sprintf + </dt> + <dd><code><code class='datatype'>int</code> sprintf(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Appends the output from <code>sprintf</code> at the end of the string. + Returns the resulting size of the String.Buffer. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class String.Iterator</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when + called with a string. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>event_mask</code></dt> - <dd></dd><dd class='body--doc'>An event mask specifing bitwise OR of one or more event types to - monitor, selected from <code>Stdio.NOTE_WRITE</code> and friends. - </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_iterator</code> + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + predef::Iterator + </dt> + <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class String.Replace</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This is a "compiled" version of the <code>replace</code> function applied on + a string, with more than one replace string. The replace strings + are given to the create method as a from and to array + and are then analyzed. The <code class='expr'>`()</code> is then called with a + string and the replace rules in the Replace object will be + applied. The Replace object is used internally by the Pike + optimizer and need not be used manually. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _decode + </dt> + <dd><code>String.Replace decode_value(string(8bit) data)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _encode + </dt> + <dd><code>string(8bit) encode_value(String.Replace data)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + `() + </dt> + <dd><code><code class='datatype'>string</code> res = <code class='class'>String.Replace()</code>()</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>String.Replace String.Replace()</code> + <code>String.Replace String.Replace(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>))</code> + <code>String.Replace String.Replace(<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='datatype'>string</code> <code class='argument'>to</code>)</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class String.SingleReplace</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This is a "compiled" version of the <code>replace</code> function applied on + a string, with just one replace string. The replace strings are + given to the create method as a from and tom string and + are then analyzed. The <code class='expr'>`()</code> is then called with a string + and the replace rule in the Replace object will be applied. The + Replace object is used internally by the Pike optimizer and need + not be used manually. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _decode + </dt> + <dd><code>String.SingleReplace decode_value(string(8bit) data)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _encode + </dt> + <dd><code>string(8bit) encode_value(String.SingleReplace data)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + `() + </dt> + <dd><code><code class='datatype'>string</code> res = <code class='class'>String.SingleReplace()</code>()</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>String.SingleReplace String.SingleReplace(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>from</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>to</code>)</code></dd> + <dt class='head--doc'>Note</dt> - <dd class='body--doc'>These functions do not set the file nonblocking. + <dd class='body--doc'>May be called with either zero or two arguments. + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class String.SplitIterator</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>An iterator that iterates over substrings of a string, separated + by a character or several different characters. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Callbacks are also set by <code>set_callbacks</code> and - <code>set_nonblocking()</code>. + <dd class='body--doc'>Typically you don't need to explicitly use the SplitIterator. + Expressions like the following are automatically optimized into + using a SplitIterator. + <pre><code>foreach(str/"\n", string line) + write("%s\n", line); + </code></pre></dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>String.SplitIterator String.SplitIterator(<code class='datatype'>string</code> <code class='argument'>buffer</code>, <code class='datatype'>int</code>|<code class='datatype'>array</code>(<code class='datatype'>int</code>)|<code class='datatype'>multiset</code>(<code class='datatype'>int</code>) <code class='argument'>split_set</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>flags</code>, <code class='datatype'>function</code>(:<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>feed</code>)</code></dd> + + <dt class='head--doc'>Parameter <code class='parameter'>buffer</code></dt> + <dd></dd><dd class='body--doc'>The string to split. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>After a callback has been called, it's disabled until it has - accessed the stream accordingly, i.e. the <code>write_cb</code> callback - is disabled after it's been called until something has been - written with <code>write</code>, and the <code>write_oob_cb</code> callback is - likewise disabled until something has been written with - <code>write_oob</code>. Since the data already has been read when the read - callbacks are called, this effect is not noticeable for them. + <dt class='head--doc'>Parameter <code class='parameter'>split_set</code></dt> + <dd></dd><dd class='body--doc'>The character or characters to split on. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Installing callbacks means that you will start doing I/O on the - stream from the thread running the backend. If you are running - these set functions from another thread you must be prepared - that the callbacks can be called immediately by the backend - thread, so it might not be safe to continue using the stream in - this thread. - Because of that, it's useful to talk about "callback mode" when - any callback is installed. In callback mode the stream should be - seen as "bound" to the backend thread. For instance, it's only - the backend thread that reliably can end callback mode before - the stream is "handed over" to another thread. + <dt class='head--doc'>Parameter <code class='parameter'>flags</code></dt> + <dd></dd><dd class='body--doc'>Skip empty elements if set. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Callback mode has nothing to do with nonblocking mode - although - the two often are used together they don't have to be. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The file object will stay referenced from the backend object as - long as there are callbacks that can receive events. - </dd> - <dt class='head--doc'>Bugs</dt> - <dd class='body--doc'>Setting a close callback without a read callback currently only - works when there's no risk of getting more data on the stream. - Otherwise the close callback will be silently deregistered if - data arrives. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>fs_event callbacks only trigger on systems that support these events. - Currently, this includes systems that use kqueue, such as Mac OS X, - and various flavours of BSD. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_callbacks</code>, <code>set_nonblocking()</code>, <code>set_id()</code>, - <code>set_backend</code>, <code>query_read_callback</code>, <code>query_write_callback</code>, - <code>query_read_oob_callback</code>, <code>query_write_oob_callback</code>, - <code>query_close_callback</code> + <dt class='head--doc'>Parameter <code class='parameter'>feed</code></dt> + <dd></dd><dd class='body--doc'>Callback function that is called once the <code>buffer</code> is used up + and the SplitIterator wants more data. </dd></dl> <hr /> <dl class='group--doc'> - + <dt class='head--type'>Inherit + predef::Iterator + </dt> + <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Module String.Elite</h2> + </dt><dd> + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - set_id + elite_string </dt> - <dd><code><code class='datatype'>void</code> set_id(<code class='datatype'>mixed</code> <code class='argument'>id</code>)</code></dd> + <dd><code><code class='datatype'>string</code> elite_string(<code class='datatype'>string</code> <code class='argument'>in</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..100)</code> <code class='argument'>leetp</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>eightbit</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function sets the <tt>id</tt> of this file. The <tt>id</tt> is mainly - used as an identifier that is sent as the first argument to all - callbacks. The default <tt>id</tt> is <code class='expr'>0</code> (zero). Another possible - use of the <tt>id</tt> is to hold all data related to this file in a - mapping or array. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_id()</code> + <dd class='body--doc'>Translates a string to 1337. The optional + argument leetp is the maximum percentage of + leetness (100=max leet, 0=no leet). + The translation is performed in three steps, + first the neccesary elite translations (picture -> pic, + cool->kewl etc), then optional translations + (ok->k, dude->dood, -ers -> -orz), then + calls elite_word on the resulting words. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_nonblocking + elite_word </dt> - <dd><code><code class='datatype'>void</code> set_nonblocking(<code class='object unresolved'>read_callback_t</code> <code class='argument'>read_callback</code>, <code class='object unresolved'>write_callback_t</code> <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code>)</code> - <code><code class='datatype'>void</code> set_nonblocking(<code class='object unresolved'>read_callback_t</code> <code class='argument'>read_callback</code>, <code class='object unresolved'>write_callback_t</code> <code class='argument'>write_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_callback</code>, <code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_callback</code>)</code> - <code><code class='datatype'>void</code> set_nonblocking()</code></dd> + <dd><code><code class='datatype'>string</code> elite_word(<code class='datatype'>string</code> <code class='argument'>in</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..100)</code> <code class='argument'>leetp</code>, <code class='datatype'>void</code>|<code class='datatype'>int(0..2)</code> <code class='argument'>eightbit</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function sets a stream to nonblocking mode and installs the - specified callbacks. See the <code class='expr'>set_*_callback</code> functions - for details about them. If no arguments are given, the callbacks - will be cleared. + <dd class='body--doc'>Translates one word to 1337. The optional + argument leetp is the maximum percentage of + leetness (100=max leet, 0=no leet). + elite_word only do character-based translation, + for instance from "k" to "|<", but no language + translation (no "cool" to "kewl"). + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Module String.HTML</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Functions that helps generating HTML. All functions generates + HTML that is XHTML compliant as well as backwards compatible + with old HTML standards in what extent is possible. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + pad_rows + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) pad_rows(<code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <code class='argument'>rows</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>padding</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Pads out the rows in a array of rows to equal length. The new elements in + the rows will have the value provided in <code>padding</code>, or "&nbsp;". + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + select + </dt> + <dd><code><code class='datatype'>string</code> select(<code class='datatype'>string</code> <code class='argument'>name</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <code class='argument'>choices</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>selected</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Creates an HTML select list. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>As opposed to calling the set callback functions separately, - this function will set all the callbacks and nonblocking mode - atomically so that no callback gets called in between. That - avoids races in case the backend is executed by another thread. + <dt class='head--doc'>Parameter <code class='parameter'>name</code></dt> + <dd></dd><dd class='body--doc'>The name of the select list. Will be used in the name attribute + of the select element. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Out-of-band data was not be supported on Pike 0.5 and earlier, - and not on Pike 0.6 through 7.4 if they were compiled with the - option <tt>'--without-oob'</tt>. + <dt class='head--doc'>Parameter <code class='parameter'>choices</code></dt> + <dd></dd><dd class='body--doc'>May either be an array of strings, where each string is a choice, + or an array of pairs. A pair is an array with two strings. The + first string is the value of the choice while the second string + is the presentation text associated with the value. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_blocking()</code>, <code>set_callbacks</code>, <code>set_read_callback()</code>, - <code>set_write_callback()</code>, <code>set_read_oob_callback()</code>, - <code>set_write_oob_callback()</code>, <code>set_close_callback()</code> - <code>set_nonblocking_keep_callbacks()</code>, - <code>set_blocking_keep_callbacks()</code> - </dd></dl> + <dt class='head--doc'>Parameter <code class='parameter'>selected</code></dt> + <dd></dd><dd class='body--doc'>The value that should be selected by default, if any. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>select("language", + ({ ({ "eng", "English" }), + ({ "swe", "Swedish" }), + ({ "nor", "Norwegian" }) }), + "swe"); + </pre></dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - tcgetattr - Method - tcsetattr + simple_obox </dt> - <dd><code><code class='datatype'>mapping</code> tcgetattr()</code> - <code><code class='datatype'>int</code> tcsetattr(<code class='datatype'>mapping</code> <code class='argument'>attr</code>)</code> - <code><code class='datatype'>int</code> tcsetattr(<code class='datatype'>mapping</code> <code class='argument'>attr</code>, <code class='datatype'>string</code> <code class='argument'>when</code>)</code></dd> + <dd><code><code class='datatype'>string</code> simple_obox(<code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>string</code>)) <code class='argument'>rows</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>frame_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>cell_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>width</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>padding</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>int</code>, <code class='datatype'>string</code>, <code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>cell_callback</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Gets/sets term attributes. The returned value/the <code>attr</code> parameter - is a mapping on the form - <table class='box'><tr><td><code><code class='key'>"ispeed"</code> : <code class='datatype'>int(-1..)</code></code></td><td>In baud rate. - </td></tr> - <tr><td><code><code class='key'>"ospeed"</code> : <code class='datatype'>int(-1..)</code></code></td><td>Out baud rate. - </td></tr> - <tr><td><code><code class='key'>"csize"</code> : <code class='datatype'>int(-1..-1)</code>|<code class='datatype'>int(5..8)</code></code></td><td>Character size in bits. - </td></tr> - <tr><td><code><code class='key'>"rows"</code> : <code class='datatype'>int</code></code></td><td>Terminal rows. - </td></tr> - <tr><td><code><code class='key'>"columns"</code> : <code class='datatype'>int</code></code></td><td>Terminal columns. - </td></tr> - <tr><td><code><code class='key'>flag_name</code> : <code class='datatype'>bool</code></code></td><td>The value of a named flag. The flag name is - the string describing the termios flags (IGNBRK, BRKINT, - IGNPAR, PARMRK, INPCK, ISTRIP, INLCR, IGNCR, ICRNL, IUCLC, - IXON, IXANY, IXOFF, IMAXBEL, OPOST, OLCUC, ONLCR, OCRNL, - ONOCR, ONLRET, OFILL, OFDEL, OXTABS, ONOEOT, CSTOPB, CREAD, - PARENB, PARODD, HUPCL, CLOCAL, CRTSCTS, ISIG, ICANON, XCASE, - ECHO, ECHOE, ECHOK, ECHONL, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, - NOFLSH, TOSTOP, PENDIN). See the manpage for termios or - other documentation for more information. All flags are not - available on all platforms. - </td></tr> - <tr><td><code><code class='key'>character_name</code> : <code class='datatype'>int(8bit)</code></code></td><td>Sets the value of a control character (VINTR, VQUIT, VERASE, - VKILL, VEOF, VTIME, VMIN, VSWTC, VSTART, VSTOP, VSUSP, VEOL, - VREPRINT, VDISCARD, VWERASE, VLNEXT, VEOL2). All control - characters are not available on all platforms. - </td></tr> - </table>Negative values are not allowed as indata, but might appear in the - result from <code>tcgetattr</code> when the actual value is unknown. <code>tcsetattr</code> - returns 0 if failed. - The argument <code>when</code> to <code>tcsetattr</code> describes when the - changes are to take effect: - <table class='box'><tr><td><code><code class='key'>"TCSANOW"</code></code></td><td>The change occurs immediately (default). - </td></tr> - <tr><td><code><code class='key'>"TCSADRAIN"</code></code></td><td>The change occurs after all output has been written. - </td></tr> - <tr><td><code><code class='key'>"TCSAFLUSH"</code></code></td><td>The change occurs after all output has been written, - and empties input buffers. - </td></tr> - </table> + <dd class='body--doc'>This function should solve most of the obox needs that arises. It + creates a table out of the array of arrays of strings fed into it. + The tables will (with default settings) have a thin black outline + around the table and between its cells. Much effort has gone into + finding a simple HTML reresentation of such obox that is rendered + in a similar way in all popular browsers. The current + implementation has been tested against IE, Netscape, Mozilla, + Opera and Konquest. </dd> - + <dt class='head--doc'>Parameter <code class='parameter'>rows</code></dt> + <dd></dd><dd class='body--doc'>Simply an array of arrays with strings. The strings are the + values that should appear in the table cells. All rows should + have equal number of cells, otherwise the result will not be + very eye pleasing. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>frame_color</code></dt> + <dd></dd><dd class='body--doc'>The color of the surrounding frame. Defaults to "#000000". + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>cell_color</code></dt> + <dd></dd><dd class='body--doc'>The background color of the cells. Defaults to "#ffffff". + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>width</code></dt> + <dd></dd><dd class='body--doc'>The border width. Defaults to "1". + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>padding</code></dt> + <dd></dd><dd class='body--doc'>The amount of padding in each cell. Defaults to "3". + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>cell_callback</code></dt> + <dd></dd><dd class='body--doc'>If provided, the cell callback will be called for each cell. As + in parameters it will get the current x and y coordinates in the + table. The upper left cell is 0,0. In addition to the + coordinates it will also receive the background color and the + contents of the current cell. It is expected to return a + td-element. + </dd> <dt class='head--doc'>Example</dt> - <dd class='example'><pre>// setting the terminal in raw mode: - Stdio.stdin->tcsetattr((["ECHO":0,"ICANON":0,"VMIN":0,"VTIME":0])); + <dd class='example'><pre>function cb = lambda(int x, int y, string bgcolor, string contents) { + if(y%2) return "<td bgcolor='#aaaaff'>"+contents+"</td>"; + return "<td bgcolor='"+bgcolor+"'>"+contents+"</td>"; + } + simple_obox(my_rows, "#0000a0", 0, "1", "3", cb); </pre></dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Unknown flags are ignored by <code>tcsetattr()</code>. <code>tcsetattr</code> always - changes the attribute, so only include attributes that actually - should be altered in the attribute mapping. - </dd> - <dt class='head--doc'>Bugs</dt> - <dd class='body--doc'>Terminal rows and columns setting by <code>tcsetattr()</code> is not - currently supported. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>pad_rows</code> </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.FILE</h2> + <dl><dt><h2 class='header'>Class String.HTML.OBox</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'><code>Stdio.FILE</code> is a buffered version of <code>Stdio.File</code>, it inherits - <code>Stdio.File</code> and has most of the functionality of <code>Stdio.File</code>. - However, it has an input buffer that allows line-by-line input. - It also has support for automatic charset conversion for both input - and output (see <code>Stdio.FILE()->set_charset()</code>). + <dd class='body--doc'>Provides the same functionality as the <code>simple_obox</code> function, + in a "streaming" way. The real gain is different addtition methods + as well as the possibility to change the cell callback at any time. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The output part of <code>Stdio.FILE</code> is currently not buffered. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'>simple_obox </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - _get_iterator + add_cell </dt> - <dd><code>Stdio.FILE a; - foreach( a; index; value ) or </code><code><code class='modifier'>protected</code> <code class='datatype'>object</code> _get_iterator()</code></dd> + <dd><code><code class='datatype'>void</code> add_cell(<code class='datatype'>string</code> <code class='argument'>contents</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an iterator that will loop over the lines in this file. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>line_iterator()</code> + <dd class='body--doc'>Adds a cell with the provided content. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - getchar + add_raw_cell </dt> - <dd><code><code class='modifier'>local</code> <code class='datatype'>int</code> getchar()</code></dd> + <dd><code><code class='datatype'>void</code> add_raw_cell(<code class='datatype'>string</code> <code class='argument'>cell</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function returns one character from the input stream. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns the ISO-10646 (Unicode) value of the character. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Returns an <code class='expr'>int</code> and not a <code class='expr'>string</code> of length 1. + <dd class='body--doc'>Adds this cell to the table unmodified, e.g. it should have an enclosing + td or th element. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - gets + add_row </dt> - <dd><code><code class='datatype'>string</code> gets(<code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code>)</code></dd> + <dd><code><code class='datatype'>void</code> add_row(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>cells</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read one line of input with support for input conversion. + <dd class='body--doc'>Adds a complete row. If the current row is nonempty a + new row will be started. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_tagdata_cell + </dt> + <dd><code><code class='datatype'>void</code> add_tagdata_cell(<code class='datatype'>string</code> <code class='argument'>tag</code>, <code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>args</code>, <code class='datatype'>string</code> <code class='argument'>contents</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Creates a cell from the provided arguments and adds it to the table. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>not_all</code></dt> - <dd></dd><dd class='body--doc'>Set this parameter to ignore partial lines at EOF. This - is useful for eg monitoring a growing logfile. + <dt class='head--doc'>Parameter <code class='parameter'>tag</code></dt> + <dd></dd><dd class='body--doc'>The name of the element that should be produces. Typically + "td" or "th". </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns the line read if successful, and <code class='expr'>0</code> if - no more lines are available. + <dt class='head--doc'>Parameter <code class='parameter'>args</code></dt> + <dd></dd><dd class='body--doc'>A mapping with the elements attributes. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>ngets()</code>, <code>read()</code>, <code>line_iterator()</code>, <code>set_charset()</code> + <dt class='head--doc'>Parameter <code class='parameter'>contents</code></dt> + <dd></dd><dd class='body--doc'>The element contents. </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Inherit - file + <dt class='head--type'>Method + cast </dt> - <dd><code>inherit File : file</code></dd> + <dd><code>(int)String.HTML.OBox() (float)String.HTML.OBox() (string)String.HTML.OBox() (array)String.HTML.OBox() (mapping)String.HTML.OBox() (multiset)String.HTML.OBox()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>It is possible to case this object to a string, which does the same + as calling <code>render</code>, and to an array, which returns the cells in an + array of rows. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>String.HTML.OBox String.HTML.OBox(<code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>frame_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>cell_color</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>width</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>padding</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>int</code>, <code class='datatype'>string</code>, <code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>cell_callback</code>)</code></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - line_iterator + new_row </dt> - <dd><code><code class='datatype'>object</code> line_iterator(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>trim</code>)</code></dd> + <dd><code><code class='datatype'>void</code> new_row()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an iterator that will loop over the lines in this file. - If <code>trim</code> is true, all <tt>'\r'</tt> characters will be removed - from the input. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It's not supported to call this method more than once - unless a call to <code>seek</code> is done in advance. Also note that it's - not possible to intermingle calls to <code>read</code>, <code>gets</code> or other - functions that read data with the line iterator, it will produce - unexpected results since the internal buffer in the iterator will not - contain sequential file-data in those cases. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>_get_iterator()</code> + <dd class='body--doc'>Begin a new row. Succeeding cells will be added to this + row instead of the current. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - ngets + pad_rows </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) ngets(<code class='datatype'>void</code>|<code class='datatype'>int(1..)</code> <code class='argument'>n</code>, <code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>not_all</code>)</code></dd> + <dd><code><code class='datatype'>void</code> pad_rows()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get <code>n</code> lines. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>n</code></dt> - <dd></dd><dd class='body--doc'>Number of lines to get, or all remaining if zero. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>not_all</code></dt> - <dd></dd><dd class='body--doc'>Set this parameter to ignore partial lines at EOF. This - is useful for eg monitoring a growing logfile. + <dd class='body--doc'>Ensures that all rows have the same number of cells. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - openat + render </dt> - <dd><code><code class='object unresolved'>FILE</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='object unresolved'>FILE</code> openat(<code class='datatype'>string</code> <code class='argument'>filename</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>, <code class='datatype'>int</code> <code class='argument'>mask</code>)</code></dd> + <dd><code><code class='datatype'>string</code> render()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>Stdio.File()->openat()</code>, but returns an <code>Stdio.FILE</code> - object. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->openat()</code> + <dd class='body--doc'>Returns the result. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - pipe + set_cell_callback </dt> - <dd><code><code class='object unresolved'>FILE</code> pipe(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_cell_callback(<code class='datatype'>function</code>(<code class='datatype'>int</code>, <code class='datatype'>int</code>, <code class='datatype'>string</code>, <code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>cell_callback</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_extra_args + </dt> + <dd><code><code class='datatype'>void</code> set_extra_args(<code class='datatype'>array</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>)) <code class='argument'>extra_args</code>)</code></dd> + <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>Stdio.File()->pipe()</code>, but returns an <code>Stdio.FILE</code> - object. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->pipe()</code> + <dd class='body--doc'>The argument in the mappings will be added to the cell in the + cooresponding column of the table. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - printf + set_extra_args </dt> - <dd><code><code class='datatype'>int</code> printf(<code class='datatype'>string</code> <code class='argument'>format</code>, <code class='datatype'>mixed</code> ... <code class='argument'>data</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_extra_args(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>string</code>) <code class='argument'>extra_args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function does approximately the same as: - <code class='expr'><code>write</code>(<code>sprintf</code>(<code>format</code>,@<code>data</code>))</code>. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>write()</code>, <code>sprintf()</code> + <dd class='body--doc'>The argument in the mapping will be added to all created table cells. </dd></dl> - + </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Module Array</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>General functions to operate on arrays. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - read + all </dt> - <dd><code><code class='datatype'>string</code> read(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>bytes</code>, <code class='datatype'>void</code>|<code class='datatype'>bool</code> <code class='argument'>now</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> all(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>predicate</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read <code>bytes</code> (wide-) characters with buffering and support for - input conversion. + <dd class='body--doc'>Returns 1 if all of the elements in <code>a</code> fulfills the requirement + <code>predicate</code>( <code>a</code>[i], @<code>extra_args</code> ), otherwise 0. The + predicate should return non-zero for an element that meets the + requirements and zero for those that do not. </dd> - + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>Array.all( ({ 2, 4, 6, 8 }), `<, 17 ) + </pre></dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->read()</code>, <code>set_charset()</code>, <code>unread()</code> + <dd class='body--doc'><code>any</code>, <code>has_value</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_charset + any </dt> - <dd><code><code class='datatype'>void</code> set_charset(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>charset</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> any(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>predicate</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets the input and output charset of this file to the specified - <code>charset</code>. If <code>charset</code> is 0 or not specified the environment - is used to try to detect a suitable charset. - The default charset if this function is not called is - <tt>"ISO-8859-1"</tt>. - </dd><dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Consider using one of - ISO-IR-196 (<tt>"\e%G"</tt> - switch to UTF-8 with return) - or ISO-IR-190 (<tt>"\e%/G"</tt> - switch to UTF-8 level 1 no return) - or ISO-IR-191 (<tt>"\e%/H"</tt> - switch to UTF-8 level 2 no return) - or ISO-IR-192 (<tt>"\e%/I"</tt> - switch to UTF-8 level 3 no return) - or ISO-IR-193 (<tt>"\e%/J"</tt> - switch to UTF-16 level 1 no return) - or ISO-IR-194 (<tt>"\e%/K"</tt> - switch to UTF-16 level 2 no return) - or ISO-IR-195 (<tt>"\e%/L"</tt> - switch to UTF-16 level 3 no return) - or ISO-IR-162 (<tt>"\e%/@"</tt> - switch to UCS-2 level 1) - or ISO-IR-163 (<tt>"\e%/A"</tt> - switch to UCS-4 level 1) - or ISO-IR-174 (<tt>"\e%/C"</tt> - switch to UCS-2 level 2) - or ISO-IR-175 (<tt>"\e%/D"</tt> - switch to UCS-4 level 2) - or ISO-IR-176 (<tt>"\e%/E"</tt> - switch to UCS-2 level 3) - or ISO-IR-177 (<tt>"\e%/F"</tt> - switch to UCS-4 level 3) - or ISO-IR-178 (<tt>"\e%B"</tt> - switch to UTF-1) - automatically to encode wide strings. + <dd class='body--doc'>Returns 1 if any of the elements in <code>a</code> fulfills the requirement + <code>predicate</code>( <code>a</code>[i], @<code>extra_args</code> ), otherwise 0. The + predicate should return non-zero for an element that meets the + requirements and zero for those that do not. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>Array.any( ({ 2, 4, 6, 8 }), `>, 5 ) + </pre></dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>all</code>, <code>has_value</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - ungets + arrayify </dt> - <dd><code><code class='datatype'>void</code> ungets(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='datatype'>array</code> arrayify(<code class='datatype'>void</code>|<code class='datatype'>array</code>|<code class='datatype'>mixed</code> <code class='argument'>x</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function puts a line back in the input buffer. The line - can then be read with eg <code>read()</code>, <code>gets()</code> or <code>getchar()</code>. + <dd class='body--doc'>Make an array of the argument, if it isn't already. An undefined + argument gives the empty array. This is useful when something is + either an array or a basic datatype, for instance in headers from + the MIME module or Protocols.HTTP.Server. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The string is autoterminated by an extra line-feed. + <dt class='head--doc'>Parameter <code class='parameter'>x</code></dt> + <dd></dd><dd class='body--doc'>Result depends of the argument type: + <dl class='group--doc'><dt>arrayp(x)</dt> + <dd>arrayify(x) => x </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read()</code>, <code>gets()</code>, <code>getchar()</code>, <code>unread()</code> + <dt>undefinedp(x)</dt> + <dd>arrayify(x) => ({}) + </dd> + <dt>otherwise</dt> + <dd>arrayify(x) => ({ x }) + </dd> + </dl> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - unread + columns </dt> - <dd><code><code class='datatype'>void</code> unread(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) columns(<code class='datatype'>array</code> <code class='argument'>x</code>, <code class='datatype'>array</code> <code class='argument'>ind</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function puts a string back in the input buffer. The string - can then be read with eg <code>read()</code>, <code>gets()</code> or <code>getchar()</code>. + <dd class='body--doc'>Get multiple columns from an array. + This function is equvivalent to + <pre> + map(ind, lambda(mixed i) { return column(x, i); }) + </pre> </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read()</code>, <code>gets()</code>, <code>getchar()</code>, <code>ungets()</code> + <dd class='body--doc'><code>column()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - write + combinations </dt> - <dd><code><code class='datatype'>int</code> write(<code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>string</code> <code class='argument'>what</code>, <code class='datatype'>mixed</code> ... <code class='argument'>fmt</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) combinations(<code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>int</code> <code class='argument'>len</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Write <code>what</code> with support for output_conversion. + <dd class='body--doc'>Returns an array of all combinations of length <code>len</code> of + elements from <code>arr</code>. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File()->write()</code> + <dd class='body--doc'><code>permute()</code> </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.Port</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Handles listening to socket ports. Whenever you need a bound - socket that is open and listens for connections you should - use this program. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - accept + common_prefix </dt> - <dd><code><code class='object unresolved'>File</code> accept()</code></dd> + <dd><code><code class='datatype'>array</code> common_prefix(<code class='datatype'>array</code>(<code class='datatype'>array</code>) <code class='argument'>arrs</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function completes a connection made from a remote machine to - this port. It returns a two-way stream in the form of a clone of - <code>Stdio.File</code>. The new file is by initially set to blocking mode. + <dd class='body--doc'>Find the longest common prefix from an array of arrays. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>Stdio.File</code> + <dd class='body--doc'><code>String.common_prefix</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - accept + compact_diff3 </dt> - <dd><code><code class='object unresolved'>Stdio.File</code> accept()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) compact_diff3(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>, <code class='datatype'>array</code> <code class='argument'>old</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the first connection request waiting for this port and return - it as a connected socket. - If no connection request is waiting and the port is in nonblocking - mode (i.e. an accept callback is installed) then zero is returned. - Otherwise this function waits until a connection has arrived. - In Pike 7.8 and later the returned object is created via <code>fd_factory()</code>. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>In Pike 7.7 and later the resulting file object will be assigned - to the same backend as the port object. + <dd class='body--doc'>Given three arrays like those returned from <code>diff3</code>, this + function "compacts" the diff3 result by removing all differences + where <tt>a</tt> and <tt>b</tt> agrees against <tt>old</tt>. The result is + on the same form as the result from <code>diff</code>, and doesn't + include the sequence from <tt>old</tt>. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - bind + count </dt> - <dd><code><code class='datatype'>int</code> bind(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>reuse_port</code>)</code></dd> + <dd><code><code class='datatype'>int</code> count(<code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code> <code class='argument'>haystack</code>, <code class='datatype'>mixed</code> <code class='argument'>needle</code>)</code> + <code><code class='datatype'>mapping</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) count(<code class='datatype'>array</code>|<code class='datatype'>mapping</code>|<code class='datatype'>multiset</code> <code class='argument'>haystack</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Opens a socket and binds it to port number on the local machine. - If the second argument is present, the socket is set to - nonblocking and the callback funcition is called whenever - something connects to it. The callback will receive the id for - this port as argument and should typically call <code>accept</code> to - establish a connection. - If the optional argument <code>ip</code> is given, <code>bind</code> will try to bind - to an interface with that host name or IP number. Omitting this - will bind to all available IPv4 addresses; specifying "::" will - bind to all IPv4 and IPv6 addresses. - If the OS supports TCP_FASTOPEN it is enabled automatically. - If the OS supports SO_REUSEPORT it is enabled if the fourth argument is true. + <dd class='body--doc'>Returns the number of occurrences of <code>needle</code> in <code>haystack</code>. + If the optional <code>needle</code> argument is omitted, <code>count</code> instead + works similar to the unix command <tt>sort|uniq -c</tt>, returning + a mapping with the number of occurrences of each element in + <code>haystack</code>. For array or mapping <code>haystack</code>s, it's the values + that are counted, for multisets the indices, as you'd expect. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>1 is returned on success, zero on failure. <code>errno</code> provides - further details about the error in the latter case. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>accept</code>, <code>set_id</code> + <dd class='body--doc'><code>String.count</code>, <code>search</code>, <code>has_value</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - bind_unix + diff </dt> - <dd><code><code class='datatype'>int</code> bind_unix(<code class='datatype'>string</code> <code class='argument'>path</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) diff(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Opens a Unix domain socket at the given path in the file system. - If the second argument is present, the socket is set to - nonblocking and the callback funcition is called whenever - something connects to it. The callback will receive the id for - this port as argument and should typically call <code>accept</code> to - establish a connection. + <dd class='body--doc'>Calculates which parts of the arrays that are common to both, and + which parts that are not. </dd> <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>1 is returned on success, zero on failure. <code>errno</code> provides - further details about the error in the latter case. + <dd class='body--doc'>Returns an array with two elements, the first is an array of parts in + array <code>a</code>, and the second is an array of parts in array <code>b</code>. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function is only available on systems that support Unix domain - sockets. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code>path</code> had a quite restrictive length limit (~100 characters) - prior to Pike 7.8.334. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>accept</code>, <code>set_id</code> + <dd class='body--doc'><code>diff_compare_table()</code>, <code>diff_longest_sequence()</code>, + <code>String.fuzzymatch()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - close + diff3 </dt> - <dd><code><code class='datatype'>void</code> close()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) diff3(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>, <code class='datatype'>array</code> <code class='argument'>c</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Closes the socket. + <dd class='body--doc'>Return the three-way difference between the arrays. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>Array.diff()</code>, <code>Array.diff_longest_sequence()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + diff_compare_table </dt> - <dd><code>Stdio.Port Stdio.Port()</code> - <code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>)</code> - <code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code> - <code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>string</code> <code class='argument'>ip</code>)</code> - <code>Stdio.Port Stdio.Port(<code class='argument'>"stdin"</code>)</code> - <code>Stdio.Port Stdio.Port(<code class='argument'>"stdin"</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>int</code>)) diff_compare_table(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>If the first argument is other than <code class='expr'>"stdin"</code> the arguments will - be passed to <code>bind()</code>. - When create is called with <code class='expr'>"stdin"</code> as the first argument, a - socket is created out of the file descriptor <code class='expr'>0</code>. This is only - useful if it actually is a socket to begin with, and is equivalent to - creating a port and initializing it with <code>listen_fd</code>(0). + <dd class='body--doc'>Returns an array which maps from index in <code>a</code> to corresponding + indices in <code>b</code>. + <pre> + > Array.diff_compare_table( ({ "a","b","c" }), ({ "b", "b", "c", "d", "b" })); + Result: ({ + ({ }), + ({ + 0, + 1, + 4 + }), + ({ + 2 + }) + }) + </pre> </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind</code> + <dd class='body--doc'><code>diff()</code>, <code>diff_longest_sequence()</code>, <code>String.fuzzymatch()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + diff_dyn_longest_sequence </dt> - <dd><code>Stdio.Port Stdio.Port(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>ip</code>)</code> - <code>Stdio.Port Stdio.Port(<code class='argument'>"stdin"</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) diff_dyn_longest_sequence(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>When called with an int or any string except <code class='expr'>"stdin"</code> as - first argument, this function does the same as <code>bind()</code> would do - with the same arguments. - When called with <code class='expr'>"stdin"</code> as argument, a socket is created - out of the file descriptor 0. This is only useful if that actually - IS a socket to begin with, and is equivalent to creating a port and - initializing it with <code>listen_fd</code>(0). + <dd class='body--doc'>Gives the longest sequence of indices in <code>b</code> that have corresponding + values in the same order in <code>a</code>. + This function performs the same operation as <code>diff_longest_sequence()</code>, + but uses a different algorithm, which in some rare cases might be faster + (usually it's slower though). </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind</code>, <code>listen_fd</code> + <dd class='body--doc'><code>diff_longest_sequence()</code>, <code>diff()</code>, <code>diff_compare_table()</code>, + <code>String.fuzzymatch()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - errno + diff_longest_sequence </dt> - <dd><code><code class='datatype'>int</code> errno()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) diff_longest_sequence(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>array</code> <code class='argument'>b</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>If the last call done on this port failed, this function will - return an integer describing what went wrong. Refer to your unix - manual for further information. + <dd class='body--doc'>Gives the longest sequence of indices in <code>b</code> that have corresponding + values in the same order in <code>a</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>diff()</code>, <code>diff_compare_table()</code>, <code>String.fuzzymatch()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - fd_factory + dwim_sort_func </dt> - <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>Fd</code> fd_factory()</code></dd> + <dd><code><code class='datatype'>int(-1..1)</code> dwim_sort_func(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Factory creating empty <code>Fd</code> objects. - This function is called by <code>accept()</code> when it needs to create - a new file. + <dd class='body--doc'>Sort without respect to number formatting (most notably leading + zeroes). </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Inherit - _port + <dt class='head--type'>Method + everynth </dt> - <dd><code>inherit _port : _port</code></dd> - </dl> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) everynth(<code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>a</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>start</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return an array with every <code>n</code>:th element of the array <code>a</code>. + If <code>n</code> is zero every other element will be returned. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>splice()</code>, <code>`/()</code> + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - listen_fd + flatten </dt> - <dd><code><code class='datatype'>int</code> listen_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>accept_callback</code>)</code></dd> + <dd><code><code class='datatype'>array</code> flatten(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>mapping</code>(<code class='datatype'>array</code>:<code class='datatype'>array</code>)|<code class='datatype'>void</code> <code class='argument'>state</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function does the same as <code>bind</code>, except that instead of - creating a new socket and bind it to a port, it expects the file - descriptor <code>fd</code> to be an already open port. + <dd class='body--doc'>Flatten a multi-dimensional array to a one-dimensional array. </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function is only for the advanced user, and is generally used - when sockets are passed to Pike at exec time. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind</code>, <code>accept</code> + <dd class='body--doc'>Prior to Pike 7.5.7 it was not safe to call this function + with cyclic data-structures. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_address + greedy_diff </dt> - <dd><code><code class='datatype'>string</code> query_address()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>(<code class='datatype'>array</code>)) greedy_diff(<code class='datatype'>array</code> <code class='argument'>from</code>, <code class='datatype'>array</code> <code class='argument'>to</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Get the address and port of the local socket end-point. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns the address and port of a socket end-point - on the form <code class='expr'>"x.x.x.x port"</code> (IPv4) or - <code class='expr'>"x:x:x:x:x:x:x:x port"</code> (IPv6). - If there is some error querying or formatting the address, - <code class='expr'>0</code> (zero) is returned and <code>errno()</code> will return the - error code. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>An error is thrown if the socket isn't bound. + <dd class='body--doc'>Like <code>Array.diff</code>, but tries to generate bigger continuous chunks of the + differences, instead of maximizing the number of difference chunks. More + specifically, <code>greedy_diff</code> optimizes the cases where <code>Array.diff</code> returns + <code class='expr'>({ ..., A, Z, B, ({}), C, ... })</code> + <code class='expr'>({ ..., A, X, B,  Y+B, C, ... })</code> + into the somewhat shorter diff arrays + <code class='expr'>({ ..., A, Z,     B+C, ... })</code> + <code class='expr'>({ ..., A, X+B+Y, B+C, ... })</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_backend + interleave_array </dt> - <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) interleave_array(<code class='datatype'>array</code>(<code class='datatype'>mapping</code>(<code class='datatype'>int</code>:<code class='datatype'>mixed</code>)) <code class='argument'>tab</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the backend used for the accept callback. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_backend</code> + <dd class='body--doc'>Interleave a sparse matrix. + Returns an array with offsets that describe how to shift the + rows of <code>tab</code> so that only at most one non-zero value exists in + every column. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_fd + longest_ordered_sequence </dt> - <dd><code><code class='datatype'>int</code> query_fd()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) longest_ordered_sequence(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the file descriptor number associated with this object. + <dd class='body--doc'>Find the longest ordered sequence of elements. + This function returns an array of the indices in the longest + ordered sequence of elements in the array. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>diff()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_id + lyskom_sort_func </dt> - <dd><code><code class='datatype'>mixed</code> query_id()</code></dd> + <dd><code><code class='datatype'>int(-1..1)</code> lyskom_sort_func(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function returns the id for this port. The id is normally the - first argument to accept_callback. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_id</code> + <dd class='body--doc'>Sort comparison function that does not care about case, nor about + the contents of any parts of the string enclosed with '()' + Example: "Foo (bar)" is given the same weight as "foo (really!)" </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_backend + oid_sort_func </dt> - <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> + <dd><code><code class='datatype'>int(-1..1)</code> oid_sort_func(<code class='datatype'>string</code> <code class='argument'>a</code>, <code class='datatype'>string</code> <code class='argument'>b</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the backend used for the accept callback. + <dd class='body--doc'>Sort with care of numerical sort for OID values, e.g. + "1.2.1" before "1.11.1". </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><code class='expr'>a<b</code> + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td><code class='expr'>a==b</code> + </td></tr> + <tr><td><code><code class='key'>1</code></code></td><td><code class='expr'>a>b</code> + </td></tr> + </table></dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The backend keeps a reference to this object as long as the port - is accepting connections, but this object does not keep a - reference to the backend. + <dd class='body--doc'>In Pike 7.6 and older this function returned <code class='expr'>0</code> both when + <code class='expr'>a<b</code> and <code class='expr'>a==b</code>. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_backend</code> + <dd class='body--doc'><code>sort_array</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_id + partition </dt> - <dd><code><code class='datatype'>mixed</code> set_id(<code class='datatype'>mixed</code> <code class='argument'>id</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) partition(<code class='datatype'>array</code> <code class='argument'>a</code>, <code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>arbiter</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function sets the id used for accept_callback by this port. - The default id is <code>this_object()</code>. + <dd class='body--doc'>Splits an array in two, according to an arbitration function + <code>arbiter</code>. The elements in <code>a</code> who return non-zero for the + expression <code>arbiter</code>( <code>a</code>[i], @<code>extra_args</code> ) end up in + the first sub-array, the others in the second. The order is + preserved from the original array. </dd> - + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>Array.partition( enumerate( 9 ), lambda(int n) { return n>3 && n<7; } ); + > ({ ({ 4, 5, 6 }), ({ 0, 1, 2, 3, 7, 8 }) }) + </pre></dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_id</code> + <dd class='body--doc'><code>filter</code>, <code>`/</code>, <code>`%</code> </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.UDP</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>UDP (User Datagram Protocol) handling. - </dd></dl> + - + <hr /> <dl class='group--doc'> - <dt class='head--type'>Constant - MSG_OOB + <dt class='head--type'>Method + permute </dt> - <dd><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_OOB</code></code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this constant. + <dd><code><code class='datatype'>array</code> permute(<code class='datatype'>array</code> <code class='argument'>in</code>, <code class='datatype'>int(0..)</code> <code class='argument'>number</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Give a specified permutation of an array. + The number of permutations is equal to <code class='expr'>sizeof(<code>in</code>)!</code> + (the factorial of the size of the given array). + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>shuffle()</code> </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Constant - MSG_PEEK + <dt class='head--type'>Method + pop </dt> - <dd><code><code class='datatype'>constant</code> Stdio.UDP.<code class='constant'>MSG_PEEK</code></code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this constant. + <dd><code><code class='datatype'>array</code> pop(<code class='datatype'>array</code> <code class='argument'>list</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Pops and returns the last value of the array, shortening the + array by one element. + If there are no elements in the array then 0 is returned otherwise + an array is returned where the first returned element is the popped + value, and the second element is the modified array. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>Array.pop(({ "a", "b", "c", "d" })); + > ({ "d", ({ "a", "b", "c" }) }) + </pre></dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>ADT.Stack</code>, <code>ADT.Stack.pop</code>, <code>ADT.Stack.quick_pop</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - add_membership + push </dt> - <dd><code><code class='datatype'>int</code> add_membership(<code class='datatype'>string</code> <code class='argument'>group</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>address</code>)</code></dd> + <dd><code><code class='datatype'>array</code> push(<code class='datatype'>array</code> <code class='argument'>list</code>, <code class='datatype'>mixed</code> <code class='argument'>element</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Join a multicast group. + <dd class='body--doc'>Threats an Array as a stack and pushes the element onto the + end. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>group</code></dt> - <dd></dd><dd class='body--doc'><code>group</code> contains the address of the multicast group the - application wants to join. It must be a valid multicast address. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> - <dd></dd><dd class='body--doc'><code>address</code> is the address of the local interface with which - the system should join to the multicast group. If not provided - the system will select an appropriate interface. - See also the Unix man page for setsocketopt IPPROTO_IP IP_ADD_MEMBERSHIP - and IPPROTO_IPV6 IPV6_JOIN_GROUP. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The <code>address</code> parameter is currently not supported for IPv6. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. - </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>Array.push(({ "a", "b", "c", "d" }), "e"); + > ({ "a", "b", "c", "d", "e" }) + </pre></dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>drop_membership()</code> + <dd class='body--doc'><code>ADT.Stack</code>, <code>ADT.Stack.push</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - bind + reduce </dt> - <dd><code><code class='object unresolved'>UDP</code> bind(<code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>address</code>, <code class='datatype'>string</code>|<code class='datatype'>bool</code> <code class='argument'>no_reuseaddr</code>)</code></dd> + <dd><code><code class='datatype'>mixed</code> reduce(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>fun</code>, <code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> <code class='argument'>zero</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Binds a port for receiving or transmitting UDP. + <dd class='body--doc'><code>reduce()</code> sends the first two elements in <code>arr</code> to <code>fun</code>, + then the result and the next element in <code>arr</code> to <code>fun</code> and + so on. Then it returns the result. The function will return + <code>zero</code> if <code>arr</code> is the empty array. If <code>arr</code> has + only one element, that element will be returned. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>port</code></dt> - <dd></dd><dd class='body--doc'>Either a port number or the name of a service as listed in - <tt>/etc/services</tt>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> - <dd></dd><dd class='body--doc'>Local address to bind to. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>no_reuseaddr</code></dt> - <dd></dd><dd class='body--doc'>If set to <code class='expr'>1</code>, Pike will not set the <code class='expr'>SO_REUSEADDR</code> option - on the UDP port. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'><code class='expr'>SO_REUSEADDR</code> is never applied when binding a random port - (<code class='expr'>bind(0)</code>). - In general, <code class='expr'>SO_REUSEADDR</code> is not desirable on UDP ports. - Unless used for receiving multicast, be sure to never bind a - non-random port without setting <code class='expr'>no_reuseaddr</code> to <code class='expr'>1</code>. - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>Throws error when unable to bind port. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>rreduce()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - close + rreduce </dt> - <dd><code><code class='datatype'>bool</code> close()</code></dd> + <dd><code><code class='datatype'>mixed</code> rreduce(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>fun</code>, <code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> <code class='argument'>zero</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Closes an open UDP port. + <dd class='body--doc'><code>rreduce()</code> sends the last two elements in <code>arr</code> to <code>fun</code>, + then the third last element in <code>arr</code> and the result to <code>fun</code> and + so on. Then it returns the result. The function will return + <code>zero</code> if <code>arr</code> is the empty array. If <code>arr</code> has + only one element, that element will be returned. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This method was introduced in Pike 7.5. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>reduce()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - connect + search_array </dt> - <dd><code><code class='datatype'>bool</code> connect(<code class='datatype'>string</code> <code class='argument'>address</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>)</code></dd> + <dd><code><code class='datatype'>int</code> search_array(<code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>string</code>|<code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>int</code> <code class='argument'>fun</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Establish an UDP connection. - This function connects an UDP socket previously created with - <code>Stdio.UDP()</code> to a remote socket. The <code>address</code> is the IP name or - number for the remote machine. + <dd class='body--doc'><code>search_array()</code> works like <code>map()</code>, only it returns the index + of the first call that returnes true instead. + If no call returns true, -1 is returned. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>If the socket is in nonblocking mode, you have to wait - for a write or close callback before you know if the connection - failed or not. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind()</code>, <code>query_address()</code> + <dd class='body--doc'><code>sum()</code>, <code>map()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - drop_membership + shift </dt> - <dd><code><code class='datatype'>int</code> drop_membership(<code class='datatype'>string</code> <code class='argument'>group</code>, <code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>address</code>)</code></dd> + <dd><code><code class='datatype'>array</code> shift(<code class='datatype'>array</code> <code class='argument'>list</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Leave a multicast group. + <dd class='body--doc'>Shifts the first value of the array off and returns it, shortening + the array by 1 and moving everything down. If there are no elements + in the array it returns 0. + Returns an array where the first element is the shifted value and the + second element is the modified array. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>group</code></dt> - <dd></dd><dd class='body--doc'><code>group</code> contains the address of the multicast group the - application wants to join. It must be a valid multicast address. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>address</code></dt> - <dd></dd><dd class='body--doc'><code>address</code> is the address of the local interface with which - the system should join to the multicast group. If not provided - the system will select an appropriate interface. - See also the Unix man page for setsocketopt IPPROTO_IP IP_DROP_MEMBERSHIP - and IPPROTO_IPV6 IPV6_LEAVE_GROUP. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The <code>address</code> parameter is currently not supported for IPv6. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. - </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>Array.shift(({ "a", "b", "c", "d"})); + > ({ "a", ({ "b", "c", "d" }) }) + </pre></dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>add_membership()</code> + <dd class='body--doc'><code>ADT.Stack</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - enable_broadcast + shuffle </dt> - <dd><code><code class='datatype'>bool</code> enable_broadcast()</code></dd> + <dd><code><code class='datatype'>array</code> shuffle(<code class='datatype'>array</code> <code class='argument'>arr</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the broadcast flag. - If enabled then sockets receive packets sent to a broadcast - address and they are allowed to send packets to a - broadcast address. + <dd class='body--doc'><code>shuffle()</code> gives back the same elements, but in random order. + The array is modified destructively. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> on success, <code class='expr'>0</code> (zero) otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This is normally only avalable to root users. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>permute()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - enable_multicast + sort_array </dt> - <dd><code><code class='datatype'>bool</code> enable_multicast(<code class='datatype'>string</code> <code class='argument'>reply_address</code>)</code></dd> + <dd><code><code class='datatype'>array</code> sort_array(<code class='datatype'>array</code> <code class='argument'>arr</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>)|<code class='datatype'>void</code> <code class='argument'>cmp</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the local device for a multicast socket. + <dd class='body--doc'>This function sorts the array <code>arr</code> after a compare-function + <code>cmp</code> which takes two arguments and should return <code class='expr'>1</code> if the + first argument is larger then the second. Returns the sorted array + - <code>arr</code> is not sorted destructively. + The remaining arguments <code>args</code> will be sent as 3rd, 4th etc. argument + to <code>cmp</code>. + If <code>cmp</code> is omitted, <code>`>()</code> is used instead. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>reply_address</code></dt> - <dd></dd><dd class='body--doc'>Local address that should appear in the multicast packets. - See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF - and IPPROTO_IPV6 IPV6_MULTICAST_IF. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>map()</code>, <code>sort()</code>, <code>`>()</code>, <code>dwim_sort_func</code>, <code>lyskom_sort_func</code>, + <code>oid_sort_func</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - errno + splice </dt> - <dd><code><code class='datatype'>int</code> errno()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) splice(<code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>arr1</code>, <code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>arr2</code>, <code class='datatype'>array</code>(<code class='datatype'>mixed</code>) ... <code class='argument'>more_arrays</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the error code for the last command on this object. - Error code is normally cleared when a command is successful. + <dd class='body--doc'>Splice two or more arrays. + This means that the returned array has the first element in the + first given array, then the first argument in next array and so + on for all arrays. Then the second elements are added, etc. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>`/()</code>, <code>`*()</code>, <code>`+()</code>, <code>`-()</code>, <code>everynth()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get_type + sum </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) get_type()</code></dd> + <dd><code><code class='datatype'>mixed</code> sum(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns socket type and protocol family. + <dd class='body--doc'>Sum the elements of an array using `+. The empty array + results in 0. </dd></dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Inherit - UDP + <dt class='head--type'>Method + sum_arrays </dt> - <dd><code>inherit _Stdio.UDP : UDP</code></dd> - </dl> + <dd><code><code class='datatype'>array</code> sum_arrays(<code class='datatype'>function</code>(<code class='datatype'>int(0..0)</code> ... :<code class='datatype'>mixed</code>) <code class='argument'>sum</code>, <code class='datatype'>array</code> ... <code class='argument'>args</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Applies the function <code>sum</code> columnwise on the elements in the + provided arrays. E.g. <code class='expr'>sum_array(`+,a,b,c)</code> does the same + as <code class='expr'>`+(a[*],b[*],c[*])</code>. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_address + transpose </dt> - <dd><code><code class='datatype'>string</code> query_address()</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>array</code>) transpose(<code class='datatype'>array</code>(<code class='datatype'>array</code>) <code class='argument'>matrix</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the local address of a socket on the form "x.x.x.x port". - If this file is not a socket, not connected or some other error occurs, - zero is returned. + <dd class='body--doc'>Takes an array of equally sized arrays (essentially a matrix of size M*N) + and returns the transposed (N*M) version of it, where rows and columns + are exchanged for one another. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_backend + uniq </dt> - <dd><code><code class='object unresolved'>Pike.Backend</code> query_backend()</code></dd> + <dd><code><code class='datatype'>array</code> uniq(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the backend used for the read callback. + <dd class='body--doc'>Remove elements that are duplicates. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_backend</code> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns an copy of the array <code>a</code> with all + duplicate values removed. The order of the values is kept in the + result; it's always the first of several equal elements that is + kept. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Elements are compared with <code>`==</code>. They are also hashed (see + <code>lfun::__hash</code> for further details if the array contains + objects). </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - query_fd + uniq2 </dt> - <dd><code><code class='datatype'>int</code> query_fd()</code></dd> + <dd><code><code class='datatype'>array</code> uniq2(<code class='datatype'>array</code> <code class='argument'>a</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Gets the file descriptor for this UDP port. + <dd class='body--doc'>Perform the same action as the Unix uniq command on an array, + that is, fold consecutive occurrences of the same element into + a single element of the result array: + aabbbcaababb -> abcabab. + See also the <code>uniq</code> function. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - read + unshift </dt> - <dd><code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) read()</code> - <code><code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>) read(<code class='datatype'>int</code> <code class='argument'>flag</code>)</code></dd> + <dd><code><code class='datatype'>array</code> unshift(<code class='datatype'>array</code> <code class='argument'>list</code>, <code class='datatype'>mixed</code> <code class='argument'>element</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read from the UDP socket. - Flag <code>flag</code> is a bitfield, 1 for out of band data and 2 for peek + <dd class='body--doc'>Does the opposite of "shift". Or the opposite of a "push", + depending on how you look at it. Prepends the element to + the front of the array and returns the new array. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>mapping(string:int|string) in the form - ([ - "data" : string received data - "ip" : string received from this ip - "port" : int ...and this port - ]) + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>Array.unshift(({ "b", "c", "d" }), "a"); + > ({ "a", "b", "c", "d" }) + </pre></dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>ADT.Stack</code> + </dd></dl> + <dl><dt><h2 class='header'>Class Array.Iterator</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when + called with an array. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>set_read_callback()</code>, <code>MSG_OOB</code>, <code>MSG_PEEK</code> + <dd class='body--doc'><code>get_iterator</code> </dd></dl> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + predef::Iterator + </dt> + <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> + </dl> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Module Mapping</h2> + </dt><dd> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - send + <dt class='head--type'>Constant + delete </dt> - <dd><code><code class='datatype'>int</code> send(<code class='datatype'>string</code> <code class='argument'>to</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>message</code>)</code> - <code><code class='datatype'>int</code> send(<code class='datatype'>string</code> <code class='argument'>to</code>, <code class='datatype'>int</code>|<code class='datatype'>string</code> <code class='argument'>port</code>, <code class='datatype'>string</code> <code class='argument'>message</code>, <code class='datatype'>int</code> <code class='argument'>flags</code>)</code></dd> + <dd><code><code class='datatype'>constant</code> Mapping.<code class='constant'>delete</code></code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Send data to a UDP socket. The recipient address will be <code>to</code> - and port will be <code>port</code>. - Flag <code>flag</code> is a bitfield, 1 for out of band data and - 2 for don't route flag. + <dd class='body--doc'>Alias for <code>m_delete()</code> + </dd></dl> + <dl><dt><h2 class='header'>Class Mapping.Iterator</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when + called with a mapping. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><table class='box'><tr><td><code><code class='key'>(0..)</code></code></td><td>The number of bytes that were actually written. - </td></tr> - <tr><td><code><code class='key'>(..-1)</code></code></td><td>Failed to send the <code>message</code>. Check <code>errno()</code> for - the cause. Common causes are: - <table class='box'><tr><td><code><code class='key'>System.EMSGSIZE</code></code></td><td>The <code>message</code> is too large to send unfragmented. - </td></tr> - <tr><td><code><code class='key'>System.EWOULDBLOCK</code></code></td><td>The send buffers are full. - </td></tr> - </table></td></tr> - </table> - </dd> - <dt class='head--doc'>Throws</dt> - <dd class='body--doc'>Throws errors on invalid arguments and uninitialized object. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Versions of Pike prior to 8.1.5 threw errors also on EMSGSIZE - (<code class='expr'>"Too big message"</code>) and EWOULDBLOCK - .(<code class='expr'>"Message would block."</code>). These versions of Pike also - did not update the object errno on this function failing. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_iterator</code> </dd></dl> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + predef::Iterator + </dt> + <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> + </dl> + </dd></dl><dl><dt><h2 class='header'>Class Mapping.ShadowedMapping</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>A mapping look-alike that overrides (ie shadows) another <code>parent</code> mapping. + The class implements most of the usual mapping operations. + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_backend + create </dt> - <dd><code><code class='datatype'>void</code> set_backend(<code class='object unresolved'>Pike.Backend</code> <code class='argument'>backend</code>)</code></dd> + <dd><code>Mapping.ShadowedMapping Mapping.ShadowedMapping(<code class='datatype'>mapping</code>|<code class='object unresolved'>ShadowedMapping</code> <code class='argument'>parent</code>, <code class='datatype'>mapping</code>|<code class='datatype'>void</code> <code class='argument'>shadow</code>, <code class='datatype'>bool</code>|<code class='datatype'>void</code> <code class='argument'>modify_parent</code>)</code></dd> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the backend used for the read callback. + <dt class='head--doc'>Parameter <code class='parameter'>parent</code></dt> + <dd></dd><dd class='body--doc'>Mapping to be shadowed. </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The backend keeps a reference to this object as long as there can - be calls to the read callback, but this object does not keep a - reference to the backend. + <dt class='head--doc'>Parameter <code class='parameter'>shadow</code></dt> + <dd></dd><dd class='body--doc'>Initial shadow of <code>parent</code>. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>query_backend</code> + <dt class='head--doc'>Parameter <code class='parameter'>modify_parent</code></dt> + <dd></dd><dd class='body--doc'>Modifications should be done to <code>parent</code> rather than + to <code>shadow</code>. If this is set, only entries that are + already present in <code>shadow</code> can be modified by later + operations. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_blocking + create </dt> - <dd><code><code class='datatype'>object</code> set_blocking()</code></dd> + <dd><code>Mapping.ShadowedMapping Mapping.ShadowedMapping(<code class='datatype'>mapping</code>|<code class='object unresolved'>ShadowedMapping</code> <code class='argument'>parent</code>)</code></dd> + </dl> - + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Variable + parent + </dt> + <dd><code><code class='modifier'>protected</code> <code class='datatype'>mapping</code>|<code class='object unresolved'>ShadowedMapping</code> Mapping.ShadowedMapping.parent</code></dd> + </dl> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Module Multiset</h2> + </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets this object to be blocking. + <dd class='body--doc'>Multiset handling. + </dd></dl><dl><dt><h2 class='header'>Class Multiset.Iterator</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>An object of this class is returned by <code>get_iterator()</code> when + called with a multiset. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>get_iterator</code> </dd></dl> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + predef::Iterator + </dt> + <dd><code>inherit predef::Iterator : predef::Iterator</code></dd> + </dl> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Module Int</h2> + </dt><dd> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - set_buffer + <dt class='head--type'>Constant + NATIVE_MIN + Constant + NATIVE_MAX </dt> - <dd><code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>, <code class='datatype'>string</code> <code class='argument'>mode</code>)</code> - <code><code class='datatype'>void</code> set_buffer(<code class='datatype'>int</code> <code class='argument'>bufsize</code>)</code></dd> + <dd><code><code class='datatype'>constant</code> Int.<code class='constant'>NATIVE_MIN</code></code> + <code><code class='datatype'>constant</code> Int.<code class='constant'>NATIVE_MAX</code></code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set internal socket buffer. - This function sets the internal buffer size of a socket or stream. - The second argument allows you to set the read or write buffer by - specifying <code class='expr'>"r"</code> or <code class='expr'>"w"</code>. + <dd class='body--doc'>The limits for using the native representation of integers on the + current architecture. Any integer that is outside this range uses + a more complex and slower representation. Also, some builtin + functions that don't expect very large integers might start to + complain about invalid argument type when given values outside + this range (they typically say something like "Expected integer, + got object"). + <code>NATIVE_MIN</code> is not greater than <code class='expr'>-2147483648</code> + (<code class='expr'>-0x80000000</code>). + <code>NATIVE_MAX</code> is not less than <code class='expr'>2147483647</code> + (<code class='expr'>0x7fffffff</code>). </dd> <dt class='head--doc'>Note</dt> - <dd class='body--doc'>It is not guaranteed that this function actually does anything, - but it certainly helps to increase data transfer speed when it does. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>open_socket()</code>, <code>accept()</code> + <dd class='body--doc'>The size of the native integers can be controlled when Pike is + compiled with the configure flags <code class='expr'>--with-int-int</code>, + <code class='expr'>--with-long-int</code>, and <code class='expr'>--with-long-long-int</code>. The + default is to use the longest available integer type that fits + inside a pointer, which typically means that it's 64 bit on "true" + 64 bit architectures. </dd></dl> <hr /> <dl class='group--doc'> - + <dt class='head--type'>Variable + inf + </dt> + <dd><code><code class='object unresolved'>Inf</code> Int.inf</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>An object that behaves like positive infinity. + </dd></dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - set_fd + parity </dt> - <dd><code><code class='object unresolved'>UDP</code> set_fd(<code class='datatype'>int</code> <code class='argument'>fd</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> parity(<code class='datatype'>int(0..)</code> <code class='argument'>value</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Use the file descriptor <code>fd</code> for UDP. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>bind</code> + <dd class='body--doc'>Returns the parity of the integer <code>value</code>. If the + parity is odd 1 is returned. If it is even 0 is + returned. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_multicast_ttl + reflect </dt> - <dd><code><code class='datatype'>int</code> set_multicast_ttl(<code class='datatype'>int</code> <code class='argument'>ttl</code>)</code></dd> + <dd><code><code class='datatype'>int(0..)</code> reflect(<code class='datatype'>int</code> <code class='argument'>value</code>, <code class='datatype'>int(0..)</code> <code class='argument'>bits</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the time-to-live value of outgoing multicast packets - for this socket. + <dd class='body--doc'>Reverses the order of the low order <code>bits</code> number of bits + of the value <code>value</code>. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>ttl</code></dt> - <dd></dd><dd class='body--doc'>The number of router hops sent multicast packets should - survive. - It is very important for multicast packets to set the - smallest TTL possible. The default before calling this - function is 1 which means that multicast packets don't - leak from the local network unless the user program - explicitly requests it. - See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL - and IPPROTO_IPV6 IPV6_MULTICAST_HOPS. - </dd> + <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function did not support IPv6 in Pike 7.8 and earlier. + <dd class='body--doc'>Any higher order bits of the value will be cleared. + The returned value will thus be unsigned. </dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>add_membership()</code> + <dd class='body--doc'><code>reverse()</code>, <code>swap_word()</code>, <code>swap_long()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_nonblocking + swap_long </dt> - <dd><code><code class='object unresolved'>UDP</code> set_nonblocking()</code> - <code><code class='object unresolved'>UDP</code> set_nonblocking(<code class='datatype'>function</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>), <code class='datatype'>mixed</code> ... :<code class='datatype'>void</code>) <code class='argument'>read_cb</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> + <dd><code><code class='datatype'>int(32bit)</code> swap_long(<code class='datatype'>int(32bit)</code> <code class='argument'>i</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set this object to nonblocking mode. - If <code>read_cb</code> and <code>extra_args</code> are specified, they will be passed on - to <code>set_read_callback()</code>. + <dd class='body--doc'>Swaps the upper and lower word in a longword, and the upper and + lower bytes in the words. Simply put, the bytes are reversed. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The called object. + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>swap_word()</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_read_callback + swap_word </dt> - <dd><code><code class='object unresolved'>UDP</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mapping</code>(<code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>string</code>), <code class='datatype'>mixed</code> ... :<code class='datatype void'>void</code>) <code class='argument'>read_cb</code>, <code class='datatype'>mixed</code> ... <code class='argument'>extra_args</code>)</code></dd> + <dd><code><code class='datatype'>int(16bit)</code> swap_word(<code class='datatype'>int(16bit)</code> <code class='argument'>i</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The <code>read_cb</code> function will receive a mapping similar to the mapping - returned by <code>read()</code>: - <table class='box'><tr><td><code><code class='key'>"data"</code> : <code class='datatype'>string</code></code></td><td>Received data. - </td></tr> - <tr><td><code><code class='key'>"ip"</code> : <code class='datatype'>string</code></code></td><td>Data was sent from this IP. - </td></tr> - <tr><td><code><code class='key'>"port"</code> : <code class='datatype'>int</code></code></td><td>Data was sent from this port. - </td></tr> - </table> + <dd class='body--doc'>Swaps the upper and lower byte in a word. </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>The called object. - </dd> + <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read()</code> + <dd class='body--doc'><code>swap_long()</code> </dd></dl> - + <dl><dt><h2 class='header'>Class Int.Inf</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The type of <code>Int.inf</code>. Do not create more instances of this. + </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Module Float</h2> + </dt><dd> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + DIGITS_10 + Constant + MIN_10_EXP + Constant + MAX_10_EXP + Constant + MIN + Constant + MAX + Constant + EPSILON + </dt> + <dd><code><code class='datatype'>constant</code> Float.<code class='constant'>DIGITS_10</code></code> + <code><code class='datatype'>constant</code> Float.<code class='constant'>MIN_10_EXP</code></code> + <code><code class='datatype'>constant</code> Float.<code class='constant'>MAX_10_EXP</code></code> + <code><code class='datatype'>constant</code> Float.<code class='constant'>MIN</code></code> + <code><code class='datatype'>constant</code> Float.<code class='constant'>MAX</code></code> + <code><code class='datatype'>constant</code> Float.<code class='constant'>EPSILON</code></code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>These constants define the limits for floats on the current + architecture: + <dl class='group--doc'><dt>DIGITS_10</dt> + <dd>The number of decimal digits that can be represented. Any number + with this many decimal digits can be stored in a float and + converted back to decimal form without change. <code>DIGITS_10</code> is + not less than <code class='expr'>6</code>. + </dd> + <dt>MIN_10_EXP</dt> + <dt>MAX_10_EXP</dt> + <dd>Limits of the exponent in decimal base. 10 raised to any number + within this range can be represented in normalized form. + <code>MIN_10_EXP</code> is not greater than <code class='expr'>-37</code>. <code>MAX_10_EXP</code> is + not less than <code class='expr'>37</code>. + </dd> + <dt>MIN</dt> + <dd>The smallest normalized float greater than zero. It's not + greater than <code class='expr'>1e-37</code>. + </dd> + <dt>MAX</dt> + <dd>The largest finite float. It's not less than <code class='expr'>1e37</code>. + </dd> + <dt>EPSILON</dt> + <dd>The difference between 1 and the smallest value greater than 1 + that can be represented. It's not greater than <code class='expr'>1e-5</code>. + </dd> + </dl> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The size of the float type can be controlled when Pike is compiled + with the configure flags <code class='expr'>--with-double-precision</code> and + <code class='expr'>--with-long-double-precision</code>. The default is to use the + longest available float type that fits inside a pointer. + </dd></dl> + + <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - set_type + <dt class='head--type'>Constant + FLOAT_PRECISION + Constant + DOUBLE_PRECISION + Constant + LONG_DOUBLE_PRECISION </dt> - <dd><code><code class='object unresolved'>UDP</code> set_type(<code class='datatype'>int</code> <code class='argument'>sock_type</code>)</code> - <code><code class='object unresolved'>UDP</code> set_type(<code class='datatype'>int</code> <code class='argument'>sock_type</code>, <code class='datatype'>int</code> <code class='argument'>family</code>)</code></dd> + <dd><code><code class='datatype'>constant</code> Float.<code class='constant'>FLOAT_PRECISION</code></code> + <code><code class='datatype'>constant</code> Float.<code class='constant'>DOUBLE_PRECISION</code></code> + <code><code class='datatype'>constant</code> Float.<code class='constant'>LONG_DOUBLE_PRECISION</code></code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Sets socket type and protocol family. + <dd class='body--doc'>Tells which C compiler float type that is used for Pike floats. + Only one of these constants will exist (with the value <code class='expr'>1</code>) + at runtime. + <dl class='group--doc'><dt>FLOAT_PRECISION</dt> + <dd>The <code class='expr'>float</code> type of the C compiler is used. + </dd> + <dt>DOUBLE_PRECISION</dt> + <dd>The <code class='expr'>double</code> type of the C compiler is used. + </dd> + <dt>LONG_DOUBLE_PRECISION</dt> + <dd>The <code class='expr'>long double</code> type of the C compiler is used. + </dd> + </dl> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The float type can be controlled when Pike is compiled with the + configure flags <code class='expr'>--with-double-precision</code> and + <code class='expr'>--with-long-double-precision</code>. The default is to use the + longest available float type that fits inside a pointer. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - wait + isnan </dt> - <dd><code><code class='datatype'>bool</code> wait(<code class='datatype'>int</code>|<code class='datatype'>float</code> <code class='argument'>timeout</code>)</code></dd> + <dd><code><code class='datatype'>bool</code> isnan(<code class='datatype'>float</code> <code class='argument'>x</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Check for data and wait max. <code>timeout</code> seconds. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Returns <code class='expr'>1</code> if data are ready, <code class='expr'>0</code> (zero) otherwise. + <dd class='body--doc'>Returns true if <code>x</code> is nan. </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Module Stdio.Terminfo</h2> + </dd></dl><dl><dt><h2 class='header'>Module Function</h2> </dt><dd> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - getFallbackTerm + Y </dt> - <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>Termcap</code> getFallbackTerm(<code class='datatype'>string</code> <code class='argument'>term</code>)</code></dd> + <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) Y(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an object describing the fallback terminal for the terminal - <code>term</code>. This is usually equvivalent to <code>Stdio.Terminfo.getTerm("dumb")</code>. + <dd class='body--doc'>The dreaded fixpoint combinator "Y". + The Y combinator is useful when writing recursive lambdas. It + converts a lambda that expects a self-reference as its first argument + into one which can be called without this argument. </dd> - + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>This example creates a lambda that computes the faculty function. + <pre><code>Function.Y(lambda(function f, int n) { return n>1? n*f(n-1) : 1; }) + </code></pre> + </pre></dd> <dt class='head--doc'>See also</dt> - <dd class='body--doc'>Stdio.Terminfo.getTerm + <dd class='body--doc'><code>this_function</code> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - getTerm + call_callback </dt> - <dd><code><code class='object unresolved'>Termcap</code> getTerm(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>term</code>)</code></dd> + <dd><code><code class='datatype'>void</code> call_callback(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code> ... <code class='argument'>args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns an object describing the terminal term. If term is not specified, it will - default to <code>getenv("TERM")</code> or if that fails to "dumb". - Lookup of terminal information will first be done in the systems terminfo - database, and if that fails in the termcap database. If neither database exists, a - hardcoded entry for "dumb" will be used. + <dd class='body--doc'>Call a callback function, but send throws from the callback + function (ie, errors) to master()->handle_error. + Also accepts if f is zero (0) without error. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'>Stdio.Terminfo.getTerminfo, Stdio.Terminfo.getTermcap, Stdio.getFallbackTerm - </dd></dl> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code>Functions.call_callback(the_callback,some,arguments);</code></pre>equals + <pre><code>{ + mixed err=catch { if (the_callback) the_callback(some,arguments); }; + if (err) master()->handle_error(err); + } + </code></pre>(Approximately, since call_callback also calls handle_error + if 0 were thrown.) + </pre></dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - getTermcap + composite </dt> - <dd><code><code class='object unresolved'>Termcap</code> getTermcap(<code class='datatype'>string</code> <code class='argument'>term</code>)</code></dd> + <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) composite(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) ... <code class='argument'>f</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the terminal description object for <code>term</code> from the - systems termcap database. Returns 0 if not found. + <dd class='body--doc'>Creates a composite function of the provided functions. The + composition function of f() and g(), q(x)=f(g(x)), is created by + <code class='expr'>function q = Function.composite(f, g);</code>. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'>Stdio.Terminfo.getTerm, Stdio.Terminfo.getTerminfo - </dd></dl> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code>map(input/",", + Function.composite(String.trim, upper_case)); + </code></pre> + </pre></dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - getTerminfo + curry </dt> - <dd><code><code class='object unresolved'>Terminfo</code> getTerminfo(<code class='datatype'>string</code> <code class='argument'>term</code>)</code></dd> + <dd><code><code class='datatype'>function</code>(<code class='datatype'>mixed</code> ... :<code class='datatype'>function</code>(<code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>|<code class='datatype'>void</code>)) curry(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the terminal description object for <code>term</code> from the - systems terminfo database. Returns 0 if not found. + <dd class='body--doc'>Partially evaluate a function call. + This function allows N parameters to be given to a function taking + M parameters (N<=M), yielding a new function taking M-N parameters. + What is actually returned from this function is a function taking N + parameters, and returning a function taking M-N parameters. </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'>Stdio.Terminfo.getTerm, Stdio.Terminfo.getTermcap - </dd></dl> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>This example creates a function adding 7 to its argument. + <pre><code>Function.curry(`+)(7)</code></pre> + </pre></dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - is_tty + defined </dt> - <dd><code><code class='datatype'>int</code> is_tty()</code></dd> + <dd><code><code class='datatype'>string</code> defined(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>fun</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns 1 if <code>Stdio.stdin</code> is connected to an interactive - terminal that can handle backspacing, carriage return without - linefeed, and the like. + <dd class='body--doc'>Returns a string with filename and linenumber where <code>fun</code> + was defined. + Returns <code class='expr'>0</code> (zero) when no line can be found, e.g. for + builtin functions and functions in destructed objects. </dd></dl> - <dl><dt><h2 class='header'>Class Stdio.Terminfo.MetaTerminfoDB</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><code>TerminfoDB</code> that merges several directorys. - </dd></dl> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + splice_call </dt> - <dd><code>Stdio.Terminfo.MetaTerminfoDB Stdio.Terminfo.MetaTerminfoDB(<code class='datatype'>array</code>(<code class='object unresolved'>TerminfoDB</code>|<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>dbs</code>)</code></dd> + <dd><code><code class='datatype'>mixed</code> splice_call(<code class='datatype'>array</code> <code class='argument'>args</code>, <code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code>|<code class='datatype'>void</code> ... <code class='argument'>extra</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Create a new Meta <code>TerminfoDB</code>. + <dd class='body--doc'>Calls the given function with the <code>args</code> array plus the optional + extra arguments as its arguments and returns the result. + Most useful in conjunction with <code>map</code>, and particularly in combination + with <code>sscanf</code> with <code class='expr'>"...%{...%}..."</code> scan strings (which indeed + was what it was invented for in the first place). </dd> - <dt class='head--doc'>Parameter <code class='parameter'>dbs</code></dt> - <dd></dd><dd class='body--doc'>Array with elements in priority order. Elements may be either - <table class='box'><tr><td><code><code class='object unresolved'>TerminfoDB</code></code></td><td>An active <code>TerminfoDB</code>. - </td></tr> - <tr><td><code><code class='datatype'>string</code></code></td><td>A directory that may exist and contain a terminfo database. - </td></tr> - </table> + <dt class='head--doc'>Parameter <code class='parameter'>args</code></dt> + <dd></dd><dd class='body--doc'>The first arguments the function <code>f</code> expects. </dd> - + <dt class='head--doc'>Parameter <code class='parameter'>f</code></dt> + <dd></dd><dd class='body--doc'>The function to apply the arguments on. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>extra</code></dt> + <dd></dd><dd class='body--doc'>Optional extra arguments to send to <code>f</code>. + </dd> <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>If the resulting set of <code>TerminfoDB</code>'s is empty, - the object will be destructed. - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.Termcap</h2> + <dd class='body--doc'>Whatever the supplied function <code>f</code> returns. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code>class Product(string name, string version) + { + string _sprintf() + { + return sprintf("Product(%s/%s)", name, version); + } + } + map(({ ({ "pike", "7.1.11" }), + ({ "whitefish", "0.1" }) }), + Function.splice_call, Product); + ({ /* 2 elements */ + Product(pike/7.1.11), + Product(whitefish/0.1) + }) + </code></pre> + </pre></dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + uncurry + </dt> + <dd><code><code class='datatype'>function</code>(<code class='datatype'>mixed</code> ... :<code class='datatype'>mixed</code>) uncurry(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function, given a function taking N parameters, returns a new + function taking N+1 parameters. The first argument will be + ignored. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code>> Function.uncurry(`+)(7,2,3) + Result: 5</code></pre> + </pre></dd></dl> + <dl><dt><h2 class='header'>Class Function.bind</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Termcap terminal description object. - </dd></dl> + <dd class='body--doc'>Partially evaluate a function call. + This function returns a function that when called will do the + specified argument mapping. It is similar to <code>curry</code>, but allows + more dynamic changes of the argument evaluation, you can leave the + first argument unspecified while setting others, or simply change + the argument order. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>f</code></dt> + <dd></dd><dd class='body--doc'>The first argument is the function to be called. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>bind_args</code></dt> + <dd></dd><dd class='body--doc'>All other arguments are either a generic value, which will be sent + as-is to the function or one of the placeholder values defined in + <code>Function.Placeholder</code>, or one of your own implementation (inherit + <code>Function.Placeholder.Base</code> and implement the value function.). + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>This example returns a function that limits the given argument + to between 0 and 99. + <pre><code>import Function.Placeholder; + function clip = Function.bind(limit, 0, arg0, 100); + </code></pre> + </pre></dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Variable - aliases + f + Variable + bind_args </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) Stdio.Terminfo.Termcap.aliases</code></dd> + <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) Function.bind.f</code> + <code><code class='datatype'>array</code>(<code class='datatype'>mixed</code>) Function.bind.bind_args</code></dd> </dl>
2167: <dt class='head--type'>Method create </dt> - <dd><code>Stdio.Terminfo.Termcap Stdio.Terminfo.Termcap(<code class='datatype'>string</code> <code class='argument'>cap</code>, <code class='object unresolved'>TermcapDB</code>|<code class='datatype'>void</code> <code class='argument'>tcdb</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>maxrecurse</code>)</code></dd> + <dd><code>Function.bind Function.bind(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>, <code class='datatype'>mixed</code> ... <code class='argument'>bind_args</code>)</code></dd> </dl> - + </dd></dl><dl><dt><h2 class='header'>Module Function.Placeholder</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Placeholder arguments for <code>Function.bind</code> + </dd></dl> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Constant + arg0 + Constant + arg1 + Constant + arg2 + Constant + arg3 + Constant + arg4 + Constant + arg5 + Constant + arg6 + Constant + arg7 + Constant + arg8 + Constant + arg9 + </dt> + <dd><code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg0</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg1</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg2</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg3</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg4</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg5</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg6</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg7</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg8</code></code> + <code><code class='datatype'>constant</code> Function.Placeholder.<code class='constant'>arg9</code></code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>arg<n> will return an instance of <code>Arg</code> that returns the n:th arg. + For convenience for c++11 developers _0, _1 etc also works. + Note that arg0 is the first argument, not arg1 + </dd></dl> + + <hr /> <dl class='group--doc'> - + <dt class='head--type'>Variable + rest + </dt> + <dd><code><code class='object unresolved'>Arg</code> Function.Placeholder.rest</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return all arguments not used by any <code>Arg</code> or <code>Splice</code>. + Unlike <code>Splice</code> this will return non-continous unused arguments. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>This creates a version of call_out that has the function argument as + the last argument + <pre><code>import Function.Placeholder; + Function.bind( call_out, Arg(-1), rest)</code></pre> + </pre></dd></dl> + <dl><dt><h2 class='header'>Class Function.Placeholder.Arg</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Arg(x) returns the value of argument X + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>Function.Placeholder.Arg Function.Placeholder.Arg(<code class='datatype'>int</code> <code class='argument'>num</code>)</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Inherit - TermMachine + Base </dt> - <dd><code>inherit TermMachine : TermMachine</code></dd> + <dd><code>inherit Base : Base</code></dd> </dl> <hr /> <dl class='group--doc'> - + <dt class='head--type'>Variable + num + </dt> + <dd><code><code class='datatype'>int</code> Function.Placeholder.Arg.num</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - tputs + value </dt> - <dd><code><code class='datatype'>string</code> tputs(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> + <dd><code><code class='datatype'>mixed</code> value(<code class='object unresolved'>bind</code> <code class='argument'>x</code>, <code class='datatype'>array</code> <code class='argument'>args</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Put termcap string + <dd class='body--doc'>The function that is called to return the argument value. </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.TermcapDB</h2> + </dd></dl><dl><dt><h2 class='header'>Class Function.Placeholder.Expr</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Termcap database - </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.Terminfo</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Terminfo terminal description object + <dd class='body--doc'>Expr(x) returns the result of calling <code>x</code>. + The function will be passed the list of arguments. + If _splice is true, zero or more argument is returned in an array + Function.Placeholder.arg1 is thus more or less equivalent to + <pre><code>Expr(lambda(array args){return args[1];}); + </code></pre> </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Variable - aliases + func + Variable + _splice </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>string</code>) Stdio.Terminfo.Terminfo.aliases</code></dd> + <dd><code><code class='datatype'>function</code>(:<code class='datatype void'>void</code>) Function.Placeholder.Expr.func</code> + <code><code class='datatype'>void</code>|<code class='object unresolved'>bool</code> Function.Placeholder.Expr._splice</code></dd> </dl>
2214: <dt class='head--type'>Method create </dt> - <dd><code>Stdio.Terminfo.Terminfo Stdio.Terminfo.Terminfo(<code class='datatype'>string</code> <code class='argument'>filename</code>)</code></dd> + <dd><code>Function.Placeholder.Expr Function.Placeholder.Expr(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>func</code>, <code class='datatype'>void</code>|<code class='object unresolved'>bool</code> <code class='argument'>_splice</code>)</code></dd> </dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Inherit - TermMachine + Base </dt> - <dd><code>inherit TermMachine : TermMachine</code></dd> + <dd><code>inherit Base : Base</code></dd> </dl> - + </dd></dl><dl><dt><h2 class='header'>Class Function.Placeholder.Splice</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Splice(from) adds all arguments starting with argument number <code class='expr'>from</code>, + optionally ending with end. + Equivalent to <code class='expr'>args[from .. end]</code> + </dd></dl> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>Function.Placeholder.Splice Function.Placeholder.Splice(<code class='datatype'>int</code> <code class='argument'>from</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>end</code>)</code></dd> + </dl> - + <hr /> <dl class='group--doc'> - + <dt class='head--type'>Variable + from + Variable + end + </dt> + <dd><code><code class='datatype'>int</code> Function.Placeholder.Splice.from</code> + <code><code class='datatype'>void</code>|<code class='datatype'>int</code> Function.Placeholder.Splice.end</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + Base + </dt> + <dd><code>inherit Base : Base</code></dd> + </dl> + </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Module Program</h2> + </dt><dd> + + <hr /> + <dl class='group--doc'> <dt class='head--type'>Method - tputs + all_inherits </dt> - <dd><code><code class='datatype'>string</code> tputs(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function - </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.Terminfo.TerminfoDB</h2> - </dt><dd><dl class='group--doc'> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>program</code>) all_inherits(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> + <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Terminfo database for a single directory. - </dd></dl></dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.Readline</h2> - </dt><dd> + <dd class='body--doc'>Enumerate all programs this program inherits, directly or indirectly. + Similar to inherit_tree() but returns a flat array. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>> class a{} + > class b{} + > class c{ inherit a; } + > class d{ inherit b; inherit c; } + > Program.inherit_tree(d); + Result: ({ /* 3 elements */ + b, + c, + a + }) + </pre></dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - add_to_kill_ring + defined </dt> - <dd><code><code class='datatype'>void</code> add_to_kill_ring(<code class='datatype'>string</code> <code class='argument'>s</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>string</code> defined(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns a string with filename and linenumber describing where + the program <code>p</code> was defined. + The returned string is of the format <code class='expr'>"filename:linenumber"</code>. + If it cannot be determined where the program was defined, <code class='expr'>0</code> + (zero) will be returned. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + defined </dt> - <dd><code>Stdio.Readline Stdio.Readline(<code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>infd</code>, <code class='datatype'>object</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>interm</code>, <code class='datatype'>object</code>|<code class='datatype'>void</code> <code class='argument'>outfd</code>, <code class='datatype'>object</code>|<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>outterm</code>)</code></dd> + <dd><code><code class='datatype'>string</code> defined(<code class='datatype'>program</code> <code class='argument'>x</code>, <code class='datatype'>string</code> <code class='argument'>identifier</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Creates a Readline object, that takes input from <code>infd</code> and has output - on <code>outfd</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>infd</code></dt> - <dd></dd><dd class='body--doc'>Defaults to <code>Stdio.stdin</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>interm</code></dt> - <dd></dd><dd class='body--doc'>Defaults to <code>Stdio.Terminfo.getTerm()</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>outfd</code></dt> - <dd></dd><dd class='body--doc'>Defaults to <code>infd</code>, unless <code>infd</code> is 0, in which case - <code>outfd</code> defaults to <code>Stdio.stdout</code>. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>outterm</code></dt> - <dd></dd><dd class='body--doc'>Defaults to <code>interm</code>. + <dd class='body--doc'>Returns a string with filename and linenumber where <code>idenfifier</code> + in <code>x</code> was defined. + Returns <code class='expr'>0</code> (zero) when no line can be found, e.g. for + builtin functions. + If <code>idenfier</code> can not be found in <code>x</code> this function returns + where the program is defined. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - delete + implements </dt> - <dd><code><code class='datatype'>void</code> delete(<code class='datatype'>int</code> <code class='argument'>p1</code>, <code class='datatype'>int</code> <code class='argument'>p2</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>int</code> implements(<code class='datatype'>program</code> <code class='argument'>prog</code>, <code class='datatype'>program</code> <code class='argument'>api</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns 1 if <code>prog</code> implements <code>api</code>. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - delta_history + inherit_list </dt> - <dd><code><code class='datatype'>void</code> delta_history(<code class='datatype'>int</code> <code class='argument'>d</code>)</code></dd> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>program</code>) inherit_list(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Changes the line to a line from the history <code>d</code> steps from the - current entry (0 being the current line, negative values older, - and positive values newer). - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Only effective if you have a history object. + <dd class='body--doc'>Returns an array with the programs that <code>p</code> has inherited. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - edit + inherit_tree </dt> - <dd><code><code class='datatype'>string</code> edit(<code class='datatype'>string</code> <code class='argument'>data</code>, <code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>local_prompt</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>attrs</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function - </dd></dl> + <dd><code><code class='datatype'>array</code> inherit_tree(<code class='datatype'>program</code> <code class='argument'>p</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Recursively builds a inheritance tree by + fetching programs inheritance lists. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns an array with programs or arrays + as elements. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>> class a{} + > class b{} + > class c{ inherit a; } + > class d{ inherit b; inherit c; } + > Program.inherit_tree(d); + Result: ({ /* 3 elements */ + d, + ({ /* 1 element */ + program + }), + ({ /* 2 elements */ + c, + ({ /* 1 element */ + program + }) + }) + }) + </pre></dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - enable_history + inherits </dt> - <dd><code><code class='datatype'>void</code> enable_history(<code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='object unresolved'>History</code>|<code class='datatype'>int</code> <code class='argument'>hist</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>int</code> inherits(<code class='datatype'>program</code>|<code class='datatype'>object</code> <code class='argument'>child</code>, <code class='datatype'>program</code> <code class='argument'>parent</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns 1 if <code>child</code> has inherited <code>parent</code>. </dd></dl> - + </dd></dl><dl><dt><h2 class='header'>Module ADT</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Various Abstract Data Types. + </dd></dl> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Inherit + _ADT + </dt> + <dd><code>inherit _ADT : _ADT</code></dd> + </dl> + <dl><dt><h2 class='header'>Class ADT.BitBuffer</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Implements a FIFO bit buffer, i.e. a buffer that operates on bits + instead of bytes. It is not designed for performance, but as a way + to handle complicated file formats and other standards where you + may need to work on unaligned data units of sub byte size, without + having to fry your brain while keeping track of all the bits + yourself. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre>> ADT.BitBuffer b=ADT.BitBuffer(); + > b->put1(2); + (1) Result: ADT.BitBuffer(11) + > b->put0(15); + (2) Result: ADT.BitBuffer("\300\0"0) + > b->drain(); + (3) Result: "\300\0" + > sizeof(b); + (4) Result: 1 + </pre></dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - eof + _sizeof </dt> - <dd><code><code class='datatype'>void</code> eof()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>int</code> sizeof( ADT.BitBuffer arg )</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><code>sizeof()</code> will return the number of bits in the buffer. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get_history + create </dt> - <dd><code><code class='object unresolved'>History</code> get_history()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code>ADT.BitBuffer ADT.BitBuffer(<code class='datatype'>void</code>|<code class='datatype'>string</code> <code class='argument'>data</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The buffer can be initialized with initial data during creation. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get_input_controller + drain </dt> - <dd><code><code class='object unresolved'>InputController</code> get_input_controller()</code></dd> + <dd><code><code class='datatype'>string</code> drain()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>get current input control object - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Terminal input controller object + <dd class='body--doc'>Drains the buffer of all full (8-bits wide) bytes. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get_output_controller + feed </dt> - <dd><code><code class='object unresolved'>OutputController</code> get_output_controller()</code></dd> + <dd><code><code class='object unresolved'>this_program</code> feed(<code class='datatype'>string</code> <code class='argument'>x</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>get current output control object - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Terminal output controller object + <dd class='body--doc'>Adds full bytes to the buffer. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - get_prompt + get </dt> - <dd><code><code class='datatype'>string</code> get_prompt()</code></dd> + <dd><code><code class='datatype'>int</code> get(<code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the current prompt string. + <dd class='body--doc'>Get <code>bits</code> from the buffer. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>Throws an error in case of data underflow. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The bits are extracted with the most significant bit first. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - getcursorpos + put </dt> - <dd><code><code class='datatype'>int</code> getcursorpos()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='object unresolved'>this_program</code> put(<code class='datatype'>int</code> <code class='argument'>value</code>, <code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Put <code>bits</code> number of bits with the value <code>value</code> into the + buffer. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><code>value</code> must not be larger than what can be stored with the + number of bits given in <code>bits</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The bits are added to the buffer with the most significant + bit first. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - getmark + put0 </dt> - <dd><code><code class='datatype'>int</code> getmark()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='object unresolved'>this_program</code> put0(<code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Put <code>bits</code> number of 0 bits into the buffer. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - gettext + put1 </dt> - <dd><code><code class='datatype'>string</code> gettext()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='object unresolved'>this_program</code> put1(<code class='datatype'>int</code> <code class='argument'>bits</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Put <code>bits</code> number of 1 bits into the buffer. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - history + read </dt> - <dd><code><code class='datatype'>void</code> history(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>string</code> read(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>bytes</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads <code>bytes</code> (or less) bytes from the buffer and returns as + string. </dd></dl> - + </dd></dl><dl><dt><h2 class='header'>Class ADT.CircularList</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This is an circular list implemented by an array. It has a constant time + complexity for pop and push. It has a limited max size but it can be + increased with the method allocate. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - insert + _equal </dt> - <dd><code><code class='datatype'>void</code> insert(<code class='datatype'>string</code> <code class='argument'>s</code>, <code class='datatype'>int</code> <code class='argument'>p</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>bool</code> equal(ADT.CircularList from, <code class='datatype'>mixed</code> <code class='argument'>coll</code>)</code></dd> + + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <tt>true</tt> if the object <code>coll</code> is a <code>CircularList</code> + and contains the same values in the same order. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - kill + _get_iterator </dt> - <dd><code><code class='datatype'>void</code> kill(<code class='datatype'>int</code> <code class='argument'>p1</code>, <code class='datatype'>int</code> <code class='argument'>p2</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code>ADT.CircularList a; + foreach( a; index; value ) or </code><code><code class='object unresolved'>CircularListIterator</code> _get_iterator(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>ind</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Create and initiate a new CircularListIterator that could be used + to iterate over this list. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>ind</code></dt> + <dd></dd><dd class='body--doc'>If an <code>ind</code> value is supplied the iterator will be positioned at + that index. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>An iterator. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - kill_ring_yank + _indices </dt> - <dd><code><code class='datatype'>string</code> kill_ring_yank()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>array</code> indices( ADT.CircularList arg )</code></dd> + + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The indices in this list as an array. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - list_completions + _insert_element </dt> - <dd><code><code class='datatype'>void</code> list_completions(<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>c</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>void</code> _insert_element(<code class='datatype'>int</code> <code class='argument'>index</code>, <code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Insert an element in the list at the position <code>index</code>, the value + at the position <code>index</code> and all above will have their index increased + by one. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> + <dd></dd><dd class='body--doc'>The index to insert the value at. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>The new value. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error if the index is out of range. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - message + _remove_element </dt> - <dd><code><code class='datatype'>void</code> message(<code class='datatype'>string</code> <code class='argument'>msg</code>)</code></dd> + <dd><code><code class='datatype'>mixed</code> _remove_element(<code class='datatype'>int</code> <code class='argument'>index</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Print a message to the output device + <dd class='body--doc'>Remove the values at index <code>index</code> from the list. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> + <dd></dd><dd class='body--doc'>The index to remove. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The removed value. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error if the index is out of range. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - newline + _search </dt> - <dd><code><code class='datatype'>string</code> newline()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>int</code> search(ADT.CircularList from, <code class='datatype'>mixed</code> <code class='argument'>value</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>start</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Search the list for a specific value. Return the index of the first + value that is equal to <code>value</code>. If no value was found <code class='expr'>UNDEFINED</code> + is returned instead + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>The value to find + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>start</code></dt> + <dd></dd><dd class='body--doc'>If a start value is supplied it will start searching at the index + <code>start</code>. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the index of the found value or <code class='expr'>UNDEFINED</code>. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error if the start is out of range. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - pointmark + _sizeof </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) pointmark()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>int</code> sizeof( ADT.CircularList arg )</code></dd> + + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The number of elements in this list. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - read + _values </dt> - <dd><code><code class='datatype'>string</code> read(<code class='datatype'>string</code>|<code class='datatype'>void</code> <code class='argument'>prompt</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>attrs</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>array</code> values( ADT.CircularList arg )</code></dd> + + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The values in this list as an array. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - redisplay + `+ </dt> - <dd><code><code class='datatype'>void</code> redisplay(<code class='datatype'>int</code> <code class='argument'>clear</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>nobackup</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='object unresolved'>CircularList</code> res = <code class='class'>ADT.CircularList()</code> + <code class='class'>coll</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Addition operator + Append the content of this CircularList and @<code>coll</code> and + return the results as a new <code>CircularList</code>. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>coll</code></dt> + <dd></dd><dd class='body--doc'>The lists to append to this list + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The result of the append as a new <code>CircularList</code>. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - region + `[] </dt> - <dd><code><code class='datatype'>string</code> region(<code class='datatype'>int</code> ... <code class='argument'>args</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>mixed</code> res = <code class='class'>ADT.CircularList()</code>[ <code class='class'>index</code> ]</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Index operator + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> + <dd></dd><dd class='body--doc'>The index to get the value for, could be negative to index from the end. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The value at the index <code>index</code> + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error if the index is out of range. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_blocking + `[]= </dt> - <dd><code><code class='datatype'>void</code> set_blocking()</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='class'>ADT.CircularList()</code>[ <code class='class'>index</code> ] = <code class='class'>value</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Index assign operator. + Set the value at the index <code>index</code> to be <code>value</code> + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>index</code></dt> + <dd></dd><dd class='body--doc'>The index to set + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>The new value + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The new value at the index <code>index</code> + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error if the index is out of range. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_echo + add </dt> - <dd><code><code class='datatype'>void</code> set_echo(<code class='datatype'>int</code> <code class='argument'>onoff</code>)</code></dd> + <dd><code><code class='datatype'>void</code> add(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set text echo on or off. + <dd class='body--doc'>Add a value at the front of the list </dd> - <dt class='head--doc'>Parameter <code class='parameter'>onoff</code></dt> - <dd></dd><dd class='body--doc'>1 for echo, 0 for no echo. + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>The value to add. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error if the list is full. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_nonblocking + allocate </dt> - <dd><code><code class='datatype'>void</code> set_nonblocking(<code class='datatype'>function</code>(:<code class='datatype void'>void</code>) <code class='argument'>f</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>void</code> allocate(<code class='datatype'>int</code> <code class='argument'>elements</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Increase the maxsize of the CircularlList. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>elements</code></dt> + <dd></dd><dd class='body--doc'>Add this number of new elements to the list. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_prompt + cast </dt> - <dd><code><code class='datatype'>string</code> set_prompt(<code class='datatype'>string</code> <code class='argument'>newp</code>, <code class='datatype'>array</code>(<code class='datatype'>string</code>)|<code class='datatype'>void</code> <code class='argument'>newattrs</code>)</code></dd> + <dd><code>(<code class='datatype'>array</code>)ADT.CircularList()</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the prompt string. + <dd class='body--doc'>Cast operator. </dd> - <dt class='head--doc'>Parameter <code class='parameter'>newp</code></dt> - <dd></dd><dd class='body--doc'>New prompt string + <dt class='head--doc'>Parameter <code class='parameter'>type</code></dt> + <dd></dd><dd class='body--doc'>Casts to this type. + Casts to the following types are supported: + <table class='box'><tr><td><code><code class='key'>"array"</code></code></td><td>Cast the content of this list to an array. + </td></tr> + </table> </dd> - <dt class='head--doc'>Parameter <code class='parameter'>newattrs</code></dt> - <dd></dd><dd class='body--doc'>Terminal attributes + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>An array with the contents of this list. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - setcursorpos + clear </dt> - <dd><code><code class='datatype'>int</code> setcursorpos(<code class='datatype'>int</code> <code class='argument'>p</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>void</code> clear()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Clear the contents of the list. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - setmark + create </dt> - <dd><code><code class='datatype'>int</code> setmark(<code class='datatype'>int</code> <code class='argument'>p</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code>ADT.CircularList ADT.CircularList(<code class='datatype'>array</code>|<code class='datatype'>int</code> <code class='argument'>arg</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Creates a new <code>CircularList</code> around the array arg or a new + <code>CircularList</code> with the maximum size of arg. </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - write + delete_value </dt> - <dd><code><code class='datatype'>void</code> write(<code class='datatype'>string</code> <code class='argument'>msg</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>word_wrap</code>)</code></dd> - <dt class='head--fixme'>FIXME</dt> - <dd class='body--fixme'>Document this function + <dd><code><code class='datatype'>int</code> delete_value(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove the first occurrence of the value <code>value</code> from the list. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>The value to remove from the list. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The index of the removed element or -1 if there was no value to + remove. </dd></dl> - <dl><dt><h2 class='header'>Class Stdio.Readline.DefaultEditKeys</h2> - </dt><dd> + - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - backward_char + first </dt> - <dd><code><code class='datatype'>void</code> backward_char()</code></dd> - </dl> + <dd><code><code class='object unresolved'>CircularListIterator</code> first()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Create and initiate a new CircularListIterator that could be used + to iterate over this list. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>An iterator positioned at the first element in the list. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - backward_delete_char + is_empty </dt> - <dd><code><code class='datatype'>void</code> backward_delete_char()</code></dd> - </dl> + <dd><code><code class='datatype'>bool</code> is_empty()</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code class='expr'>1</code> if the list is empty otherwise <code class='expr'>0</code>. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - backward_kill_word + last </dt> - <dd><code><code class='datatype'>void</code> backward_kill_word()</code></dd> - </dl> + <dd><code><code class='object unresolved'>CircularListIterator</code> last()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Create and initiate a new CircularListIterator that could be used + to iterate over this list. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>An iterator positioned after the last element in the list. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - backward_word + max_size </dt> - <dd><code><code class='datatype'>void</code> backward_word()</code></dd> - </dl> + <dd><code><code class='datatype'>int</code> max_size()</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the maximal size of this list. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - beginning_of_line + peek_back </dt> - <dd><code><code class='datatype'>void</code> beginning_of_line()</code></dd> - </dl> + <dd><code><code class='datatype'>mixed</code> peek_back()</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The value at the back of the list but do not remove it from the list. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - capitalize_word + peek_front </dt> - <dd><code><code class='datatype'>void</code> capitalize_word()</code></dd> - </dl> + <dd><code><code class='datatype'>mixed</code> peek_front()</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The value at the front of the list but do not remove it from the list. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - clear_screen + pop_back </dt> - <dd><code><code class='datatype'>void</code> clear_screen()</code></dd> - </dl> + <dd><code><code class='datatype'>mixed</code> pop_back()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove the value at the back of the list and return it. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The value at the back of the list. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + pop_front </dt> - <dd><code>Stdio.Readline.DefaultEditKeys Stdio.Readline.DefaultEditKeys(<code class='datatype'>object</code> <code class='argument'>readline</code>)</code></dd> - </dl> + <dd><code><code class='datatype'>mixed</code> pop_front()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove the value at the front of the list and return it. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The value at the front of the list. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - delete_char + push_back </dt> - <dd><code><code class='datatype'>void</code> delete_char()</code></dd> - </dl> + <dd><code><code class='datatype'>void</code> push_back(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a new value at the end of the list. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>The value to add. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - delete_char_or_eof + push_front </dt> - <dd><code><code class='datatype'>void</code> delete_char_or_eof()</code></dd> - </dl> + <dd><code><code class='datatype'>void</code> push_front(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a new value at the end of the list. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>The value to add. + </dd></dl> + <dl><dt><h2 class='header'>Class ADT.CircularList.CircularListIterator</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This is the iterator for the CircularList. It implements the + IndexIterator and the OutputIterator. + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - down_history + _equal </dt> - <dd><code><code class='datatype'>void</code> down_history()</code></dd> - </dl> + <dd><code><code class='datatype'>bool</code> equal(ADT.CircularList.CircularListIterator from, <code class='datatype'>mixed</code> <code class='argument'>iter</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Compare this iterator with another iterator. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>iter</code></dt> + <dd></dd><dd class='body--doc'>The iterator to compare with + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <tt>true</tt> if both iterators iterates over the same + objects and are positioned at the same spot. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - downcase_word + `! </dt> - <dd><code><code class='datatype'>void</code> downcase_word()</code></dd> - </dl> + <dd><code><code class='datatype'>bool</code> res = !<code class='class'>ADT.CircularList.CircularListIterator()</code></code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <tt>false</tt> if the iterator has reached the end. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - end_of_line + `+ </dt> - <dd><code><code class='datatype'>void</code> end_of_line()</code></dd> - </dl> + <dd><code><code class='object unresolved'>CircularListIterator</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> + <code class='class'>steps</code></code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Move the iterator <code>steps</code> steps forward (negative value on <code>steps</code> + will cause the iterator to move backwards) and return the result + as a new iterator. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>A new iterator positioned <code>steps</code> steps forward. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - forward_char + `+= </dt> - <dd><code><code class='datatype'>void</code> forward_char()</code></dd> - </dl> + <dd><code><code class='class'>ADT.CircularList.CircularListIterator()</code> += <code class='class'>steps</code></code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Move this iterator <code>steps</code> steps forward (negative value on <code>steps</code> + will cause the iterator to move backwards) and return the result. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This iterator positioned <code>steps</code> steps forward. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - forward_word + `- </dt> - <dd><code><code class='datatype'>void</code> forward_word()</code></dd> - </dl> + <dd><code><code class='object unresolved'>CircularListIterator</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> - <code class='class'>steps</code></code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Move the iterator <code>steps</code> steps backwards (negative value on + <code>steps</code> will cause the iterator to move forwards) and return + the result as a new iterator. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>A new iterator positioned <code>steps</code> steps backwards. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - kill_line + `< </dt> - <dd><code><code class='datatype'>void</code> kill_line()</code></dd> - </dl> + <dd><code><code class='datatype'>bool</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> < <code class='class'>iter</code></code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Less then operator + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <tt>true</tt> if this iterator has a lower index + then <code>iter</code>. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - kill_region + `> </dt> - <dd><code><code class='datatype'>void</code> kill_region()</code></dd> - </dl> + <dd><code><code class='datatype'>bool</code> res = <code class='class'>ADT.CircularList.CircularListIterator()</code> > <code class='class'>iter</code></code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Greater then operator + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <tt>true</tt> if this iterator has a higher index + then <code>iter</code>. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - kill_ring_save + create </dt> - <dd><code><code class='datatype'>void</code> kill_ring_save()</code></dd> - </dl> + <dd><code>ADT.CircularList.CircularListIterator ADT.CircularList.CircularListIterator(<code class='datatype'>object</code> <code class='argument'>list</code>, <code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>start</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Creates a new iterator for the CircularList <code>list</code>. If <code>start</code> is + supplied it will try to position the iterator at <code>start</code>. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - kill_whole_line + distance </dt> - <dd><code><code class='datatype'>void</code> kill_whole_line()</code></dd> - </dl> + <dd><code><code class='datatype'>int</code> distance(<code class='datatype'>object</code> <code class='argument'>iter</code>)</code></dd> - + <dt class='head--doc'>Parameter <code class='parameter'>iter</code></dt> + <dd></dd><dd class='body--doc'>The iterator to measure the distance to. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns distance between this iterator and <code>iter</code>. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>An error if the two iterator could not be compared. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - kill_word + get_collection </dt> - <dd><code><code class='datatype'>void</code> kill_word()</code></dd> - </dl> + <dd><code><code class='object unresolved'>CircularList</code> get_collection()</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the CircularList this iterator currently iterates over. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - newline + has_next </dt> - <dd><code><code class='datatype'>void</code> newline()</code></dd> - </dl> + <dd><code><code class='datatype'>bool</code> has_next(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>steps</code>)</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <tt>true</tt> if it is possible to move <code>steps</code> steps + forwards, if <code>steps</code> weren't supplied it check if it is + possible to move one step forward. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - quoted_insert + has_previous </dt> - <dd><code><code class='datatype'>void</code> quoted_insert()</code></dd> - </dl> + <dd><code><code class='datatype'>bool</code> has_previous(<code class='datatype'>void</code>|<code class='datatype'>int</code> <code class='argument'>steps</code>)</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <tt>true</tt> if it is possible to move <code>steps</code> steps + backwards, if <code>steps</code> weren't supplied it check if it is + possible to move one step backward. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - redisplay + index </dt> - <dd><code><code class='datatype'>void</code> redisplay()</code></dd> - </dl> + <dd><code><code class='datatype'>int</code> index()</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The index at the current position. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - self_insert_command + set_value </dt> - <dd><code><code class='datatype'>void</code> self_insert_command(<code class='datatype'>string</code> <code class='argument'>str</code>)</code></dd> - </dl> + <dd><code><code class='datatype'>mixed</code> set_value(<code class='datatype'>mixed</code> <code class='argument'>val</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the value at the current position. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>val</code></dt> + <dd></dd><dd class='body--doc'>The new value + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the old value + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_default_bindings + value </dt> - <dd><code><code class='modifier'>protected</code> <code class='datatype'>void</code> set_default_bindings()</code></dd> - </dl> + <dd><code><code class='datatype'>mixed</code> value()</code></dd> - + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>The value at the current position. + </dd></dl> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class ADT.Heap</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This class implements a (min-)heap. The value of a child node will + always be greater than or equal to the value of its parent node. + Thus, the top node of the heap will always hold the smallest value. + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - set_mark + _sizeof </dt> - <dd><code><code class='datatype'>void</code> set_mark()</code></dd> - </dl> + <dd><code><code class='datatype'>int</code> sizeof( ADT.Heap arg )</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the number of elements in the heap. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - swap_mark_and_point + adjust </dt> - <dd><code><code class='datatype'>void</code> swap_mark_and_point()</code></dd> - </dl> + <dd><code><code class='object unresolved'>Element</code> adjust(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Takes a value in the heap and sorts it through the heap to maintain + its sort criteria (increasing order). + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>Either the element handle returned by <code>push()</code>, or the pushed + value itself. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the element handle for the value (if present in the heap), + and <code class='expr'>0</code> (zero) otherwise. + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - transpose_chars + low_peek </dt> - <dd><code><code class='datatype'>void</code> transpose_chars()</code></dd> - </dl> + <dd><code><code class='object unresolved'>Element</code> low_peek()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the <code>Element</code> on top of the heap (which is also the one with + the smallest value in the heap) without removing it. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the smallest <code>Element</code> on the heap if any, and + <code class='expr'>UNDEFINED</code> otherwise. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>peek()</code>, <code>low_pop()</code>, <code>pop()</code> + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - up_history + low_pop </dt> - <dd><code><code class='datatype'>void</code> up_history()</code></dd> - </dl> + <dd><code><code class='object unresolved'>Element</code> low_pop()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Removes and returns the <code>Element</code> on top of the heap, + which also is the smallest value in the heap. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns <code>UNDEFINED</code> if the heap is empty. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>pop()</code>, <code>peek()</code>, <code>push()</code>, <code>remove()</code> + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - upcase_word + peek </dt> - <dd><code><code class='datatype'>void</code> upcase_word()</code></dd> - </dl> + <dd><code><code class='datatype'>mixed</code> peek()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the item on top of the heap (which is also the smallest value + in the heap) without removing it. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns the smallest value on the heap if any, and + <code class='expr'>UNDEFINED</code> otherwise. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>low_peek()</code>, <code>pop()</code> + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - yank + pop </dt> - <dd><code><code class='datatype'>void</code> yank()</code></dd> - </dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.Readline.History</h2> - </dt><dd> + <dd><code><code class='datatype'>mixed</code> pop()</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Removes and returns the item on top of the heap, + which also is the smallest value in the heap. + </dd> + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'>Throws an error if the heap is empty. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>low_pop()</code>, <code>peek()</code>, <code>push()</code>, <code>remove()</code> + </dd></dl> + + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - create + push </dt> - <dd><code>Stdio.Readline.History Stdio.Readline.History(<code class='datatype'>int</code> <code class='argument'>maxhist</code>, <code class='datatype'>void</code>|<code class='datatype'>array</code>(<code class='datatype'>string</code>) <code class='argument'>hist</code>)</code></dd> - </dl> + <dd><code><code class='object unresolved'>Element</code> push(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Push an element onto the heap. The heap will automatically sort itself + so that the smallest value will be at the top. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Returns an element handle, which can be used with + <code>adjust()</code> and <code>remove()</code>. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>If <code>value</code> is a <code>Heap.Element</code> and already present on the heap + this is equivalent to calling <code>adjust()</code>. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>pop()</code>, <code>remove()</code> + </dd></dl> - + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - encode + remove </dt> - <dd><code><code class='datatype'>string</code> encode()</code></dd> - </dl> + <dd><code><code class='datatype'>void</code> remove(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Remove a value from the heap. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>value</code></dt> + <dd></dd><dd class='body--doc'>Value to remove. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>push()</code>, <code>pop()</code> + </dd></dl> + <dl><dt><h2 class='header'>Class ADT.Heap.Element</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Heap element. + </dd></dl> <hr /> <dl class='group--doc'> <dt class='head--type'>Method - finishline + create </dt> - <dd><code><code class='datatype'>void</code> finishline(<code class='datatype'>string</code> <code class='argument'>text</code>)</code></dd> + <dd><code>ADT.Heap.Element ADT.Heap.Element(<code class='datatype'>mixed</code> <code class='argument'>value</code>)</code></dd> </dl> <hr /> <dl class='group--doc'> - <dt class='head--type'>Method - get_history_num + <dt class='head--type'>Variable + value </dt> - <dd><code><code class='datatype'>int</code> get_history_num()</code></dd> + <dd><code><code class='datatype'>mixed</code> ADT.Heap.Element.value</code></dd> </dl> - + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class ADT.History</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>A history is a stack where you can only push entries. When the stack has + reached a certain size the oldest entries are removed on every push. + Other proposed names for this data type is leaking stack and table + (where you push objects onto the table in one end and objects are falling + off the table in the other. + </dd></dl> - + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _indices + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) indices( ADT.History arg )</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the index numbers of the history entries + available. + </dd></dl> + + <hr /> <dl class='group--doc'> <dt class='head--type'>Method - history + _sizeof </dt> - <dd><code><code class='datatype'>string</code> history(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>string</code> <code class='argument'>text</code>)</code></dd> - </dl> + <dd><code><code class='datatype'>int</code> sizeof( ADT.History arg )</code></dd> - + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>A <code>sizeof</code> operation on this object returns the number + of elements currently in the hi

autodoc.git/ traditional_manual/ chapter_9.html

2017-07-10

2017-07-10 10:30:01 by Henrik Grubbström (Grubba) <grubba@grubba.org>