Idio Functions

function not/function x

invert the boolean sense of x

Param x:

value to invert

Type x:

any

Result:

boolean inverse of x

Rtype:

boolean

This is the function equivalent of the not special form.

template when test body

if test is true run body

Param test:

test condition

Type test:

expression

Param body:

expressions

Type test:

expression

Return:

value from body or #<void>

template unless test body

if test is false run body

Param test:

test condition

Type test:

expression

Param body:

expressions

Type test:

expression

Return:

value from body or #<void>

template case key clauses

Each clause in clauses takes the form ((v ...) expr ...) except the last clause which can take the form (else expr ...).

key is evaluated and then compared with memv against the list in the head of each clause in clauses.

If the comparison is true then the result of case is the result of evaluating the expressions in the body of the clause. No other clauses are considered.

If no comparison is true and there is an else clause then it is run otherwise the result is #<void>.

template do var-clauses test-result body

Despite the visual differences, do performs much the same task as C’s for (init; test; step) body statement.

var-clauses is a list of var-clause which is a tuple, (var init step). Each var is initialised to init and adjusted by step each time round the loop.

test-result offers a little more flexibility than C in that test-result is the tuple (test expr) where test is evaluated each time round the loop, the same as C, but do allows you to run some arbitrary expr for the result to be returned from do.

body is the usual body form.

Example:

Increment i starting from 1. If i is 10 then return i + 13. The body, i, is a placeholder in this instance.

do ((i 1 (1 + i))) ((eq i 10) i + 13) i      ; 23

template C/for var-clauses test body

C/for is a variation on do but adds continue and break continuations to alter the flow of control.

var-clauses is a list of var-clause which is a tuple, (var init step). Each var is initialised to init and adjusted by step each time round the loop.

Note

Each var is local to the body loop.

test is evaluated each time round the loop, the same as C. If the test fails (break) is implicitly called.

body is the usual body form.

C/for returns either #<void>, from the implicit (break), or the value supplied to any explicit call to break.

Example:

Loop over i, starting from 1 and less than 10. If i is 3 then return 99 otherwise return i + 13.

C/for ((i 1 (1 + i))) (i lt 10) {
  if (i eq 3) {
    break 99
  }
  i + 13
}

See also

while the degenerative form of C/for with no var-clauses.

template break [value]

break returns value from the enclosing C/for or while loop or #<void> if no value is supplied.

Warning

break ignores any protection blocks set up by unwind-protect or dynamic-wind.

template continue [value]

continue stops processing the current C/for or while body and starts the next iteration of the loop. value is ignored and set to #<void> if not supplied.

Warning

continue ignores any protection blocks set up by unwind-protect or dynamic-wind.

template while test body

while is the degenerative form of C/for with no var-clauses.

function map f lists

apply f to the collected n^th elements of each list in lists. f should accept as many arguments as there are lists and each list in lists should be the same length.

Param f:

function to be applied

Type f:

function

Param lists:

lists, arrays or strings

Type lists:

list

Return:

list of the results from applying f

Rtype:

list

Example:

Multiply a list of numbers by 10:

map (function (n) n * 10) '(1 2 3)                   ; '(10 20 30)

Add two lists of numbers:

map (function (n1 n2) n1 + n2) '(1 2 3) '(4 5 6)     ; '(5 7 9)

Combine the elements of arrays (list, of course, takes any number of arguments):

map list #[1 2 3] #[4 5 6] #[7 8 9]       ; '((1 4 7) (2 5 8) (3 6 9))

See also

for-each which does the same but doesn’t return a list

function map* f lists

apply f to the collected n^th elements of each list in lists. f should accept as many arguments as there are lists and each list in lists should be the same length.

Param f:

function to be applied

Type f:

function

Param lists:

lists, arrays or strings

Type lists:

list

Return:

list of the results from applying f

Rtype:

list

map* is a variant of map that handles improper lists.

function for-each f lists

apply f to the collected n^th elements of each list in lists. f should accept as many arguments as there are lists and each list in lists should be the same length.

Param f:

function to be applied

Type f:

function

Param lists:

lists, arrays or strings

Type lists:

list

Return:

#<void>

See also

map which does the same but returns a list of the results of f

function for-each* f lists

apply f to the collected n^th elements of each list in lists. f should accept as many arguments as there are lists and each list in lists should be the same length.

Param f:

function to be applied

Type f:

function

Param lists:

lists, arrays or strings

Type lists:

list

Return:

#<void>

for-each* is a variant of for-each that handles improper lists.

template for vars in values body

for takes two forms:

for v in value body

for (v1 v2 ...) in values body

where body is a body form that uses the variable(s) v or v1, v2, etc.,

In the first, singular, form, value can be a list, array or string.

A string will be split into Unicode code points.

In the second, multiple, form, values must be a list of lists, arrays or strings and should be of the same type.

Strings will be split into Unicode code points.

Example:

Printing the elements of a string, one per line:

Idio> for x in "hello" {
  printf "%s\n" x
}
h
e
l
l
o
#<void>

Printing the paired elements of two lists, a pair per line:

Idio> for (x y) in '((1 2 3) (#\a #\b #\c)) {
  printf "%s - %s\n" x y
}
1 - a
2 - b
3 - c
#<void>

function fold-left f init lists

call func for each element in list l with arguments: element and val

val is updated to the value returned by func.

The final value of val is returned.

Param func:

func to be called with each val, element tuple

Type func:

2-ary function

Param val:

initial value for val

Type val:

value

Param l:

list

Type l:

list

Return:

final value of val

apply f to the collected n^th elements of each list in lists together with a cumulative result value which is initialised to init.

f should accept one more argument than there are lists and each list in lists should be the same length.

The first time f is called the first argument is init. The subsequent times f is called the first argument is the return value from the previous call to f.

Param f:

function to be applied

Type f:

function

Param init:

initial value of the cumulative result

Type init:

any

Param lists:

list of lists

Type lists:

list

Return:

cumulative result

Rtype:

any

See also

fold-right which does the same but processes lists right to left

Warning

There is a Scheme function, foldl which accepts the cumulative result as the last argument.

function fold-right f init lists

apply f to the collected n^th elements of each list in the reversed lists together with a cumulative result value which is initialised to init.

f should accept one more argument than there are lists and each list in lists should be the same length.

The first time f is called the first argument is init. The subsequent times f is called the first argument is the return value from the previous call to f.

Param f:

function to be applied

Type f:

function

Param init:

initial value of the cumulative result

Type init:

any

Param lists:

list of lists

Type lists:

list

Return:

cumulative result

Rtype:

any

See also

fold-left which does the same but processes lists left to right

Warning

There is a Scheme function, foldr which accepts the cumulative result as the last argument.

template unwind-protect body finally

evaluate body and then evaluate finally irrespective of how body completed

Param body:

expressions

Type body:

expressions

Param finally:

expressions

Type finally:

expressions

Return:

the result of evaluating body

Rtype:

any

See also

dynamic-wind

function dynamic-wind pre-thunk value-thunk post-thunk

evaluate pre-thunk and then evaluate value-thunk then evaluate post-thunk irrespective of how value-thunk completed

Param pre-thunk:

thunk

Type pre-thunk:

function

Param value-thunk:

thunk

Type value-thunk:

function

Param post-thunk:

thunk

Type post-thunk:

function

Return:

the result of evaluating value-thunk

Rtype:

any

This is derived from ports of Oleg Kiselyov’s delim-control-n.scm and dynamic-wind implementation.

This implementation might not be complete or robust.

function apply fn [args]

call fn with args

Param fn:

function to call

Type fn:

function

Param args:

arguments to fn

Type args:

parameters plus list

The last element of args is special. If it is a list then the elements of that list are appended to the arguments to fn

apply \+ 1 2 3            ; 6
apply \+ 1 2 3 #n         ; 6
apply \+ 1 2 3 '(4 5)     ; 15

function exit status

attempt to exit with status status

Param status:

exit status

Type status:

fixnum or C/int

Does not return [1].

This form will attempt to run through the full system shutdown.

See also

libc/exit for a more abrupt exit

[1]

YMMV

function identity e

return e

Param e:

expression to return

Type e:

any

Return:

e

function value-index o i

if i is a function then invoke (i o)

otherwise index the object o by i

Param o:

object to index

Type o:

any

Param i:

index

Type i:

any

Return:

the indexed value

Raises ^rt-parameter-value-error:

Indexable object types are those with a value-index vtable method associated with them. Standard indexable types with the implementation function call are:

list	(nth o i)	nth indexes start at 1
string	(string-ref o i)	string-ref
array	(array-ref o i)	array-ref indexes can be negative
hash	(hash-ref o i)	hash-ref
struct instance	(struct-instance-ref o i)	struct-instance-ref
tagged C/pointer	(accessor o i)

Note that, in particular for struct instance, the symbol used for a symbolic field name may have been evaluated to a value.

Quote if necessary: o.'i

value-index is not as efficient as calling the accessor function directly.

Example:

An example where i is a function is using fields to split a string (on IFS):

Idio> "here and there" . fields
#[ "here and there" "here" "and" "there" ]

An array example which can use a negative index:

Idio> a := #[ 'a 'b 'c ]
#[ 'a 'b 'c ]
Idio> a.2
'c
Idio> a.-1
'c

function add-value-index o f

Associate a indexer function f with o.

f will be invoked with the value to be indexed and the index.

This is currently only used for:

• struct instances where a struct type was associated with a indexer. When we come to index a struct instance we check to see if a indexer exists for its type.

function set-value-index! o i v

set value of the object o indexed by i to v

Param o:

object to index

Type o:

any

Param i:

index

Type i:

any

Param v:

value

Type v:

any

Return:

the indexed value

Raises ^rt-parameter-value-error:

Indexable object types are those with a defined setter or with a set-value-index! vtable method associated with them. Standard vtable methods and setters are:

string	(string-set! o i v)
array	(array-set! o i v)
hash	(hash-set! o i v)
struct instance	(struct-instance-set! o i v)
tagged C/pointer	(setter o i)

Note that, in particular for struct instance, the symbol used for a symbolic field name may have been evaluated to a value.

Quote if necessary: o.'i = v

Note

Not all tagged C/pointer types have an associated setter. struct-stat, for example, does not have an associated setter.

set-value-index! is not as efficient as calling the setting function directly.

function copy-value v [depth]

copy v to depth

Param v:

value to copy

Type v:

any

Param depth:

'shallow or 'deep (default)

Type depth:

symbol, optional

Return:

copy of v

function find-lib libname

search IDIOLIB for libname with a set of possible file name extensions

Param libname:

library name to search for

Type libname:

string

Return:

pathname to libname

Rtype:

pathname or #f

function type->string o

return the type of o as a string

Param o:

object

Return:

a string representation of the type of o

function typename o

return the type name of o

Param o:

object

Return:

the type of o

function members o

return the members of o as a list

Param o:

object

Return:

a list of the members of o

o should be an object with members such as a struct-instance or C/pointer.

function gc/collect

invoke the garbage collector

Return:

#<unspec>

function idio-debug fmt o

print the string value of o according to fmt to stderr

There must be a single %s conversion specification

idio-debug "foo is %-20s\n" foo

Param fmt:

printf(3) format string

Type fmt:

string

Param o:

value to dump

Type o:

any

Return:

#<unspec>

function idio-dump o

print the internal details of o to stderr

Param o:

value to dump

Type o:

any

Return:

#<unspec>

function ASCII-Decimal_Number? cp

Is cp an ASCII digit?

Param cp:

code point to test

Type cp:

unicode

Return:

boolean

This closure, defined in lib/bootstrap/common.idio should be overriden by the ‘more correct’ unicode/ASCII-Decimal_Number? primitive in src/usi-wrap.c but exists for handling printing if bootstrap fails.

template help sym

provide some helpful documentation for sym

Param sym:

name to describe

Type sym:

symbol

Return:

#<unspec>

Some provenance is given for functions; field and ancestry details for structs; imports and exports for modules.

Note

help is a template so you do not need to quote sym.

The documentation is currently the raw reStructuredText. Some re-imagining is required.

function idio-version [detail]

Report details of the Idio version.

Param details:

provide more details on IDIOLIB, defaults to #f

Type details:

boolean, optional

Keyword :raw:

do not substitute $HOME, defaults to #f

Type :raw:

boolean, optional

Last built at 2024-05-17T06:10:46Z+0000 from 62cca4c (dev) for Idio 0.3.b.6