<xtree [XTREE=$treename] $command [$values] [$treename][ /]>
<xtree [XTREE=$treename] [options] $command [$values] [$treename]>
xtree function is a fast way to maintain a sorted list of
string values in memory - faster than using a SQL table. Values can
be added, removed, counted and deleted from a tree, named with
$treename (default tree name is empty). The
parameter is the list of values to operate on, for
SET it is the option(s) to
set. Otherwise the
$values parameter is not given, or is empty
$treename is specified via the last-argument syntax.
Each value in an xtree has a count and a sequence number associated
with it. The count is the number of times the value was inserted.
The sequence number is the order in which the value was first
inserted, starting with 0 for the first value inserted. These values
are retrieved either with the
(non-loop syntax), or in the
variables (looping version).
If no options (or only
XTREE option) are given to
xtree, it returns values in
$ret as a simple function.
If any of the following options are given (except
xtree is a looping block command, e.g. a closing
</xtree>" tag is expected, and
set as in
$loop always starts at 0). Any
statements inside the block are executed once per returned value, with
$ret being a loop variable accumulating values. In addition,
$ret.seq are also looped
over and set to the corresponding count and sequence numbers for
$ret. The loop can be exited with
RETURN. The loop syntax was added in version 2.6.938200000
19990924. Options are:
SQL, do not accumulate hits in
$ret.seq, and do not make them loop variables; each new value erases the previous.
ROWshould be used in a looping
xtreewhen a large number of return values are expected but only need to be examined one at a time; this saves memory and time since all the values do not have to be stored in memory.
ROWshould also be used when functions are called within the block, because otherwise
$retis a loop variable, hindering multi-value returns.
ROWshould also be used when the
SEQcommands are not to be used, as it saves the memory of preserving those values for a later
SKIP=$nSkip the first
$nvalues. This does not affect the value of
MAX=$nReturn at most
XTREE=$treenameUse tree named
$treenameinstead of the default. This option was added in version 5.01.1217380000 20080729. The old syntax was to give the tree name as the last argument, with no option name, which can be confusing. Only one syntax -
XTREEoption or last-unnamed-argument - may be used in a statement.
$command argument determines what
whether it takes a
$values argument or not, and what values, if
any, are returned. It is one of the following commands:
CLEARClear the tree. All counts are set to 0, but the tree and its values remain in memory.
$valuesneed not be set. No values are returned.
DUMPDump the tree. The return value
$retis a unique, sorted list of the values in the tree that have non-zero counts, in ascending order. In the looping syntax,
$ret.seqare set to the corresponding count and sequence numbers; in the non-looping syntax, these values must be retrieved with separate
SEQcommands afterwards. If the
CLEARoption (not command) is set with
SET, each value is also cleared as it is returned.
$valuesneed not be set.
COUNTDump the value counts from the immediately previous non-looping
INSERTcommand on the same-named tree.
$retwill contain a list of the number of times each value from the operation occurs in the tree. For the looping syntax, nothing is returned - the counts and sequences are available during the
$valuesneed not be set.
SEQReturns the corresponding sequence numbers (starting at 0), from the immediately previous non-looping
INSERTon the same-named tree. These indicate the order in which the strings were originally added. For the looping syntax, nothing is returned - the counts and sequences are available during the
$valuesneed not be set.
$valuesto the tree, if not already present, and increment their counts. If the
NOADDoption is set (below), new values are not added; only already-present values are incremented. In versions after 3.01.963400000 20000712, the inserted values, counts, and sequence numbers are returned. This saves an extra
SEARCHto determine the numbers right after an
INSERT. Previous versions returned nothing.
$valuesfrom the tree, i.e. sets their counts to 0. No values are returned in
SEARCHReturns a list of the
$valuesthat are in the tree. For the looping syntax,
$ret.seqare set to the corresponding count and sequence numbers. For the non-looping syntax, use
SEQimmediately afterward to obtain the counts and sequence numbers.
Set the option(s) given in
$values. In version
6.00.1305253000 20110512 and later, 1 is returned on success, 0 on
failure; previous versions always returned empty string. Looping
version iterates 0 times (since there is no equivalent count and
sequence number for the returned success/fail code).
Do not add new values to the tree during an
Inserting a previously-cleared value will make it
"reappear", because it was present before but now has a
non-zero count. But wholly-new values will not be inserted.
clearAlso clear the tree during a
stringcomparemode $modeSet string compare mode - how values are compared - for the tree to
$mode. The syntax is the same as the
stringcomparemode(here). The default (and the meaning of values
builtin) is the current
stringcomparemode. This option must be set before any data is inserted into the tree, as it would alter the sort order. Added in version 6.
storefolded $onOffSet the store-folded flag for the tree to
$onOff(i.e. "on" or "off"). Enabling store-folded increases speed slightly, at the expense of not retaining inserted values exactly.
storefolded is on, values are folded (according to
stringcomparemode) once, at insert time, and stored
folded. This increases speed because only one folding is
needed. However, values returned from
DUMP etc. will
be the folded value, not the originally-inserted value.
stringcomparemode is set to
the inserted value "
McDuff" will be
storefolded is off (the default), values are folded
whenever needed for comparisons, and stored exactly as
inserted. This decreases speed because potentially more than
one folding is needed. However, the originally-inserted value
is preserved, i.e. if "
McDuff" is inserted in an
ignorecase tree, it will be
In either case,
stringcomparemode is respected for
searches, inserts etc.; just the value of
affected. This option must be set before any data is
inserted into the tree, as it would alter the sort order.
Added in version 6.
storefolded are off;
stringcomparemode is the
same as the
<apicp> value. Note that since the last
two settings can only be set on an empty tree, defaults can
only be fully restored on an empty tree as well. In version
6.00.1305312600 20110513 and earlier,
storefolded mode were not restored at all when
Gets the option(s) listed in
$values. Added in version
6.00.1305253000 20110512. Options and what they return are:
1 if not adding new values to the tree during an
0 if adding.
1 if clearing the tree during a
DUMP, 0 if not.
stringcomparemode for the tree.
1 if storing values folded, 0 if not.
The number of items in the tree, i.e. the number of non-zero
count items (returned by
DUMP). It is much faster
(constant-time) to obtain this value via
DUMPing the tree and checking
The number of allocated items in the tree, i.e. including zero-count (cleared) items.
The number of bytes of memory used by the tree.
FLUSHRemove the tree and free its memory.
xtree function returns either nothing, a list of strings,
or a list of integer counts. If invoked as a looping command,
$ret.seq may be set as well.
<$txt = "senselessness" "this" "test" "finesse">
<rex "." $txt> <!-- split the words into letters -->
<xtree INSERT $ret>
<xtree ROW DUMP>
The output would be a count of how many times each letter occurs among all the words:
xtree function was added Apr. 29 1997. The loop syntax
was added in version 2.6.938200000 19990924, as was support for
full binary data.
$ret.seq are only set in the looping version.
It is not possible to modify an xtree while inside an
loop for the same tree, nor is it possible to start another
DUMP inside the loop. An error message such as "Cannot
flush xtree: still in use" or "Cannot insert into xtree while
walking it" may be generated in such cases.
In long-running scripts, trees should be
FLUSHed when done,
to save memory. Since they are kept only in memory, they will be lost
when the script exits.
ROW should be used whenever possible
to save memory and speed.
In version 6 and later, string comparisons use the current apicp stringcomparemode setting (here), changeable with the set stringcomparemode tree option.