# 10. Specific Datatype Modules

  ## Module String

    Constant __HAVE_SPRINTF_NEGATIVE_F__

      ``constant` `int` String.`__HAVE_SPRINTF_NEGATIVE_F__``

    Description

      Presence of this symbol indicates that `sprintf()` supports little endian output for the `'F'`-format specifier.

    See also

      `sprintf()`, `lfun::_sprintf()`

    Constant __HAVE_SPRINTF_STAR_MAPPING__

      ``constant` `int` String.`__HAVE_SPRINTF_STAR_MAPPING__``

    Description

      Presence of this symbol indicates that `sprintf()` supports mappings for the `'*'`-modifier syntax.

    See also

      `sprintf()`, `lfun::_sprintf()`

    Method capitalize

      ``string` capitalize(`string` `str`)`

    Description

      Convert the first character in `str` to upper case, and return the new string.

    See also

      `lower_case()`, `upper_case()`

    Method common_prefix

      ``string` common_prefix(`array`(`string`) `strs`)`

    Description

      Find the longest common prefix from an array of strings.

    Method count

      ``int` count(`string` `haystack`, `string` `needle`)`

    Description

      Count the number of non-overlapping times the string `needle` occurs in the string `haystack`. The special cases for the needle `""` 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.

    See also

      `search()`, ``/()`

    Method expand_tabs

      ``string` expand_tabs(`string` `s`, `int`|`void` `tab_width`, `string`|`void` `substitute_tab`, `string`|`void` `substitute_space`, `string`|`void` `substitute_newline`)`

    Description

      Expands tabs in a string to ordinary spaces, according to common tabulation rules.

    Method fuzzymatch

      ``int(0..100)` fuzzymatch(`string` `a`, `string` `b`)`

    Description

      This function compares two strings using a fuzzy matching routine. The higher the resulting value, the better the strings match.

    See also

      `Array.diff()`, `Array.diff_compare_table()` `Array.diff_longest_sequence()`

    Method hex2string

      ``string` hex2string(`string` `hex`)`

    Description

      Convert a string of hexadecimal digits to binary data.

    See also

      `string2hex()`

    Method implode_nicely

      ``string` implode_nicely(`array`(`string`|`int`|`float`) `foo`, `string`|`void` `separator`)`

    Description

      This function implodes a list of words to a readable string, e.g. `({"straw","berry","pie"})` becomes `"straw, berry and pie"`. If the separator is omitted, the default is `"and"`. If the words are numbers they are converted to strings first.

    See also

      ``*()`

    Method int2char

      ``string` int2char(`int` `x`)`

    Description

      Same as sprintf("%c",x);

    See also

      `sprintf()`

    Method int2hex

      ``string` int2hex(`int` `x`)`

    Description

      Same as `sprintf("%x",x);`, i.e. returns the integer `x` in hexadecimal base using lower cased symbols.

    See also

      `sprintf()`

    Method int2roman

      ``string` int2roman(`int` `m`)`

    Description

      Converts the provided integer to a roman integer (i.e. a string).

    Throws

      Throws an error if `m` is outside the range 0 to 10000.

    Method int2size

      ``string` int2size(`int` `size`)`

    Description

      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.

    Method levenshtein_distance

      ``int` levenshtein_distance(`string` `a`, `string` `b`)`

    Description

      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.

    Method normalize_space

      ``string` normalize_space(`string` `s`, `string`|`void` `whitespace`)`

    Parameter `s`

      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.

    Parameter `whitespace`

      Defines what is considered to be white space eligible for normalisation. It has a default value that starts with `" \t\r\n\v\f"` and in addition to that contains all whitespace characters part of Unicode. The first character denotes the character for replacing whitespace sequences.

    Note

      Trailing and leading whitespace around \r and \n characters is stripped as well (only useful if they're not in the `whitespace` set).

    Note

      This function is a lot faster with just one argument (i.e. the builtin whitespace set has an optimised code path).

    Method range

      ``array`(`int`) range(`string` `s`)`

    Description

      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.

    Method secure

      ``string` secure(`string` `str`)`

    Description

      Marks the string as secure, which will clear the memory area before freeing the string.

    See also

      `Object.secure()`

    Method sillycaps

      ``string` sillycaps(`string` `str`)`

    Description

      Convert the first character in each word (separated by spaces) in `str` to upper case, and return the new string.

    Method soundex

      ``string` soundex(`string` `word`)`

    Description

      Returns the soundex value of `word` 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.

    Method status

      ``string` status(`int` `verbose`)`

    Description

      Get string table statistics.

    Returns

      Returns a string with an ASCII table containing the current string table statistics.

    Note

      Currently returns the empty string (`""`) if `verbose` is zero.

    Note

      The formatting and contents of the result may vary between different versions of Pike.

    Method string2hex

      ``string` string2hex(`string` `data`)`

    Description

      Convert a string of binary data to a hexadecimal string.

    See also

      `hex2string()`

    Method trim_all_whites

      ``string` trim_all_whites(`string` `s`)`

    Description

      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 `s`.

    Method trim_whites

      ``string` trim_whites(`string` `s`)`

    Description

      Trim leading and trailing spaces and tabs from the string `s`.

    Method width

      ``int(8..8)`|`int(16..16)`|`int(32..32)` width(`string` `s`)`

    Description

      Returns the width of a string.

    Returns

      Three return values are currently possible:

      ``8`` | The string `s` only contains characters <= 255.
      ``16`` | The string `s` only contains characters <= 65535.
      ``32`` | The string `s` contains characters >= 65536.

    Note

      It is possible that a future version of Pike may return further values. In particular the width `7` seems like it could be useful.

    ## Class String.Bootstring

      Description

        This class implements the "Bootstring" string transcoder described in ftp://ftp.rfc-editor.org/in-notes/rfc3492.txt.

      Method create

        `String.Bootstring String.Bootstring(`int` `base`, `int` `tmin`, `int` `tmax`, `int` `skew`, `int` `damp`, `int` `initial_bias`, `int` `initial_n`, `int` `delim`, `string` `digits`)`

      Description

        Creates a Bootstring transcoder instance using the specified parameters.

      Parameter `base`

        The base used by the variable-length integers.

      Parameter `tmin`

        The minimum threshold digit value for the variable-length integers. Must be >=0 and <= tmax.

      Parameter `tmax`

        The maximum threshold digit value for the variable-length integers. Must be <= base-1.

      Parameter `skew`

        The skew term for the bias adapation. Must be >= 1.

      Parameter `damp`

        The damping factor for the bias adaption. Must be >= 2.

      Parameter `initial_bias`

        The initial bias for the variable-length integer thresholding. initial_bias % base must be <= base - tmin.

      Parameter `initial_n`

        The first code point outside the "basic" set of code points.

      Parameter `delim`

        The "basic" code point used as the delimiter.

      Parameter `digits`

        The "basic" code points used as digits. The length of the string should be the same as the base parameter.

      Method decode

        ``string` decode(`string` `s`)`

      Description

        Decodes a Bootstring encoded string of "basic" code points back to the original string space.

      Method encode

        ``string` encode(`string` `s`)`

      Description

        Encodes a string using Bootstring encoding into a string constisting only of "basic" code points (< initial_n).

    ## Class String.Buffer

      Description

        A buffer, used for building strings. It's conceptually similar to a string, but you can only `add` strings to it, and you can only `get` 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.

      Example

            For the fastest possible operation, write your code like this:
            String.Buffer b = String.Buffer( );

            function add = b->add;

            .. call add several times in code ...

            string result = b->get(); // also clears the buffer

      Method _sizeof

        ``int` sizeof( String.Buffer arg )`

      Description

        Returns the size of the buffer.

      Method _sprintf

        `string sprintf(string format, ... String.Buffer arg ... )`

      Description

        It is possible to `sprintf` a String.Buffer object as `%s` just as if it was a string.

      Method `+

        ``String.Buffer` res = `String.Buffer()` + `what``

      Method `+=

        ``String.Buffer()` += `what``

      Method add

        ``int` add(`string`|`String.Buffer` ... `data`)`

      Description

        Adds `data` to the buffer.

      Returns

        Returns the size of the buffer.

      Note

        Pike 7.8 and earlier did not support adding `String.Buffer`s directly.

      Method cast

        `(int)String.Buffer()
        (float)String.Buffer()
        (string)String.Buffer()
        (array)String.Buffer()
        (mapping)String.Buffer()
        (multiset)String.Buffer()`

      Description

        It is possible to cast a String.Buffer object to a `string` and an `int`.

      Method clear

        ``void` clear()`

      Description

        Empty the buffer, and don't care about the old content.

      Note

        This function was not available in Pike 7.8 and earlier.

      See also

        `get()`

      Method create

        `String.Buffer String.Buffer(`int` `initial_size`)`

      Description

        Initializes a new buffer.

        If no `initial_size` is specified, 256 is used. If you know approximately how big the buffer will be, you can optimize the operation of `add()` (slightly) by passing the size to this function.

      Method get

        ``string` get()`

      Description

        Get the data from the buffer.

      Note

        This will clear the data in the buffer

      See also

        `get_copy()`, `clear()`

      Method get_copy

        ``string` get_copy()`

      Description

        Get the data from the buffer. Significantly slower than `get`, but does not clear the buffer.

      See also

        `get()`

      Method putchar

        ``void` putchar(`int` `c`)`

      Description

        Appends the character `c` at the end of the string.

      Method sprintf

        ``int` sprintf(`strict_sprintf_format` `format`, `sprintf_args` ... `args`)`

      Description

        Appends the output from `sprintf` at the end of the string. Returns the resulting size of the String.Buffer.

    ## Class String.Iterator

      Description

        An object of this class is returned by `get_iterator()` when called with a string.

      See also

        `get_iterator`

      Inherit predef::Iterator

        `inherit predef::Iterator : predef::Iterator`

    ## Class String.Replace

      Description

        This is a "compiled" version of the `replace` 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 ``()` 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.

      Method _decode

        `String.Replace decode_value(string(8bit) data)`

      Method _encode

        `string(8bit) encode_value(String.Replace data)`

      Method `()

        ``string` res = `String.Replace()`()`

      Method create

        `String.Replace String.Replace(`array`(`string`)|`mapping`(`string`:`string`)|`void` `from`, `array`(`string`)|`string`|`void` `to`)`

    ## Class String.SingleReplace

      Description

        This is a "compiled" version of the `replace` 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 ``()` 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.

      Method _decode

        `String.SingleReplace decode_value(string(8bit) data)`

      Method _encode

        `string(8bit) encode_value(String.SingleReplace data)`

      Method `()

        ``string` res = `String.SingleReplace()`()`

      Method create

        `String.SingleReplace String.SingleReplace(`string`|`void` `from`, `string`|`void` `to`)`

      Note

        May be called with either zero or two arguments.

    ## Class String.SplitIterator

      Description

        An iterator that iterates over substrings of a string, separated by a character or several different characters.

      Note

        Typically you don't need to explicitly use the SplitIterator. Expressions like the following are automatically optimized into using a SplitIterator.

            foreach(str/"\n", string line)
                  write("%s\n", line);

      Method create

        `String.SplitIterator String.SplitIterator(`string` `buffer`, `int`|`array`(`int`)|`multiset`(`int`) `split_set`, `int`|`void` `flags`, `function`(:`string`)|`void` `feed`)`

      Parameter `buffer`

        The string to split.

      Parameter `split_set`

        The character or characters to split on.

      Parameter `flags`

        Skip empty elements if set.

      Parameter `feed`

        Callback function that is called once the `buffer` is used up and the SplitIterator wants more data.

      Inherit predef::Iterator

        `inherit predef::Iterator : predef::Iterator`

    ## Module String.Elite

      Method elite_string

        ``string` elite_string(`string` `in`, `void`|`int(0..100)` `leetp`, `void`|`bool` `eightbit`)`

      Description

        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 necessary elite translations (picture -> pic, cool->kewl etc), then optional translations (ok->k, dude->dood, -ers -> -orz), then calls elite_word on the resulting words.

      Method elite_word

        ``string` elite_word(`string` `in`, `void`|`int(0..100)` `leetp`, `void`|`int(0..2)` `eightbit`)`

      Description

        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").

    ## Module String.HTML

      Description

        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.

      Method pad_rows

        ``array`(`array`(`string`)) pad_rows(`array`(`array`(`string`)) `rows`, `void`|`string` `padding`)`

      Description

        Pads out the rows in a array of rows to equal length. The new elements in the rows will have the value provided in `padding`, or "&nbsp;".

      Method select

        ``string` select(`string` `name`, `array`(`string`)|`array`(`array`(`string`)) `choices`, `void`|`string` `selected`)`

      Description

        Creates an HTML select list.

      Parameter `name`

        The name of the select list. Will be used in the name attribute of the select element.

      Parameter `choices`

        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.

      Parameter `selected`

        The value that should be selected by default, if any.

      Example

            select("language",
                  ({ ({ "eng", "English" }),
                     ({ "swe", "Swedish" }),
                     ({ "nor", "Norwegian" }) }),
                  "swe");

      Method simple_obox

        ``string` simple_obox(`array`(`array`(`string`)) `rows`, `void`|`string` `frame_color`, `void`|`string` `cell_color`, `void`|`string` `width`, `void`|`string` `padding`, `void`|`function`(`int`, `int`, `string`, `string`:`string`) `cell_callback`)`

      Description

        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.

      Parameter `rows`

        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.

      Parameter `frame_color`

        The color of the surrounding frame. Defaults to "#000000".

      Parameter `cell_color`

        The background color of the cells. Defaults to "#ffffff".

      Parameter `width`

        The border width. Defaults to "1".

      Parameter `padding`

        The amount of padding in each cell. Defaults to "3".

      Parameter `cell_callback`

        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.

      Example

            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);

      See also

        `pad_rows`

      ## Class String.HTML.OBox

        Description

          Provides the same functionality as the `simple_obox` 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.

        See also

          simple_obox

        Method add_cell

          ``void` add_cell(`string` `contents`)`

        Description

          Adds a cell with the provided content.

        Method add_raw_cell

          ``void` add_raw_cell(`string` `cell`)`

        Description

          Adds this cell to the table unmodified, e.g. it should have an enclosing td or th element.

        Method add_row

          ``void` add_row(`array`(`string`) `cells`)`

        Description

          Adds a complete row. If the current row is nonempty a new row will be started.

        Method add_tagdata_cell

          ``void` add_tagdata_cell(`string` `tag`, `mapping`(`string`:`string`) `args`, `string` `contents`)`

        Description

          Creates a cell from the provided arguments and adds it to the table.

        Parameter `tag`

          The name of the element that should be produces. Typically "td" or "th".

        Parameter `args`

          A mapping with the elements attributes.

        Parameter `contents`

          The element contents.

        Method cast

          `(int)String.HTML.OBox()
          (float)String.HTML.OBox()
          (string)String.HTML.OBox()
          (array)String.HTML.OBox()
          (mapping)String.HTML.OBox()
          (multiset)String.HTML.OBox()`

        Description

          It is possible to case this object to a string, which does the same as calling `render`, and to an array, which returns the cells in an array of rows.

        Method create

          `String.HTML.OBox String.HTML.OBox(`void`|`string` `frame_color`, `void`|`string` `cell_color`, `void`|`string` `width`, `void`|`string` `padding`, `void`|`function`(`int`, `int`, `string`, `string`:`string`) `cell_callback`)`

        Method new_row

          ``void` new_row()`

        Description

          Begin a new row. Succeeding cells will be added to this row instead of the current.

        Method pad_rows

          ``void` pad_rows()`

        Description

          Ensures that all rows have the same number of cells.

        Method render

          ``string` render()`

        Description

          Returns the result.

        Method set_cell_callback

          ``void` set_cell_callback(`function`(`int`, `int`, `string`, `string`:`string`) `cell_callback`)`

        Method set_extra_args

          ``void` set_extra_args(`mapping`(`string`:`string`) `extra_args`)`

        Description

          The argument in the mapping will be added to all created table cells.

        Method set_extra_args

          ``void` set_extra_args(`array`(`mapping`(`string`:`string`)) `extra_args`)`

        Description

          The argument in the mappings will be added to the cell in the cooresponding column of the table.

  ## Module Array

    Description

      General functions to operate on arrays.

    Method all

      ``bool` all(`array` `a`, `function`(`int(0..0)`, `mixed` ... :`mixed`) `predicate`, `mixed` ... `extra_args`)`

    Description

      Returns 1 if all of the elements in `a` fulfills the requirement `predicate`( `a`[i], @`extra_args` ), otherwise 0. The predicate should return non-zero for an element that meets the requirements and zero for those that do not.

    Example

          Array.all( ({ 2, 4, 6, 8 }), `<, 17 )

    See also

      `any`, `has_value`

    Method any

      ``bool` any(`array` `a`, `function`(`int(0..0)`, `mixed` ... :`mixed`) `predicate`, `mixed` ... `extra_args`)`

    Description

      Returns 1 if any of the elements in `a` fulfills the requirement `predicate`( `a`[i], @`extra_args` ), otherwise 0. The predicate should return non-zero for an element that meets the requirements and zero for those that do not.

    Example

          Array.any( ({ 2, 4, 6, 8 }), `>, 5 )

    See also

      `all`, `has_value`

    Method arrayify

      ``array` arrayify(`void`|`array`|`mixed` `x`)`

    Description

      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.

    Parameter `x`

      Result depends of the argument type:

      arrayp(x)

        arrayify(x) => x

      undefinedp(x)

        arrayify(x) => ({})

      otherwise

        arrayify(x) => ({ x })

    Method columns

      ``array`(`array`) columns(`array` `x`, `array` `ind`)`

    Description

      Get multiple columns from an array.

      This function is equivalent to

             map(ind, lambda(mixed i) { return column(x, i); })

    See also

      `column()`

    Method combinations

      ``array`(`array`) combinations(`array` `arr`, `int` `len`)`

    Description

      Returns an array of all combinations of length `len` of elements from `arr`.

    See also

      `permute()`

    Method common_prefix

      ``array` common_prefix(`array`(`array`) `arrs`)`

    Description

      Find the longest common prefix from an array of arrays.

    See also

      `String.common_prefix`

    Method compact_diff3

      ``array`(`array`(`array`)) compact_diff3(`array` `a`, `array` `b`, `array` `old`)`

    Description

      Given three arrays like those returned from `diff3`, this function "compacts" the diff3 result by removing all differences where `a` and `b` agrees against `old`. The result is on the same form as the result from `diff`, and doesn't include the sequence from `old`.

    Method count

      ``int` count(`array`|`mapping`|`multiset` `haystack`, `mixed` `needle`)`
      ``mapping`(`mixed`:`int`) count(`array`|`mapping`|`multiset` `haystack`)`

    Description

      Returns the number of occurrences of `needle` in `haystack`. If the optional `needle` argument is omitted, `count` instead works similar to the unix command `sort|uniq -c`, returning a mapping with the number of occurrences of each element in `haystack`. For array or mapping `haystack`s, it's the values that are counted, for multisets the indices, as you'd expect.

    See also

      `String.count`, `search`, `has_value`

    Method diff

      ``array`(`array`(`array`)) diff(`array` `a`, `array` `b`)`

    Description

      Calculates which parts of the arrays that are common to both, and which parts that are not.

    Returns

      Returns an array with two elements, the first is an array of parts in array `a`, and the second is an array of parts in array `b`.

    See also

      `diff_compare_table()`, `diff_longest_sequence()`, `String.fuzzymatch()`

    Method diff3

      ``array`(`array`(`array`)) diff3(`array` `a`, `array` `b`, `array` `c`)`

    Description

      Return the three-way difference between the arrays.

    See also

      `Array.diff()`, `Array.diff_longest_sequence()`

    Method diff_compare_table

      ``array`(`array`(`int`)) diff_compare_table(`array` `a`, `array` `b`)`

    Description

      Returns an array which maps from index in `a` to corresponding indices in `b`.

           > Array.diff_compare_table( ({ "a","b","c" }), ({ "b", "b", "c", "d", "b" }));
           Result: ({
                       ({ }),
                       ({
                           0,
                           1,
                           4
                       }),
                       ({
                           2
           	        })
                   })

    See also

      `diff()`, `diff_longest_sequence()`, `String.fuzzymatch()`

    Method diff_dyn_longest_sequence

      ``array`(`int`) diff_dyn_longest_sequence(`array` `a`, `array` `b`)`

    Description

      Gives the longest sequence of indices in `b` that have corresponding values in the same order in `a`.

      This function performs the same operation as `diff_longest_sequence()`, but uses a different algorithm, which in some rare cases might be faster (usually it's slower though).

    See also

      `diff_longest_sequence()`, `diff()`, `diff_compare_table()`, `String.fuzzymatch()`

    Method diff_longest_sequence

      ``array`(`int`) diff_longest_sequence(`array` `a`, `array` `b`)`

    Description

      Gives the longest sequence of indices in `b` that have corresponding values in the same order in `a`.

    See also

      `diff()`, `diff_compare_table()`, `String.fuzzymatch()`

    Method dwim_sort_func

      ``int(-1..1)` dwim_sort_func(`string` `a`, `string` `b`)`

    Description

      Sort without respect to number formatting (most notably leading zeroes).

    Method everynth

      ``array`(`mixed`) everynth(`array`(`mixed`) `a`, `void`|`int` `n`, `void`|`int` `start`)`

    Description

      Return an array with every `n`:th element of the array `a`.

      If `n` is zero every other element will be returned.

    See also

      `splice()`, ``/()`

    Method flatten

      ``array` flatten(`array` `a`, `mapping`(`array`:`array`)|`void` `state`)`

    Description

      Flatten a multi-dimensional array to a one-dimensional array.

    Note

      Prior to Pike 7.5.7 it was not safe to call this function with cyclic data-structures.

    Method greedy_diff

      ``array`(`array`(`array`)) greedy_diff(`array` `from`, `array` `to`)`

    Description

      Like `Array.diff`, but tries to generate bigger continuous chunks of the differences, instead of maximizing the number of difference chunks. More specifically, `greedy_diff` optimizes the cases where `Array.diff` returns `({ ..., A, Z, B, ({}), C, ... })` `({ ..., A, X, B, Y+B, C, ... })` into the somewhat shorter diff arrays `({ ..., A, Z, B+C, ... })` `({ ..., A, X+B+Y, B+C, ... })`

    Method interleave_array

      ``array`(`int`) interleave_array(`array`(`mapping`(`int`:`mixed`)) `tab`)`

    Description

      Interleave a sparse matrix.

      Returns an array with offsets that describe how to shift the rows of `tab` so that only at most one non-zero value exists in every column.

    Method longest_ordered_sequence

      ``array`(`int`) longest_ordered_sequence(`array` `a`)`

    Description

      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.

    See also

      `diff()`

    Method lyskom_sort_func

      ``int(-1..1)` lyskom_sort_func(`string` `a`, `string` `b`)`

    Description

      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!)"

    Method oid_sort_func

      ``int(-1..1)` oid_sort_func(`string` `a`, `string` `b`)`

    Description

      Sort with care of numerical sort for OID values, e.g. "1.2.1" before "1.11.1".

    Returns

      ``-1`` | `a<b`
      ``0`` | `a==b`
      ``1`` | `a>b`

    Note

      In Pike 7.6 and older this function returned `0` both when `a<b` and `a==b`.

    See also

      `sort_array`

    Method partition

      ``array`(`array`) partition(`array` `a`, `function`(`int(0..0)`, `mixed` ... :`mixed`) `arbiter`, `mixed` ... `extra_args`)`

    Description

      Splits an array in two, according to an arbitration function `arbiter`. The elements in `a` who return non-zero for the expression `arbiter`( `a`[i], @`extra_args` ) end up in the first sub-array, the others in the second. The order is preserved from the original array.

    Example

          Array.partition( enumerate( 9 ), lambda(int n) { return n>3 && n<7; } );
             > ({ ({ 4, 5, 6 }), ({ 0, 1, 2, 3, 7, 8 }) })

    See also

      `filter`, ``/`, ``%`

    Method permute

      ``array` permute(`array` `in`, `int(0..)` `number`)`

    Description

      Give a specified permutation of an array.

      The number of permutations is equal to `sizeof(`in`)!` (the factorial of the size of the given array).

    See also

      `shuffle()`

    Method pop

      ``array` pop(`array` `list`)`

    Description

      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.

    Example

          Array.pop(({ "a", "b", "c", "d" }));
             > ({ "d", ({ "a", "b", "c" }) })

    See also

      `ADT.Stack`, `ADT.Stack.pop`, `ADT.Stack.quick_pop`

    Method push

      ``array` push(`array` `list`, `mixed` `element`)`

    Description

      Threats an Array as a stack and pushes the element onto the end.

    Example

          Array.push(({ "a", "b", "c", "d" }), "e");
             > ({ "a", "b", "c", "d", "e" })

    See also

      `ADT.Stack`, `ADT.Stack.push`

    Method reduce

      ``mixed` reduce(`function`(:`void`) `fun`, `array` `arr`, `mixed`|`void` `zero`)`

    Description

      `reduce()` sends the first two elements in `arr` to `fun`, then the result and the next element in `arr` to `fun` and so on. Then it returns the result. The function will return `zero` if `arr` is the empty array. If `arr` has only one element, that element will be returned.

    See also

      `rreduce()`

    Method rreduce

      ``mixed` rreduce(`function`(:`void`) `fun`, `array` `arr`, `mixed`|`void` `zero`)`

    Description

      `rreduce()` sends the last two elements in `arr` to `fun`, then the third last element in `arr` and the result to `fun` and so on. Then it returns the result. The function will return `zero` if `arr` is the empty array. If `arr` has only one element, that element will be returned.

    See also

      `reduce()`

    Method search_array

      ``int` search_array(`array` `arr`, `string`|`function`(:`void`)|`int` `fun`, `mixed` ... `args`)`

    Description

      `search_array()` works like `map()`, only it returns the index of the first call that returnes true instead.

      If no call returns true, -1 is returned.

    See also

      `sum()`, `map()`

    Method shift

      ``array` shift(`array` `list`)`

    Description

      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.

    Example

          Array.shift(({ "a", "b", "c", "d"}));
             > ({ "a", ({ "b", "c", "d" }) })

    See also

      `ADT.Stack`

    Method shuffle

      ``array` shuffle(`array` `arr`)`

    Description

      `shuffle()` gives back the same elements, but in random order. The array is modified destructively.

    See also

      `permute()`

    Method sort_array

      ``array` sort_array(`array` `arr`, `function`(:`void`)|`void` `cmp`, `mixed` ... `args`)`

    Description

      This function sorts the array `arr` after a compare-function `cmp` which takes two arguments and should return `1` if the first argument is larger then the second. Returns the sorted array - `arr` is not sorted destructively.

      The remaining arguments `args` will be sent as 3rd, 4th etc. argument to `cmp`.

      If `cmp` is omitted, ``>()` is used instead.

    See also

      `map()`, `sort()`, ``>()`, `dwim_sort_func`, `lyskom_sort_func`, `oid_sort_func`

    Method splice

      ``array`(`mixed`) splice(`array`(`mixed`) `arr1`, `array`(`mixed`) `arr2`, `array`(`mixed`) ... `more_arrays`)`

    Description

      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.

    See also

      ``/()`, ``*()`, ``+()`, ``-()`, `everynth()`

    Method sum

      ``mixed` sum(`array` `a`)`

    Description

      Sum the elements of an array using `+. The empty array results in 0.

    Method sum_arrays

      ``array` sum_arrays(`function`(`int(0..0)` ... :`mixed`) `sum`, `array` ... `args`)`

    Description

      Applies the function `sum` columnwise on the elements in the provided arrays. E.g. `sum_array(`+,a,b,c)` does the same as ``+(a[*],b[*],c[*])`.

    Method transpose

      ``array`(`array`) transpose(`array`(`array`) `matrix`)`

    Description

      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.

    Method uniq

      ``array` uniq(`array` `a`)`

    Description

      Remove elements that are duplicates.

    Returns

      This function returns an copy of the array `a` 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.

    Note

      Elements are compared with ``==`. They are also hashed (see `lfun::__hash` for further details if the array contains objects).

    Method uniq2

      ``array` uniq2(`array` `a`)`

    Description

      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 `uniq` function.

    Method unshift

      ``array` unshift(`array` `list`, `mixed` `element`)`

    Description

      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.

    Example

          Array.unshift(({ "b", "c", "d" }), "a");
             > ({ "a", "b", "c", "d" })

    See also

      `ADT.Stack`

    ## Class Array.Iterator

      Description

        An object of this class is returned by `get_iterator()` when called with an array.

      See also

        `get_iterator`

      Inherit predef::Iterator

        `inherit predef::Iterator : predef::Iterator`

  ## Module Mapping

    Constant delete

      ``constant` Mapping.`delete``

    Description

      Alias for `m_delete()`

    ## Class Mapping.Iterator

      Description

        An object of this class is returned by `get_iterator()` when called with a mapping.

      See also

        `get_iterator`

      Inherit predef::Iterator

        `inherit predef::Iterator : predef::Iterator`

    ## Class Mapping.ShadowedMapping

      Description

        A mapping look-alike that overrides (ie shadows) another `parent` mapping.

        The class implements most of the usual mapping operations.

      Method create

        `Mapping.ShadowedMapping Mapping.ShadowedMapping(`mapping`|`ShadowedMapping` `parent`)`

      Method create

        `Mapping.ShadowedMapping Mapping.ShadowedMapping(`mapping`|`ShadowedMapping` `parent`, `mapping`|`void` `shadow`, `bool`|`void` `modify_parent`)`

      Parameter `parent`

        Mapping to be shadowed.

      Parameter `shadow`

        Initial shadow of `parent`.

      Parameter `modify_parent`

        Modifications should be done to `parent` rather than to `shadow`. If this is set, only entries that are already present in `shadow` can be modified by later operations.

      Variable parent

        ``protected` `mapping`|`ShadowedMapping` Mapping.ShadowedMapping.parent`

  ## Module Multiset

    ## Class Multiset.Iterator

      Description

        An object of this class is returned by `get_iterator()` when called with a multiset.

      See also

        `get_iterator`

      Inherit predef::Iterator

        `inherit predef::Iterator : predef::Iterator`

  ## Module Int

    Constant NATIVE_MIN
    Constant NATIVE_MAX

      ``constant` Int.`NATIVE_MIN``
      ``constant` Int.`NATIVE_MAX``

    Description

      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").

      `NATIVE_MIN` is not greater than `-2147483648` (`-0x80000000`).

      `NATIVE_MAX` is not less than `2147483647` (`0x7fffffff`).

    Note

      The size of the native integers can be controlled when Pike is compiled with the configure flags `--with-int-int`, `--with-long-int`, and `--with-long-long-int`. 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.

    Variable inf

      ``Inf` Int.inf`

    Description

      An object that behaves like positive infinity.

    Method parity

      ``bool` parity(`int(0..)` `value`)`

    Description

      Returns the parity of the integer `value`. If the parity is odd 1 is returned. If it is even 0 is returned.

    Method reflect

      ``int(0..)` reflect(`int` `value`, `int(0..)` `bits`)`

    Description

      Reverses the order of the low order `bits` number of bits of the value `value`.

    Note

      Any higher order bits of the value will be cleared. The returned value will thus be unsigned.

    See also

      `reverse()`, `swap_word()`, `swap_long()`

    Method swap_long

      ``int(32bit)` swap_long(`int(32bit)` `i`)`

    Description

      Swaps the upper and lower word in a longword, and the upper and lower bytes in the words. Simply put, the bytes are reversed.

    See also

      `swap_word()`

    Method swap_word

      ``int(16bit)` swap_word(`int(16bit)` `i`)`

    Description

      Swaps the upper and lower byte in a word.

    See also

      `swap_long()`

    ## Class Int.Inf

      Description

        The type of `Int.inf`. Do not create more instances of this.

  ## Module Float

    Constant DIGITS_10
    Constant MIN_10_EXP
    Constant MAX_10_EXP
    Constant MIN
    Constant MAX
    Constant EPSILON

      ``constant` Float.`DIGITS_10``
      ``constant` Float.`MIN_10_EXP``
      ``constant` Float.`MAX_10_EXP``
      ``constant` Float.`MIN``
      ``constant` Float.`MAX``
      ``constant` Float.`EPSILON``

    Description

      These constants define the limits for floats on the current architecture:

      DIGITS_10

        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. `DIGITS_10` is not less than `6`.

      MIN_10_EXP
      MAX_10_EXP

        Limits of the exponent in decimal base. 10 raised to any number within this range can be represented in normalized form. `MIN_10_EXP` is not greater than `-37`. `MAX_10_EXP` is not less than `37`.

      MIN

        The smallest normalized float greater than zero. It's not greater than `1e-37`.

      MAX

        The largest finite float. It's not less than `1e37`.

      EPSILON

        The difference between 1 and the smallest value greater than 1 that can be represented. It's not greater than `1e-5`.

    Note

      The size of the float type can be controlled when Pike is compiled with the configure flags `--with-double-precision` and `--with-long-double-precision`. The default is to use the longest available float type that fits inside a pointer.

    Constant FLOAT_PRECISION
    Constant DOUBLE_PRECISION
    Constant LONG_DOUBLE_PRECISION

      ``constant` Float.`FLOAT_PRECISION``
      ``constant` Float.`DOUBLE_PRECISION``
      ``constant` Float.`LONG_DOUBLE_PRECISION``

    Description

      Tells which C compiler float type that is used for Pike floats. Only one of these constants will exist (with the value `1`) at runtime.

      FLOAT_PRECISION

        The `float` type of the C compiler is used.

      DOUBLE_PRECISION

        The `double` type of the C compiler is used.

      LONG_DOUBLE_PRECISION

        The `long double` type of the C compiler is used.

    Note

      The float type can be controlled when Pike is compiled with the configure flags `--with-double-precision` and `--with-long-double-precision`. The default is to use the longest available float type that fits inside a pointer.

    Method isnan

      ``bool` isnan(`float` `x`)`

    Description

      Returns true if `x` is nan.

  ## Module Function

    Method Y

      ``function`(:`void`) Y(`function`(:`void`) `f`)`

    Description

      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.

    Example

          This example creates a lambda that computes the faculty function.
          Function.Y(lambda(function f, int n) { return n>1? n*f(n-1) : 1; })

    Method call_callback

      ``void` call_callback(`function`(:`void`) `f`, `mixed` ... `args`)`

    Description

      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.

    Example

          Functions.call_callback(the_callback,some,arguments);equals
          {
               mixed err=catch { if (the_callback) the_callback(some,arguments); };
               if (err) master()->handle_error(err);
            }
          (Approximately, since call_callback also calls handle_error
           if 0 were thrown.)

    Method curry

      ``function`(`mixed` ... :`function`(`mixed` ... :`mixed`|`void`)) curry(`function`(:`void`) `f`)`

    Description

      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.

    Example

          This example creates a function adding 7 to its argument.
          Function.curry(`+)(7)

    Method defined

      ``string` defined(`function`(:`void`) `fun`)`

    Description

      Returns a string with filename and linenumber where `fun` was defined.

      Returns `0` (zero) when no line can be found, e.g. for builtin functions and functions in destructed objects.

    Method splice_call

      ``mixed` splice_call(`array` `args`, `function`(:`void`) `f`, `mixed`|`void` ... `extra`)`

    Description

      Calls the given function with the `args` array plus the optional extra arguments as its arguments and returns the result.

      Most useful in conjunction with `map`, and particularly in combination with `sscanf` with `"...%{...%}..."` scan strings (which indeed was what it was invented for in the first place).

    Parameter `args`

      The first arguments the function `f` expects.

    Parameter `f`

      The function to apply the arguments on.

    Parameter `extra`

      Optional extra arguments to send to `f`.

    Returns

      Whatever the supplied function `f` returns.

    Example

          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)
            })

    Method uncurry

      ``function`(`mixed` ... :`mixed`) uncurry(`function`(:`void`) `f`)`

    Description

      This function, given a function taking N parameters, returns a new function taking N+1 parameters. The first argument will be ignored.

    Example

          >  Function.uncurry(`+)(7,2,3)
           Result: 5

  ## Module Program

    Method all_inherits

      ``array`(`program`) all_inherits(`program` `p`)`

    Description

      Enumerate all programs this program inherits, directly or indirectly. Similar to inherit_tree() but returns a flat array.

    Example

          > class a{}
            > class b{}
            > class c{ inherit a; }
            > class d{ inherit b; inherit c; }
            > Program.inherit_tree(d);
            Result: ({ /* 3 elements */
                        b,
                        c,
                        a
                    })

    Method defined

      ``string` defined(`program` `p`)`

    Description

      Returns a string with filename and linenumber describing where the program `p` was defined.

      The returned string is of the format `"filename:linenumber"`.

      If it cannot be determined where the program was defined, `0` (zero) will be returned.

    Method defined

      ``string` defined(`program` `x`, `string` `identifier`)`

    Description

      Returns a string with filename and linenumber where `identifier` in `x` was defined.

      Returns `0` (zero) when no line can be found, e.g. for builtin functions.

      If `identifier` can not be found in `x` this function returns where the program is defined.

    Method implements

      ``int` implements(`program` `prog`, `program` `api`)`

    Description

      Returns 1 if `prog` implements `api`.

    Method inherit_list

      ``array`(`program`) inherit_list(`program` `p`)`

    Description

      Returns an array with the programs that `p` has inherited.

    Method inherit_tree

      ``array` inherit_tree(`program` `p`)`

    Description

      Recursively builds a inheritance tree by fetching programs inheritance lists.

    Returns

      Returns an array with programs or arrays as elements.

    Example

          > 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
                            })
                        })
                    })

    Method inherits

      ``int` inherits(`program`|`object` `child`, `program` `parent`)`

    Description

      Returns 1 if `child` has inherited `parent`.

  ## Module ADT

    Description

      Various Abstract Data Types.

    Inherit _ADT

      `inherit _ADT : _ADT`

    ## Class ADT.BitBuffer

      Description

        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.

      Example

            > 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

      Method _sizeof

        ``int` sizeof( ADT.BitBuffer arg )`

      Description

        `sizeof()` will return the number of bits in the buffer.

      Method create

        `ADT.BitBuffer ADT.BitBuffer(`void`|`string` `data`)`

      Description

        The buffer can be initialized with initial data during creation.

      Method drain

        ``string` drain()`

      Description

        Drains the buffer of all full (8-bits wide) bytes.

      Method feed

        ``this_program` feed(`string` `x`)`

      Description

        Adds full bytes to the buffer.

      Method get

        ``int` get(`int` `bits`)`

      Description

        Get `bits` from the buffer.

      Throws

        Throws an error in case of data underflow.

      Note

        The bits are extracted with the most significant bit first.

      Method put

        ``this_program` put(`int` `value`, `int` `bits`)`

      Description

        Put `bits` number of bits with the value `value` into the buffer.

      Note

        `value` must not be larger than what can be stored with the number of bits given in `bits`.

      Note

        The bits are added to the buffer with the most significant bit first.

      Method put0

        ``this_program` put0(`int` `bits`)`

      Description

        Put `bits` number of 0 bits into the buffer.

      Method put1

        ``this_program` put1(`int` `bits`)`

      Description

        Put `bits` number of 1 bits into the buffer.

      Method read

        ``string` read(`void`|`int` `bytes`)`

      Description

        Reads `bytes` (or less) bytes from the buffer and returns as string.

    ## Class ADT.CircularList

      Description

        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.

      Method _equal

        ``bool` equal(ADT.CircularList from, `mixed` `coll`)`

      Returns

        Returns `true` if the object `coll` is a `CircularList` and contains the same values in the same order.

      Method _get_iterator

        `ADT.CircularList a;
        foreach( a; index; value ) or
        ```CircularListIterator` _get_iterator(`void`|`int` `ind`)`

      Description

        Create and initiate a new CircularListIterator that could be used to iterate over this list.

      Parameter `ind`

        If an `ind` value is supplied the iterator will be positioned at that index.

      Returns

        An iterator.

      Method _indices

        ``array` indices( ADT.CircularList arg )`

      Returns

        The indices in this list as an array.

      Method _insert_element

        ``void` _insert_element(`int` `index`, `mixed` `value`)`

      Description

        Insert an element in the list at the position `index`, the value at the position `index` and all above will have their index increased by one.

      Parameter `index`

        The index to insert the value at.

      Parameter `value`

        The new value.

      Throws

        An error if the index is out of range.

      Method _remove_element

        ``mixed` _remove_element(`int` `index`)`

      Description

        Remove the values at index `index` from the list.

      Parameter `index`

        The index to remove.

      Returns

        The removed value.

      Throws

        An error if the index is out of range.

      Method _search

        ``int` search(ADT.CircularList from, `mixed` `value`, `void`|`int` `start`)`

      Description

        Search the list for a specific value. Return the index of the first value that is equal to `value`. If no value was found `UNDEFINED` is returned instead

      Parameter `value`

        The value to find

      Parameter `start`

        If a start value is supplied it will start searching at the index `start`.

      Returns

        Returns the index of the found value or `UNDEFINED`.

      Throws

        An error if the start is out of range.

      Method _sizeof

        ``int` sizeof( ADT.CircularList arg )`

      Returns

        The number of elements in this list.

      Method _values

        ``array` values( ADT.CircularList arg )`

      Returns

        The values in this list as an array.

      Method `+

        ``CircularList` res = `ADT.CircularList()` + `coll``

      Description

        Addition operator

        Append the content of this CircularList and @`coll` and return the results as a new `CircularList`.

      Parameter `coll`

        The lists to append to this list

      Returns

        The result of the append as a new `CircularList`.

      Method `[]

        ``mixed` res = `ADT.CircularList()`[ `index` ]`

      Description

        Index operator

      Parameter `index`

        The index to get the value for, could be negative to index from the end.

      Returns

        The value at the index `index`

      Throws

        An error if the index is out of range.

      Method `[]=

        ``ADT.CircularList()`[ `index` ] = `value``

      Description

        Index assign operator. Set the value at the index `index` to be `value`

      Parameter `index`

        The index to set

      Parameter `value`

        The new value

      Returns

        The new value at the index `index`

      Throws

        An error if the index is out of range.

      Method add

        ``void` add(`mixed` `value`)`

      Description

        Add a value at the front of the list

      Parameter `value`

        The value to add.

      Throws

        An error if the list is full.

      Method allocate

        ``void` allocate(`int` `elements`)`

      Description

        Increase the maxsize of the CircularlList.

      Parameter `elements`

        Add this number of new elements to the list.

      Method cast

        `(`array`)ADT.CircularList()`

      Description

        Cast operator.

      Parameter `type`

        Casts to this type.

        Casts to the following types are supported:

        ``"array"`` | Cast the content of this list to an array.

      Returns

        An array with the contents of this list.

      Method clear

        ``void` clear()`

      Description

        Clear the contents of the list.

      Method create

        `ADT.CircularList ADT.CircularList(`array`|`int` `arg`)`

      Description

        Creates a new `CircularList` around the array arg or a new `CircularList` with the maximum size of arg.

      Method delete_value

        ``int` delete_value(`mixed` `value`)`

      Description

        Remove the first occurrence of the value `value` from the list.

      Parameter `value`

        The value to remove from the list.

      Returns

        The index of the removed element or -1 if there was no value to remove.

      Method first

        ``CircularListIterator` first()`

      Description

        Create and initiate a new CircularListIterator that could be used to iterate over this list.

      Returns

        An iterator positioned at the first element in the list.

      Method is_empty

        ``bool` is_empty()`

      Returns

        Returns `1` if the list is empty otherwise `0`.

      Method last

        ``CircularListIterator` last()`

      Description

        Create and initiate a new CircularListIterator that could be used to iterate over this list.

      Returns

        An iterator positioned after the last element in the list.

      Method max_size

        ``int` max_size()`

      Returns

        Returns the maximal size of this list.

      Method peek_back

        ``mixed` peek_back()`

      Returns

        The value at the back of the list but do not remove it from the list.

      Method peek_front

        ``mixed` peek_front()`

      Returns

        The value at the front of the list but do not remove it from the list.

      Method pop_back

        ``mixed` pop_back()`

      Description

        Remove the value at the back of the list and return it.

      Returns

        The value at the back of the list.

      Method pop_front

        ``mixed` pop_front()`

      Description

        Remove the value at the front of the list and return it.

      Returns

        The value at the front of the list.

      Method push_back

        ``void` push_back(`mixed` `value`)`

      Description

        Add a new value at the end of the list.

      Parameter `value`

        The value to add.

      Method push_front

        ``void` push_front(`mixed` `value`)`

      Description

        Add a new value at the front of the list.

      Parameter `value`

        The value to add.

      ## Class ADT.CircularList.CircularListIterator

        Description

          This is the iterator for the CircularList. It implements the IndexIterator and the OutputIterator.

        Method _equal

          ``bool` equal(ADT.CircularList.CircularListIterator from, `mixed` `iter`)`

        Description

          Compare this iterator with another iterator.

        Parameter `iter`

          The iterator to compare with

        Returns

          Returns `true` if both iterators iterates over the same objects and are positioned at the same spot.

        Method `!

          ``bool` res = !`ADT.CircularList.CircularListIterator()``

        Returns

          Returns `false` if the iterator has reached the end.

        Method `+

          ``CircularListIterator` res = `ADT.CircularList.CircularListIterator()` + `steps``

        Description

          Move the iterator `steps` steps forward (negative value on `steps` will cause the iterator to move backwards) and return the result as a new iterator.

        Returns

          A new iterator positioned `steps` steps forward.

        Method `+=

          ``ADT.CircularList.CircularListIterator()` += `steps``

        Description

          Move this iterator `steps` steps forward (negative value on `steps` will cause the iterator to move backwards) and return the result.

        Returns

          This iterator positioned `steps` steps forward.

        Method `-

          ``CircularListIterator` res = `ADT.CircularList.CircularListIterator()` - `steps``

        Description

          Move the iterator `steps` steps backwards (negative value on `steps` will cause the iterator to move forwards) and return the result as a new iterator.

        Returns

          A new iterator positioned `steps` steps backwards.

        Method `<

          ``bool` res = `ADT.CircularList.CircularListIterator()` < `iter``

        Description

          Less then operator

        Returns

          Returns `true` if this iterator has a lower index then `iter`.

        Method `>

          ``bool` res = `ADT.CircularList.CircularListIterator()` > `iter``

        Description

          Greater then operator

        Returns

          Returns `true` if this iterator has a higher index then `iter`.

        Method create

          `ADT.CircularList.CircularListIterator ADT.CircularList.CircularListIterator(`object` `list`, `void`|`int` `start`)`

        Description

          Creates a new iterator for the CircularList `list`. If `start` is supplied it will try to position the iterator at `start`.

        Method distance

          ``int` distance(`object` `iter`)`

        Parameter `iter`

          The iterator to measure the distance to.

        Returns

          Returns distance between this iterator and `iter`.

        Throws

          An error if the two iterator could not be compared.

        Method get_collection

          ``CircularList` get_collection()`

        Returns

          Returns the CircularList this iterator currently iterates over.

        Method has_next

          ``bool` has_next(`void`|`int` `steps`)`

        Returns

          Returns `true` if it is possible to move `steps` steps forwards, if `steps` weren't supplied it check if it is possible to move one step forward.

        Method has_previous

          ``bool` has_previous(`void`|`int` `steps`)`

        Returns

          Returns `true` if it is possible to move `steps` steps backwards, if `steps` weren't supplied it check if it is possible to move one step backward.

        Method index

          ``int` index()`

        Returns

          The index at the current position.

        Method set_value

          ``mixed` set_value(`mixed` `val`)`

        Description

          Set the value at the current position.

        Parameter `val`

          The new value

        Returns

          Returns the old value

        Method value

          ``mixed` value()`

        Returns

          The value at the current position.

    ## Class ADT.Heap

      Description

        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.

      Method _sizeof

        ``int` sizeof( ADT.Heap arg )`

      Description

        Returns the number of elements in the heap.

      Method adjust

        ``Element` adjust(`mixed` `value`)`

      Description

        Takes a value in the heap and sorts it through the heap to maintain its sort criteria (increasing order).

      Parameter `value`

        Either the element handle returned by `push()`, or the pushed value itself.

      Returns

        Returns the element handle for the value (if present in the heap), and `0` (zero) otherwise.

      Method low_peek

        ``Element` low_peek()`

      Description

        Returns the `Element` on top of the heap (which is also the one with the smallest value in the heap) without removing it.

      Returns

        Returns the smallest `Element` on the heap if any, and `UNDEFINED` otherwise.

      See also

        `peek()`, `low_pop()`, `pop()`

      Method low_pop

        ``Element` low_pop()`

      Description

        Removes and returns the `Element` on top of the heap, which also is the smallest value in the heap.

      Returns

        Returns `UNDEFINED` if the heap is empty.

      See also

        `pop()`, `peek()`, `push()`, `remove()`

      Method peek

        ``mixed` peek()`

      Description

        Returns the item on top of the heap (which is also the smallest value in the heap) without removing it.

      Returns

        Returns the smallest value on the heap if any, and `UNDEFINED` otherwise.

      See also

        `low_peek()`, `pop()`

      Method pop

        ``mixed` pop()`

      Description

        Removes and returns the item on top of the heap, which also is the smallest value in the heap.

      Throws

        Throws an error if the heap is empty.

      See also

        `low_pop()`, `peek()`, `push()`, `remove()`

      Method push

        ``Element` push(`mixed` `value`)`

      Description

        Push an element onto the heap. The heap will automatically sort itself so that the smallest value will be at the top.

      Returns

        Returns an element handle, which can be used with `adjust()` and `remove()`.

      Note

        If `value` is a `Heap.Element` and already present on the heap this is equivalent to calling `adjust()`.

      See also

        `pop()`, `remove()`

      Method remove

        ``void` remove(`mixed` `value`)`

      Description

        Remove a value from the heap.

      Parameter `value`

        Value to remove.

      See also

        `push()`, `pop()`

      Method size

        ``__deprecated__` `int` size()`

      Description

        Returns the number of elements in the heap.

      Deprecated

        Replaced by `lfun::_sizeof`.

      Method top

        ``__deprecated__` `mixed` top()`

      Description

        Removes and returns the item on top of the heap, which also is the smallest value in the heap.

      Deprecated

        Replaced by `pop`.

      ## Class ADT.Heap.Element

        Description

          Heap element.

        Method create

          `ADT.Heap.Element ADT.Heap.Element(`mixed` `value`)`

        Variable value

          ``mixed` ADT.Heap.Element.value`

    ## Class ADT.History

      Description

        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.

      Method _indices

        ``array`(`int`) indices( ADT.History arg )`

      Description

        Returns the index numbers of the history entries available.

      Method _sizeof

        ``int` sizeof( ADT.History arg )`

      Description

        A `sizeof` operation on this object returns the number of elements currently in the history, e.g. <= the current max size.

      Method _values

        ``array` values( ADT.History arg )`

      Description

        Returns the values of the available history entries.

      Method `[]

        ``mixed` res = `ADT.History()`[ `i` ]`

      Description

        Get a value from the history as if it was an array, e.g. both positive and negative numbers may be used. The positive numbers are however offset with 1, so [1] is the first entry in the history and [-1] is the last.

      Method `[]=

        ``ADT.History()`[ `i` ] = `value``

      Description

        Overwrite one value in the history. The history position may be identified either by positive or negative offset, like ``[]`.

      Method create

        `ADT.History ADT.History(`int` `max_size`)`

      Description

        `max_size` is the maximum number of entries that can reside in the history at the same time.

      Method flush

        ``void` flush()`

      Description

        Empties the history. All entries in the history are removed, to allow garbage collect to remove them. The entry sequence counter is not reset.

      Method get_first_entry_num

        ``int` get_first_entry_num()`

      Description

        Returns the absolute sequence number of the oldest result still in the history. Returns 0 if there are no results in the history.

      Method get_latest_entry_num

        ``int` get_latest_entry_num()`

      Description

        Returns the absolute sequence number of the latest result inserted into the history.

      Method get_maxsize

        ``int` get_maxsize()`

      Description

        Returns the maximum number of values in the history

      See also

        `set_maxsize`

      Method push

        ``void` push(`mixed` `value`)`

      Description

        Push a new value into the history.

      Method query_no_adjacent_duplicates

        ``bool` query_no_adjacent_duplicates()`

      Description

        Tells if the History object allows adjacent equal values. 1 means that only uniqe values are allowed adter each other.

      See also

        `set_no_adjacent_duplicates`

      Method set_maxsize

        ``void` set_maxsize(`int` `_maxsize`)`

      Description

        Set the maximume number of entries that can be stored in the history simultaneous.

      See also

        `get_maxsize`

      Method set_no_adjacent_duplicates

        ``void` set_no_adjacent_duplicates(`bool` `i`)`

      Description

        Change how the History object should treat two identical values in a row. If 1 than only unique values are allowed after each other.

      See also

        `query_no_adjacent_duplicates`

    ## Class ADT.List

      Description

        Linked list of values.

      Method _sizeof

        ``int(0..)` sizeof( ADT.List arg )`

      Description

        Returns the number of elements in the list.

      Method _sprintf

        `string sprintf(string format, ... ADT.List arg ... )`

      Description

        Describe the list.

      See also

        `sprintf()`, `lfun::_sprintf()`

      Method _values

        ``array` values( ADT.List arg )`

      Description

        Returns an array of elements in the list.

      Method `[]

        ``mixed` res = `ADT.List()`[ `key` ]`

      Method append

        ``void` append(`mixed` ... `values`)`

      Description

        Append `values` to the end of the list.

      See also

        `insert()`

      Method cast

        `(`array`)ADT.List()`

      Description

        Cast the lists. `array` is the only supported type.

      Method create

        `ADT.List ADT.List(`mixed` ... `values`)`

      Description

        Create a new `List`, and initialize it with `values`.

      Method flush

        ``void` flush()`

      Description

        Empties the List.

      Method head

        ``mixed` head()`

      Description

        Get the element at the head of the list.

      Throws

        Throws an error if the list is empty.

      See also

        `is_empty()`, `tail()`, `pop()`

      Method insert

        ``void` insert(`mixed` ... `values`)`

      Description

        Insert `values` at the front of the list.

      See also

        `append()`

      Method is_empty

        ``bool` is_empty()`

      Description

        Check if the list is empty.

      Returns

        Returns `1` if the list is empty, and `0` (zero) if there are elements in the list.

      Method pop

        ``mixed` pop()`

      Description

        Pop the element at the head of the list from the list.

      Throws

        Throws an error if the list is empty.

      See also

        `is_empty()`, `head()`, `tail()`, `pop_back()`

      Method pop_back

        ``mixed` pop_back()`

      Description

        Pop the element at the tail of the list from the list.

      Throws

        Throws an error if the list is empty.

      See also

        `is_empty()`, `head()`, `tail()`, `pop()`

      Method tail

        ``mixed` tail()`

      Description

        Get the element at the tail of the list.

      Throws

        Throws an error if the list is empty.

      See also

        `is_empty()`, `head()`, `pop_back()`

      ## Class ADT.List._get_iterator

        Description

          `Iterator` that loops over the `List`.

        Method `+=

          ``ADT.List._get_iterator()` += `steps``

        Description

          Advance or retrace the specified number of `steps`.

        See also

          `next()`, `prev`

        Method append

          ``void` append(`mixed` `val`)`

        Description

          Append `val` after the current position.

        See also

          `insert()`, `delete()`, `set()`

        Method delete

          ``void` delete()`

        Description

          Delete the current node.

          The current position will advance to the next node. This function thus performes the reverse operation of `insert()`.

        See also

          `insert()`, `append()`, `set()`

        Method first

          ``bool` first()`

        Description

          Reset the iterator to point to the first element in the list.

        Returns

          Returns `1` if there are elements in the list, and `0` (zero) if the list is empty.

        Method insert

          ``void` insert(`mixed` `val`)`

        Description

          Insert `val` at the current position.

        See also

          `append()`, `delete()`, `set()`

        Method next

          ``bool` next()`

        Description

          Advance to the next element in the list.

        Returns

          Returns `1` on success, and `0` (zero) at the end of the list.

        See also

          `prev()`

        Method prev

          ``bool` prev()`

        Description

          Retrace to the previous element in the list.

        Returns

          Returns `1` on success, and `0` (zero) at the beginning of the list.

        See also

          `next()`

        Method set

          ``void` set(`mixed` `val`)`

        Description

          Set the value of the current position to `val`.

        See also

          `insert()`, `append()`, `delete()`

        Method value

          ``mixed` value()`

        Returns

          Returns the value at the current position.

    ## Class ADT.Priority_queue

      Description

        This class implements a priority queue. Each element in the priority queue is assigned a priority value, and the priority queue always remains sorted in increasing order of the priority values. The top of the priority queue always holds the element with the smallest priority. The priority queue is realized as a (min-)heap.

      Method adjust_pri

        ``void` adjust_pri(`mixed` `handle`, `int` `new_pri`)`

      Description

        Adjust the priority value `new_pri` of an element `handle` in the priority queue. The priority queue will automatically sort itself so that the element with the smallest priority value will be at the top.

      Inherit Heap

        `inherit .Heap : Heap`

      Method peek

        ``mixed` peek()`

      Description

        Returns the item on top of the priority queue (which is also the element with the smallest priority value) without removing it.

      Method pop

        ``mixed` pop()`

      Description

        Removes and returns the item on top of the heap, which also is the smallest value in the heap.

      Method push

        ``elem` push(`int` `pri`, `mixed` `val`)`

      Description

        Push an element `val` into the priority queue and assign a priority value `pri` to it. The priority queue will automatically sort itself so that the element with the smallest priority will be at the top.

    ## Class ADT.Queue

      Description

        A simple FIFO queue.

      Method cast

        `(int)ADT.Queue()
        (float)ADT.Queue()
        (string)ADT.Queue()
        (array)ADT.Queue()
        (mapping)ADT.Queue()
        (multiset)ADT.Queue()`

      Description

        It is possible to cast ADT.Queue to an array.

      Method create

        `ADT.Queue ADT.Queue(`mixed` ... `args`)`

      Description

        Creates a queue with the initial items `args` in it.

      Method flush

        ``void` flush()`

      Description

        Empties the queue.

      Method read
      Method get

        ``mixed` read()`
        ``mixed` get()`

      Description

        Returns the next element from the queue.

      Method is_empty

        ``bool` is_empty()`

      Description

        Returns true if the queue is empty, otherwise zero.

      Method peek

        ``mixed` peek()`

      Description

        Returns the next element from the queue without removing it from the queue.

      Method write
      Method put

        ``void` write(`mixed` ... `items`)`
        ``void` put(`mixed` ... `items`)`

      Description

        Adds `items` to the queue.

    ## Class ADT.Sequence

      Description

        The sequence work similar to an array but has the possibilities to insert and remove elements. It also has a more powerful iterator.

      Method _equal

        ``bool` equal(ADT.Sequence from, `mixed` `coll`)`

      Returns

        Returns `true` if the object `coll` is a `Sequence` and contains the same values in the same order.

      Method _get_iterator

        `ADT.Sequence a;
        foreach( a; index; value ) or
        ```SequenceIterator` _get_iterator(`void`|`int` `ind`)`

      Description

        Create and initiate a new SequenceIterator that could be used to iterate over this sequence.

      Parameter `ind`

        If an `ind` value is supplied the iterator will be positioned at that index.

      Returns

        An iterator.

      Method _indices

        ``array` indices( ADT.Sequence arg )`

      Returns

        The indices in this adapter as an array.

      Method _insert_element

        ``void` _insert_element(`int` `index`, `mixed` `value`)`

      Description

        Insert an element in the sequence at the position `index`, the value at the position `index` and all above will have their index increased by one.

      Parameter `index`

        The index to insert the value at.

      Parameter `value`

        The new value.

      Method _remove_element

        ``mixed` _remove_element(`int` `index`)`

      Description

        Remove the values at index `index` from the sequence.

      Parameter `index`

        The index to remove.

      Returns

        The removed value.

      Method _search

        ``int` search(ADT.Sequence from, `mixed` `value`, `void`|`int` `start`)`

      Description

        Search the sequence for a specific value. Return the index of the first value that is equal to `value`. If no value was found `UNDEFINED` is returned instead.

      Parameter `value`

        The value to find.

      Parameter `start`

        If a start value is supplied it will start searching at the index `start`.

      Returns

        Returns the index of the found value or `UNDEFINED`.

      Method _sizeof

        ``int` sizeof( ADT.Sequence arg )`

      Returns

        The number of elements in this adapter.

      Method _values

        ``array` values( ADT.Sequence arg )`

      Returns

        The values in this adapter as an array.

      Method `&

        ``Sequence` res = `ADT.Sequence()` & `coll``

      Description

        And operator Perform an and on this sequence and the `coll` sequence by only returning those values that is present in both sequences as a new `Sequence`. The remaining values is in the same order as they are in this sequence and the values are compared using `==.

      Parameter `coll`

        The sequence to and to this sequence.

      Returns

        The result of the and as a new `Sequence`.

      Method `+

        ``Sequence` res = `ADT.Sequence()` + `coll``

      Description

        Addition operator

        Append the content of @`coll` to this sequence and return the results as a new `Sequence`.

      Parameter `coll`

        The sequences to append to this sequence.

      Returns

        The result of the append as a new `Sequence`.

      Method `-

        ``Sequence` res = `ADT.Sequence()` - `coll``

      Description

        Subtraction operator

        Removes those values in this sequence that also are present in @`coll` and return the results as a new `Sequence`.

      Parameter `coll`

        The sequence to subtract from this sequence.

      Returns

        The result of the subtraction as a new `Sequence`.

      Method `[]

        ``mixed` res = `ADT.Sequence()`[ `index` ]`

      Description

        Index operator.

      Parameter `index`

        The index to get the value for, could be negative to index from the end.

      Returns

        The value at the index `index`.

      Throws

        An error if the index is out of range.

      Method `[]=

        ``ADT.Sequence()`[ `index` ] = `value``

      Description

        Index assign operator. Set the value at the index `index` to be `value`.

      Parameter `index`

        The index to set.

      Parameter `value`

        The new value.

      Returns

        The new value at the index `index`.

      Method `^

        ``Sequence` res = `ADT.Sequence()` ^ `coll``

      Description

        Xor operator Perform a xor on this sequence and the `coll` sequence by returning those values that is present in one of the sequences but not in both adapters as a new `Sequence`. The values are compared using `==.

      Parameter `coll`

        The sequence to xor with this sequence.

      Returns

        The result of the xor as a new `Sequence`.

      Method `|

        ``Sequence` res = `ADT.Sequence()` | `coll``

      Description

        Or operator Perform an or on this sequence and the `coll` sequence by returning those values that is present in both sequences as a new `Sequence`. The values are compared using `==.

      Parameter `coll`

        The sequence to or with this sequence.

      Returns

        The result of the or as a new `Sequence`.

      Method add

        ``void` add(`mixed` `value`)`

      Description

        Add a value at the end of the sequence.

      Parameter `value`

        The value to add.

      Method cast

        `(`array`)ADT.Sequence()`

      Description

        Cast operator.

      Parameter `type`

        Casts to this type.

        Casts to the following types are supported:

        ``"array"`` | Cast the content of this sequence to an array.

      Returns

        An array with the contents of this sequence.

      Method clear

        ``void` clear()`

      Description

        Clear the contents of the sequence.

      Method create

        `ADT.Sequence ADT.Sequence(`array`|`int` `arg`)`

      Description

        Creates a new `Sequence` around the array arg or a new `Sequence` with the size of arg.

      Method delete_value

        ``int` delete_value(`mixed` `value`)`

      Description

        Remove the first occurrence of the value `value` from the sequence.

      Parameter `value`

        The value to remove from the sequence.

      Returns

        The index of the removed element or -1 if there was no value to remove.

      Method first

        ``SequenceIterator` first()`

      Description

        Create and initiate a new SequenceIterator that could be used to iterate over this sequence.

      Returns

        An iterator positioned at the first element in the sequence.

      Method is_empty

        ``bool` is_empty()`

      Returns

        Returns `1` if the sequence is empty otherwise `0`.

      Method last

        ``SequenceIterator` last()`

      Description

        Create and initiate a new SequenceIterator that could be used to iterate over this sequence.

      Returns

        An iterator positioned after the last element in the sequence.

      Method max_size

        ``int` max_size()`

      Returns

        Returns -1.

      ## Class ADT.Sequence.SequenceIterator

        Description

          This is the iterator for the Sequence. It implements the IndexIterator and the OutputIterator

        Method _equal

          ``bool` equal(ADT.Sequence.SequenceIterator from, `mixed` `iter`)`

        Description

          Compare this iterator with another iterator.

        Parameter `iter`

          The iterator to compare with.

        Returns

          Returns `true` if both iterators iterates over the same objects and are positioned at the same spot.

        Method `!

          ``bool` res = !`ADT.Sequence.SequenceIterator()``

        Returns

          Returns `false` if the iterator has reached the end.

        Method `+

          ``SequenceIterator` res = `ADT.Sequence.SequenceIterator()` + `steps``

        Description

          Move the iterator `steps` steps forward (negative value on `steps` will cause the iterator to move backwards) and return the result as a new iterator.

        Returns

          A new iterator positioned `steps` steps forward.

        Method `+=

          ``ADT.Sequence.SequenceIterator()` += `steps``

        Description

          Move this iterator `steps` steps forward (negative value on `steps` will cause the iterator to move backwards) and return the result.

        Returns

          This iterator positioned `steps` steps forward.

        Method `-

          ``SequenceIterator` res = `ADT.Sequence.SequenceIterator()` - `steps``

        Description

          Move the iterator `steps` steps backwards (negative value on `steps` will cause the iterator to move forwards) and return the result as a new iterator.

        Returns

          A new iterator positioned `steps` steps backwards.

        Method `<

          ``bool` res = `ADT.Sequence.SequenceIterator()` < `iter``

        Description

          Less then operator.

        Returns

          Returns `true` if this iterator has a lower index then `iter`.

        Method `>

          ``bool` res = `ADT.Sequence.SequenceIterator()` > `iter``

        Description

          Greater then operator.

        Returns

          Returns `true` if this iterator has a higher index then `iter`.

        Method create

          `ADT.Sequence.SequenceIterator ADT.Sequence.SequenceIterator(`object` `sequence`, `void`|`int` `start`)`

        Description

          Creates a new iterator for the sequence `sequence`. If start is supplied it will try to position the iterator at `start`.

        Method distance

          ``int` distance(`object` `iter`)`

        Parameter `iter`

          The iterator to measure the distance to.

        Returns

          Returns distance between this iterator and `iter`.

        Throws

          An error if the two iterator could not be compared.

        Method get_collection

          ``Sequence` get_collection()`

        Returns

          Returns the Sequence this iterator currently iterates over.

        Method has_next

          ``bool` has_next(`void`|`int` `steps`)`

        Returns

          Returns `true` if it is possible to move `steps` steps forwards, if `steps` weren't supplied it check if it is possible to move one step forward.

        Method has_previous

          ``bool` has_previous(`void`|`int` `steps`)`

        Returns

          Returns `true` if it is possible to move `steps` steps backwards, if `steps` weren't supplied it check if it is possible to move one step backward.

        Method index

          ``int` index()`

        Returns

          The index at the current position.

        Method set_value

          ``mixed` set_value(`mixed` `val`)`

        Description

          Set the value at the current position.

        Parameter `val`

          The new value.

        Returns

          Returns the old value.

        Method value

          ``mixed` value()`

        Returns

          The value at the current position.

    ## Class ADT.Set

      Description

        ADT.Set implements a datatype for sets. These sets behave much like multisets, except that they are restricted to containing only one instance of each member value.

        From a performance viewpoint, it is probably more efficient for a Pike program to use mappings to serve as sets, rather than using an ADT.Set,so ADT.Set is mainly provided for the sake of completeness and code readability.

      Method _indices

        ``array`(`mixed`) indices( ADT.Set arg )`

      Description

        In analogy with multisets, indices() of an ADT.Set givess an array containing all members of the set.

      Method _sizeof

        ``int` sizeof( ADT.Set arg )`

      Description

        Number of items in the set.

      Method _sprintf

        `string sprintf(string format, ... ADT.Set arg ... )`

      Description

        Printable representation of the set.

      Method _values

        ``array`(`mixed`) values( ADT.Set arg )`

      Description

        In analogy with multisets, values() of an ADT.Set givess an array indicating the number of occurrences in the set for each position in the member array returned by indices(). (Most of the time, this is probably rather useless for sets, since the result is an array which just contain 1's, one for each member of the set. Still, this function is provided for consistency.

      Method `&

        ``this_program` res = `ADT.Set()` & `other``

      Description

        Intersection. Returns a set containing those values that were present in both the operand sets.

      Method `-

        ``this_program` res = `ADT.Set()` - `other``

      Description

        Difference. The expression 'A - B', where A and B are sets, returns all elements in A that are not also present in B.

      Method `<

        ``bool` res = `ADT.Set()` < `other``

      Description

        True subset. A < B returns true if each item in A is also present in B, and B contains at least one item not present in A.

      Method `==

        ``bool` res = `ADT.Set()` == `other``

      Description

        Equality. A == B returns true if all items in A are present in B, and all items in B are present in A. Otherwise, it returns false.

      Method `>

        ``bool` res = `ADT.Set()` > `other``

      Description

        True superset. A > B returns true if each item in B is also present in A, and A contains at least one item not present in B.

      Method `[]

        ``bool` res = `ADT.Set()`[ `item` ]`

      Description

        Indexing a set with a value V gives 1 if V is a member of the set, otherwise 0.

      Method `[]=

        ``ADT.Set()`[ `item` ] = `value``

      Description

        Setting an index V to 0 removes V from the set. Setting it to a non-0 value adds V as a member of the set.

      Method `|

        ``this_program` res = `ADT.Set()` | `other``

      Description

        Union. Returns a set containing all elements present in either or both of the operand sets.

      Method add

        ``void` add(`mixed` ... `items`)`

      Description

        Add `items` to the set.

      Method cast

        `(int)ADT.Set()
        (float)ADT.Set()
        (string)ADT.Set()
        (array)ADT.Set()
        (mapping)ADT.Set()
        (multiset)ADT.Set()`

      Description

        An ADT.Set can be cast to an array or a multiset.

      Method contains

        ``bool` contains(`mixed` `item`)`

      Description

        Check whether a value is a member of the set.

      Method create

        `ADT.Set ADT.Set(`void`|`ADT.Set`|`array`|`multiset`|`mapping` `initial_data`)`

      Description

        Create an ADT.Set, optionally initialized from another ADT.Set or a compatible type. If no initial data is given, the set will start out empty.

      Method filter

        ``this_program` filter(`function`(:`void`) `f`)`

      Description

        Return a filtered version of the set, containing only those members for which the filtering function `f` returned true.

        The filtering function is called with a single mixed-type argument which is the member value to be checked.

      Method filter_destructively

        ``this_program` filter_destructively(`function`(:`void`) `f`)`

      Description

        Destructively filter the set, i.e. remove every element for which the filtering function `f` returns 0, and then return the set.

        The filtering function is called with a single mixed-type argument which is the member value to be checked.

      Method is_empty

        ``bool` is_empty()`

      Description

        Returns 1 if the set is empty, otherwise 0.

      Method map

        ``array`(`mixed`) map(`function`(:`void`) `f`)`

      Description

        Map the values of a set: calls the map function `f` once for each member of the set, returning an array which contains the result of each one of those function calls. Note that since a set isn't ordered, the values in the returned array will be in more or less random order. If you need to know which member value produced which result, you have to make that a part of what the filtering function returns.

        The filtering function `f` is called with a single, mixed-type argument which is the member value to be mapped.

      Method remove

        ``void` remove(`mixed` ... `items`)`

      Description

        Remove `items` from the set.

      Method reset

        ``void` reset()`

      Description

        Remove all items from the set.

      Method subset

        ``bool` subset(`ADT.Set` `other`)`

      Description

        Subset. A <= B returns true if all items in A are also present in B.

      Method superset

        ``bool` superset(`ADT.Set` `other`)`

      Description

        Superset. A >= B returns true if all items in B are also present in A.

    ## Class ADT.Stack

      Description

        This class implements a simple stack. Instead of adding and removing elements to an array, and thus making it vary in size for every push and pop operation, this stack tries to keep the stack size constant. If however the stack risks to overflow, it will allocate double its current size, i.e. pushing an element on an full 32 slot stack will result in a 64 slot stack with 33 elements.

      Method _search

        ``int` search(ADT.Stack from, `mixed` `item`)`

      Description

        Return the stack-depth to `item`.

        This function makes it possible to use eg `search()` and `has_value()` on the stack.

      Method _sizeof

        ``int` sizeof( ADT.Stack arg )`

      Description

        `sizeof` on a stack returns the number of entries in the stack.

      Method _values

        ``array` values( ADT.Stack arg )`

      Description

        `values` on a stack returns all the entries in the stack, in order.

      Method `+

        ``this_program` res = `ADT.Stack()` + `s``

      Description

        A stack added with another stack yields a third a third stack will all the stack elements from the two first stacks.

      Method create

        `ADT.Stack ADT.Stack(`int`|`void` `initial_size`)`

      Description

        An initial stack size can be given when a stack is cloned. The default value is 32.

      Method pop

        ``mixed` pop(`void`|`int` `val`)`

      Description

        Pops and returns entry `val` from the stack, counting from the top. If no value is given the top element is popped and returned. All popped entries are freed from the stack.

      Method push

        ``void` push(`mixed` `val`)`

      Description

        Push an element on the top of the stack.

      Method quick_pop

        ``void` quick_pop(`void`|`int` `val`)`

      Description

        Pops `val` entries from the stack, or one entry if no value is given. The popped entries are not actually freed, only the stack pointer is moved.

      Method reset

        ``void` reset(`int`|`void` `initial_size`)`

      Description

        Empties the stack, resets the stack pointer and shrinks the stack size to the given value or 32 if none is given.

      See also

        `create`

      Method set_stack

        ``void` set_stack(`array` `stack`)`

      Description

        Sets the stacks content to the provided array.

      Method top

        ``mixed` top()`

      Description

        Returns the top element from the stack, without popping it.

      Throws

        Throws an error if called on an empty stack.

    ## Class ADT.Struct

      Description

        Implements a struct which can be used for serialization and deserialization of data.

      Example

            class ID3 {
                 inherit ADT.Struct;
                 Item head = Chars(3);
                 Item title = Chars(30);
                 Item artist = Chars(30);
                 Item album = Chars(30);
                 Item year = Chars(4);
                 Item comment = Chars(30);
                 Item genre = Byte();
               }
               Stdio.File f = Stdio.File("foo.mp3");
               f->seek(-128);
               ADT.Struct tag = ID3(f);
               if(tag->head=="TAG") {
                 write("Title: %s\n", tag->title);
                 tag->title = "A new title" + "\0"*19;
                 f->seek(-128);
                 f->write( (string)tag );
               }

      Example

            class HollerithString {
                 inherit ADT.Struct;
                 Item strlen = Word();
                 Item str = Chars(strlen);
               }

      Method _indices

        ``array`(`string`) indices( ADT.Struct arg )`

      Description

        The indices of a struct is the name of the struct items.

      Method _sizeof

        ``int` sizeof( ADT.Struct arg )`

      Description

        The size of the struct object is the number of bytes allocated for the struct.

      Method _values

        ``array` values( ADT.Struct arg )`

      Description

        The values of a struct is the values of the struct items.

      Method `[]
      Method `->

        ``mixed` res = `ADT.Struct()`[ `item` ]`
        ``mixed` res = `ADT.Struct()`->X`

      Description

        The struct can be indexed by item name to get the associated value.

      Method `[]=
      Method `->=

        ``ADT.Struct()`[ `item` ] = y`
        ``ADT.Struct()`->X = y`

      Description

        It is possible to assign a new value to a struct item by indexing it by name and assign a value.

      Method cast

        `(int)ADT.Struct()
        (float)ADT.Struct()
        (string)ADT.Struct()
        (array)ADT.Struct()
        (mapping)ADT.Struct()
        (multiset)ADT.Struct()`

      Description

        The struct can be casted into a string, which is eqivivalent to running `encode`, or into an array. When casted into an array each array element is the encoded value of that struct item.

      Method create

        `ADT.Struct ADT.Struct(`void`|`string`|`Stdio.File` `data`)`

      Parameter `data`

        Data to be decoded and populate the struct. Can either be a file object or a string.

      Method decode

        ``void` decode(`string`|`Stdio.File` `data`)`

      Description

        Decodes `data` according to the struct and populates the struct variables. The `data` can either be a file object or a string.

      Method encode

        ``string` encode()`

      Description

        Serializes the struct into a string. This string is equal to the string fed to `decode` if nothing in the struct has been altered.

      ## Class ADT.Struct.Byte

        Description

          One byte, integer value between 0 and 255.

        Method create

          `ADT.Struct.Byte ADT.Struct.Byte(`void`|`int(8bit)` `initial_value`)`

        Description

          The byte can be initialized with an optional value.

        Inherit Item

          `inherit Item : Item`

      ## Class ADT.Struct.Chars

        Description

          A string of bytes.

        Method create

          `ADT.Struct.Chars ADT.Struct.Chars(`int`|`Item` `size`, `void`|`string` `value`)`

        Description

          `size` is the number of bytes that are part of this struct item, or optionally an earlier Item that will be looked up in runtime. The initial value of the char string is `value` or, if not provided, a string of zero bytes.

        Inherit Item

          `inherit Item : Item`

      ## Class ADT.Struct.Drow

        Description

          One word (2 bytes) in intel order, integer value between 0 and 65535.

        See also

          `Word`

        Inherit Word

          `inherit Word : Word`

      ## Class ADT.Struct.Gnol

        Description

          One longword (4 bytes) in intel order, integer value between 0 and 2^32.

        See also

          `Long`

        Method create

          `ADT.Struct.Gnol ADT.Struct.Gnol(`void`|`int(0..)` `initial_value`)`

        Description

          The longword can be initialized with an optional value.

        Inherit Drow

          `inherit Drow : Drow`

      ## Class ADT.Struct.Item

        Description

          Interface class for struct items.

      ## Class ADT.Struct.Long

        Description

          One longword (4 bytes) in network order, integer value between 0 and 2^32.

        See also

          `Gnol`

        Method create

          `ADT.Struct.Long ADT.Struct.Long(`void`|`int(0..)` `initial_value`)`

        Description

          The longword can be initialized with an optional value.

        Inherit Word

          `inherit Word : Word`

      ## Class ADT.Struct.SByte

        Description

          One byte, signed integer value between -128 and 127.

        Method create

          `ADT.Struct.SByte ADT.Struct.SByte(`void`|`int(-128..127)` `initial_value`)`

        Description

          The byte can be initialized with an optional value.

        Inherit Item

          `inherit Item : Item`

      ## Class ADT.Struct.SLong

        Description

          One longword (4 bytes) in network order, signed integer value -(2^31) <= x < 2^31-1.

        Method create

          `ADT.Struct.SLong ADT.Struct.SLong(`void`|`int` `initial_value`)`

        Description

          The longword can be initialized with an optional value.

        Inherit SWord

          `inherit SWord : SWord`

      ## Class ADT.Struct.SWord

        Description

          One word (2 bytes) in network order, signed integer value between 0 and 65535.

        Method create

          `ADT.Struct.SWord ADT.Struct.SWord(`void`|`int(-32768..32767)` `initial_value`)`

        Description

          The word can be initialized with an optional value.

        Inherit Item

          `inherit Item : Item`

      ## Class ADT.Struct.Word

        Description

          One word (2 bytes) in network order, integer value between 0 and 65535.

        See also

          `Drow`

        Method create

          `ADT.Struct.Word ADT.Struct.Word(`void`|`int(16bit)` `initial_value`)`

        Description

          The word can be initialized with an optional value.

        Inherit Item

          `inherit Item : Item`

      ## Class ADT.Struct.int16

        Description

          Alias for `SWord`

        Inherit SWord

          `inherit SWord : SWord`

      ## Class ADT.Struct.int32

        Description

          Alias for `SLong`

        Inherit SLong

          `inherit SLong : SLong`

      ## Class ADT.Struct.int64

        Description

          64 bit signed integer.

        Inherit SLong

          `inherit SLong : SLong`

      ## Class ADT.Struct.int8

        Description

          Alias for `SByte`

        Inherit SByte

          `inherit SByte : SByte`

      ## Class ADT.Struct.uint16

        Description

          Alias for `Word`

        Inherit Word

          `inherit Word : Word`

      ## Class ADT.Struct.uint32

        Description

          Alias for `Long`

        Inherit Long

          `inherit Long : Long`

      ## Class ADT.Struct.uint64

        Description

          64 bit unsigned integer.

        Inherit Long

          `inherit Long : Long`

      ## Class ADT.Struct.uint8

        Description

          Alias for `Byte`

        Inherit Byte

          `inherit Byte : Byte`

    ## Class ADT.struct

      Description

        String buffer with the possibility to read and write data as they would be formatted in structs.

      Method add_data

        ``this_program` add_data(`string(8bit)` `s`)`

      Description

        Adds the data `s` verbatim to the end of the buffer.

      Method contents

        ``string(8bit)` contents()`

      Description

        Trims the buffer to only contain the data after the read pointer and returns the contents of the buffer.

      Method create

        `ADT.struct ADT.struct(`void`|`string(8bit)` `s`)`

      Description

        Create a new buffer, optionally initialized with the value `s`.

      Method get_bignum

        ``Gmp.mpz` get_bignum(`int`|`void` `len`)`

      Description

        Reads a bignum written by `put_bignum` from the buffer.

      Method get_fix_string

        ``string(8bit)` get_fix_string(`int` `len`)`

      Description

        Reads a fixed sized string of length `len` from the buffer.

      Method get_fix_uint_array

        ``array`(`int`) get_fix_uint_array(`int` `item_size`, `int` `size`)`

      Description

        Reads an array of integers as written by `put_fix_uint_array` from the buffer.

      Method get_rest

        ``string(8bit)` get_rest()`

      Description

        Get the remaining data from the buffer and clears the buffer.

      Method get_uint

        ``int(0..)` get_uint(`int` `len`)`

      Description

        Reads an unsigned integer from the buffer.

      Method get_var_string

        ``string(8bit)` get_var_string(`int` `len`)`

      Description

        Reads a string written by `put_var_string` from the buffer.

      Method get_var_uint_array

        ``array`(`int`) get_var_uint_array(`int` `item_size`, `int` `len`)`

      Description

        Reads an array of integers as written by `put_var_uint_array` from the buffer.

      Inherit Buffer

        `inherit Stdio.Buffer : Buffer`

      Method is_empty

        ``bool` is_empty()`

      Description

        Returns one if there is any more data to read.

      Method pop_data

        ``string(8bit)` pop_data()`

      Description

        Return all the data in the buffer and empties it.

      Method put_bignum

        ``this_program` put_bignum(`Gmp.mpz` `i`, `int(0..)`|`void` `len_width`)`

      Description

        Appends a bignum `i` as a variable string preceded with an unsigned integer of the size `len_width` declaring the length of the string. `len_width` defaults to 2.

      Method put_fix_string

        ``this_program` put_fix_string(`string(8bit)` `s`)`

      Description

        Appends the fix sized string `s` to the buffer.

      Method put_fix_uint_array

        ``this_program` put_fix_uint_array(`array`(`int`) `data`, `int(0..)` `item_size`)`

      Description

        Appends an array of unsigned integers of width `item_size` to the buffer.

      Method put_uint

        ``this_program` put_uint(`int` `i`, `int(0..)` `len`)`

      Description

        Appends an unsigned integer in network order to the buffer.

      Parameter `i`

        Unsigned integer to append.

      Parameter `len`

        Length of integer in bytes.

      Method put_var_string

        ``this_program` put_var_string(`string(8bit)` `s`, `int(0..)` `len_width`)`

      Description

        Appends a variable string `s` preceded with an unsigned integer of the size `len_width` declaring the length of the string. The string `s` should be 8 bits wide.

      Method put_var_string_array

        ``this_program` put_var_string_array(`array`(`string(8bit)`) `data`, `int(0..)` `item_size`, `int(0..)` `len`)`

      Description

        Appends an array of variable length strings with `item_size` bytes hollerith coding, prefixed by a `len` bytes large integer declaring the total size of the array in bytes.

      Method put_var_uint_array

        ``this_program` put_var_uint_array(`array`(`int`) `data`, `int(0..)` `item_size`, `int(0..)` `len`)`

      Description

        Appends an array of unsigned integers of width `item_size` to the buffer, preceded with an unsigned integer `len` declaring the size of the array in bytes.

    ## Module ADT.CritBit

      Description

        This module offers CritBit tree implementations for different key types.

      Note

        These CritBit trees support prefixes as proper keys. Hence they should really be called Tries.

      Method Tree

        ``object` Tree(`void`|`string`|`program`|`mapping` `type`)`

      Description

        Creates a CritBit tree for keys of type `type`. If no argument is given, an instance of `ADT.CritBit.StringTree` is returned. Supported types are `"string"`, `"int"`, `"float"`, `"ipv4"` and `Calendar.TimeRange`.

      Method sort_ipv4

        ``array`(`string`) sort_ipv4(`array`(`string`) `a`, `array` ... `data`)`

      Description

        Sorts an ARRAY OF IPv4-Adresses (and optional netmasks) given in dotted decimal representation with the /23 netmask notation.

      Example

            > array(string) a = ({ "127.0.0.121",
            >	 "127.0.0.0/16",
            >	 "127.0.0.1/8",
            >	 "127.0.0.0/8",
            >	 "128.0.0.0/1",
            >	 "192.168.21.3",
            >	 "8.8.8.8" });
            > write("%O\n", CritBit.sort_ipv4(a));
            ({ /* 7 elements */
            	"8.8.8.8",
            	"127.0.0.0/8",
            	"127.0.0.0/16",
            	"127.0.0.1/8",
            	"127.0.0.121",
            	"128.0.0.0/1",
            	"192.168.21.3"
            })

      ## Class ADT.CritBit.DateTree

        Method copy

          ``this_program` copy()`

        Description

          Copy callback to also clone backwards

        Method decode_key

          ``int`|`object` decode_key(`int` `i`)`

        Description

          Decodes an integer back to a `Calendar.TimeRange` object. Keeps a mapping of all keys stored in the tree to transform back.

        Method encode_key

          ``int` encode_key(`object`|`int` `o`)`

        Description

          Encodes a Calendar.TimeRange object into unix timestanp.

        Inherit IntTree

          `inherit C::IntTree : IntTree`

      ## Class ADT.CritBit.FloatTree

        Description

          This class implements a CritBit-tree/trie that can be used as a mapping-like data structure. Values of `float|int` can be used as indices, while any possible type (also `mixed`) can be stored.

          CritBit trees are prefixed based search trees that allow for fast random access as well as prefix and range based lookups. Keys are stored in alphabetical order and can be iterated over using `foreach`. Other than that, it can be used like `mapping(float|int:mixed)`.

        Example

              ADT.CritBit.FloatTree tree = ADT.CritBit.FloatTree();
              float|int key1 = 12.0;
              tree[key1] = ({ 4, 5, 6 });
              tree[key1]; // now is ({ 4, 5, 6 })
              m_delete(tree, key1); // tree is empty again

        Example

              ADT.CritBit.FloatTree tree = ADT.CritBit.FloatTree();
              array(float|int) a = ({ 80.4, 99.9, 14.2 });
              foreach(a; int idx; float|int val) {
              tree[val] = idx;
              }
              foreach(tree; float|int key; mixed val) {
              // in here the keys will be reached in order 14.2, 80.4 and 99.9.
              }

        Example

              ADT.CritBit.FloatTree tree = ADT.CritBit.FloatTree();
              array(float|int) a = ({ 80.4, 99.9, 14.2 });
              foreach (a; int idx; float|int val) {
              tree[val] = idx;
              }
              foreach(ADT.CritBit.FloatTree.Iterator(tree, -1); float|int key; mixed val) {
              // in here the keys will be reached in order 99.9, 80.4 and 14.2.
              }

        See also

          `ADT.CritBit.FloatTree.Iterator`

        Method _equal

          ``bool` equal(ADT.CritBit.FloatTree from, `mixed` `o`)`

        Method _indices

          ``array` indices( ADT.CritBit.FloatTree arg )`

        Description

          Returns a sorted array of indices of the `FloatTree`.

        Method _m_delete

          ``mixed` m_delete(ADT.CritBit.FloatTree from, `mixed` `key`)`

        Description

          m_delete callback.

        Method _random

          ``array` random( ADT.CritBit.FloatTree arg )`

        Description

          Get a random entry.

        Returns

          An array `({ key, value })`.

        Method _sizeof

          ``int` sizeof( ADT.CritBit.FloatTree arg )`

        Description

          Gives the number of entries in the `FloatTree`.

        Method _values

          ``array` values( ADT.CritBit.FloatTree arg )`

        Description

          Returns an array of values of the `FloatTree` object. The returned array matches `_indices` so that `mkmapping(indices(tree), values(tree))` would create a mapping with the same contents as this `FloatTree`.

        Method `+

          ``mixed` res = `ADT.CritBit.FloatTree()` + `o``

        Description

          Add callback. Returns the union of two trees.

        Method `-

          ``mixed` res = `ADT.CritBit.FloatTree()` - `o``

        Description

          Sub[s]tract two trees from each other (key-wise).

        Method `[..]

          ``mixed` res = `ADT.CritBit.FloatTree()`[start..end]`

        See also

          `predef::`[..]`

        Method `[]

          ``mixed` res = `ADT.CritBit.FloatTree()`[ `key` ]`

        Method `[]=

          ``ADT.CritBit.FloatTree()`[ `key` ] = `val``

        Method bkey

          ``string` bkey(`mixed` `key`)`

        Description

          Render the internally used binary representation of the key into a string as a strings of '0's and '1's.

        Method cast

          `(`mapping`)ADT.CritBit.FloatTree()`

        Description

          Cast callback. Supports only cast to mapping and behaves as the inverse of create().

        Method copy

          ``FloatTree` copy()`

        Description

          Create a copy of the tree.

        Method create

          `ADT.CritBit.FloatTree ADT.CritBit.FloatTree(`array`|`mapping`|`void` `o`)`

        Description

          Create a FloatTree from o.

        Method encode_key
        Method decode_key

          ``float`|`int` encode_key(`mixed` `o`)`
          ``mixed` decode_key(`float`|`int` `o`)`

        Description

          These callbacks can be implemented when inheriting FloatTree in order to allow for arbitrary key types. `encode_key` is similar to the `lfun::_hash()` callback. This only works as expected when it is possible to implement a unique representation for keys. These callbacks are called everytime a key is stored or indexed in the tree.

        Method depth

          ``int(0..)` depth()`

        Description

          Calculate the depth of the tree.

        Method first

          ``float`|`int` first()`

        Description

          Get the lexicographically first index in the tree.

        Method get_subtree

          ``FloatTree` get_subtree(`void`|`mixed` `key`)`

        Description

          Get a copy of the subtree starting at prefix `key`.

        Method last

          ``float`|`int` last()`

        Description

          Get the lexicographically last index in the tree.

        Method next

          ``float`|`int` next(`mixed` `current`)`

        Description

          Get the key after `current` in lexicographical order.

        Method nth

          ``mixed` nth(`int(0..)` `n`)`

        Description

          Get the `n`th entry in order.

        Returns

          An array `({ key, value })`.

        Method previous

          ``float`|`int` previous(`mixed` `current`)`

        Description

          Get the key before `current` in lexicographical order.

        ## Class ADT.CritBit.FloatTree._get_iterator

          Description

            Iterator class for FloatTree trees. Supports iterating over ranges with arbitrary stepping and direction.

            This is used by default when calling `foreach` on an object of FloatTree. In `foreach` the iterator runs over all elements from the first to the last.

          See also

            `predef::Iterator` for a description of the interface.

          Method create

            `ADT.CritBit.FloatTree._get_iterator ADT.CritBit.FloatTree._get_iterator(`void`|`int` `step`, `void`|`mixed` `start`, `void`|`mixed` `stop`)`

          Description

            Returns an iterator object that runs from `start` to `stop` using a stepsize of `step`. The arguments default to `1`, `tree->first()` and `tree->last()`, respectively.

      ## Class ADT.CritBit.IPv4Tree

        Description

          This class implements a CritBit-tree/trie that can be used as a mapping-like data structure. Values of `string` can be used as indices, while any possible type (also `mixed`) can be stored.

          CritBit trees are prefixed based search trees that allow for fast random access as well as prefix and range based lookups. Keys are stored in alphabetical order and can be iterated over using `foreach`. Other than that, it can be used like `mapping(string:mixed)`.

        Example

              ADT.CritBit.IPv4Tree tree = ADT.CritBit.IPv4Tree();
              string key1 = "127.0.0.0/8";
              tree[key1] = "reject";
              tree[key1]; // now is "reject"
              m_delete(tree, key1); // tree is empty again

        Example

              ADT.CritBit.IPv4Tree tree = ADT.CritBit.IPv4Tree();
              array(string) a = ({ "10.243.7.1", "127.0.0.1/8", "172.16.5.2" });
              foreach(a; int idx; string val) {
              tree[val] = idx;
              }
              foreach(tree; string key; mixed val) {
              // in here the keys will be reached in order "10.243.7.1", "127.0.0.1/8" and "172.16.5.2".
              }

        Example

              ADT.CritBit.IPv4Tree tree = ADT.CritBit.IPv4Tree();
              array(string) a = ({ "10.243.7.1", "127.0.0.1/8", "172.16.5.2" });
              foreach (a; int idx; string val) {
              tree[val] = idx;
              }
              foreach(ADT.CritBit.IPv4Tree.Iterator(tree, -1); string key; mixed val) {
              // in here the keys will be reached in order "172.16.5.2", "127.0.0.1/8" and "10.243.7.1".
              }

        See also

          `ADT.CritBit.IPv4Tree.Iterator`

        Method _equal

          ``bool` equal(ADT.CritBit.IPv4Tree from, `mixed` `o`)`

        Method _indices

          ``array` indices( ADT.CritBit.IPv4Tree arg )`

        Description

          Returns a sorted array of indices of the `IPv4Tree`.

        Method _m_delete

          ``mixed` m_delete(ADT.CritBit.IPv4Tree from, `mixed` `key`)`

        Description

          m_delete callback.

        Method _random

          ``array` random( ADT.CritBit.IPv4Tree arg )`

        Description

          Get a random entry.

        Returns

          An array `({ key, value })`.

        Method _sizeof

          ``int` sizeof( ADT.CritBit.IPv4Tree arg )`

        Description

          Gives the number of entries in the `IPv4Tree`.

        Method _values

          ``array` values( ADT.CritBit.IPv4Tree arg )`

        Description

          Returns an array of values of the `IPv4Tree` object. The returned array matches `_indices` so that `mkmapping(indices(tree), values(tree))` would create a mapping with the same contents as this `IPv4Tree`.

        Method `+

          ``mixed` res = `ADT.CritBit.IPv4Tree()` + `o``

        Description

          Add callback. Returns the union of two trees.

        Method `-

          ``mixed` res = `ADT.CritBit.IPv4Tree()` - `o``

        Description

          Sub[s]tract two trees from each other (key-wise).

        Method `[..]

          ``mixed` res = `ADT.CritBit.IPv4Tree()`[start..end]`

        See also

          `predef::`[..]`

        Method `[]

          ``mixed` res = `ADT.CritBit.IPv4Tree()`[ `key` ]`

        Method `[]=

          ``ADT.CritBit.IPv4Tree()`[ `key` ] = `val``

        Method bkey

          ``string` bkey(`mixed` `key`)`

        Description

          Render the internally used binary representation of the key into a string as a strings of '0's and '1's.

        Method cast

          `(`mapping`)ADT.CritBit.IPv4Tree()`

        Description

          Cast callback. Supports only cast to mapping and behaves as the inverse of create().

        Method common_prefix

          ``string`|`int` common_prefix()`

        Description

          Returns the common prefix of all keys. If the tree has no elements, `UNDEFINED` is returned.

        Method copy

          ``IPv4Tree` copy()`

        Description

          Create a copy of the tree.

        Method create

          `ADT.CritBit.IPv4Tree ADT.CritBit.IPv4Tree(`array`|`mapping`|`void` `o`)`

        Description

          Create a IPv4Tree from o.

        Method encode_key
        Method decode_key

          ``string` encode_key(`mixed` `o`)`
          ``mixed` decode_key(`string` `o`)`

        Description

          These callbacks can be implemented when inheriting IPv4Tree in order to allow for arbitrary key types. `encode_key` is similar to the `lfun::_hash()` callback. This only works as expected when it is possible to implement a unique representation for keys. These callbacks are called everytime a key is stored or indexed in the tree.

        Method depth

          ``int(0..)` depth()`

        Description

          Calculate the depth of the tree.

        Method first

          ``string` first()`

        Description

          Get the lexicographically first index in the tree.

        Method get_subtree

          ``IPv4Tree` get_subtree(`void`|`mixed` `key`)`

        Description

          Get a copy of the subtree starting at prefix `key`.

        Method last

          ``string` last()`

        Description

          Get the lexicographically last index in the tree.

        Method next

          ``string` next(`mixed` `current`)`

        Description

          Get the key after `current` in lexicographical order.

        Method nth

          ``mixed` nth(`int(0..)` `n`)`

        Description

          Get the `n`th entry in order.

        Returns

          An array `({ key, value })`.

        Method previous

          ``string` previous(`mixed` `current`)`

        Description

          Get the key before `current` in lexicographical order.

        ## Class ADT.CritBit.IPv4Tree._get_iterator

          Description

            Iterator class for IPv4Tree trees. Supports iterating over ranges with arbitrary stepping and direction.

            This is used by default when calling `foreach` on an object of IPv4Tree. In `foreach` the iterator runs over all elements from the first to the last.

          See also

            `predef::Iterator` for a description of the interface.

          Method create

            `ADT.CritBit.IPv4Tree._get_iterator ADT.CritBit.IPv4Tree._get_iterator(`void`|`int` `step`, `void`|`mixed` `start`, `void`|`mixed` `stop`)`

          Description

            Returns an iterator object that runs from `start` to `stop` using a stepsize of `step`. The arguments default to `1`, `tree->first()` and `tree->last()`, respectively.

      ## Class ADT.CritBit.IntTree

        Description

          This class implements a CritBit-tree/trie that can be used as a mapping-like data structure. Values of `int` can be used as indices, while any possible type (also `mixed`) can be stored.

          CritBit trees are prefixed based search trees that allow for fast random access as well as prefix and range based lookups. Keys are stored in alphabetical order and can be iterated over using `foreach`. Other than that, it can be used like `mapping(int:mixed)`.

        Example

              ADT.CritBit.IntTree tree = ADT.CritBit.IntTree();
              int key1 = 12;
              tree[key1] = ({ 1, 2 ,3 });
              tree[key1]; // now is ({ 1, 2 ,3 })
              m_delete(tree, key1); // tree is empty again

        Example

              ADT.CritBit.IntTree tree = ADT.CritBit.IntTree();
              array(int) a = ({ 1025, 15000, 3 });
              foreach(a; int idx; int val) {
              tree[val] = idx;
              }
              foreach(tree; int key; mixed val) {
              // in here the keys will be reached in order 3, 1025 and 15000.
              }

        Example

              ADT.CritBit.IntTree tree = ADT.CritBit.IntTree();
              array(int) a = ({ 1025, 15000, 3 });
              foreach (a; int idx; int val) {
              tree[val] = idx;
              }
              foreach(ADT.CritBit.IntTree.Iterator(tree, -1); int key; mixed val) {
              // in here the keys will be reached in order 15000, 1025 and 3.
              }

        See also

          `ADT.CritBit.IntTree.Iterator`

        Method _equal

          ``bool` equal(ADT.CritBit.IntTree from, `mixed` `o`)`

        Method _indices

          ``array` indices( ADT.CritBit.IntTree arg )`

        Description

          Returns a sorted array of indices of the `IntTree`.

        Method _m_delete

          ``mixed` m_delete(ADT.CritBit.IntTree from, `mixed` `key`)`

        Description

          m_delete callback.

        Method _random

          ``array` random( ADT.CritBit.IntTree arg )`

        Description

          Get a random entry.

        Returns

          An array `({ key, value })`.

        Method _sizeof

          ``int` sizeof( ADT.CritBit.IntTree arg )`

        Description

          Gives the number of entries in the `IntTree`.

        Method _values

          ``array` values( ADT.CritBit.IntTree arg )`

        Description

          Returns an array of values of the `IntTree` object. The returned array matches `_indices` so that `mkmapping(indices(tree), values(tree))` would create a mapping with the same contents as this `IntTree`.

        Method `+

          ``mixed` res = `ADT.CritBit.IntTree()` + `o``

        Description

          Add callback. Returns the union of two trees.

        Method `-

          ``mixed` res = `ADT.CritBit.IntTree()` - `o``

        Description

          Sub[s]tract two trees from each other (key-wise).

        Method `[..]

          ``mixed` res = `ADT.CritBit.IntTree()`[start..end]`

        See also

          `predef::`[..]`

        Method `[]

          ``mixed` res = `ADT.CritBit.IntTree()`[ `key` ]`

        Method `[]=

          ``ADT.CritBit.IntTree()`[ `key` ] = `val``

        Method bkey

          ``string` bkey(`mixed` `key`)`

        Description

          Render the internally used binary representation of the key into a string as a strings of '0's and '1's.

        Method cast

          `(`mapping`)ADT.CritBit.IntTree()`

        Description

          Cast callback. Supports only cast to mapping and behaves as the inverse of create().

        Method copy

          ``IntTree` copy()`

        Description

          Create a copy of the tree.

        Method create

          `ADT.CritBit.IntTree ADT.CritBit.IntTree(`array`|`mapping`|`void` `o`)`

        Description

          Create a IntTree from o.

        Method encode_key
        Method decode_key

          ``int` encode_key(`mixed` `o`)`
          ``mixed` decode_key(`int` `o`)`

        Description

          These callbacks can be implemented when inheriting IntTree in order to allow for arbitrary key types. `encode_key` is similar to the `lfun::_hash()` callback. This only works as expected when it is possible to implement a unique representation for keys. These callbacks are called everytime a key is stored or indexed in the tree.

        Method depth

          ``int(0..)` depth()`

        Description

          Calculate the depth of the tree.

        Method first

          ``int` first()`

        Description

          Get the lexicographically first index in the tree.

        Method get_subtree

          ``IntTree` get_subtree(`void`|`mixed` `key`)`

        Description

          Get a copy of the subtree starting at prefix `key`.

        Method last

          ``int` last()`

        Description

          Get the lexicographically last index in the tree.

        Method next

          ``int` next(`mixed` `current`)`

        Description

          Get the key after `current` in lexicographical order.

        Method nth

          ``mixed` nth(`int(0..)` `n`)`

        Description

          Get the `n`th entry in order.

        Returns

          An array `({ key, value })`.

        Method previous

          ``int` previous(`mixed` `current`)`

        Description

          Get the key before `current` in lexicographical order.

        ## Class ADT.CritBit.IntTree._get_iterator

          Description

            Iterator class for IntTree trees. Supports iterating over ranges with arbitrary stepping and direction.

            This is used by default when calling `foreach` on an object of IntTree. In `foreach` the iterator runs over all elements from the first to the last.

          See also

            `predef::Iterator` for a description of the interface.

          Method create

            `ADT.CritBit.IntTree._get_iterator ADT.CritBit.IntTree._get_iterator(`void`|`int` `step`, `void`|`mixed` `start`, `void`|`mixed` `stop`)`

          Description

            Returns an iterator object that runs from `start` to `stop` using a stepsize of `step`. The arguments default to `1`, `tree->first()` and `tree->last()`, respectively.

      ## Class ADT.CritBit.RangeSet

        Description

          Data structure representing a set of disjunct `ADT.Interval` objects. Can be thought of as an interval with gaps.

        Method create

          `ADT.CritBit.RangeSet ADT.CritBit.RangeSet(`function`(:`void`)|`object`|`program` `tree`)`

        Description

          Create a RangeSet from a given tree program.

      ## Class ADT.CritBit.StringTree

        Description

          This class implements a CritBit-tree/trie that can be used as a mapping-like data structure. Values of `string` can be used as indices, while any possible type (also `mixed`) can be stored.

          CritBit trees are prefixed based search trees that allow for fast random access as well as prefix and range based lookups. Keys are stored in alphabetical order and can be iterated over using `foreach`. Other than that, it can be used like `mapping(string:mixed)`.

        Example

              ADT.CritBit.StringTree tree = ADT.CritBit.StringTree();
              string key1 = "foo";
              tree[key1] = ({ 7, 8, 9 });
              tree[key1]; // now is ({ 7, 8, 9 })
              m_delete(tree, key1); // tree is empty again

        Example

              ADT.CritBit.StringTree tree = ADT.CritBit.StringTree();
              array(string) a = ({ "fooo", "bar", "ahead" });
              foreach(a; int idx; string val) {
              tree[val] = idx;
              }
              foreach(tree; string key; mixed val) {
              // in here the keys will be reached in order "ahead", "bar" and "foo".
              }

        Example

              ADT.CritBit.StringTree tree = ADT.CritBit.StringTree();
              array(string) a = ({ "fooo", "bar", "ahead" });
              foreach (a; int idx; string val) {
              tree[val] = idx;
              }
              foreach(ADT.CritBit.StringTree.Iterator(tree, -1); string key; mixed val) {
              // in here the keys will be reached in order "foo", "bar" and "ahead".
              }

        See also

          `ADT.CritBit.StringTree.Iterator`

        Method _equal

          ``bool` equal(ADT.CritBit.StringTree from, `mixed` `o`)`

        Method _indices

          ``array` indices( ADT.CritBit.StringTree arg )`

        Description

          Returns a sorted array of indices of the `StringTree`.

        Method _m_delete

          ``mixed` m_delete(ADT.CritBit.StringTree from, `mixed` `key`)`

        Description

          m_delete callback.

        Method _random

          ``array` random( ADT.CritBit.StringTree arg )`

        Description

          Get a random entry.

        Returns

          An array `({ key, value })`.

        Method _sizeof

          ``int` sizeof( ADT.CritBit.StringTree arg )`

        Description

          Gives the number of entries in the `StringTree`.

        Method _values

          ``array` values( ADT.CritBit.StringTree arg )`

        Description

          Returns an array of values of the `StringTree` object. The returned array matches `_indices` so that `mkmapping(indices(tree), values(tree))` would create a mapping with the same contents as this `StringTree`.

        Method `+

          ``mixed` res = `ADT.CritBit.StringTree()` + `o``

        Description

          Add callback. Returns the union of two trees.

        Method `-

          ``mixed` res = `ADT.CritBit.StringTree()` - `o``

        Description

          Sub[s]tract two trees from each other (key-wise).

        Method `[..]

          ``mixed` res = `ADT.CritBit.StringTree()`[start..end]`

        See also

          `predef::`[..]`

        Method `[]

          ``mixed` res = `ADT.CritBit.StringTree()`[ `key` ]`

        Method `[]=

          ``ADT.CritBit.StringTree()`[ `key` ] = `val``

        Method bkey

          ``string` bkey(`mixed` `key`)`

        Description

          Render the internally used binary representation of the key into a string as a strings of '0's and '1's.

        Method cast

          `(`mapping`)ADT.CritBit.StringTree()`

        Description

          Cast callback. Supports only cast to mapping and behaves as the inverse of create().

        Method common_prefix

          ``string`|`int` common_prefix()`

        Description

          Returns the common prefix of all keys. If the tree has no elements, `UNDEFINED` is returned.

        Method copy

          ``StringTree` copy()`

        Description

          Create a copy of the tree.

        Method create

          `ADT.CritBit.StringTree ADT.CritBit.StringTree(`array`|`mapping`|`void` `o`)`

        Description

          Create a StringTree from o.

        Method encode_key
        Method decode_key

          ``string` encode_key(`mixed` `o`)`
          ``mixed` decode_key(`string` `o`)`

        Description

          These callbacks can be implemented when inheriting StringTree in order to allow for arbitrary key types. `encode_key` is similar to the `lfun::_hash()` callback. This only works as expected when it is possible to implement a unique representation for keys. These callbacks are called everytime a key is stored or indexed in the tree.

        Method depth

          ``int(0..)` depth()`

        Description

          Calculate the depth of the tree.

        Method first

          ``string` first()`

        Description

          Get the lexicographically first index in the tree.

        Method get_subtree

          ``StringTree` get_subtree(`void`|`mixed` `key`)`

        Description

          Get a copy of the subtree starting at prefix `key`.

        Method last

          ``string` last()`

        Description

          Get the lexicographically last index in the tree.

        Method next

          ``string` next(`mixed` `current`)`

        Description

          Get the key after `current` in lexicographical order.

        Method nth

          ``mixed` nth(`int(0..)` `n`)`

        Description

          Get the `n`th entry in order.

        Returns

          An array `({ key, value })`.

        Method previous

          ``string` previous(`mixed` `current`)`

        Description

          Get the key before `current` in lexicographical order.

        ## Class ADT.CritBit.StringTree._get_iterator

          Description

            Iterator class for StringTree trees. Supports iterating over ranges with arbitrary stepping and direction.

            This is used by default when calling `foreach` on an object of StringTree. In `foreach` the iterator runs over all elements from the first to the last.

          See also

            `predef::Iterator` for a description of the interface.

          Method create

            `ADT.CritBit.StringTree._get_iterator ADT.CritBit.StringTree._get_iterator(`void`|`int` `step`, `void`|`mixed` `start`, `void`|`mixed` `stop`)`

          Description

            Returns an iterator object that runs from `start` to `stop` using a stepsize of `step`. The arguments default to `1`, `tree->first()` and `tree->last()`, respectively.

    ## Module ADT.Relation

      ## Class ADT.Relation.Binary

        Method _sizeof

          ``mixed` sizeof( ADT.Relation.Binary arg )`

        Description

          Returns the number of relation entries in the relation. (Or with other words: the number of relations in the relation set.)

        Method `&

          ``mixed` res = `ADT.Relation.Binary()` & `rel``

        Description

          The expression `rel1 & rel2' returns a new relation which has those and only those relation entries that are present in both rel1 and rel2.

        Method `()

          ``mixed` res = `ADT.Relation.Binary()`()`

        Description

          Does the same as the `contains` function: returns true if the relation "`left` R `right`" exists, and otherwise false.

        Method `+
        Method `|

          ``mixed` res = `ADT.Relation.Binary()` + `rel``
          ``mixed` res = `ADT.Relation.Binary()` | `rel``

        Description

          The expression `rel1 | rel2' and `rel1 + rel2' returns a new relation which has all the relation entries present in rel1, or rel2, or both.

        Method `-

          ``mixed` res = `ADT.Relation.Binary()` - `rel``

        Description

          The expression `rel1 - rel2' returns a new relation which has those and only those relation entries that are present in rel1 and not present in rel2.

        Method add

          ``this_program` add(`mixed` `left`, `mixed` `right`)`

        Description

          Adds "`left` R `right`" as a member of the relation. Returns the same relation.

        Method contains

          ``mixed` contains(`mixed` `left`, `mixed` `right`)`

        Description

          Return true/false: does the relation "`left` R `right`" exist?

        Method filter

          ``object` filter(`function`(:`void`) `f`)`

        Description

          Filters the entries in the relation, and returns a relation with all those entries for which the filtering function `f` returned true. The function `f` gets two arguments: the left and the right value for every entry in the relation.

        Method filter_destructively

          ``this_program` filter_destructively(`function`(:`void`) `f`)`

        Description

          Filters the entries in the relation destructively, removing all entries for which the filtering function `f` returns false. The function `f` gets two arguments: the left and the right value for each entry in the relation.

        Method find_shortest_path

          ``array` find_shortest_path(`mixed` `from`, `mixed` `to`, `void`|`multiset` `avoiding`)`

        Description

          Assuming the relation's domain and range sets are equal, and that the relation xRy means "there is a path from node x to node y", `find_shortest_path` attempts to find a path with a minimum number of steps from one given node to another. The path is returned as an array of nodes (including the starting and ending node), or 0 if no path was found. If several equally short paths exist, one of them will be chosen pseudorandomly.

          Trying to find a path from a node to itself will always succeed, returning an array of one element: the node itself. (Or in other words, a path with no steps, only a starting/ending point).

          The argument `avoiding` is either 0 (or omitted), or a multiset of nodes that must not be part of the path.

        Method get_id

          ``mixed` get_id()`

        Description

          Return the ID value which was given as first argument to create().

        Method make_symmetric

          ``this_program` make_symmetric()`

        Description

          Makes the relation symmetric, i.e. makes sure that if xRy is part of the relation set, then yRx should also be a part of the relation set.

        Method map

          ``array` map(`function`(:`void`) `f`)`

        Description

          Maps every entry in the relation. The function f gets two arguments: the left and the right relation value. Returns an array with the return values of f for each and every mapped entry.

          Note: since the entries in the relation are not ordered, the returned array will have its elements in no particular order. If you need to know which relation entry produced which result in the array, you have to make that information part of the value that `f` returns.

        Method remove

          ``this_program` remove(`mixed` `left`, `mixed` `right`)`

        Description

          Removes "`left` R `right`" as a member of the relation. Returns the same relation.

        ## Class ADT.Relation.Binary._get_iterator

          Description

            An iterator which makes all the left/right entities in the relation available as index/value pairs.

    ## Module ADT.Table

      Description

        ADT.Table is a generic module for manipulating tables.

        Each table contains one or several columns. Each column is associated with a name, the column name. Optionally, one can provide a column type. The Table module can do a number of operations on a given table, like computing the sum of a column, grouping, sorting etc.

        All column references are case insensitive. A column can be referred to by its position (starting from zero). All operations are non-destructive. That means that a new table object will be returned after, for example, a sort.

      ## Class ADT.Table.table

        Description

          The table base-class.

        Method _indices

          ``array`(`string`) indices( ADT.Table.table arg )`

        Description

          This method returns the column names for the table. The case used when the table was created will be returned.

        Method _sizeof

          ``int` sizeof( ADT.Table.table arg )`

        Description

          This method returns the number of rows in the table.

        Method _values

          ``array`(`array`) values( ADT.Table.table arg )`

        Description

          This method returns the contents of a table as a two dimensional array. The format is an array of rows. Each row is an array of columns.

        Method `==

          ``int` res = `ADT.Table.table()` == `table``

        Description

          This method compares two tables. They are equal if the contents of the tables and the column names are equal. The column name comparison is case insensitive.

        Method `[]

          ``array` res = `ADT.Table.table()`[ `column` ]`

        Description

          Same as `col()`.

        Method append_bottom

          ``object` append_bottom(`object` `table`)`

        Description

          This method appends two tables. The table given as an argument will be added at the bottom of the current table. Note, the column names must be equal. The column name comparison is case insensitive.

        Method append_right

          ``object` append_right(`object` `table`)`

        Description

          This method appends two tables. The table given as an argument will be added on the right side of the current table. Note that the number of rows in both tables must be equal.

        Method col

          ``array` col(`int`|`string` `column`)`

        Description

          This method returns the contents of a given column as an array.

        Method create

          `ADT.Table.table ADT.Table.table(`array`(`array`) `table`, `array`(`string`) `column_names`, `array`(`mapping`(`string`:`string`))|`void` `column_types`)`

        Description

          The `ADT.Table.table` class takes two or three arguments:

        Parameter `table`

          The first argument is a two-dimensional array consisting of one array of columns per row. All rows must have the same number of columns as specified in `column_names`.

        Parameter `column_names`

          This argument is an array of column names associated with each column in the table. References by column name are case insensitive. The case used in `column_names` will be used when the table is displayed. A column can also be referred to by its position, starting from zero.

        Parameter `column_types`

          This is an optional array of mappings. The column type information is only used when displaying the table. Currently, only the keyword `"type"` is recognized. The type can be specified as `"text"` or `"num"` (numerical). Text columns are left adjusted, whereas numerical columns are right adjusted. If a mapping in the array is 0 (zero), it will be assumed to be a text column. If `column_types` is omitted, all columns will displayed as text.

          See `ADT.Table.ASCII.encode()` on how to display a table.

        See also

          `ADT.Table.ASCII.encode()`

        Method decode

          ``object` decode(`string` `s`)`

        Description

          This method returns a table object from a binary string representation of a table, as returned by `encode()`.

        Method distinct

          ``this_program` distinct(`int`|`string` ... `columns`)`

        Description

          This method groups by the given columns and returns a table with only unique rows. When no columns are given, all rows will be unique. A new table object will be returned.

        Method encode

          ``string` encode()`

        Description

          This method returns a binary string representation of the table. It is useful when one wants to store a the table, for example in a file.

        Method group

          ``this_program` group(`mapping`(`int`|`string`:`function`(:`void`))|`function`(:`void`) `f`, `mixed` ... `args`)`

        Description

          This method calls the function `f` for each column each time a non uniqe row will be joined. The table will be grouped by the columns not listed. The result will be returned as a new table object.

        Method limit

          ``object` limit(`int` `n`)`

        Description

          This method truncates the table to the first `n` rows and returns a new object.

        Method map

          ``object` map(`function`(:`void`) `f`, `array`(`int`|`string`)|`int`|`string` `columns`, `mixed` ... `args`)`

        Description

          This method calls the function `f` for all rows in the table. The value returned will replace the values in the columns given as argument to map. If the function returns an array, several columns will be replaced. Otherwise the first column will be replaced. The result will be returned as a new table object.

        Method remove

          ``object` remove(`int`|`string` ... `columns`)`

        Description

          Like `select()`, but the given `columns` will not be in the resulting table.

        Method rename

          ``object` rename(`string`|`int` `from`, `string` `to`)`

        Description

          This method renames the column named `from` to `to` and returns a new table object. Note that `from` can be the column position.

        Method reverse

          ``object` reverse()`

        Description

          This method reverses the rows of the table and returns a new table object.

        Method row

          ``array` row(`int` `row_number`)`

        Description

          This method returns the contents of a given row as an array.

        Method rsort

          ``object` rsort(`int`|`string` ... `columns`)`

        Description

          Like `sort()`, but in descending order.

        Method select

          ``object` select(`int`|`string` ... `columns`)`

        Description

          This method returns a new table object with the selected columns only.

        Method sort

          ``object` sort(`int`|`string` ... `columns`)`

        Description

          This method sorts the table in ascendent order on one or several columns and returns a new table object. The left most column is sorted last. Note that the sort is stable.

        See also

          `rsort()`

        Method sum

          ``this_program` sum(`int`|`string` ... `columns`)`

        Description

          This method sums all equal rows. The table will be grouped by the columns not listed. The result will be returned as a new table object.

        Method type

          ``mapping` type(`int`|`string` `column`, `void`|`mapping` `type`)`

        Description

          This method gives the type for the given `column`.

          If a second argument is given, the old type will be replaced with `type`. The column type is only used when the table is displayed. The format is as specified in `create()`.

        Method where

          ``object` where(`array`(`int`|`string`)|`int`|`string` `columns`, `function`(:`void`) `f`, `mixed` ... `args`)`

        Description

          This method calls the function for each row. If the function returns zero, the row will be thrown away. If the function returns something non-zero, the row will be kept. The result will be returned as a new table object.

      ## Module ADT.Table.ASCII

        Method encode

          ``string` encode(`object` `table`, `void`|`mapping` `options`)`

        Description

          This method returns a table represented in ASCII suitable for human eyes. `options` is an optional mapping. If the keyword `"indent"` is used with a number, the table will be indented with that number of space characters.