File: refN.html

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

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

<h1>N</h1>

<dl>

<dt><a id="+Need"><code>+Need</code></a></dt>
<dd>Prefix class for mandatory <code><a
href="refR.html#+relation">+relation</a></code>s. Note that this does not
enforce any requirements by itself, it only returns an error message if the
<code>mis&gt;</code> message is explicitly called, e.g. by GUI functions. See
also <a href="ref.html#dbase">Database</a>.

<pre>
(rel nr (+Need +Key +Number))  # Item number is mandatory
</pre></dd>

<dt><a id="+Number"><code>+Number</code></a></dt>
<dd>Class for numeric relations, a subclass of <code><a
href="refR.html#+relation">+relation</a></code>. Accepts an optional argument
for the fixpoint scale (currently not used). See also <a
href="ref.html#dbase">Database</a>.

<pre>
(rel pr (+Number) 2)  # Price, with two decimal places
</pre></dd>

<dt><a id="n=="><code>(n== 'any ..) -> flg</code></a></dt>
<dd>Returns <code>T</code> when not all <code>any</code> arguments are the same
(pointer equality). <code>(n== 'any ..)</code> is equivalent to <code>(not (==
'any ..))</code>. See also <code><a href="ref_.html#==">==</a></code> and <a
href="ref.html#cmp">Comparing</a>.

<pre>
: (n== 'a 'a)
-> NIL
: (n== (1) (1))
-> T
</pre></dd>

<dt><a id="n0"><code>(n0 'any) -> flg</code></a></dt>
<dd>Returns <code>T</code> when <code>any</code> is not a number with value
zero. See also <code><a href="ref_.html#=0">=0</a></code>, <code><a
href="refL.html#lt0">lt0</a></code>, <code><a
href="refL.html#le0">le0</a></code>, <code><a
href="refG.html#ge0">ge0</a></code> and <code><a
href="refG.html#gt0">gt0</a></code>.

<pre>
: (n0 (- 6 3 2 1))
-> NIL
: (n0 'a)
-> T
</pre></dd>

<dt><a id="nT"><code>(nT 'any) -> flg</code></a></dt>
<dd>Returns <code>T</code> when <code>any</code> is not the symbol
<code>T</code>. See also <a href="ref_.html#=T">=T</a>.

<pre>
: (nT 0)
-> T
: (nT "T")
-> T
: (nT T)
-> NIL
</pre></dd>

<dt><a id="name"><code>(name 'sym) -> sym</code></a></dt>
<dd>Returns a new transient symbol with the name of <code>sym</code>. See also
<code><a href="refS.html#str">str</a></code>, <code><a
href="refS.html#sym">sym</a></code>, <code><a
href="refS.html#symbols">symbols</a></code>, <code><a
href="refZ.html#zap">zap</a></code> and <code><a
href="refI.html#intern">intern</a></code>.

<pre>
: (name 'abc)
-> "abc"
: (name "abc")
-> "abc"
: (name '{A17})
-> "A17"
: (name (new))
-> NIL
</pre></dd>

<dt><a id="namespaces"><code>(namespaces ['flg]) -> lst</code></a></dt>
<dd>(Debug mode only) Returns a list of all <a
href="ref.html#namespaces">namespaces</a> nested in the current search
order. When <code>flg</code> is non-<code>NIL</code>, their nested tree
is printed as a side effect. See also <code><a
href="refS.html#symbols">symbols</a></code> and <code><a
href="refS.html#shadows">shadows</a></code>.

<pre>
$ pil +
: (namespaces)
-> (pico vip llvm priv)
: (namespaces T)
   pico
      vip
      llvm
      priv
-> (pico vip llvm priv)

$ pty  # After starting "steps", "browser" and "chess" in PilBox
chess: (namespaces T)
   chess
   simul
   android
      steps
      browser
   pico
      svg
      vip
      gis
      llvm
      priv
-> (chess simul android steps browser pico svg vip gis llvm priv)
</pre></dd>

<dt><a id="nand"><code>(nand 'any ..) -> flg</code></a></dt>
<dd>Logical NAND. The expressions <code>any</code> are evaluated from left to
right. If <code>NIL</code> is encountered, <code>T</code> is returned
immediately. Else <code>NIL</code> is returned. <code>(nand ..)</code> is
equivalent to <code>(not (and ..))</code>. See also <code><a
href="refA.html#and">and</a></code>, <code><a
href="refN.html#nor">nor</a></code>, <code><a
href="refU.html#unless">unless</a></code>, <code><a
href="refI.html#ifn">ifn</a></code> and <code><a
href="refN.html#nond">nond</a></code>.

<pre>
: (nand (lt0 7) (read))
-> T
: (nand (lt0 -7) (read))
abc
-> NIL
: (nand (lt0 -7) (read))
NIL
-> T
</pre></dd>

<dt><a id="native"><code>(native 'cnt1|sym1 'cnt2|sym2 'any 'any ..) -> any</code></a></dt>
<dd>Calls a native function. The first argument should specify a shared object
library, either <code>"@"</code> (the current main program), <code>sym1</code>
(a library path name), or <code>cnt1</code> (a library handle obtained by a
previous call). The second argument should be a symbol name <code>sym2</code>,
or a function handle <code>cnt2</code> obtained by a previous call).
Practically, the first two arguments will be always passed as transient symbols,
which will get the library handle and function handle assigned as values to be
cached and used in subsequent calls. The third argument <code>any</code> is a
result specification, while all following arguments are the arguments to the
native function. The functionality is described in detail in <a
href="native.html">Native C Calls</a>.

<p><a id="natResult">The result specification</a> may either be one of the
atoms

<pre>
   NIL   void
   B     byte        # Byte (unsigned 8 bit)
   C     char        # Character (UTF-8, 1-4 bytes)
   W     short       # Word (signed 16 bit)
   I     int         # Integer (signed 32 bit)
   U     unsigned    # Unsigned integer (32 bit)
   N     long        # Number (signed 64 bit)
   P     void*       # Pointer (unsigned 64 bit)
   S     string      # String (UTF-8)
  -1.0   float       # Scaled fixpoint number
  +1.0   double      # Scaled fixpoint number
   T                 # Direct Lisp value
</pre>

<p>or nested lists of these atoms with size specifications to denote arrays and
structures, e.g.

<pre>
   (N . 4)        # long[4];           -> (1 2 3 4)
   (N (C . 4))    # {long; char[4];}   -> (1234 ("a" "b" "c" NIL))
   (N (B . 7))    # {long; byte[7];}   -> (1234 (1 2 3 4 5 6 7))
</pre>

<p>Arguments can be
<ul>
<li>integers (up to 64-bit) or pointers, passed as numbers
<li>strings, passed as symbols
<li>Lisp expressions, passed as cons pairs with <code>T</code> in the CAR
<li>fixpoint numbers, passed as cons pairs consisting of a the value and the
   scale (if the scale is positive, the number is passed as a
   <code>double</code>, otherwise as a <code>float</code>)
<li>structures, passed as lists with
   <ul>
   <li>a variable in the CAR (to receive the returned structure data, ignored
      when the CAR is <code>NIL</code>)
   <li>a cons pair for the size and result specification in the CADR (see
      above), and
   <li>an optional sequence of <a id="natItem">initialization items</a> in the
      CDDR, where each may be
      <ul>
      <li>a positive number, stored as an unsigned byte value
      <li>a negative number, whose absolute value is stored as an unsigned
         integer
      <li>a pair <code>(num . cnt)</code> where '<code>num</code>' is stored in
         a field of '<code>cnt</code>' bytes
      <li>a pair <code>(sym . cnt)</code> where '<code>sym</code>' is stored as
         a null-terminated string in a field of '<code>cnt</code>' bytes
      <li>a list <code>(1.0 num ...)</code> where the '<code>num</code>'
         elements (scaled fixpoint numbers) are stored as a sequence of double
         precision floating point numbers
      <li>a list <code>(-1.0 num ...)</code> where the '<code>num</code>'
         elements (scaled fixpoint numbers) are stored as a sequence of single
         precision floating point numbers
      </ul>
      If the last CDR of the initialization sequence is a number, it is used
      as a fill-byte value for the remaining space in the structure.
   </ul>
</ul>

<p><code>native</code> takes care of allocating memory for strings, arrays or
structures, and frees that memory when done.

<p>For NaN or negative infinity fixpoint values <code>NIL</code>, and for
positive infinity <code>T</code> is returned.

<p>See also <code><a href="ref_.html#%25@">%@</a></code>, <code><a
href="refS.html#struct">struct</a></code>, <code><a
href="refA.html#adr">adr</a></code>, <code><a
href="refL.html#lisp">lisp</a></code> and <code><a
href="refE.html#errno">errno</a></code>.

<pre>
: (native "@" "unlink" 'I "file")  # Same as (%@ "unlink" 'I "file")
-> 0
: (native "libcrypto.so" "SHA1" '(B . 20) "abcd" 4 0)
-> (129 254 139 254 135 87 108 62 203 34 66 111 142 87 132 115 130 145 122 207)
</pre></dd>

<dt><a id="need"><code>(need 'cnt ['lst ['any]]) -> lst</code></a></dt>
<dt><code>(need 'cnt ['num|sym]) -> lst</code></dt>
<dd>Produces a list of at least <code>cnt</code> elements. When called without
optional arguments, a list of <code>cnt</code> <code>NIL</code>'s is returned.
When <code>lst</code> is given, it is extended to the left (if <code>cnt</code>
is positive) or (destructively) to the right (if <code>cnt</code> is negative)
with <code>any</code> elements. In the second form, a list of <code>cnt</code>
atomic values is returned. See also <code><a
href="refR.html#range">range</a></code>.

<pre>
: (need 5)
-> (NIL NIL NIL NIL NIL)  # Allocate 5 cells
: (need 5 '(a b c))
-> (NIL NIL a b c)
: (need -5 '(a b c))
-> (a b c NIL NIL)
: (need 5 '(a b c) " ")  # String alignment
-> (" " " " a b c)
: (need 7 0)
-> (0 0 0 0 0 0 0)
: (need 5 (2 3) 1)
-> (1 1 1 2 3)
</pre></dd>

<dt><a id="new"><code>(new ['flg|num|sym] ['typ ['any ..]]) -> obj</code></a></dt>
<dd>Creates and returns a new object. If the first (optional) argument is
<code>T</code> or a number, the new object will be an external symbol (created
in database file 1 if <code>T</code>, or in the corresponding database file if
<code>num</code> is given). If it is a symbol, it is used directly.
<code>typ</code> (a list of classes) is assigned to the <code>VAL</code>, and
the initial <code>T</code> message is sent with the arguments <code>any</code>
to the new object. If no <code>T</code> message is defined for the classes in
<code>typ</code> or their superclasses, the <code>any</code> arguments should
evaluate to alternating keys and values for the initialization of the new
object. See also <code><a href="refB.html#box">box</a></code>, <code><a
href="refO.html#object">object</a></code>, <code><a
href="refC.html#class">class</a></code>, <code><a
href="refT.html#type">type</a></code>, <code><a
href="refI.html#isa">isa</a></code>, <code><a
href="refS.html#send">send</a></code> and <a href="ref.html#dbase">Database</a>.

<pre>
: (new)
-> $134426427
: (new T '(+Address))
-> {A3}
</pre></dd>

<dt><a id="new!"><code>(new! 'typ ['any ..]) -> obj</code></a></dt>
<dd><a href="ref.html#trans">Transaction</a> wrapper function for <code><a
href="refN.html#new">new</a></code>. <code>(new! '(+Cls) 'key 'val ...)</code>
is equivalent to <code>(dbSync) (new (db: +Cls) '(+Cls) 'key 'val ...) (commit
'upd)</code>. See also <code><a href="refR.html#request!">request!</a></code>, <code><a
href="refS.html#set!">set!</a></code>, <code><a
href="refP.html#put!">put!</a></code> and <code><a
href="refI.html#inc!">inc!</a></code>.

<pre>
: (new! '(+Item)  # Create a new item
   'nr 2                      # Item number
   'nm "Spare Part"           # Description
   'sup (db 'nr '+CuSu 2)     # Supplier
   'inv 100                   # Inventory
   'pr 12.50 )                # Price
</pre></dd>

<dt><a id="next"><code>(next) -> any</code></a></dt>
<dd>Can only be used inside functions with a variable number of arguments (with
<code>@</code>). Returns the next argument from the internal list. See also
<code><a href="refA.html#args">args</a></code>, <code><a
href="refA.html#arg">arg</a></code>, <code><a
href="refR.html#rest">rest</a></code>, and <code><a
href="refP.html#pass">pass</a></code>.

<pre>
: (de foo @ (println (next)))          # Print next argument
-> foo
: (foo)
NIL
-> NIL
: (foo 123)
123
-> 123
</pre></dd>

<dt><a id="nil"><code>(nil . prg) -> NIL</code></a></dt>
<dd>Executes <code>prg</code>, and returns <code>NIL</code>. See also <code><a
href="refT.html#t">t</a></code>, <code><a href="refP.html#prog">prog</a></code>,
<code><a href="refP.html#prog1">prog1</a></code> and <code><a
href="refP.html#prog2">prog2</a></code>.

<pre>
: (nil (println 'OK))
OK
-> NIL
</pre></dd>

<dt><a id="nil/1"><code>nil/1</code></a></dt>
<dd><a href="ref.html#pilog">Pilog</a> predicate expects an argument variable,
and succeeds if that variable is bound to <code>NIL</code>. See also <code><a
href="refN.html#not/1">not/1</a></code>.

<pre>
: (? @X NIL (nil @X))
 @X=NIL
-> NIL
</pre></dd>

<dt><a id="noLint"><code>(noLint 'sym)</code></a></dt>
<dt><code>(noLint 'sym|(sym . cls) 'sym2)</code></dt>
<dd>(Debug mode only) Excludes the check for a function definition of
<code>sym</code> (in the first form), or for variable binding and usage of
<code>sym2</code> in the function definition, file contents or method body of
<code>sym</code> (second form), during calls to <code><a
href="refL.html#lint">lint</a></code>. See also <code><a
href="refL.html#lintAll">lintAll</a></code>.

<pre>
: (de foo ()
   (bar FreeVariable) )
-> foo
: (lint 'foo)
-> ((def bar) (bnd FreeVariable))
: (noLint 'bar)
-> bar
: (noLint 'foo 'FreeVariable)
-> (foo . FreeVariable)
: (lint 'foo)
-> NIL
</pre></dd>

<dt><a id="nond"><code>(nond ('any1 . prg1) ('any2 . prg2) ..) -> any</code></a></dt>
<dd>Negated ("non-cond") multi-way conditional: If any of the <code>anyN</code>
conditions evaluates to <code>NIL</code>, <code>prgN</code> is executed and the
result returned. Otherwise (all conditions evaluate to non-<code>NIL</code>),
<code>NIL</code> is returned. See also <code><a
href="refC.html#cond">cond</a></code>, <code><a
href="refI.html#ifn">ifn</a></code>, <code><a
href="refU.html#unless">unless</a></code>, <code><a
href="refN.html#nor">nor</a></code> and <code><a
href="refN.html#nand">nand</a></code>.

<pre>
: (nond
   ((= 3 3) (println 1))
   ((= 3 4) (println 2))
   (NIL (println 3)) )
2
-> 2
</pre></dd>

<dt><a id="nor"><code>(nor 'any ..) -> flg</code></a></dt>
<dd>Logical NOR. The expressions <code>any</code> are evaluated from left to
right. If a non-<code>NIL</code> value is encountered, <code>NIL</code> is
returned immediately. Else <code>T</code> is returned. <code>(nor ..)</code> is
equivalent to <code>(not (or ..))</code>. See also <code><a
href="refO.html#or">or</a></code>, <code><a
href="refN.html#nand">nand</a></code>, <code><a
href="refU.html#unless">unless</a></code>, <code><a
href="refI.html#ifn">ifn</a></code> and <code><a
href="refN.html#nond">nond</a></code>.

<pre>
: (nor (lt0 7) (= 3 4))
-> T
</pre></dd>

<dt><a id="not"><code>(not 'any) -> flg</code></a></dt>
<dd>Logical negation. Returns <code>T</code> if <code>any</code> evaluates to
<code>NIL</code>.

<pre>
: (not (== 'a 'a))
-> NIL
: (not (get 'a 'a))
-> T
</pre></dd>

<dt><a id="not/1"><code>not/1</code></a></dt>
<dd><a href="ref.html#pilog">Pilog</a> predicate that succeeds if and only if
the goal cannot be proven. See also <code><a
href="refN.html#nil/1">nil/1</a></code>, <code><a
href="refT.html#true/0">true/0</a></code> and <code><a
href="refF.html#fail/0">fail/0</a></code>.

<pre>
: (? (equal 3 4))
-> NIL
: (? (not (equal 3 4)))
-> T
</pre></dd>

<dt><a id="nsp"><code>(nsp 'sym) -> sym</code></a></dt>
<dd>Returns the (first) <a href="ref.html#namespaces">namespace</a>
where <code>sym</code> is found in, according to the current <code><a
href="refS.html#symbols">symbols</a></code> search order. See also
<code><a href="refP.html#pico">pico</a></code>.

<pre>
(load "@lib/gis.l")

: (symbols '(gis pico))
-> (pico)
gis: (nsp 'gis)
-> pico
gis: (nsp 'Zoom)
-> gis
gis: (nsp 'osmStat)
-> gis
</pre></dd>

<dt><a id="nth"><code>(nth 'lst 'cnt ..) -> lst</code></a></dt>
<dd>Returns the tail of <code>lst</code> starting from the <code>cnt</code>'th
element of <code>lst</code>. Successive <code>cnt</code> arguments operate on
the CARs of the results in the same way. <code>(nth 'lst 2)</code> is equivalent
to <code>(cdr 'lst)</code>. See also <code><a
href="refG.html#get">get</a></code>.

<pre>
: (nth '(a b c d) 2)
-> (b c d)
: (nth '(a (b c) d) 2 2)
-> (c)
: (cdadr '(a (b c) d))
-> (c)
</pre></dd>

<dt><a id="num?"><code>(num? 'any) -> num | NIL</code></a></dt>
<dd>Returns <code>any</code> when the argument <code>any</code> is a number,
otherwise <code>NIL</code>. See also <code><a
href="refS.html#sym?">sym?</a></code>, <code><a
href="refA.html#atom">atom</a></code> and <code><a
href="refP.html#pair">pair</a></code>.

<pre>
: (num? 123)
-> 123
: (num? (1 2 3))
-> NIL
</pre></dd>

</dl>

</body>
</html>