File: refU.html

package info (click to toggle)
picolisp 25.12-1
links: PTS, VCS
area: main
in suites: sid
size: 7,388 kB
sloc: ansic: 3,092; javascript: 1,004; makefile: 107; sh: 2
file content (433 lines) | stat: -rw-r--r-- 13,602 bytes
parent folder | download | duplicates (3)
<!--
# VIP @lib/vip/html.l
# 26oct23 Software Lab. Alexander Burger
-->

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>U</title>
<link rel="stylesheet" href="doc.css" type="text/css">
</head>
<body>

<h1>U</h1>

<dl>

<dt><a id="*Uni"><code>*Uni</code></a></dt>
<dd>A global variable holding an <code><a href="refI.html#idx">idx</a></code>
tree, with all unique data that were collected with the comma (<code>,</code>)
read-macro. Typically used for localization. Setting <code>*Uni</code> to
<code>T</code> disables this mechanism. See also <code><a
href="ref.html#macro-io">Read-Macros</a></code> and <code><a
href="refL.html#locale">locale</a></code>.

<pre>
: (off *Uni)            # Clear
-> NIL
: ,"abc"                # Collect a transient symbol
-> "abc"
: ,(1 2 3)              # Collect a list
-> (1 2 3)
: *Uni
-> ("abc" NIL (1 2 3))
</pre></dd>

<dt><a id="+UB"><code>+UB</code></a></dt>
<dd>Prefix class for <code><a href="refA.html#+Aux">+Aux</a></code> to maintain
an UB-Tree index instead of the direct values. This allows efficient range
access to multi-dimensional data. Only positive numeric keys are supported. See
also <code><a href="refU.html#ubIter">ubIter</a></code> and <a
href="ref.html#dbase">Database</a>.

<pre>
(class +Pos +Entity)
(rel x (+UB +Aux +Ref +Number) (y z))
(rel y (+Number))
(rel z (+Number))

: (scan (tree 'x '+Pos))
(288362200753438306 . {13}) {13}
(348187139486943716 . {16}) {16}
(605261596962573238 . {11}) {11}
(638523558602802506 . {7}) {7}   # UBKEY of (453062 450921 613956)
(654697989157410399 . {12}) {12}
...

: (show '{7})
{7} (+Pos)
   x 453062
   y 450921
   z 613956
-> {7}

# Discrete queries work the same way as without the +UB prefix
: (db 'x '+Pos 453062 'y 450921 'z 613956)
-> {7}
: (aux 'x '+Pos 453062 450921 613956)
-> {7}
: (? (db x +Pos (453062 450921 613956) @Pos))
 @Pos={7}
-> NIL

# Range queries work efficiently with 'collect'. Note that though also Pilog
queries can handle UB-trees, they may do so sub-optimally for certain ranges.
: (collect 'x '+Pos (200000 200000 200000) (899999 899999 899999))
-> ({7} {14} {17} {15})
</pre></dd>

<dt><a id="u"><code>(u) -> T</code></a></dt>
<dd>(Debug mode only) Removes <code><a href="ref_.html#!">!</a></code> all
breakpoints in all subexpressions of the current breakpoint. Typically used when
single-stepping a function or method with <code><a
href="refD.html#debug">debug</a></code>. See also <code><a
href="refD.html#d">d</a></code> and <code><a
href="refU.html#unbug">unbug</a></code>.

<pre>
! (u)                         # Unbug subexpression(s) at breakpoint
-> T
</pre></dd>

<dt><a id="ubIter"><code>(ubIter 'tree 'dim 'fun 'lst1 'lst2)</code></a></dt>
<dd>Efficiently iterates through a database <code><a
href="refU.html#+UB">+UB</a></code> tree, by applying <code>fun</code> to all
values. <code>dim</code> is the number of the key dimensions, <code>lst1</code>
and <code>lst2</code> specify a range of keys. <code><a
href="refC.html#collect">collect</a></code> uses <code>ubIter</code> internally
for UB-tree queries. See also <code><a href="refI.html#iter">iter</a></code>.

<pre>
: (ubIter (tree 'x '+Pos) 3 show (200000 200000 200000) (899999 899999 899999))
{7} (+Pos)
   z 613956
   y 450921
   x 453062
{14} (+Pos)
   z 771372
   y 262217
   x 862358
{17} (+Pos)
   z 676836
   y 529576
   x 398229
{15} (+Pos)
   z 889332
   y 691799
   x 265381
-> NIL
</pre></dd>

<dt><a id="udp"><code>(udp 'any1 'any2 'any3) -> any</code></a></dt>
<dt><code>(udp 'cnt) -> any</code></dt>
<dd>Simple unidirectional sending/receiving of UDP packets. In the first form,
<code>any3</code> is sent to a UDP server listening at host <code>any1</code>,
port <code>any2</code>. In the second form, one item is received from a UDP
socket <code>cnt</code>, established with <code><a
href="refP.html#port">port</a></code>. See also <code><a
href="refL.html#listen">listen</a></code> and <code><a
href="refC.html#connect">connect</a></code>.

<pre>
# First session
: (port T 6666)
-> 3
: (udp 3)  # Receive a datagram

# Second session (on the same machine)
: (udp "localhost" 6666 '(a b c))
-> (a b c)

# First session
-> (a b c)
</pre></dd>

<dt><a id="ultimo"><code>(ultimo 'y 'm) -> cnt</code></a></dt>
<dd>Returns the <code><a href="refD.html#date">date</a></code> of the last day
of the month <code>m</code> in the year <code>y</code>. See also <code><a
href="refD.html#day">day</a></code> and <code><a
href="refW.html#week">week</a></code>.

<pre>
: (date (ultimo 2007 1))
-> (2007 1 31)
: (date (ultimo 2007 2))
-> (2007 2 28)
: (date (ultimo 2004 2))
-> (2004 2 29)
: (date (ultimo 2000 2))
-> (2000 2 29)
: (date (ultimo 1900 2))
-> (1900 2 28)
</pre></dd>

<dt><a id="unbug"><code>(unbug 'sym) -> T</code></a></dt>
<dt><code>(unbug 'sym 'cls) -> T</code></dt>
<dt><code>(unbug '(sym . cls)) -> T</code></dt>
<dd>(Debug mode only) Removes all <code><a href="ref_.html#!">!</a></code>
breakpoints in the function or method body of sym, as inserted with <code><a
href="refD.html#debug">debug</a></code> or <code><a
href="refD.html#d">d</a></code>, or directly with <code><a
href="refV.html#vi">vi</a></code>. See also <code><a
href="refU.html#u">u</a></code>.

<pre>
: (pp 'tst)
(de tst (N)
   (! println (+ 3 N)) )         # 'tst' has a breakpoint '!'
-> tst
: (unbug 'tst)                   # Unbug it
-> T
: (pp 'tst)                      # Restore
(de tst (N)
   (println (+ 3 N)) )
</pre></dd>

<dt><a id="undef"><code>(undef 'sym) -> fun</code></a></dt>
<dt><code>(undef 'sym 'cls) -> fun</code></dt>
<dt><code>(undef '(sym . cls)) -> fun</code></dt>
<dd>Undefines the function or method <code>sym</code>. Returns the previous
definition. See also <code><a href="refD.html#de">de</a></code>, <code><a
href="refD.html#dm">dm</a></code>, <code><a href="refD.html#def">def</a></code>
and <code><a href="refR.html#redef">redef</a></code>.

<pre>
: (de hello () "Hello world!")
-> hello
: hello
-> (NIL "Hello world!")
: (undef 'hello)
-> (NIL "Hello world!")
: hello
-> NIL
</pre></dd>

<dt><a id="unify"><code>(unify 'any) -> lst</code></a></dt>
<dt><code>(unify 'cnt) -> cnt</code></dt>
<dd>The first form unifies <code>any</code> with the current <a
href="ref.html#pilog">Pilog</a> environment at the current level and with a
value of <code>NIL</code>, and returns the new environment or <code>NIL</code>
if not successful. The second form unifies all variables at the given level with
the current one. See also <code><a href="refP.html#prove">prove</a></code> and
<code><a href="ref_.html#-%3E">-&gt;</a></code>.

<pre>
: (? (^ @A (unify '(@B @C))))
 @A=(((NIL . @C) 0 . @C) ((NIL . @B) 0 . @B) T)
</pre></dd>

<dt><a id="uniq"><code>(uniq 'lst) -> lst</code></a></dt>
<dd>Returns a unique list, by eliminating all duplicate elements from
<code>lst</code>. See also <a href="ref.html#cmp">Comparing</a>, <code><a
href="refS.html#sort">sort</a></code> and <code><a
href="refG.html#group">group</a></code>.

<pre>
: (uniq (2 4 6 1 2 3 4 5 6 1 3 5))
-> (2 4 6 1 3 5)
</pre></dd>

<dt><a id="uniq/2"><code>uniq/2</code></a></dt>
<dd><a href="ref.html#pilog">Pilog</a> predicate that succeeds if the second
argument is not yet stored in the first argument's index structure. <code><a
href="refI.html#idx">idx</a></code> is used internally storing for the values
and checking for uniqueness. See also <code><a
href="refM.html#member/2">member/2</a></code>.

<pre>
: (let U NIL
   (? (lst @X (a b c b c d)) (uniq U @X)) )
 @X=a
 @X=b
 @X=c
 @X=d
-> NIL
: (solve '((^ @B (box)) (lst @X (a b c b c d)) (uniq @B @X)) @X)
-> (a b c d)
</pre></dd>

<dt><a id="unless"><code>(unless 'any . prg) -> any</code></a></dt>
<dd>Conditional execution: When the condition <code>any</code> evaluates to
non-<code>NIL</code>, <code>NIL</code> is returned. Otherwise <code>prg</code>
is executed and the result returned. See also <code><a
href="refW.html#when">when</a></code>, <code><a
href="refI.html#ifn">ifn</a></code>, <code><a
href="refN.html#nor">nor</a></code>, <code><a
href="refN.html#nand">nand</a></code> and <code><a
href="refN.html#nond">nond</a></code>.

<pre>
: (unless (= 3 3) (println 'Strange 'result))
-> NIL
: (unless (= 3 4) (println 'Strange 'result))
Strange result
-> result
</pre></dd>

<dt><a id="until"><code>(until 'any . prg) -> any</code></a></dt>
<dd>Conditional loop: While the condition <code>any</code> evaluates to
<code>NIL</code>, <code>prg</code> is repeatedly executed. If <code>prg</code>
is never executed, <code>NIL</code> is returned. Otherwise the result of
<code>prg</code> is returned. See also <code><a
href="refW.html#while">while</a></code>, <code><a
href="refF.html#for">for</a></code>, <code><a
href="refL.html#loop">loop</a></code> and <code><a
href="refD.html#do">do</a></code>.

<pre>
: (until (=T (setq N (read)))
   (println 'square (* N N)) )
4
square 16
9
square 81
T
-> 81
</pre></dd>

<dt><a id="untrace"><code>(untrace 'sym) -> sym</code></a></dt>
<dt><code>(untrace 'sym 'cls) -> sym</code></dt>
<dt><code>(untrace '(sym . cls)) -> sym</code></dt>
<dd>(Debug mode only) Removes the <code><a href="ref_.html#$">$</a></code> trace
function call at the beginning of the function or method body of
<code>sym</code>, so that no more trace information will be printed before and
after execution. Built-in functions (SUBRs) are automatically converted to their
original form (see <code><a href="refS.html#subr">subr</a></code>). See also
<code><a href="refT.html#trace">trace</a></code> and <code><a
href="refT.html#traceAll">traceAll</a></code>.

<pre>
: (trace '+)                           # Trace the '+' function
-> +
: +
-> (@ ($ + @ (pass $385455126)))       # Modified for tracing
: (untrace '+)                         # Untrace '+'
-> +
: +
-> 67319120                            # Back to original form
</pre></dd>

<dt><a id="up"><code>(up [cnt] sym ['val]) -> any</code></a></dt>
<dd>Looks up (or modifies) the <code>cnt</code>'th previously saved value of
<code>sym</code> in the corresponding enclosing environment. If <code>cnt</code>
is not given, 1 is used. It is allowed to omit the <code>sym</code> argument,
then the corresponding expression (function or method call) is returned. See
also <code><a href="refE.html#eval">eval</a></code>, <code><a
href="refR.html#run">run</a></code>, <code><a
href="refT.html#trail">trail</a></code> and <code><a
href="refE.html#env">env</a></code>.

<pre>
: (let N 1 ((quote (N) (println N (up N))) 2))
2 1
-> 1
: (let N 1 ((quote (N) (println N (up N) (up N 7))) 2) N)
2 1 7
-> 7

: (de foo (N)
   (println (up))
   (inc N) )
-> foo
: (foo 7)
(foo 7)
-> 8
</pre></dd>

<dt><a id="upd"><code>(upd sym ..) -> lst</code></a></dt>
<dd>Synchronizes the internal state of all passed (external) symbols by passing
them to <code><a href="refW.html#wipe">wipe</a></code>. <code>upd</code> is the
standard function passed to <code><a href="refC.html#commit">commit</a></code>
during database <code><a href="ref.html#trans">transactions</a></code>.

<pre>
(commit 'upd)  # Commit changes, informing all sister processes
</pre></dd>

<dt><a id="upp?"><code>(upp? 'any) -> sym | NIL</code></a></dt>
<dd>Returns <code>any</code> when the argument is a string (symbol) that starts
with an uppercase character. See also <code><a
href="refU.html#uppc">uppc</a></code> and <code><a
href="refL.html#low?">low?</a></code>

<pre>
: (upp? "A")
-> "A"
: (upp? "a")
-> NIL
: (upp? 123)
-> NIL
: (upp? ".")
-> NIL
</pre></dd>

<dt><a id="uppc"><code>(uppc 'any) -> any</code></a></dt>
<dd>Upper case conversion: If <code>any</code> is not a symbol, it is returned
as it is. Otherwise, a new transient symbol with all characters of
<code>any</code>, converted to upper case, is returned. See also <code><a
href="refL.html#lowc">lowc</a></code>, <code><a
href="refF.html#fold">fold</a></code> and <code><a
href="refU.html#upp?">upp?</a></code>.

<pre>
: (uppc 123)
-> 123
: (uppc "abc")
-> "ABC"
: (uppc 'car)
-> "CAR"
</pre></dd>

<dt><a id="use"><code>(use sym . prg) -> any</code></a></dt>
<dt><code>(use (sym ..) . prg) -> any</code></dt>
<dd>Defines local variables. The value of the symbol <code>sym</code> - or the
values of the symbols <code>sym</code> in the list of the second form - are
saved, <code>prg</code> is executed, then the symbols are restored to their
original values. During execution of <code>prg</code>, the values of the symbols
can be temporarily modified. The return value is the result of <code>prg</code>.
See also <code><a href="refB.html#bind">bind</a></code>, <code><a
href="refJ.html#job">job</a></code> and <code><a
href="refL.html#let">let</a></code>.

<pre>
: (setq  X 123  Y 456)
-> 456
: (use (X Y) (setq  X 3  Y 4) (* X Y))
-> 12
: X
-> 123
: Y
-> 456
</pre></dd>

<dt><a id="useKey"><code>(useKey 'sym 'cls ['hook]) -> num</code></a></dt>
<dd>Generates or reuses a key for a database tree, by randomly trying to locate
a free number. See also <code><a href="refG.html#genKey">genKey</a></code>.

<pre>
: (maxKey (tree 'nr '+Item))
-> 8
: (useKey 'nr '+Item)
-> 12
</pre></dd>

<dt><a id="usec"><code>(usec ['flg]) -> num</code></a></dt>
<dd>Returns a number of microseconds. If <code>flg</code> is
non-<code>NIL</code>, the microsecond fraction of the last call to <code><a
href="refT.html#time">time</a></code> is returned, otherwise the number of
microseconds since interpreter startup. See also <code><a
href="refD.html#date">date</a></code>.

<pre>
: (usec)
-> 1154702479219050
: (list (date (date)) (time (time T)) (usec T))
-> ((2013 1 4) (10 12 39) 483321)
</pre></dd>

</dl>

</body>
</html>