- in - ITEM is a numeric string, symbol or keyword, or a number
- in - TRIM: default is #f.
- If TRIM is #t, default trim is invoked (trims #\newline, #\tab, #\space).
- If other characters need to be trimmed, use strim or trim-string, e.g., (strim "string" "characters") .
- sym/str->num is an alias for obj->num.
- returns: a number or #f if ITEM does not convert to a number.
(obj->num "873") => 873
(obj->num '|873|) => 873
(obj->num #x873) => 2163
(obj->num "2163 ") => #f
(obj->num " 2163 " #t) => 2163
(obj->num (strim "\t\t 2163--- \n" "-")) => 2163
(obj->num (trim-string '|\x9<enscript>
<syntax>strls->symls LIST</syntax>
* in - LIST of strings, symbols, keywords
* returns: list of symbols or '() if LIST is #f.
<syntax>symls->strls LIST</syntax>
* in - LIST of symbols, numbers, keywords
* returns: list of strings, or '() if LIST is #f.
<syntax>strls->numls LIST</syntax>
* in - LIST containing numeric symbols or strings, or numbers
* returns: list of numbers, or '() if LIST is #f..
** {{objs->numls}} is an alias for {{strls->numls}}
Note: list conversions will insert #f when an element of the input list can't be converted to the output list type.
==== alist replace/append/delete
The alist is commonly used as a database in Scheme programs for small data sets, such as configuration options or temporary data. Frequently modifying the data is called for, with 3 or 4 operations being used:
* Adding a pair to the alist.
* Deleting a pair from the alist.
* Replacing the data (cdr) of a pair.
* Appending data to the existing data of a pair/list.
The semantics of these operations can be surprising. Using {{set-cdr!}} on a pair extracted from an alist by {{assoc ...}} is visible in the alist. Preserving the original alist requires making modifications to a "deep copy" of the original, leaving the original unaltered.
{{alist/r_}}, {{alist/a_}} and {{alist/d_}} provide adding, replacing, appending and removing alist data. The "+" variants return a new alist, the "!" change the input alist.
<procedure>alist-dup ALIST</procedure>
* in - ALIST - the alist to duplicate
* returns: new alist identical to ALIST.
<syntax>alist/r+ K V ALIST</syntax>
* in - K - the ''key'', car, of a pair in the alist.
* in - V - the ''value'', cdr, of the pair.
* in - ALIST
** {{alist/r+}} replaces the value (cdr) of a pair with a new value, V. If the key, K, doesn't exist in any pair in the ALIST, a new K-V pair is added to the alist. In either case, a fresh ALIST is returned.
* returns: altered ALIST, original ALIST is unchanged.
<syntax>alist/r! K V ALIST</syntax>
* Destructive variant of {{alist/r+}}, sets ALIST to new ALIST.
* returns: modified input alist.
<syntax>alist/a+ K V ALIST</syntax>
* in - K, V as above.
* in - ALIST
** ALIST is modified, V is ''appended to'' the pair's current value. If the key is not found in the ALIST, a new K-V pair is added to the ALIST.
* returns: the amended ALIST without changing the original.
<syntax>alist/a! K V ALIST</syntax>
* Destructive variant of {{alist/a+}}, setting ALIST to modified result.
* returns: altered original alist.
<procedure>alist/d+ K ALIST</procedure>
* in - K - key of pair to remove from ALIST.
** if K isn't found in ALIST, unchanged duplicate ALIST is returned.
* returns: altered alist, original is unmodified.
<syntax>alist/d! K ALIST</syntax>
* in - K - key of pair to remove from ALIST.
** if K isn't found in ALIST, the unchanged ALIST is returned.
* returns: modified alist.
==== alist query
<procedure>k->v KEY ALIST</procedure>
* in - KEY - Performs case-sensitive search of ALIST for KEY, or car of pair.
* in - ALIST - ALIST to search.
* returns: value associated with KEY, or #f if key not found.
<procedure>k->vci KEY ALIST</procedure>
* in - KEY - Performs case-insensitive search of ALIST for KEY, or car of pair.
* in - ALIST - ALIST to search.
* returns: value associated with KEY, or #f if not found.
==== list-recv, pair-recv
{{list-recv}} is analogous to {{receive}}, except {{list-recv}} destructures a list instead of values. Most useful with procedures returning lists with small number of elements.
<syntax>list-recv (VAR1 ...) LIST BODY</syntax>
* in - VAR1 ... - number of variables must match length of LIST
* in - LIST - each element is assigned to variable in VARs.
* in - BODY - VAR1 ... are variables visible throughout BODY.
* returns: result of body expressions.
<enscript highlight='scheme'>
(import nutils)
(define (myproc x y)
(let ((a (* 101 x))
(b (* 202 y)))
(list a b)))
(list-recv (var-a var-b) (myproc 20 40)
(printnl 'var-a 'is var-a)
(printnl "var-b is" var-b))