File: refI.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 (541 lines) | stat: -rw-r--r-- 19,095 bytes
<!--
# VIP @lib/vip/html.l
# 05dec25 Software Lab. Alexander Burger
-->

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

<h1>I</h1>

<dl>

<dt><a id="+Idx"><code>+Idx</code></a></dt>
<dd>Prefix class for maintaining non-unique full-text indexes to <code><a
href="refS.html#+String">+String</a></code> relations, a subclass of <code><a
href="refR.html#+Ref">+Ref</a></code>. Accepts optional arguments for the
minimally indexed substring length (defaults to 3), and a <code><a
href="refH.html#+Hook">+Hook</a></code> attribute. Often used in combination
with the <code><a href="refS.html#+Sn">+Sn</a></code> soundex index, or the
<code><a href="refF.html#+Fold">+Fold</a></code> index prefix classes. See also
<a href="ref.html#dbase">Database</a>.

<pre>
(rel nm (+Sn +Idx +String))  # Name
</pre></dd>

<dt><a id="+IdxFold"><code>+IdxFold</code></a></dt>
<dd>Prefix class for maintaining non-unique indexes to subsequent substrings of
the <code><a href="refF.html#fold">fold</a></code>ed individual words of
<code><a href="refS.html#+String">+String</a></code> relations. Accepts optional
arguments for the minimally indexed substring length (defaults to 3), and a
<code><a href="refH.html#+Hook">+Hook</a></code> attribute. See also <code><a
href="refI.html#+Idx">+Idx</a></code> and <a href="ref.html#dbase">Database</a>.

<pre>
(rel nm (+IdxFold +String))            # Item Description
</pre></dd>

<dt><a id="+index"><code>+index</code></a></dt>
<dd>Abstract base class of all database B-Tree index relations (prefix classes
for <code><a href="refR.html#+relation">+relation</a></code>s). The class
hierarchy includes <code><a href="refK.html#+Key">+Key</a></code>, <code><a
href="refR.html#+Ref">+Ref</a></code>, <code><a
href="refI.html#+Idx">+Idx</a></code> and <code><a
href="refI.html#+IdxFold">+IdxFold</a></code>. See also <a
href="ref.html#dbase">Database</a>.

<pre>
(isa '+index Rel)  # Check for an index relation
</pre></dd>

<dt><a id="id"><code>(id 'num ['num]) -> sym</code></a></dt>
<dt><code>(id 'sym [NIL]) -> num</code></dt>
<dt><code>(id 'sym T) -> (num . num)</code></dt>
<dd>Converts one (the internal block number) or two (file and block) numbers to
an external symbol, or an external symbol to a number or a pair of numbers.

<pre>
: (id 7)
-> {7}
: (id 1 2)
-> {2}
: (id '{A2})
-> 2
: (id '{A2} T)
-> (2 . 2)
</pre></dd>

<dt><a id="idx"><code>(idx 'var 'any 'flg) -> lst</code></a></dt>
<dt><code>(idx 'var 'any) -> lst</code></dt>
<dt><code>(idx 'var) -> lst</code></dt>
<dd>Maintains an index tree in <code>var</code>, and checks for the existence of
<code>any</code>. If <code>any</code> is contained in <code>var</code>, the
corresponding subtree is returned, otherwise <code>NIL</code>. In the first
form, <code>any</code> is destructively inserted into the tree if
<code>flg</code> is non-<code>NIL</code> (and <code>any</code> was not already
there), or deleted from the tree if <code>flg</code> is <code>NIL</code>. If all
elements are inserted in sorted order, the tree degenerates into a linear list.
In such cases, <code>0</code> may be passed for <code>flg</code> to randomize
the insertion order. The second form only checks for existence, but does not
change the index tree. In the third form (when called with a single
<code>var</code> argument) the contents of the tree are returned as a sorted
list.

See also <code><a
href="refL.html#lup">lup</a></code>, <code><a
href="refE.html#enum">enum</a></code>, <code><a
href="refH.html#hash">hash</a></code>, <code><a
href="refR.html#rev">rev</a></code>, <code><a
href="refD.html#depth">depth</a></code>, <code><a
href="refS.html#sort">sort</a></code>, <code><a
href="refB.html#balance">balance</a></code> and <code><a
href="refM.html#member">member</a></code>.

<pre>
: (idx 'X 'd T)                              # Insert data
-> NIL
: (idx 'X 2 T)
-> NIL
: (idx 'X '(a b c) T)
-> NIL
: (idx 'X 17 T)
-> NIL
: (idx 'X 'A T)
-> NIL
: (idx 'X 'd T)
-> (d (2 NIL 17 NIL A) (a b c))              # 'd' already existed
: (idx 'X T T)
-> NIL
: X                                          # View the index tree
-> (d (2 NIL 17 NIL A) (a b c) NIL T)
: (idx 'X 'A)                                # Check for 'A'
-> (A)
: (idx 'X 'B)                                # Check for 'B'
-> NIL
: (idx 'X)
-> (2 17 A d (a b c) T)                      # Get list
: (idx 'X 17 NIL)                            # Delete '17'
-> (17 NIL A)
: X
-> (d (2 NIL A) (a b c) NIL T)               # View it again
: (idx 'X)
-> (2 A d (a b c) T)                         # '17' is deleted

: (off X Y)
-> NIL
: (for I 9 (idx 'X I T))                     # Sorted insert order
-> NIL
: (for I 9 (idx 'Y I 0))                     # Randomize
-> NIL
: (view X T)
                        9
                     8
                  7
               6
            5
         4
      3
   2
1
-> NIL
: (view Y T)
         9
      8
         7
   6
      5
         4
3
   2
      1
-> NIL
</pre></dd>

<dt><a id="if"><code>(if 'any1 any2 . prg) -> any</code></a></dt>
<dd>Conditional execution: If the condition <code>any1</code> evaluates to
non-<code>NIL</code>, <code>any2</code> is evaluated and returned. Otherwise,
<code>prg</code> is executed and the result returned. See also <code><a
href="refI.html#ifn">ifn</a></code>, <code><a
href="refC.html#cond">cond</a></code>, <code><a
href="refW.html#when">when</a></code> and <code><a
href="refI.html#if2">if2</a></code>.

<pre>
: (if (> 4 3) (println 'OK) (println 'Bad))
OK
-> OK
: (if (> 3 4) (println 'OK) (println 'Bad))
Bad
-> Bad
</pre></dd>

<dt><a id="if2"><code>(if2 'any1 'any2 any3 any4 any5 . prg) -> any</code></a></dt>
<dd>Four-way conditional execution for two conditions: If both conditions
<code>any1</code> and <code>any2</code> evaluate to non-<code>NIL</code>,
<code>any3</code> is evaluated and returned. Otherwise, <code>any4</code> or
<code>any5</code> is evaluated and returned if <code>any1</code> or
<code>any2</code> evaluate to non-<code>NIL</code>, respectively. If none of the
conditions evaluate to non-<code>NIL</code>, <code>prg</code> is executed and
the result returned. See also <code><a href="refI.html#if">if</a></code> and
<code><a href="refC.html#cond">cond</a></code>.

<pre>
: (if2 T T 'both 'first 'second 'none)
-> both
: (if2 T NIL 'both 'first 'second 'none)
-> first
: (if2 NIL T 'both 'first 'second 'none)
-> second
: (if2 NIL NIL 'both 'first 'second 'none)
-> none
</pre></dd>

<dt><a id="if@@"><code>(if@@ 'any1 any2 . prg) -> any</code></a></dt>
<dd>Conditional execution: If the value of the global variable <a
href="ref_.html#@@">@@</a></code> is non-<code>NIL</code> after the evaluation
of <code>any1</code>, <code>any2</code> is evaluated and returned. Otherwise,
<code>prg</code> is executed and the result returned. In both cases, <a
href="ref_.html#@">@</a></code> will hold the value of <code>any1</code>. See
also <code><a href="refI.html#if">if</a></code> and <code><a
href="refI.html#if2">if2</a></code>.

<pre>
: (de foo (N)
   (if (lt0 N)
      (throw 'lt0 N)
      (sqrt N) ) )
-> foo

: (if@@ (catch 'lt0 (foo 64))
   (msg @ " negative")
   @ )
-> 8

: (if@@ (catch 'lt0 (foo -64))
   (msg @ " negative")
   @ )
-64 negative
-> -64
</pre></dd>

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

<pre>
: (ifn (= 3 4) (println 'OK) (println 'Bad))
OK
-> OK
</pre></dd>

<dt><a id="import"><code>(import . lst) -> lst</code></a></dt>
<dd>Wrapper function for <code><a href="refI.html#intern">intern</a></code>.
Typically used to import symbols from other <a
href="ref.html#namespaces">namespaces</a>, as created by <code><a
href="refS.html#symbols">symbols</a></code>. <code>lst</code> should be
a list of symbols. See also <code><a
href="refP.html#pico">pico</a></code>, <code><a
href="refP.html#private">private</a></code> and <code><a
href="refL.html#local">local</a></code> and <code><a
href="refE.html#export">export</a></code>.

<pre>
: (import libA~foo libB~bar)
-> (foo bar)
</pre></dd>

<dt><a id="in"><code>(in 'any . prg) -> any</code></a></dt>
<dd>Opens <code>any</code> as input channel during the execution of
<code>prg</code>. The current input channel will be saved and restored
appropriately. If the argument is <code>NIL</code>, standard input is used. If
the argument is a symbol, it is used as a file name (opened in read-only mode).
If it is a positive number, it is used as the descriptor of an open file. If it
is a negative number, the saved input channel such many levels above the current
one is used. Otherwise (if it is a list), it is taken as a command with
arguments, and a pipe is opened for input. The (system dependent) exit status
code of the child process is stored in the global variable <code><a
href="ref_.html#@@">@@</a></code>. See also <code><a
href="refO.html#out">out</a></code>, <code><a
href="refE.html#err">err</a></code>, <code><a
href="refF.html#fd">fd</a></code>, <code><a
href="refI.html#ipid">ipid</a></code>, <code><a
href="refC.html#call">call</a></code>, <code><a
href="refL.html#load">load</a></code>, <code><a
href="refF.html#file">file</a></code>, <code><a
href="refP.html#poll">poll</a></code>, <code><a
href="refP.html#pipe">pipe</a></code> and <code><a
href="refC.html#ctl">ctl</a></code>.

<pre>
: (in "a" (list (read) (read) (read)))  # Read three items from file "a"
-> (123 (a b c) def)

: (in '(file "-b" "--mime" "bin/picolisp")  # Get the mime type
   (line T) )
-> "application/x-executable; charset=binary"
</pre></dd>

<dt><a id="inc"><code>(inc 'num) -> num</code></a></dt>
<dt><code>(inc 'var ['num]) -> num</code></dt>
<dd>The first form returns the value of <code>num</code> incremented by 1. The
second form increments the <code>VAL</code> of <code>var</code> by 1, or by
<code>num</code>. If the first argument is <code>NIL</code>, it is returned
immediately. <code>(inc Num)</code> is equivalent to <code>(+ Num 1)</code> and
<code>(inc 'Var)</code> is equivalent to <code>(set 'Var (+ Var 1))</code>. See
also <code><a href="refD.html#dec">dec</a></code> and <code><a
href="ref_.html#+">+</a></code>.

<pre>
: (inc 7)
-> 8
: (inc -1)
-> 0
: (zero N)
-> 0
: (inc 'N)
-> 1
: (inc 'N 7)
-> 8
: N
-> 8

: (setq L (1 2 3 4))
-> (1 2 3 4)
: (inc (cdr L))
-> 3
: L
-> (1 3 3 4)
</pre></dd>

<dt><a id="inc!"><code>(inc! 'obj 'sym ['num]) -> num</code></a></dt>
<dd><a href="ref.html#trans">Transaction</a> wrapper function for <code><a
href="refI.html#inc">inc</a></code>. <code>num</code> defaults to 1. Note that
for incrementing a property value of an entity typically the <code><a
href="refE.html#entityMesssages">inc!></a></code> message is used. See also
<code><a href="refN.html#new!">new!</a></code>, <code><a
href="refR.html#request!">request!</a></code>, <code><a
href="refS.html#set!">set!</a></code> and <code><a
href="refP.html#put!">put!</a></code>.

<pre>
(inc! Obj 'cnt 0)  # Incrementing a property of a non-entity object
</pre></dd>

<dt><a id="index"><code>(index 'any 'lst) -> cnt | NIL</code></a></dt>
<dd>Returns the <code>cnt</code> position of <code>any</code> in
<code>lst</code>, or <code>NIL</code> if it is not found. See also <code><a
href="refO.html#offset">offset</a></code> and <code><a
href="refS.html#sub?">sub?</a></code>.

<pre>
: (index 'c '(a b c d e f))
-> 3
: (index '(5 6) '((1 2) (3 4) (5 6) (7 8)))
-> 3
</pre></dd>

<dt><a id="info"><code>(info 'any ['flg]) -> (cnt|flg dat . tim)</code></a></dt>
<dd>Returns information about a file with the name <code>any</code>: The current
size <code>cnt</code> in bytes, and the modification date and time (UTC, or
local time if <code>flg</code> is zero). For directories, <code>T</code> is
returned instead of the size, and <code>NIL</code> for other non-regular files.
The file argument itself is stored in the global variable <code><a
href="ref_.html#@@">@@</a></code>). If <code>flg</code> is non-<code>NIL</code>
and <code>any</code> is the name of a symbolic link, then the link itself is
used, not the file that it refers to. See also <code><a
href="refD.html#dir">dir</a></code>, <code><a
href="refD.html#date">date</a></code> and <code><a
href="refT.html#time">time</a></code>.

<pre>
$ ls -l x.l
-rw-r--r--   1 abu      users         208 Jun 17 08:58 x.l
$ pil +
: (info "x.l")
-> (208 730594 . 32315)
: (stamp 730594 32315)
-> "2000-06-17 08:58:35"
</pre></dd>

<dt><a id="init"><code>(init 'tree ['any1] ['any2]) -> lst</code></a></dt>
<dd>Initializes a structure for stepping iteratively through a database tree.
<code>any1</code> and <code>any2</code> may specify a range of keys. If
<code>any1</code> is greater than <code>any2</code>, the traversal will be in
opposite direction. See also <code><a href="refT.html#tree">tree</a></code>,
<code><a href="refS.html#step">step</a></code>, <code><a
href="refI.html#iter">iter</a></code> and <code><a
href="refS.html#scan">scan</a></code>.

<pre>
: (init (tree 'nr '+Item) 3 5)
-> (((3 . 5) ((3 NIL . {B3}) (4 NIL . {B4}) (5 NIL . {B5}) (6 NIL . {B6}))))
</pre></dd>

<dt><a id="input"><code>(input exe . prg) -> any</code></a></dt>
<dd>Establishes an input stream, by redirecting the current input channel during
the execution of <code>prg</code>. The current input channel will be saved and
restored appropriately. <code>exe</code> is executed (in the context of the
original input channel) whenever a character is required by read calls in
<code>prg</code>, and should return a single character upon each execution. See
also <code><a href="refO.html#output">output</a></code>, <code><a
href="refI.html#in">in</a></code> and <code><a
href="refP.html#pipe">pipe</a></code>.

<pre>
: (input "A" (char))
-> "A"
: (let L (chop "(+ 2 (* 3 4))")
   (input (++ L) (read)) )
-> (+ 2 (* 3 4))
: (let L (chop "AQIDBAUGBw==")
   (input (++ L)
      (while (ext:Base64)
         (printsp @) ) ) )
1 2 3 4 5 6 7 -> 7
</pre></dd>

<dt><a id="insert"><code>(insert 'cnt 'lst 'any) -> lst</code></a></dt>
<dd>Inserts <code>any</code> into <code>lst</code> at position <code>cnt</code>.
This is a non-destructive operation. See also <code><a
href="refR.html#remove">remove</a></code>, <code><a
href="refP.html#place">place</a></code>, <code><a
href="refA.html#append">append</a></code>, <code><a
href="refD.html#delete">delete</a></code> and <code><a
href="refR.html#replace">replace</a></code>.

<pre>
: (insert 3 '(a b c d e) 777)
-> (a b 777 c d e)
: (insert 1 '(a b c d e) 777)
-> (777 a b c d e)
: (insert 9 '(a b c d e) 777)
-> (a b c d e 777)
</pre></dd>

<dt><a id="intern"><code>(intern 'any ['nsp]) -> sym</code></a></dt>
<dd>Creates or finds an internal symbol. If a symbol with the name
<code>any</code> is already intern, it is returned. Otherwise, <code>any</code>
is interned in the current <a href="ref.html#namespaces">namespace</a>
and returned. If <code>nsp</code> is non-<code>NIL</code>,
<code>any</code> is <i>always</i> interned in the current namespace (if
<code>nsp</code> is <code>T</code>) or in the given namespace, even if
it is found in other namespaces. See also <code><a
href="refS.html#symbols">symbols</a></code>, <code><a
href="refZ.html#zap">zap</a></code>, <code><a
href="refI.html#import">import</a></code> and <code><a
href="refE.html#extern">extern</a></code>.

<pre>
: (intern "abc")
-> abc
: (intern 'car)
-> car
: ((intern "car") (1 2 3))
-> 1
: ((intern '("c" "a" "r")) (1 2 3))
-> 1
</pre></dd>

<dt><a id="ipid"><code>(ipid) -> pid | NIL</code></a></dt>
<dd>Returns the corresponding process ID when the current input channel is
reading from a pipe, otherwise <code>NIL</code>. See also <code><a
href="refO.html#opid">opid</a></code>, <code><a
href="refI.html#in">in</a></code>, <code><a
href="refP.html#pipe">pipe</a></code> and <code><a
href="refL.html#load">load</a></code>.

<pre>
: (in '(ls "-l") (println (line T)) (kill (ipid)))
"total 7364"
-> T
</pre></dd>

<dt><a id="isa"><code>(isa 'cls|typ 'obj) -> obj | NIL</code></a></dt>
<dd>Returns <code>obj</code> when it is an object that inherits from
<code>cls</code> or <code>type</code>. See also <a href="ref.html#oop">OO
Concepts</a>, <code><a href="refC.html#class">class</a></code>, <code><a
href="refT.html#type">type</a></code>, <code><a
href="refN.html#new">new</a></code> and <code><a
href="refO.html#object">object</a></code>.

<pre>
: (isa '+Address Obj)
-> {A17}
: (isa '(+Male +Person) Obj)
-> NIL
</pre></dd>

<dt><a id="isa/2"><code>isa/2</code></a></dt>
<dd>(Deprecated since version 25.5.30) <a
href="ref.html#pilog">Pilog</a> predicate that succeeds if the second
argument is of the type or class given by the first argument, according
to the <code><a href="refI.html#isa">isa</a></code> function. Typically
used in <code><a href="refD.html#db/3">db/3</a></code> or <code><a
href="refS.html#select/3">select/3</a></code> database queries. See also
<code><a href="refS.html#same/3">same/3</a></code>, <code><a
href="refB.html#bool/3">bool/3</a></code>, <code><a
href="refR.html#range/3">range/3</a></code>, <code><a
href="refH.html#head/3">head/3</a></code>, <code><a
href="refF.html#fold/3">fold/3</a></code>, <code><a
href="refP.html#part/3">part/3</a></code> and <code><a
href="refT.html#tolr/3">tolr/3</a></code>.

<pre>
: (? (db nm +Person @Prs) (isa +Woman @Prs) (val @Nm @Prs nm))
 @Prs={A44} @Nm="Alexandra of Denmark"
 @Prs={A124} @Nm="Alice Maud Mary"
 @Prs={A21} @Nm="Anne"
 @Prs={A57} @Nm="Augusta Victoria".  # Stop
</pre></dd>

<dt><a id="iter"><code>(iter 'tree ['fun] ['any1] ['any2] ['flg]) -> NIL</code></a></dt>
<dd>Iterates through a database tree by applying <code>fun</code> to all values.
<code>fun</code> defaults to <code><a
href="refP.html#println">println</a></code>. <code>any1</code> and
<code>any2</code> may specify a range of keys. If <code>any1</code> is greater
than <code>any2</code>, the traversal will be in opposite direction. Note that
the keys need not to be atomic, depending on the application's index structure.
If <code>flg</code> is non-<code>NIL</code>, partial keys are skipped. See also
<code><a href="refT.html#tree">tree</a></code>, <code><a
href="refU.html#ubIter">ubIter</a></code>, <code><a
href="refS.html#scan">scan</a></code>, <code><a
href="refI.html#init">init</a></code> and <code><a
href="refS.html#step">step</a></code>.

<pre>
: (iter (tree 'nr '+Item))
{B1}
{B2}
{B3}
{B4}
{B5}
{B6}
-> NIL
: (iter (tree 'nr '+Item) '((This) (println (: nm))))
"Main Part"
"Spare Part"
"Auxiliary Construction"
"Enhancement Additive"
"Metal Fittings"
"Gadget Appliance"
"Testartikel"
-> NIL
</pre></dd>

</dl>

</body>
</html>