Subsections
Vectors (one dimensional arrays) and lists are generic sequences.
A string is a sequence, since it is a vector of characters.
For the specification of result type in
map, concatenate and coerce,
use class name symbol, such as cons, string, integervector, floatvector,
etc. without quotes,
since the class object is bound to the symbol.
elt sequence pos [function]


elt is the most general function to get and put (in conjunction with
setf) value at the specific position pos in sequence.
Sequence may be a list, or a vector of arbitrary
object, bit, char, integer, or float.
Elt cannot be applied to a multidimensional array.
length sequence [function]


returns the length of sequence.
For vectors, length finishes in constant time, but
time proportional to the length is required for a list.
Length never terminates if sequence is a circular list.
Use listlength, instead.
If sequence is an array with a fillpointer, length
returns the fillpointer, not the entire size of the array entity.
Use arraytotalsize to know the entire size of those arrays.
subseq sequence start [end] [function]


makes a copy of the subsequence from startth through (end1)th inclusively
out of sequence.
end is defaulted to the length of sequence.
copyseq sequence [function]


does shallowcopying of sequence, that is,
only the toplevel references in sequence are copied.
Use copytree to copy a nested list,
or copyobject for deepcopying of a sequence
containing recursive references.
reverse sequence [function]


reverse the order of sequence and returns a new sequence of the
same type as sequence.
nreverse sequence [function]


Nreverse is the destructive version of reverse.
Nreverse does not allocate memory, while reverse does.
concatenate resulttype sequence* [function]


concatenates all sequences.
Each sequence may be of any sequence type.
Unlike append, all the sequences including the last one are copied.
Resulttype should be a class such as cons, string,
vector, floatvector etc.
coerce sequence resulttype [function]


changes the type of sequence.
For examples, (coerce '(a b c) vector) = #(a b c) and
(coerce "ABC" cons) = (a b c).
A new sequence of type resulttype is created, and each element of
sequence is copied to it.
resulttype should be one of vector, integervector, floatvector,
bitvector, string, cons or other userdefined classes inheriting
one of these.
Note that sequence is copied even if its type equals to resulttype.
map resulttype function seq &rest moreseqs [function]


function is applied to a list of arguments taken from seq
and moreseqs orderly, and the result is accumulated in a sequence
of type resulttype.
fill sequence item &key (:start 0) (:end (length sequence)) [function]


fills item from startth through (end1)th in sequence.
replace dest source &key :start1 :end1 :start2 :end2 [function]


elements in dest sequence indexed between start1 and end1
are replaced with elements in source indexed between
start2 and end2.
start1 and start2 are defaulted to zero, and
end1 and end2 to the length of each sequence.
If the one of subsequences is longer than the other,
its end is truncated to match with the shorter subsequence.
sort sequence compare &optional key [function]


sequence is destructively sorted using Unix's quicksort subroutine.
key is not a keyword parameter.
Be careful with the sorting of a sequence which have same elements.
For example, (sort '(1 1) #'>) fails because comparisons
between 1 and 1 in both direction fail.
To avoid this problem, use functions like #' or #' for comparison.
merge resulttype seq1 seq2 pred &key (key #'identity) [function]


two sequences seq1 and seq2 are merged to form a single
sequence of resulttype whose elements
satisfy the comparison specified by pred.
mergelist list1 list2 pred key [function]


merges two lists. Unlike merge no general sequences are allowed
for the arguments, but mergelist runs faster than merge.
Following functions consist of one basic function and its variants
suffixed by if and ifnot.
The basic form takes at least the item and sequence arguments,
and compares item with each element in the sequence,
and do some processing,
such as finding the index,
counting the number of appearances, removing the item, etc.
Variant forms take predicate and sequence arguments,
applies the predicate to each element of sequence, and do something
if the predicate returns nonnil (if version), or nil (ifnot version).
position item seq &key :start :end :test :testnot :key (:count 1) [function]


finds countth appearance of item in seq and returns
its index.
The search begins from the startth element, ignoring elements before it.
By default, the search is performed by eql, which can be altered
by the test or testnot parameter.
positionif predicate seq &key :start :end :key [function]


positionifnot predicate seq &key :start :end :key [function]


find item seq &key :start :end :test :testnot :key (:count 1) [function]


finds countth element between the startth element
and the endth element in seq.
The element found, which is eql to item if no test or
testnot other than #'eql is specified, is returned.
findif predicate seq &key :start :end :key (:count 1) [function]


finds countth element in seq for which pred
returns non nil.
findifnot predicate seq &key :start :end :key [function]


count item seq &key :start :end :test :testnot :key [function]


counts the number of items which appear between the startth element
and the endth element in seq.
countif predicate seq &key :start :end :key [function]


count the number of elements in seq for which pred returns
non nil.
countifnot predicate seq &key :start :end :key [function]


remove item seq &key :start :end :test :testnot :key :count [function]


creates a new sequence which has eliminated count (defaulted to infinity)
occurrences of of item(s) between the startth element
and the endth element in seq.
If you are sure that there is only one occurrence of item,
count=1 should be specified to avoid meaningless scan over the whole
sequence.
removeif predicate seq &key :start :end :key :count [function]


removeifnot predicate seq &key :start :end :key :count [function]


removeduplicates seq &key :start :end :key :test :testnot :count [function]


removes duplicated items in seq and creates a new sequence.
delete item seq &key :start :end :test :testnot :key :count [function]


is same with remove except that delete modifies seq
destructively and does not create a new sequence.
If you are sure that there is only one occurrence of item,
count=1 should be specified to avoid meaningless scan over the whole
sequence.
deleteif predicate seq &key :start :end :key :count [function]


deleteifnot predicate seq &key :start :end :key :count [function]


count for removes and deletes is defaulted to 1,000,000.
If you have a long sequence and you want to delete an element which
appears only once, :count should be specified as 1.
substitute newitem olditem seq
&key :start :end :test :testnot :key :count [function]


returns a new sequence which has
substituted the count occurrence(s)
of olditem in seq with newitem.
By default, all the olditems are substituted.
(substitute #\Space #\_ "Euslisp_euslisp") ;; => "Euslisp euslisp"
substituteif newitem predicate seq &key :start :end :key :count [function]


substituteifnot newitem predicate seq &key :start :end :key :count [function]


nsubstitute newitem olditem seq &key :start :end :test :testnot :key :count [function]

 substitute the count occurrences of olditem in seq with newitem
destructively. By default, all the olditems are substituted.
nsubstituteif newitem predicate seq &key :start :end :key :count [function]


nsubstituteifnot newitem predicate seq &key :start :end :key :count [function]


listp object [function]


returns T if object is an instance of cons or NIL.
consp object [function]


equivalent to (not (atom object)). (consp '()) is nil.
car list [function]


returns the first element in list. car of NIL is NIL.
car of atom is error.
cdr list [function]

 returns the list which removed the first element
of list. cdr of NIL is NIL.
cdr of atom is error.
cadr list [function]


cddr list [function]


cdar list [function]


caar list [function]


caddr list [function]


caadr list [function]


caaar list [function]


cdadr list [function]


cdadr list [function]


cdaar list [function]


cdddr list [function]


cdddr list [function]


cddar list [function]


first list [function]

 retrieves the first element in list.
second, third, fourth, fifth, sixth, seventh, eighth are also
available.
nth count list [function]


returns the countth element in list.
Note that (nth 1 list) is equivalent to (second list),
and to (elt list 1).
nthcdr count list [function]


applies cdr count times to list.
last list [function]


the last cons is returned, not the last element.
butlast list &optional (n 1) [function]

 returns a list which does not contain the last n elements.
cons car cdr [function]


makes a new cons whose car is car and cdr is cdr.
list {element}* [function]

 makes a list of elements.
list* {element}* [function]


makes a list of elements, but the last element is consed in cdr:
for example, (list* 1 2 3 '(4 5)) = (1 2 3 4 5).
listlength list [function]


returns the length of the list. List can be circular.
makelist size &key (initialelement nil) [function]


makes a list whose length is size and elements are initialelement.
rplaca cons a [function]


replace the car of cons with a.
Use of setf to car is recommended.
rplacd cons d [function]


replace the cdr of cons with d.
Use of setf to cdr is recommended.
memq item list [function]


resembles member, but test is always done by eq.
member item list &key :key (:test #'eq) :testnot [function]

 The list is searched for an element that satisfies the test.
If none is found, NIL is returned; otherwise, the tail of list beginning
with the first element that satisfied the test is returned. The list
is searched on the top level only.
assq item alist [function]


assoc item alist &key :key (:test #'eq) :testnot [function]

 searches the association list alist. The value returned is the
first pair in the alist such that the car of the pair satisfies
the test, or NIL if there is no such pair in the alist.
rassoc item alist [function]


returns the first pair in alist whose cdr is equal to item.
pairlis l1 l2 &optional alist [function]


makes a list of pairs consing corresponding elements in l1 and l2.
If alist is given, it is concatenated at the tail of the pair list
made from l1 and l2.
acons key val alist [function]


add the key val pair to alist, that is,
(cons (cons key val) alist).
append {list}* [function]


appends list to form a new list.
All the elements in list, except the last list, are copied.
nconc {list}* [function]


concatenates list destructively by replacing the last cdr of each
list.
subst new old tree [function]


substitutes every old in tree with new.
flatten complexlist [function]


Complexlist composed of atoms and lists of any depth
is transformed into a single level linear list which have all the elements
in complexlist at the top level.
For example, (flatten '(a (b (c d) e))) = (a b c d e)
push item place [macro]


pushes item into a stack (list) bound to place.
pop stack [macro]


removes the first item from stack and returns it.
If stack is empty (nil), nil is returned.
pushnew item place &key test testnot key [macro]


pushes item in the place list
if item is not a member of place.
The test, testnot and key arguments are
passed to the member function.
adjoin item list [function]


The item is added at the head of the list if it is not included
in the list.
union list1 list2 &key (test #'eq) (testnot) (key #'identity) [function]


returns union set of two lists.
subsetp list1 list2 &key (test #'eq) (testnot) (key #'identity) [function]

 tests if list1 is a subset of list2, i.e. if each element
of list1 is a member of list2.
intersection list1 list2
&key (test #'eq) (testnot) (key #'identity) [function]


returns the intersection of two sets, list1 and list2.
setdifference list1 list2
&key (test #'eq) (testnot) (key #'identity) [function]


returns the list whose elements are only contained in list1
and not in list2.
setexclusiveor list1 list2
&key (test #'eq) (testnot) (key #'identity) [function]


returns the list of elements that appear only either in list1 or list2.
listinsert item pos list [function]


Insert item as the pos'th element in list destructively.
If pos is bigger than the length of list, item is
nconc'ed at the tail.
For example, (listinsert 'x 2 '(a b c d)) = (a b x c d)
copytree tree [function]


returns the copy of tree which may be a nested list
but cannot have circular reference. Circular lists can be copied by
copyobject.
Actually, copytree is simply coded as (subst t t tree).
mapc func arglist &rest morearglists [function]


applies func to a list of Nth elements in arglist and each of
morearglists.
The results of application are ignored and arglist is returned.
mapcar func &rest arglist [function]


maps func to each element of arglist,
and makes a list from all the results.
Before using mapcar, try dolist.
mapcan func arglist &rest morearglists [function]

 maps func to each element of arglist,
and makes a list from all the results by nconc.
Mapcan is suitable for filtering (selecting) elements
in arglist, since nconc does nothing with NIL.
Up to seven dimensional arrays are allowed.
A onedimensional array is called vector.
Vectors and lists are grouped as sequence.
If the elements of an array is of any type, the array is said to be general.
If an array does not have fillpointer, is not displaced to
another array, or is adjustable, the array is said to be simple.
Every array element can be recalled by aref and set by setf in
conjunction with aref.
But for simple vectors, there are simpler and faster access functions:
svref for simple general vectors, char and schar for
simple character vectors (string), bit and sbit for
simple bit vectors. When these functions are compiled,
the access is expanded inline and no type check and boundary check are
performed.
Since a vector is also an object,
it can be made by instantiating some vectorclass.
There are five kinds of builtin vectorclasses;
vector, string, floatvector, integervector and bitvector.
In order to ease instantiation of vectors, the function makearray
is provided.
Elementtype should be one of :integer, :bit, :character, :float, :foreign
or userdefined vector class.
:initialelement and :initialcontents key word arguments are
available to set initial values of the array you make.
arrayranklimit [constant]

 7
arraydimensionlimit [constant]

 #x1fffffff, logically, but stricter
limit is imposed by the physical or virtual memory size of the system.
vectorp object [function]


An array is not a vector even if it is one dimensional.
T is returned for vectors, integervectors, floatvectors, strings,
bitvectors or other userdefined vectors.
vector &rest elements [function]


makes a simple vector from elements.
makearray dims &key (elementtype vector) [function]
(initialcontents nil)
(initialelement nil)
(fillpointer nil)
(displacedto nil)
(displacedindexoffset 0)
(adjustable nil)

 makes a vector or array.
dims is either an integer or a list.
If dims is an integer, a simplevector is created.
svref vector pos [function]


returns posth element of vector.
Vector must be a simple general vector.
aref vector &rest (indices) [function]


returns the element indexed by indices.
Aref is not very efficient
because it needs to dispatch according to the type of vector.
Type declarations should be given to improve the speed of compiled code
whenever possible.
vectorpush val array [function]


store val at the fillpointerth slot in array.
array must have a fillpointer.
After val is stored,
the fillpointer is advanced by one to point to the next location.
If it exceeds the array boundary, an error is reported.
vectorpushextend val array [function]


Similar to vectorpush except that
the size of the array is automatically extended
when array's fillpointer reaches the end.
arrayp obj [function]

 T if obj is an instance of array or vector.
arraytotalsize array [function]

 returns the total number of elements
of array.
fillpointer array [function]


arrayrank array [function]


arraydimensions array [function]


returns a list of arraydimensions.
arraydimension array axis [function]


Axis starts from 0. arraydimension returns the axisth
dimension of array.
bit bitvec index [function]


returns the indexth element of bitvec.
Use setf and bit to change an element of a bitvector.
bitand bits1 bits2 &optional result [function]


bitior bits1 bits2 &optional result [function]


bitxor bits1 bits2 &optional result [function]


biteqv bits1 bits2 &optional result [function]


bitnand bits1 bits2 &optional result [function]


bitnor bits1 bits2 &optional result [function]


bitnot bits1 &optional result [function]


For bit vectors bits1 and bits2 of the same length,
their boolean and, inclusiveor,
exclusiveor, equivalence, notand, notor and not are returned, respectively.
There is no character type in EusLisp;
a character is represented by an integer.
In order to handle strings representing file names,
use pathnames described in 11.6.
digitcharp ch [function]


T if ch is #
0 through #
9.
alphacharp ch [function]


T if ch is #
A through #
Z or
#
a through #
z.
uppercasep ch [function]


T if ch is #
A through #
Z.
lowercasep ch [function]


T if ch is #
a through #
z.
alphanumericp ch [function]


T if ch is #
0 through #
9,
#
A through #
Z
or #
a through #
z.
charupcase ch [function]


convert the case of ch to upper.
chardowncase ch [function]


convert the case of ch to lower.
char string index [function]


returns indexth character in string.
schar string index [function]


extracts a character from string. Use schar only if the
type of string is definitely known and no type check is required.
stringp object [function]


string is a vector of bytes (integers less than 256).
stringupcase str &key start end [function]


converts str to upper case string and returns a new string.
stringdowncase str &key start end [function]


converts str to lower case string and returns a new string.
nstringupcase str [function]


converts str to upper case string destructively.
nstringdowncase str &key start end [function]


converts str to lower case string destructively.
string= str1 str2 &key start1 end1 start2 end2 [function]


T if str1 is equal to str2.
string= is case sensitive.
stringequal str1 str2 &key start1 end1 start2 end2 [function]


tests equality of str1 and str2.
stringequal is not case sensitive.
string object [function]


gets string notation of object. If object is a string, the object
is returned. If object is a symbol, its pname is copied and returned.
Note that (equal (string 'a) (symbolpname 'a))==T, but
(eq (string 'a) (symbolpname 'a))==NIL.
If object is number its string representation is returned
(this is incompatible with Common Lisp).
In order to get string representation for more complex objects,
use format with NIL in the first argument.
string str1 str2 [function]


string str1 str2 [function]


string str1 str2 [function]


string str1 str2 [function]


stringlefttrim bag str [function]


stringrighttrim bag str [function]


str is scanned from the left(or right),
and its elements are removed if
it is included in the bag list.
Once a character other than the ones in the bag is found,
further scan is aborted and the rest of str
is returned.
stringtrim bag str [function]


Bag is a sequence of character codes.
A new copy of str which does not contain characters specified in bag
in its both end is made and returned.
substringp sub string [function]


T if string sub is contained in string as a substring.
Not case sensitive.
A foreignstring is a kind of bytevector whose entity is held somewhere
outside EusLisp's heap.
While a normal string is represented by a sequence of bytes and its length,
a foreignstring holds the length and the address of the string entity.
Although foreignstring is a string,
some string and sequence functions cannot be applicable.
Only length, aref, replace, subseq and copyseq
recognize the foreignstring,
and application of other functions may cause a crash.
A foreignstring may refer to a part of I/O space usually
taken in /dev/a??d?? special file where ?? is either 32 or 16.
In case the device attached in one of these I/O space only responds
to byte access, replace always copies element byte by byte,
which is relatively slow when a large chunk of memory is accessed
consecutively.
makeforeignstring address length [function]


makes an instance of foreignstring located at address
and spanning for length bytes.
For example, (makeforeignstring (unix:malloc 32) 32)
makes a reference to a 32byte memory located outside EusLisp's heap.
Hashtable is a class to search for the value associated with a key,
as accomplished by assoc.
For a relatively large problem,
hashtable performs better than assoc, since time required for searching remains constant even
the number of keyvalue pairs increases.
Roughly speaking, hashtable should be used in search spaces with
more than 100 elements, and assoc in smaller spaces.
Hashtables automatically expands if the number of elements
in the table exceeds rehashsize.
By default, expansion occurs when a half of the table is filled.
sxhash function returns a hash value which is independent
of memory address of an object, and hash values for equal objects
are always the same.
So, hash tables can be reloadable since they use sxhash as their default
hashing functions.
While sxhash is robust and safe,
it is relatively slow because it scans all the elements
in a sequence or a tree.
For faster hashing, you may choose another hash function appropriate
for your application.
To change the hash function, send :hashfunction message
to the hashtable.
In simple cases, it is useful to change hash function from #'sxhash
to #'sys:address.
This is possible because the addresses of any objects
never change in a EusLisp process.
sxhash obj [function]


calculates the hash value for obj.
Two objects which are equal are guaranteed to yield
the same hash value.
For a symbol, hash value for its pname is returned.
For numbers, their integer representations are returned.
For a list, sum of hash values for all its elements is returned.
For a string, shifted sum of each character code is returned.
For any other objects, sxhash is recursively called to calculate
the hash value of each slot, and the sum of them is returned.
makehashtable &key (size 30) (test #'eq) (rehashsize 2.0) [function]


creates a hash table and returns it.
gethash key htab [function]


gets the value that corresponds to key in htab.
Gethash is also used to set a value to key by combining with setf.
When a new entry is entered in a hash table, and the number of filled slots
in the table exceeds 1/rehashsize, then the hash table is automatically
expanded to twice larger size.
remhash key htab [function]


removes a hash entry designated by key in htab.
maphash function htab [function]


maps function to all the elements of htab.
hashtablep x [function]

 T if x is an instance of class hashtable.
hashtable [class]
:super object
:slots (key value count
hashfunction testfunction
rehashsize empty deleted)

 defines hash table.
Key and value are simplevectors of the same size.
Count is the number of filled slots in key and value.
Hashfunction is defaulted to sxhash and
testfunction to eq.
Empty and deleted are uninterned symbols to indicate
slots are empty or deleted in the key vector.
:hashfunction newhash [method]


changes the hash function of this hash table to newhash.
Newhash must be a function with one argument and returns an integer.
One of candidates for newhash is system:address.
A queue is a data structure that allows insertion and retrieval of data
in the FIFO manner, i.e. the firstin firstout order.
Since the queue class is defined by extending the cons class,
ordinary list functions can be applied to a queue.
For example, caar retrieves the next element to be dequeued,
and cadr gets the element that is queued most recently.
queue [class]
:super cons
:slots (car cdr)

 defines queue (FIFO) objects.
:init [method]


initializes the queue to have no elements.
:enqueue val [method]


puts val in the queue as the most recent element.
:dequeue &optional (errorp nil) [method]


retrieves the oldest value in the queue, and removes it of the queue.
If the queue is empty, it reports an error when errorp is nonnil,
or returns NIL otherwise.
:empty? [method]

 returns T if the queue is empty.
:length [method]

 returns the length of the queue.
:trim s [method]

 discard old entries to keep the size of this queue to s.
:search item &optional (test #'equal) [method]

 find element which
is equal to item. the search is performed by equal, which can be altered by test
:delete item &optional (test #'equal) (count
1) [method]

 eliminate count occurrences of item in this queue.
:first [method]

 returns the first entry (oldest value) of this queue.
:last [method]

 returns tha last entry (newest value) of this queue.
Travis CI User
20170307