Generated: Monday, November 14, 2011, 09:17:27 Copyright © 2011 , Kurt NÝrmark The local LAML software home page

Reference Manual of the General LAML library

Kurt NÝrmark © normark@cs.aau.dk Department of Computer Science, Aalborg University, Denmark.

LAML Source file: lib/general.scm

This is a library of common and generally useful Scheme functions, which are used in other LAML libraries, in LAML styles, and in LAML tools. Far the majority of the functions can also be used outside LAML.

Table of Contents:
1. Optional parameter handling. 7. Other higher-order functions. 13. Functions that change letter case in string.
2. List selection functions and their generators. 8. List and Sexpr functions. 14. Byte string functions.
3. Association and property list functions. 9. Vector functions. 15. Message displaying and error handling procedures.
4. Filter and accumulation functions. 10. Conversion functions. 16. File name, file path and URL functions.
5. Mapping functions. 11. String predicates. 17. Other functions.
6. Higher-order bite functions. 12. Other string functions. 18. Bite Generators.

Alphabetic index:
absolute-file-path? (absolute-file-path? x) Return whether x represents an absolute path to a file.
absolute-url? (absolute-url? x) Does the string x represent an absolute URL.
accumulate-right (accumulate-right f init lst) A higher-order function which right accumulates the list lst by means of the binary function f, using init as the initial value of the accumulation.
alist-from-keys-and-values (alist-from-keys-and-values key-list val-list) Make an alist from a key-list and a val-list.
alist-to-propertylist (alist-to-propertylist alist) Make and return a property list from an association list.
as-01-boolean (as-01-boolean x) Convert x to C-style boolean values, 0 or 1.
as-boolean (as-boolean x) Convert x to a boolean.
as-char (as-char x) Convert x to a character.
as-list (as-list x) Convert x to a list.
as-number (as-number x) Convert x to a number.
as-quoted-string (as-quoted-string x) Convert x to a string, in which string constituents themselves are quoted.
as-string (as-string x) Convert x to a string.
as-symbol (as-symbol x) Convert x to a symbol.
as-two-complement-signed-number (as-two-complement-signed-number i n) Re-interpret the positive integer i as an n bit two's complement number.
binary-search-in-vector (binary-search-in-vector v el sel el-eq? el-leq?) Search for an element el in the sorted vector v.
binary-to-hex-string (binary-to-hex-string byte-string) Given byte-string, which is binary data.
bit-list-to-byte-string (bit-list-to-byte-string bit-list) Return a byte string with the bit from bit-list (a list of integer zeros and ones).
bite-of-length (bite-of-length n [noise-element?]) Generate and return a function: List -> List, which returns a bite of length n.
bite-of-varied-length (bite-of-varied-length f [noise-element?]) Generate and return a function: List Int -> List, which returns a bite of length f(n), where n is the bite number (1 based) passed as the second parameter to the generated function.
bite-while-accumulate (bite-while-accumulate bin-op init-val pred [noise-element?]) Generate and return a function, which returns the shortest (first) non-empty prefix bite that accumulates to a value which fulfills the predicate pred.
bite-while-compare (bite-while-compare el-relation [noise-element?]) Generate and return a function, which - when applied on a list - returns the longest bite of the list in which successive elements fulfill the binary relation el-relation.
bite-while-element (bite-while-element el-pred . attributes) Generate and return a function: List -> List, which returns the longest prefix bite in which each element, appart from sentinel elements, fulfills the prediciate el-pred.
bite-while-element-with-accumulation (bite-while-element-with-accumulation pred accumulator init-acc-val [noise-element?]) Generate and return a function: List -> List, which returns the longest prefix bite in which each element, appart from a sentinel element, fulfills the prediciate pred.
bite-while-monotone (bite-while-monotone el-comparator [noise-element?]) Generate and return a function, which - when applied on a list - returns the longest bite of the list in which successive elements are monotone measured by the el-comparator function.
bite-while-prefix (bite-while-prefix bite-pred) Generate and return a function: List -> List, which returns the longest bite of the input list, of which each prefix bite satisfies bite-pred.
blank-string? (blank-string? str) Is the string str empty or blank.
but-first-sentence-of-string (but-first-sentence-of-string str) Return all but the first sentence in str.
but-prefix-part-of-absolute-path (but-prefix-part-of-absolute-path abs-path) Return the complementary part of the absolute file path relative to (prefix-part-of-absolute-path abs-path).
but-props (but-props prop-list eliminations) Return those property names and values of prop-list which are not in eliminations.
butlast (butlast lst) Return all but the last element of a list.
byte-string-to-bit-list (byte-string-to-bit-list byte-str [number-of-bits]) Return the list of bits in byte-str with at least number-of-bits bits.
byte-string-to-integer (byte-string-to-integer byte-str) Given a byte string - most significant byte first (big endian byte order) - return the decimal integer which it represents.
capitalize-string (capitalize-string str) Mutate str to have an initial capital character.
capitalize-string-nd (capitalize-string-nd str) Return str with capital, initial character.
char->string (char->string ch) Convert a character to a string
compose (compose . f-list) Compose a list of functions to a single function.
conjunction (conjunction p q) Form the conjunction (logical and) of the two predicates p and q.
copy-files (copy-files files source-dir target-dir [warn-if-non-existing-source]) Copy each of the files in the list files from source-dir to target-dir.
copy-string-into! (copy-string-into! target i source) Copy source into target and overwrite a portion of target.
copy-text-file (copy-text-file from-path to-path overwrite?) Copy the text file in from-path to the file in to-path.
CR CR Return a CR string
curry-generalized (curry-generalized f) Generalize f with ad hoc currying.
cut-list-by-predicate (cut-list-by-predicate lst pred) Cut the tail of lst; The tail to be cutted starts with an element which fulfils pred.
decapitalize-string (decapitalize-string str) Mutate str to have lower case, initial character.
decapitalize-string-nd (decapitalize-string-nd str) Return str with lower case, initial character.
decreasing-list-with-noice? (decreasing-list-with-noice? comparator noice-fn lst) Return if lst has decreasing elements relative to the comparator.
decreasing-list? (decreasing-list? comparator lst) Return if lst has decreasing elements relative to the comparator.
defaulted-get (defaulted-get key alist default) Return the value of key in alist (by means of cdr of assq).
defaulted-get-prop (defaulted-get-prop key p-list default) Return the value of key in the property list p-list.
delete-string-portion (delete-string-portion str i lgt) Delete the substring of length lgt from index i in the string str.
directory-leave-name (directory-leave-name dir) Return the name of the leave directory of the directory dir.
directory-level-difference (directory-level-difference dir1 dir2) Return the number of directory levels in between dir1 and dir2.
disjunction (disjunction p q) Form the disjunction (logical or) of the two predicates p and q.
display-error (display-error . messages) Display an error message - in terms of messages - and stop the program.
display-message (display-message . messages) Display messages on standard output.
display-warning (display-warning . messages) Display a warning message line on standard output via the Scheme display function.
downcase-string (downcase-string str) Downcase all characters in str.
duplicates-by-predicate (duplicates-by-predicate lst p) Return the duplicates in lst.
eighth (eighth lst) Return the eighth element of a list
element-after (element-after el lst selector [eq-pred]) Return the element of lst just after el, or #f if no such element exists.
element-before (element-before el lst selector [eq-pred]) Return the element of lst just before el, or #f if no such element exists.
embed-substring (embed-substring substring str embed-function) Embed the first occurrence of substring, as found in string, into embed-function.
empty-string? (empty-string? str) Is the string str empty
ensure-directory-existence! (ensure-directory-existence! prefix-dir dir) Ensure that the directory with path (string-append prefix-dir dir) exists.
ensure-directory-path-existence! (ensure-directory-path-existence! prefix-dir path) Ensure that the relative path, as represented by the parameter path, exists in prefix-dir.
ensure-final-character (ensure-final-character str ch) Ensure that the last character in str (a string) is ch (a char)
ensure-non-existing-file-in-dir (ensure-non-existing-file-in-dir f d) Ensure that the file f (proper name and extension) is non-existing in the directory d.
errors-among-conditions (errors-among-conditions . err-condition-message-list) Return a list of error message strings for those conditions err-condition-message-list that are true.
every-second-element (every-second-element lst) Return every second element of list, starting with the first element.
exchange-chars-in-str! (exchange-chars-in-str! str n m) Exchange destructively char n and m in str.
extend-a-list (extend-a-list key value a-list) Add a key-value pair to a-list.
extend-prop-list (extend-prop-list key val prop-list) Extend prop-list with key being associated to val.
extract-substrings (extract-substrings str start-marker end-marker) Extract substrings from str which are enclosed in start-marker and end-marker (both strings).
fac (fac n) Return the factorial of n: n * (n-1) * ...
fifth (fifth lst) Return the fifth element of a list
file-append (file-append file-name x) Append x to file-name.
file-name-extension (file-name-extension file-name) Return the extension of file-name.
file-name-initial-path (file-name-initial-path file-path) Return the initial path of file-path.
file-name-proper (file-name-proper file-name) Return the part of file-name without extension and without an initial path.
file-name-proper-and-extension (file-name-proper-and-extension file-path) Return the part of file-name, with a possible extension, but without an initial path.
file-name-sans-extension (file-name-sans-extension file-name) Return the filename component sans the final extension.
file-read (file-read file-name [n]) Read a Lisp expression from a file named file-name.
file-read-all (file-read-all file-name) Read all Lisp expression from file-name.
file-write (file-write x file-name) Write the list expression x to the file named file-name.
filter (filter pred lst) Filter a list lst by means of the predicate pred.
filter-bites (filter-bites make-bite bite-pred lst) Successively take bites of list with make-bite, apply the predicate bite-pred on the bite, and splice the bite into the resulting list if bite-pred is true for the bite.
filter-map-bites (filter-map-bites make-bite bite-pred bite-transf lst) Filter bites, but additionally map the resulting bites with bite-transf after the filtering.
filter-no-ordering (filter-no-ordering pred lst) Like filter, but the ordering among elements in the resulting list is unknown and arbitrary.
filter-string (filter-string pred str) Take away all characters in the string str that satisfy pred.
find-but-tail-in-list (find-but-tail-in-list pred lst) A simple linear list search function which returns a prefix of the list.
find-in-list (find-in-list pred lst) A simple linear list search function.
find-in-property-list (find-in-property-list key p-list) Does key exists as a property name in the property list p-list? If so, return a reference to the cons cell that holds key.
find-in-string (find-in-string str ch [start-pos]) Search linearly for the character ch in the string str.
find-in-string-by-predicate (find-in-string-by-predicate pred str [start-pos]) Find the first character in str that satisfies the char-predicate pred, and return index of that char.
find-in-string-from-end (find-in-string-from-end str ch) Search linearly for the character ch in the string str, beginning from the rear end of str.
find-in-string-from-end-by-predicate (find-in-string-from-end-by-predicate pred str [start-pos]) Find the last character in str that satisfies the char-predicate pred, and return index of that char.
find-index-in-list (find-index-in-list lst pred) Find the index of the first element in lst that satisfies the element predicate pred.
find-tail-in-list (find-tail-in-list pred lst) A simple linear list search function which returns a suffix of the list.
first (first lst) Return the first element of a list
first-improper-part (first-improper-part lst) Return the first improper part of an S-expression
first-sentence-in-string (first-sentence-in-string str) Return the first sentence in str (including a point).
flatten (flatten lst-of-lst) Flatten a list of lists to one list.
fourth (fourth lst) Return the fourth element of a list
front-sublist (front-sublist lst n) Return the first n elements of lst.
front-sublist-while (front-sublist-while lst ok? max-length) Return a list prefix of lst, of which all elements satisfy the predicate ok?.
generate-leq (generate-leq enumeration-order selector [el-eq?]) Generate a less than or equal predicate from the enumeration-order.
get (get key a-list) Return a value from an alist which corresponds to key.
get-prop (get-prop key p-list) Return the value of key in the property list p-list.
hex-to-binary-string (hex-to-binary-string hex-string) Given a human readable hex string, as produced by the sibling function called binary-to-hex-string.
hex-to-binary-string-relaxed (hex-to-binary-string-relaxed hex-string) Given a human readable hex string, as produced by the sibling function called binary-to-hex-string.
id-1 (id-1 x) The identify function of one parameter
increasing-list-with-noice? (increasing-list-with-noice? comparator noice-fn lst) Return if lst has increasing elements relative to the comparator.
increasing-list? (increasing-list? comparator lst) Return if lst has increasing elements relative to the comparator.
index-in-list-by-predicate (index-in-list-by-predicate lst el c) Return the index position of the fist occurrence of el in list.
int10-to-binary (int10-to-binary n number-of-bytes) Convert a decimal integer n to a binary quantity, represented as a string of length number-of-bytes.
inverse-return-path (inverse-return-path path dir) Return the inverse file path of path, as taken relative to dir.
laml-error (laml-error . messages) Stop the program with messages.
last (last lst) Return the last element of a list.
list-but-ref (list-but-ref lst n) Return a copy of all elements in lst apart from element number n.
list-difference (list-difference lst1 lst2 [is-eq?]) Remove the elements of lst2 from lst1.
list-intersection-by-predicate (list-intersection-by-predicate lst1 lst2 pred) Return the elements of lst1 and lst2 which belong to both of the lists.
list-of-lines-to-string (list-of-lines-to-string line-lst) Concatenate the lines in the string list line-lst
list-part (list-part a b lst) Return the sublist consisting of element a to element b of the list lst.
list-prefix-while (list-prefix-while lst predicate) Return a prefix of lst as long as the predicate holds.
list-tail-flex (list-tail-flex lst n) Return the sublist of lst obtained by omitting the first n elements.
list-to-string (list-to-string lst separator) Return a string with the elements of str-lst separated by separator.
log2 (log2 x) The base 2 logarithm function.
looking-at-substring? (looking-at-substring? str pos sub-str) Does str contain sub-str as substring, starting at position pos? An efficient implementation without any string copying, only character comparsion.
make-byte-string-from-hex-2 (make-byte-string-from-hex-2 hx1 hx2) Make a string, with single character, from two hex numbers.
make-byte-string-from-hex-4 (make-byte-string-from-hex-4 hx1 hx2 hx3 hx4) Make a string, with two characters, from four hex numbers.
make-byte-string-from-hex-6 (make-byte-string-from-hex-6 hx1 hx2 hx3 hx4 hx5 hx6) Make a string, with three characters, from two six numbers.
make-byte-string-from-hex-8 (make-byte-string-from-hex-8 hx1 hx2 hx3 hx4 hx5 hx6 hx7 hx8) Make a string, with four characters, from eight hex numbers.
make-char-2-hex (make-char-2-hex hx1 hx2) Make a character from two hex numbers
make-comparator (make-comparator lt gt) Generate and return a comparison function from a 'less than' function lt, and a 'greater than' function gt.
make-list (make-list n el) Return a list of n elements, each being el
make-mutator-function (make-mutator-function n [mutator-name]) Make and return a mutator function which mutates element number n in a list.
make-selector-function (make-selector-function n [selector-name]) Returns a function, which selects element number n in a list.
map-bites (map-bites make-bite bite-transf lst) Successively take bites of the list lst with make-bite, transform these bites with bite-transf, and splice (append accumulate) the transformed bites together.
map-n-bites (map-n-bites make-bite bite-transf lst) A variant of map-bites, which passes the bite number to both make-bite and to bite-transf.
map2 (map2 f lst1 lst2) Like map, but maps f on two lists.
map3 (map3 f lst1 lst2 lst3) Like map, but maps f on three lists
map4 (map4 f lst1 lst2 lst3 lst4) Like map, but maps f on four lists
map5 (map5 f lst1 lst2 lst3 lst4 lst5) Like map, but maps f on five lists
mapping-filter (mapping-filter pred . lists) Map and filter the lists in the parameter lists by means of the predicate pred.
member-by-predicate (member-by-predicate el lst p) Is el member of lst by means of the predicate p.
merge-lists (merge-lists list1 list2 pred) Merge list1 and list2.
merge-lists-simple (merge-lists-simple lst1 lst2) Merge the two lists lst1 and lst2.
min-max-limited (min-max-limited x min max) Ensure that the number x is in between min and max, or that min or max is returned.
multi-pair (multi-pair lst-of-lst) Pair up first elements, second elements of a list of lists.
multiplum-of (multiplum-of a b) Is a (the first par) a multiplum of b (the last par)?
negate (negate p) A higher order functions which negates the predicate p.
newline-string (newline-string) Return a CR string.
nineth (nineth lst) Return the nineth element of a list
normalize-absolute-file-path (normalize-absolute-file-path abs-path) Normalizes the absolute file path for redundant ".." levels.
normalize-file-path (normalize-file-path path) Normalizes the abolute or relative file path by removal of redundant ".." levels.
normalize-relative-file-path (normalize-relative-file-path path) Normalizes the relative file path for redundant ".." levels.
number-in-base (number-in-base n base) Return the decimal number n in base.
number-interval (number-interval f t) Return a list of all integer numbers from f to t.
numeric-string? (numeric-string? str [signed?]) Returns if the string str is numeric.
optional-parameter (optional-parameter n optional-parameter-list [default-value]) Return element n of optional-parameter-list.
pad-string-to-length (pad-string-to-length lgt str [justification pad-char]) Pad the string str to a total length.
pair-up (pair-up lst1 lst2) Return a list of pairs of elements from lst1 and lst2.
parent-directory (parent-directory dir) Return the name of the parent directory of dir (a string), or #f if dir is the root directory.
path-list-to-relative-path (path-list-to-relative-path path-list) Return the relative path formed by the element of path-list.
power (power n m) Return n * n * ...
prefix-part-of-absolute-path (prefix-part-of-absolute-path abs-path) Return the prefix part of the absolute file path (the "/" or the "c:\" for instance).
proper-part (proper-part lst) Return the proper part of an S-expression.
property-subset (property-subset prop-list keylist) Return those property key/value pairs of the proper list prop-list whose keys are member of keylist.
propertylist-to-alist (propertylist-to-alist plist) Make and return an association list from a property list plist.
put-around-substring (put-around-substring str pre-index pre-putin post-index post-putin) Put pre-putin at pre-index, and post-putit at post-index in the string str.
put-into-string (put-into-string str index putin-str) Before the character with index put in putin-str into str, and return the resulting, extended string.
re-break (re-break str) A quite special HTML line breaking function.
rear-sublist (rear-sublist lst n) Return the last n elements of lst.
relative-part-of-absolute-path (relative-part-of-absolute-path abs-path) Return the suffix part of the absolute file path (the part following the initial "/" for instance).
relative-path-to-path-list (relative-path-to-path-list dir) Given a relative file path, return a list of path constituents.
relative-url? (relative-url? x) Does the string x represen a relative URL.
remove-associations (remove-associations key-list a-list) Remove the keys in key-list from the association list a-list
remove-duplicates (remove-duplicates lst) Remove duplicate elements from list.
remove-duplicates-by-predicate (remove-duplicates-by-predicate lst p) Remove duplicates from lst.
remove-duplicates-with-selection (remove-duplicates-with-selection lst selector) A variant of remove-duplicates with a selector function.
remove-prop! (remove-prop! key p-list) Remove all instances of key and its values form the property list p-list.
remove-props! (remove-props! key-list p-list) Remove all instances of keys in key-list together with its values form the property list p-list.
repeat-string (repeat-string str n) Repeat the string str n times.
replace-string (replace-string str1 str2 str3) In str1 replace all occurences of str2 with str3 and return the resulting string.
replicate-to-length (replicate-to-length lst lgt) Replicate lst cyclically to a list of length lgt
rotate-string (rotate-string str n) Rotate the string str n positions.
save-a-list (save-a-list alist filename) Save the alist on a file named filename.
save-on-file (save-on-file x filename) Displays the first parameter x on a file named filename.
second (second lst) Return the second element of a list
seventh (seventh lst) Return the seventh element of a list
shallow-copy-list (shallow-copy-list lst) Return a shallow copy of lst.
shuffle-list (shuffle-list lst) Shuffle the elements of the list lst randomly.
sixth (sixth lst) Return the sixth element of a list
skip-chars-in-string (skip-chars-in-string str char-list start-pos) Starting from start-pos, skip characters in string from char-list.
split-on (split-on ch str) Return a list of two strings taken from str.
split-point (split-point ch str) Return the character position where ch occurs the first time in str.
split-string-by-predicate (split-string-by-predicate str pred) Split the string str into a list of strings.
step-and-map-bites (step-and-map-bites make-bite bite-pred bite-transf lst) A variant of filter-map-bites which successively and step-wise applies apply bite-pred to prefixes of lst.
step-and-map-n-bites (step-and-map-n-bites make-bite bite-pred bite-transf lst) A variant of step-and-map-bites that passes the bite number to bite-trans.
string-append-with-separator (string-append-with-separator str-lst separator) Concatenate the strings in str-lst, and separate them by separator-str.
string-it (string-it x) embed the string x in double string quotes
string-it-single (string-it-single x) embed the string x in single string quotes
string-merge (string-merge str-list-1 str-list-2) Merge str-list-1 with str-list-2, returning one string.
string-of-char-list? (string-of-char-list? str char-list) Are all characters in str member of char-list (a list of characters).
string-of-negative-char-list? (string-of-negative-char-list? str char-list) Are all characters in str different from the characters in char list (a list of characters).
string-to-list (string-to-list str element-separator-chars) Convert a string to a list.
string-to-list-of-lines (string-to-list-of-lines str) Return the list of lines of the string str.
strip-initial-characters (strip-initial-characters char-list string) Strip initial occurences of chars from char-list from string.
strip-initial-spaces (strip-initial-spaces string) Strip all initial space characters and lineshifting characters from string.
strip-trailing-characters (strip-trailing-characters char-list string) Strip trailing occurences of the characters in char-list from string.
sublist-by-2columns (sublist-by-2columns lst extra) Return sublists of lst in two column format.
sublist-by-columns (sublist-by-columns n lst extra) Return sublists of lst in an n column format.
sublist-by-predicate (sublist-by-predicate lst p) Return a list of sublists of elements from lst controlled by a predicate p.
sublist-by-rows (sublist-by-rows n lst) Return a list of lists of elements from lst.
sublist-of-list (sublist-of-list lst from-pred end-pred) Returns a sublist of list, controlled by the list element predicates from-pred and end-pred.
sublist-until (sublist-until until-fn lst) Return a prefix of lst until, and including, the element accepted by until-fn.
sublistify (sublistify lst sublist-length) Divide the elements of lst into sublists of sublist-length.
subset-of-by-predicate (subset-of-by-predicate set-list-1 set-list-2 comp) Return whether every element in set-list-1 (a list) is a member of set-list-2, compared by the comparator comp.
substring-index (substring-index str str-index find-str) Return the index of the first occurence of find-str in str.
substring? (substring? s t) Is t a substring of s? This function is almost identical to substring-index which in tells at which position (if any) t occurs in s.
sum-list (sum-list lst) Add all elments in a list of numbers
symbolize-key (symbolize-key key-value-pair) A function which converts the key position in an a-lists to a symbol.
tenth (tenth lst) Return the tenth element of a list
third (third lst) Return the third element of a list
transliterate (transliterate in-string ch str) In in-string, substitute each occurence of character ch with the string str.
traverse-cons-cells (traverse-cons-cells pred cell) Return the list of all cons cells reachable from cell which satisfy pred.
turn-into-boolean (turn-into-boolean x) If x is considered true return #t else #f.
type-of (type-of x) Return the type of the value x.
unescape-text (unescape-text text esc-char) Unescape text with the escape character esc-char.
unique-timed-file-name (unique-timed-file-name prefix) Return a unique file name with prefix.
upcase-string (upcase-string str) Upcase all characters in str.
white-space-char-list white-space-char-list A list of characters considered as blank space characters


1 Optional parameter handling.
Given the function (lambda (r1 r2 . optional-parameters) ...) the function optional-parameter (see below) is able to extract optional parameter number n. Non-used optional parameter can either be passed as the #f value (false in Scheme) or not passed at all.

optional-parameter
Form (optional-parameter n optional-parameter-list [default-value])
Description Return element n of optional-parameter-list. The first element is number 1. In Scheme the optional parameters are captured as a list after the required parameters: (define f (x y . optional-parameter-list) ...). Please notice that if you pass optional parameter number i, the optional parameters 1, 2, ..., i-1 must be passed explicitly. If you explicitly pass the symbol non-passed-value, this function will always return the default value, default-value. (This means, of course, that you cannot use the symbol non-passed-value as an 'ordinary value' in your program). If no optional third parameter - default-value - is given to the function optional-parameter the value #f serves as the default default-value.
Precondition optional-parameter-list is a proper list.
Examples (optional-parameter 1 (list 'a 'b 'c) 'x) => a
(optional-parameter 4 (list 'a 'b 'c) 'x) => x
(optional-parameter 10 (list 'a 'b 'c) 'x) => x
(optional-parameter 1 (list 'non-passed-value 'b 'c) 'x) => x
(optional-parameter 3 (list 'a 'b 'c) 'x) => c
See also Scheme source file optional-parameter


2 List selection functions and their generators.
As an alternative to using car, cadr etc. we provide for generation of more general list selector functions.

make-selector-function
Form (make-selector-function n [selector-name])
Description Returns a function, which selects element number n in a list. The second parameter, which is optional, is used for error message purposes. In general, this parameter should be a string corresponding to the name of the selector function. If the second parameter is given, we check whether the list is long enough for selection. If not, we give a decent error message. We recommend use of the second parameter in order to avoid meaningless error messages. The first element is number 1. (make-selector-function 1) corresponds to car, (make-selector-function 2) corresponds to cadr, etc.
Examples ((make-selector-function 1) (list 1 2 3)) => 1
((make-selector-function 3) (list 1 2 3)) => 3
See also Scheme source file make-selector-function

make-mutator-function
Form (make-mutator-function n [mutator-name])
Description Make and return a mutator function which mutates element number n in a list. The returned function takes a list and a new value as arguments. This function takes one optional parameter, which is the name of the mutator.
Parameters n The position in the last to be mutated. The first element counts as number 1.
mutator-name The name of the mutator function. Used only for error message purposes.
Returns A function of two parameters (lambda (lst new-value) ...) that mutates element n of lst to new-value.
Examples (let ((lst '(1 2 3 4))) ((make-mutator-function 2) lst 11) lst) => (1 11 3 4)
(let ((lst '(1 2 3 4))) ((make-mutator-function 1) lst 11) lst) => (11 2 3 4)
(let ((lst '(1 2 3 4))) ((make-mutator-function 4) lst 11) lst) => (1 2 3 11)
See also Scheme source file make-mutator-function

first
Form (first lst)
Description Return the first element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file first

second
Form (second lst)
Description Return the second element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file second

third
Form (third lst)
Description Return the third element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file third

fourth
Form (fourth lst)
Description Return the fourth element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file fourth

fifth
Form (fifth lst)
Description Return the fifth element of a list
Returns The fifth element of the list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file fifth

sixth
Form (sixth lst)
Description Return the sixth element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file sixth

seventh
Form (seventh lst)
Description Return the seventh element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file seventh

eighth
Form (eighth lst)
Description Return the eighth element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file eighth

nineth
Form (nineth lst)
Description Return the nineth element of a list
Examples (map (lambda (f) (f '(1 2 3 4 5 6 7 8 9))) (list first second third fourth fifth sixth seventh eighth nineth)) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file nineth

tenth
Form (tenth lst)
Description Return the tenth element of a list
See also Scheme source file tenth


3 Association and property list functions.
Here follows a number of functions which work on alists, or make alists. Also a number of property list functions are provided.

extend-a-list
Form (extend-a-list key value a-list)
Description Add a key-value pair to a-list. Like acons in some systems. The parameter key is forced to be a symbol (converted to a symbol with as-symbol).
Examples (extend-a-list 'k 1 some-a-list) => ((k . 1) (a . 1) (b . 2) (c . 3))
(extend-a-list 'k 1 '()) => ((k . 1))
See also Scheme source file extend-a-list

extend-prop-list
Form (extend-prop-list key val prop-list)
Description Extend prop-list with key being associated to val.
See also Scheme source file extend-prop-list

get
Form (get key a-list)
Description Return a value from an alist which corresponds to key. In case the key does not exist in the alist, a fatal error will occur.
Parameters key is a symbol.
a-list an association list with symbols as keys.
Returns the first value of key in a-list.
Examples (get 'a some-a-list) => 1
(get 'b some-a-list) => 2
See also Scheme source file get
similar function defaulted-get
Note Uses the function assq (based on eq? for key comparions) internally.

defaulted-get
Form (defaulted-get key alist default)
Description Return the value of key in alist (by means of cdr of assq). If no association is found return default.
Examples (defaulted-get 'a some-a-list 10) => 1
(defaulted-get 'd some-a-list 10) => 10
See also Scheme source file defaulted-get
similar function get

get-prop
Form (get-prop key p-list)
Description Return the value of key in the property list p-list. In case the key does not exist in the property list, a fatal error will occur.
Precondition p-list is of even length
Parameters key is a symbol.
p-list a property list with symbols as keys.
Returns the first value of key in p-list
Examples (get-prop 'b some-prop-list) => 2
(get-prop 'c some-prop-list) => 3
See also Scheme source file get-prop
similar function defaulted-get-prop
Note Uses the function eq? for key comparions.

find-in-property-list
Form (find-in-property-list key p-list)
Description Does key exists as a property name in the property list p-list? If so, return a reference to the cons cell that holds key.
Examples (find-in-property-list 'x some-prop-list) => #f
(find-in-property-list 'a some-prop-list) => (a 1 b 2 c 3)
(find-in-property-list 'c some-prop-list) => (c 3)
See also Scheme source file find-in-property-list

defaulted-get-prop
Form (defaulted-get-prop key p-list default)
Description Return the value of key in the property list p-list. If key is not present in p-list, return default.
Precondition p-list is a list of even length
Examples (defaulted-get-prop 'c some-prop-list 'x) => 3
(defaulted-get-prop 'd some-prop-list 'x) => x
See also Scheme source file defaulted-get-prop
similar function get-prop

remove-prop!
Form (remove-prop! key p-list)
Description Remove all instances of key and its values form the property list p-list.
Precondition p-list is a well-formed property list.
Returns the resulting, possible shorter, property list (a reduced copy of p-list).
Examples (let ((lst (list 'a 1 'b 2 'c 3))) (remove-prop! 'b lst) lst) => (a 1 b 2 c 3)
(remove-prop! 'a some-prop-list) => (b 2 c 3)
(remove-prop! 'b some-prop-list) => (a 1 c 3)
(remove-prop! 'd some-prop-list) => (a 1 b 2 c 3)
See also Scheme source file remove-prop!
Note This is a function, not a mutating procedure.

remove-props!
Form (remove-props! key-list p-list)
Description Remove all instances of keys in key-list together with its values form the property list p-list.
Precondition p-list is a well-formed property list.
Returns the resulting, possible shorter, property list (a reduced copy of p-list).
Examples (remove-props! '(a) '(a 1 b 2 c 3)) => (b 2 c 3)
(remove-props! '(a b c) '(a 1 b 2 c 3)) => ()
(remove-props! '(c) '(a 1 b 2 c 3)) => (a 1 b 2)
(remove-props! '(b) '(a 1 b 2 c 3)) => (a 1 c 3)
(remove-props! '(b c) '(a 1 b 2 c 3)) => (a 1)
(remove-props! '(b c) '()) => ()
(remove-props! '(b c) '(a 1)) => (a 1)
(remove-props! '(b c) '(a 1 b 2)) => (a 1)
See also Scheme source file remove-props!
Note This is a function, not a mutating procedure.

remove-associations
Form (remove-associations key-list a-list)
Description Remove the keys in key-list from the association list a-list
Examples (remove-associations '(a b) '((a . 5) (b . 7) (c . 11))) => ((c . 11))
(remove-associations '(x y) '((a . 5) (b . 7) (c . 11))) => ((a . 5) (b . 7) (c . 11))
(remove-associations '(x b) '((a . 5) (b . 7) (c . 11))) => ((a . 5) (c . 11))
(remove-associations '() '((a . 5) (b . 7) (c . 11))) => ((a . 5) (b . 7) (c . 11))
See also Scheme source file remove-associations

alist-from-keys-and-values
Form (alist-from-keys-and-values key-list val-list)
Description Make an alist from a key-list and a val-list.
Precondition the lengths of the two input lists are equal.
Examples (alist-from-keys-and-values '(x y z) '(1 2 3)) => ((x . 1) (y . 2) (z . 3))
See also Scheme source file alist-from-keys-and-values

propertylist-to-alist
Form (propertylist-to-alist plist)
Description Make and return an association list from a property list plist.
Examples (propertylist-to-alist some-prop-list) => ((a . 1) (b . 2) (c . 3))
(propertylist-to-alist '()) => ()
(alist-to-propertylist (propertylist-to-alist some-prop-list)) => (a 1 b 2 c 3)
See also Scheme source file propertylist-to-alist

alist-to-propertylist
Form (alist-to-propertylist alist)
Description Make and return a property list from an association list.
Examples (alist-to-propertylist some-a-list) => (a 1 b 2 c 3)
(alist-to-propertylist (propertylist-to-alist some-prop-list)) => (a 1 b 2 c 3)
See also Scheme source file alist-to-propertylist

every-second-element
Form (every-second-element lst)
Description Return every second element of list, starting with the first element. This function is useful to extract the keys or values of a property list.
Examples (every-second-element some-prop-list) => (a b c)
(every-second-element (cons 'x some-prop-list)) => (x 1 2 3)
(every-second-element '()) => ()
See also Scheme source file every-second-element

but-props
Form (but-props prop-list eliminations)
Description Return those property names and values of prop-list which are not in eliminations.
Parameters prop-list A well-formed property list, in which the property names are symbols.
eliminations A list of property names, where each property name is a symbol.
Examples (but-props some-prop-list '(a b)) => (c 3)
(but-props some-prop-list '(d)) => (a 1 b 2 c 3)
(but-props some-prop-list '()) => (a 1 b 2 c 3)
See also Scheme source file but-props

property-subset
Form (property-subset prop-list keylist)
Description Return those property key/value pairs of the proper list prop-list whose keys are member of keylist. Comparison is done by the function memq.
Examples (property-subset some-prop-list '(a)) => (a 1)
(property-subset some-prop-list '()) => ()
(property-subset some-prop-list '(a b c)) => (a 1 b 2 c 3)
See also Scheme source file property-subset

pair-up
Form (pair-up lst1 lst2)
Description Return a list of pairs of elements from lst1 and lst2. In other words, return an association list with keys from lst1 and values from lst2. The list is as long as the shortest of lst1 and lst2.
Examples (pair-up '(a b c) '(1 2 3)) => ((a . 1) (b . 2) (c . 3))
(pair-up '(a b c) '(1 2)) => ((a . 1) (b . 2))
(pair-up '(a b c) '()) => ()
(pair-up '(a) '(1 2 3)) => ((a . 1))
(pair-up '() '(1 2 3)) => ()
(pair-up '() '()) => ()
(pair-up '(x y) '(5 6 7)) => ((x . 5) (y . 6))
See also Scheme source file pair-up

symbolize-key
Form (symbolize-key key-value-pair)
Description A function which converts the key position in an a-lists to a symbol.
Parameters key-value-pair a pair, such as ("key" . "val")
Returns a pair (key . "val")
Examples (symbolize-key (cons 'a 'b)) => (a . b)
(symbolize-key (cons "a" "b")) => (a . "b")
See also Scheme source file symbolize-key


4 Filter and accumulation functions.
This sections provides variants of the very useful higher order filtering function.

filter
Form (filter pred lst)
Description Filter a list lst by means of the predicate pred. Preserves the ordering of elements in lst.
Returns the elements in lst that fulfills the predicate pred.
Examples (filter number? (list 1 "1" 'a (list 1))) => (1)
(filter number? (list 1 1.2 3/4)) => (1 1.2 3/4)
See also Scheme source file filter
similar function filter-no-ordering
Note Based on a tail recursive traversal of lst.

filter-no-ordering
Form (filter-no-ordering pred lst)
Description Like filter, but the ordering among elements in the resulting list is unknown and arbitrary. Actually returns filtered list in reverse order. OK in situations, where a boolean result is needed: Are there anything passing the filter?
Examples (filter-no-ordering number? (list 1 1.2 3/4)) => (3/4 1.2 1)
See also Scheme source file filter-no-ordering
similar function filter

mapping-filter
Form (mapping-filter pred . lists)
Description Map and filter the lists in the parameter lists by means of the predicate pred. In the same ways as for the native map function of Scheme, lists must be a list of lists, and pred must be a function taking as many arguments as there are lists and returning a single value. If more than one list is given, then they must all be the same length. If the predicate pred returns a true value v on the elements in lists, return v instead of e (this is the mapping effect). Only return those mapped elements that fullfil pred.
Examples (mapping-filter (lambda (x) (* x 2)) '(1 2 3)) => (2 4 6)
(mapping-filter (lambda (x y) (if (even? x) (+ (* x 2) y) #f)) '(1 2 3 4 5) '(10 11 12 13 14)) => (15 21)
See also Scheme source file mapping-filter
Note Remember that any non-#f element counts as the true (#t) value.

accumulate-right
Form (accumulate-right f init lst)
Description A higher-order function which right accumulates the list lst by means of the binary function f, using init as the initial value of the accumulation.
Examples (accumulate-right - 0 '(1 2 3 4 5)) => 3
(accumulate-right - 7 '(1 2 3 4 5)) => -4
(accumulate-right + 0 '(1 2 3 4 5)) => 15
See also Scheme source file accumulate-right
Note This function is iterative.


5 Mapping functions.
Here is a set of generalized mapping functions. These functions are all similar to map (which may take an arbitrary number of lists). Notice however, that map2, map3, etc do not require all lists to be of equal lengths.

map2
Form (map2 f lst1 lst2)
Description Like map, but maps f on two lists.
Returns Returns a list of length equal to the length of the shortest of the input lists.
Examples (map2 + (list 1 2 3) (list 4 5 6)) => (5 7 9)
(map2 + (list 1 2 3) (list 4 5 6 7 8 9)) => (5 7 9)
(map2 + (list 1 2 3) '()) => ()
See also Scheme source file map2

map3
Form (map3 f lst1 lst2 lst3)
Description Like map, but maps f on three lists
Returns Returns a list of length equal to the length of the shortest of the input lists.
Examples (map3 + (list 1 2 3) (list 4 5 6) (list 7 8 9)) => (12 15 18)
See also Scheme source file map3

map4
Form (map4 f lst1 lst2 lst3 lst4)
Description Like map, but maps f on four lists
Returns Returns a list of length equal to the length of the shortest of the input lists.
Examples (map4 + (list 1 2 3) (list 4 5 6) (list 7 8) (list 7 8)) => (19 23)
See also Scheme source file map4

map5
Form (map5 f lst1 lst2 lst3 lst4 lst5)
Description Like map, but maps f on five lists
Returns Returns a list of length equal to the length of the shortest of the input lists.
Examples (map5 + (list 1 2 3) (list 4 5 6) (list 7 8) (list 7 8) (list 0)) => (19)
See also Scheme source file map5


6 Higher-order bite functions.
Mapping and filtering functions that operate on bites (sublists) of a list. A bite of a non-empty list is a non-empty prefix of the list. Consequtive bites of a list must append-accumulate to the original list. There exists a number of higher-order bite function creators, such as bite-while-element and bite-of-length, see here .

map-bites
Form (map-bites make-bite bite-transf lst)
Description Successively take bites of the list lst with make-bite, transform these bites with bite-transf, and splice (append accumulate) the transformed bites together. The bite number (starting with 1) is passed as the second parameter to make-bite.
Parameters make-bite A function which returns the next bite. Signature: List, Int -> List.
bite-transf A function which transform a bite: Signature: List -> List. (Notice that this function only takes a single parameter).
lst A list from which bites are taken, one at a time.
Examples (map-bites (bite-while-element number?) list '(1 -1 1 a 3 4 b 6 1 2 3)) => ((1 -1 1 a) (3 4 b) (6 1 2 3))
(map-bites (bite-while-element (negate number?)) list '(a b 1 c d 2 e f g h i j 3 k l)) => ((a b 1) (c d 2) (e f g h i j 3) (k l))
(map-bites (bite-while-element number?) list '(a b 1 c d 2 e f g h i j 3 k l)) => ((a) (b) (1 c) (d) (2 e) (f) (g) (h) (i) (j) (3 k) (l))
(map-bites (bite-while-element symbol? 'sentinel "first") list '(a b 1 c d 2 e f g h i j 3 k l)) => ((a b) (1 c d) (2 e f g h i j) (3 k l))
(map-bites (bite-while-element symbol? 'sentinel "last") list '(a b 1 c d 2 e f g h i j 3 k l)) => ((a b 1) (c d 2) (e f g h i j 3) (k l))
(map-bites (bite-while-element symbol? 'sentinel "alone") list '(a b 1 c d 2 e f g h i j 3 k l)) => ((a b) (1) (c d) (2) (e f g h i j) (3) (k l))
(map-bites (bite-while-accumulate + 0 (lambda (sum) (>= sum 5))) list '(0 1 2 1 2 0 1 3 0 -2 1 3 4)) => ((0 1 2 1 2) (0 1 3 0 -2 1 3) (4))
(map-bites (bite-while-compare < symbol?) list '(a 0 b c 1 d 2 -1 e f g 7 2 3)) => ((a 0 b c 1 d 2) (-1 e f g 7) (2 3))
(map-bites (lambda (lst . r) (sublist-until number? lst)) (lambda (lst) (list (list-to-string (butlast lst) ","))) '(a b 1 c d 2 e f g h i j 3 k L 4)) => ("a,b" "c,d" "e,f,g,h,i,j" "k,L")
(map-bites (lambda (lst . r) (list-part 1 3 lst)) list '(a b c d e f g h i j k l)) => ((a b c) (d e f) (g h i) (j k l))
(map-bites (lambda (lst . r) (list-part 1 3 lst)) list '(a b c d e f g h i j k l)) => ((a b c) (d e f) (g h i) (j k l))
(map-bites (bite-while-monotone (make-comparator < >)) list '(1 2 1 2 1 2 3 4)) => ((1 2) (1 2) (1 2 3 4))
(map-bites (bite-of-varied-length (lambda (n) n)) list '(1 2 3 4 5 6 7 8)) => ((1) (2 3) (4 5 6) (7 8))
(map-bites (bite-of-varied-length (lambda (n) (if (even? n) 2 4))) list '(1 2 3 4 5 6 7 8 9 10 11 12)) => ((1 2 3 4) (5 6) (7 8 9 10) (11 12))
See also Scheme source file map-bites
Useful bite creators bite-while-element bite-of-length

map-n-bites
Form (map-n-bites make-bite bite-transf lst)
Description A variant of map-bites, which passes the bite number to both make-bite and to bite-transf. So the difference between map-n-bites and map-bites is whether bit-tranf takes a second parameter or not. With this function, the bite number is made available to the bite-transformation function. The first bite is number 1.
Parameters make-bite A function which returns the next bite. Signature: List, Int -> List. (The second parameter is a 1-based bite number).
bite-transf A function which transform a bite: Signature: List, Int -> List. (The second parameter is a 1-based bite number).
lst A list from which bites are taken, one at a time.
See also Scheme source file map-n-bites

filter-bites
Form (filter-bites make-bite bite-pred lst)
Description Successively take bites of list with make-bite, apply the predicate bite-pred on the bite, and splice the bite into the resulting list if bite-pred is true for the bite. The bite number (starting with 1) is passed as the second parameter to make-bite.
Parameters make-bite A function which returns the next bite. Signature: List, Int -> List. (The second parameter is a 1-based bite number).
bite-pred A bite predicate. Signature: List -> Boolean.
lst A list from which bites are taken, one at a time.
Examples (filter-bites (bite-while-element symbol?) (lambda (bite) (even? (length bite))) '(a 1 c d 2 e f g 3 l)) => (a 1 e f g 3)
(filter-bites (bite-while-accumulate + 0 (lambda (sum) (>= sum 5))) (lambda (bite) (even? (length bite))) '(0 1 2 1 2 3 4 0 -2 1 3 4)) => (3 4)
See also Scheme source file filter-bites
Useful bite creators bite-while-element bite-of-length

filter-map-bites
Form (filter-map-bites make-bite bite-pred bite-transf lst)
Description Filter bites, but additionally map the resulting bites with bite-transf after the filtering.
Parameters make-bite A function which returns the next bite. Signature: List, Int -> List. (The second parameter is a 1-based bite number).
bite-pred A bite predicate. Signature: List -> Boolean.
bite-transf A function which transform a bite: Signature: List -> List. (Notice that this function only takes a single parameter).
lst A list from which bites are taken, one at a time.
Examples (filter-map-bites (bite-while-element number? 'sentinel "alone") (lambda (bite) (>= (length bite) 2)) list '(a b 1 2 c 3 d 4 5 6 e)) => ((1 2) (4 5 6))
See also Scheme source file filter-map-bites

step-and-map-bites
Form (step-and-map-bites make-bite bite-pred bite-transf lst)
Description A variant of filter-map-bites which successively and step-wise applies apply bite-pred to prefixes of lst. The bites are constructed by the function make-bite. Prefix bites are examined by bite-pred with the purpose of deciding if the bite should be transformed with bite-transf, or forward bite stepping should be applied. In case of forward bite stepping, the step value determines a new start position of the next bite to be taken out of list. Those bites which are selected by the predicate are transformed by the transformation function, and spliced into the resulting list. Bites which are 'stepped over' are passed non-transformed.
Parameters make-bite A function which selects a prefix of the list (a bite) for examination and possible transformation. The bite number (starting from 1) is passed to this function as the second parameter. Signature: List, Int -> List.
bite-pred A function from a sublist (the bite) to a selection value. Signature: List -> integer. A positive integer serves as boolean true (select). A negative integer n serves as boolean false (deselect) and (- n) is the stepping value. A positive result r means that a prefix of r elements (typically equal to the length of the bite) is selected for transformation, and that the next bite starts r elements ahead. A negative result n means that the next byte taken by make-bite starts (- n) steps ahead. I.e., (-n) elements are passed untransformed to the result, and the start of the next bite is (- r) elements ahead.
bite-transf A transformation function on bites. Signature: List -> List.
lst A list of elements.
Examples (step-and-map-bites (lambda (lst . rest) (list-part 1 3 lst)) (lambda (bite) (if (even? (apply + bite)) (length bite) -1)) list '(0 1 2 1 2 3 4 0 -2 1 3 4 5)) => (0 (1 2 1) 2 3 (4 0 -2) (1 3 4) 5)
See also Scheme source file step-and-map-bites
Useful bite creators bite-while-element bite-of-length
Variant with bite numbers step-and-map-n-bites
Note Use this function to impose structure on a list, by successively attempting multiple possible bites of the list.

step-and-map-n-bites
Form (step-and-map-n-bites make-bite bite-pred bite-transf lst)
Description A variant of step-and-map-bites that passes the bite number to bite-trans.
Parameters make-bite A function which selects a prefix of the list (a bite) for examination and possible transformation. The bite number (starting from 1) is passed to this function as the second parameter. Signature: List, Int -> List.
bite-pred A function from a sublist (the bite) to a selection value. Signature: List -> integer. A positive integer serves as boolean true (select). A negative integer serves as boolean false (deselect). A positive result r means that a prefix of r elements (typically equal to the length of the bite) is selected for transformation, and that the next bite starts r elements ahead. A negative result r means that (- r) elements are passed untransformed to the result, and that the start of the next potential bite is (- r) elements ahead.
bite-transf A transformation function on bites and bite numbers. Signature: List, Int -> List.
lst A list of elements.
See also Scheme source file step-and-map-n-bites
More basic variant step-and-map-bites


7 Other higher-order functions.

negate
Form (negate p)
Description A higher order functions which negates the predicate p. Negate accepts a predicate and returns the negated predicate.
Examples ((negate null?) (list 1 2 3)) => #t
((negate (negate null?)) (list 1 2 3)) => #f
See also Scheme source file negate

disjunction
Form (disjunction p q)
Description Form the disjunction (logical or) of the two predicates p and q.
Returns a predicate
Examples (map (disjunction odd? even?) (list 1 2 3 4 5)) => (#t #t #t #t #t)
See also Scheme source file disjunction

conjunction
Form (conjunction p q)
Description Form the conjunction (logical and) of the two predicates p and q.
Returns a predicate
Examples (map (conjunction odd? even?) (list 1 2 3 4 5)) => (#f #f #f #f #f)
See also Scheme source file conjunction

compose
Form (compose . f-list)
Description Compose a list of functions to a single function. Each function in the list takes a single parameter. Handles the typical case of two functions manually to achieve better efficiency.
Precondition f-list is a proper list of length ast least one.
Examples ((compose (lambda (x) (+ x 1)) (lambda (x) (* x 2))) 3) => 7
((compose (lambda (x) (* x 2)) (lambda (x) (+ x 1))) 3) => 8
See also Scheme source file compose

generate-leq
Form (generate-leq enumeration-order selector [el-eq?])
Description Generate a less than or equal predicate from the enumeration-order. If p is the generated predicate, (p x y) is true if and only if (selector x) comes before (or at the same position) as (selector y) in the enumeration-order. Thus, (selector x) is assumed to give a value in enumeration-order. Comparison with elements in the enumeration-list is done with el-eq?
Examples (sort-list (list 3 3 5 5 7 7) (generate-leq (list 5 3 7) id-1 =)) => (5 5 3 3 7 7)
See also Scheme source file generate-leq

make-comparator
Form (make-comparator lt gt)
Description Generate and return a comparison function from a 'less than' function lt, and a 'greater than' function gt. If com is a comparison function, (com x y) returns -1 if (lt x y), (com x y) returns 1 if (gt x y), else it returns 0.
Precondition If (lt x y) and (gt x y) cannot both be true.
Examples ((make-comparator < >) 2 1) => 1
((make-comparator < >) 1 2) => -1
((make-comparator < >) 1 1) => 0
(map-bites (bite-while-monotone (make-comparator < >)) list '(1 2 1 2 1 2 3 4)) => ((1 2) (1 2) (1 2 3 4))
See also Scheme source file make-comparator

curry-generalized
Form (curry-generalized f)
Description Generalize f with ad hoc currying. f is a function which, in its native form, takes two or more parameters. The generalization allows f to act as a curried function. In case (curry-generalized f) only receives a single parameter, it returns a lambda function which waits for the remaining parameters. If two or more parameters are passed to f, f is applied on the parameters; In this case (curry-generalized f) is equivalent to f.
Examples (define gmap (curry-generalized map))
(define gfilter (curry-generalized filter))
((curry-generalized map) (lambda (n) (+ n 2)) '(1 2 3)) => (3 4 5)
(procedure? ((curry-generalized map) (lambda (n) (+ n 2)))) => #t
See also Scheme source file curry-generalized


8 List and Sexpr functions.

number-interval
Form (number-interval f t)
Description Return a list of all integer numbers from f to t.
Parameters f The lower limit of the interval. An integer number.
t The upper limit of the interval. An integer number.
Returns The list of numbers from (and including) f to (and including) t. Return the empty list if f is greater than t.
Examples (number-interval 1 5) => (1 2 3 4 5)
(number-interval -5 1) => (-5 -4 -3 -2 -1 0 1)
(number-interval 1 -5) => ()
(number-interval 1 1) => (1)
See also Scheme source file number-interval

proper-part
Form (proper-part lst)
Description Return the proper part of an S-expression.
Examples (proper-part '(a b c . d)) => (a b c)
(proper-part (cons 'a 'b)) => (a)
See also Scheme source file proper-part

first-improper-part
Form (first-improper-part lst)
Description Return the first improper part of an S-expression
Examples (first-improper-part (cons 'a 'b)) => b
(first-improper-part '(a b c . e)) => e
See also Scheme source file first-improper-part

make-list
Form (make-list n el)
Description Return a list of n elements, each being el
Examples (make-list 5 6) => (6 6 6 6 6)
(make-list 0 6) => ()
See also Scheme source file make-list

replicate-to-length
Form (replicate-to-length lst lgt)
Description Replicate lst cyclically to a list of length lgt
Examples (replicate-to-length '(a b) 3) => (a b a)
(replicate-to-length '(a b) 30) => (a b a b a b a b a b a b a b a b a b a b a b a b a b a b a b)
See also Scheme source file replicate-to-length

flatten
Form (flatten lst-of-lst)
Description Flatten a list of lists to one list.
Examples (flatten (list (list '(a b c) '(d e)))) => ((a b c) (d e))
(flatten (list '(a b c) '(d e) '(a b c) '(d e))) => (a b c d e a b c d e)
(flatten '()) => ()
See also Scheme source file flatten

sum-list
Form (sum-list lst)
Description Add all elments in a list of numbers
Examples (sum-list '(1 2 3 4)) => 10
(sum-list '()) => 0
See also Scheme source file sum-list

merge-lists
Form (merge-lists list1 list2 pred)
Description Merge list1 and list2. Let e1 be the head of list1 and e2 the head of list2. take e2 if (pred e1 e2) holds. Else e1
Examples (merge-lists '(1 2 3 4) '(5 6 7 8) (lambda (x y) (even? (+ x y)))) => (5 1 6 2 7 3 8 4)
(merge-lists '(1 2 3 4) '(4 6 7 8) (lambda (x y) (even? (+ x y)))) => (1 4 6 2 7 3 8 4)
See also Scheme source file merge-lists

merge-lists-simple
Form (merge-lists-simple lst1 lst2)
Description Merge the two lists lst1 and lst2. lst1 provides the first element. When the shortets of the lists is exhausted, insert the rest of the other list.
Examples (merge-lists-simple '(a b c d) '(1 2 3)) => (a 1 b 2 c 3 d)
(merge-lists-simple '(1 2 3 4) '(5 6 7 8)) => (1 5 2 6 3 7 4 8)
(merge-lists-simple '(1 2 3 4) '(5 6 7 8 9 10 11)) => (1 5 2 6 3 7 4 8 9 10 11)
(merge-lists-simple '(1 2 3 4) '()) => (1 2 3 4)
(merge-lists-simple '() '(1 2 3 4)) => (1 2 3 4)
(merge-lists-simple '(5 6 7 8) '(1 2 3 4)) => (5 1 6 2 7 3 8 4)
See also Scheme source file merge-lists-simple

find-in-list
Form (find-in-list pred lst)
Description A simple linear list search function. Return the first element which satisfies the predicate pred. If no such element is found, return #f. Tail recursive and iterative.
Examples (find-in-list number? '(a b c 3 d e)) => 3
(find-in-list number? '(3 4 5)) => 3
(find-in-list number? '(a b c)) => #f
See also Scheme source file find-in-list
Similar string function find-in-string-by-predicate
Similar list function find-tail-in-list

find-tail-in-list
Form (find-tail-in-list pred lst)
Description A simple linear list search function which returns a suffix of the list. Return the longest possible tail of the list whose first element satisfies the predicate pred. If no such element is found, return the empty list. Tail recursive and iterative.
Examples (find-tail-in-list number? '(x "5" 6 y "7")) => (6 y "7")
(find-tail-in-list number? '(x "5" 6)) => (6)
(find-tail-in-list number? '()) => ()
See also Scheme source file find-tail-in-list
Similar function find-in-list find-but-tail-in-list

find-but-tail-in-list
Form (find-but-tail-in-list pred lst)
Description A simple linear list search function which returns a prefix of the list. Return the shortest possible prefix of the list before an element that satisfies the predicate pred. If no such element is found, return the empty list. Tail recursive and iterative.
Examples (find-but-tail-in-list number? '(a b 1 c d 2 e)) => (a b)
(find-but-tail-in-list number? '(1 c d 2 e)) => ()
(find-but-tail-in-list number? '()) => ()
(find-but-tail-in-list number? '(a 1 c d 2 e)) => (a)
See also Scheme source file find-but-tail-in-list
Similar function find-in-list find-tail-in-list

traverse-cons-cells
Form (traverse-cons-cells pred cell)
Description Return the list of all cons cells reachable from cell which satisfy pred. If a cell c is accepted by the predicate, the cells of (cdr cell) are also examined for matches.
Precondition cell is a cons cell (satisfies pair?)
Parameters pred a cons-cell predicate.
cell a pair (such as a list).
See also Scheme source file traverse-cons-cells

butlast
Form (butlast lst)
Description Return all but the last element of a list. Quick and dirty version.
Precondition lst is not empty.
Examples (butlast '(1 2 3 4)) => (1 2 3)
(butlast '(1)) => ()
(map-bites (lambda (lst . r) (sublist-until number? lst)) (lambda (lst) (list (list-to-string (butlast lst) ","))) '(a b 1 c d 2 e f g h i j 3 k L 4)) => ("a,b" "c,d" "e,f,g,h,i,j" "k,L")
See also Scheme source file butlast

last
Form (last lst)
Description Return the last element of a list. Quick and dirty version.
Precondition lst is not empty.
Examples (last '(1)) => 1
(last '(1 2 3)) => 3
(last '(1 2)) => 2
See also Scheme source file last

remove-duplicates
Form (remove-duplicates lst)
Description Remove duplicate elements from list. A non-destructive function. This function uses the Scheme function equal? (via the Scheme function member) for comparison of elements.
Examples (remove-duplicates '(1 2 3 4 5)) => (1 2 3 4 5)
(remove-duplicates '(1 2 3 2 3 4 5)) => (1 2 3 4 5)
(remove-duplicates '(1 2 3 4 5)) => (1 2 3 4 5)
(remove-duplicates '(1 2 3 2 3 4 5)) => (1 2 3 4 5)
(remove-duplicates '()) => ()
(remove-duplicates '(1 1 1 1 1)) => (1)
See also Scheme source file remove-duplicates

remove-duplicates-with-selection
Form (remove-duplicates-with-selection lst selector)
Description A variant of remove-duplicates with a selector function. This function applies a selector function before comparisons and member is called. This function uses equal? for comparison of elements.
Examples (remove-duplicates-with-selection (map (lambda (n) (list 'x n)) (list 1 1 2 2 3 3 4 4)) cadr) => ((x 1) (x 2) (x 3) (x 4))
See also Scheme source file remove-duplicates-with-selection

element-before
Form (element-before el lst selector [eq-pred])
Description Return the element of lst just before el, or #f if no such element exists. More precisely, return the element of lst just before the element e, where e contains el in the sense that (eq? (selector e) el). Via use of the optional parameter, comparison can be done by use of another function than eq?.
Parameters el The element constituent that we are looking for.
lst The list to search.
selector A function that selects a constituent of an element of the list.
eq-pred The equality predicate on list constituents. Can be used to compare el with (selector e) for any element e in lst. Defaults to eq?.
Returns An element of the list lst, preceding the element containing el. Or #f in case such an element does not exist.
Examples (element-before 4 '(1 2 3 4 5) id-1) => 3
(element-before 1 '(1 2 3 4 5) id-1) => #f
(element-before 6 '(1 2 3 4 5) id-1) => #f
(element-before 5 '(1 2 3 4 5) id-1 =) => 4
See also Scheme source file element-before

element-after
Form (element-after el lst selector [eq-pred])
Description Return the element of lst just after el, or #f if no such element exists. More precisely, return the element of lst just after the element e, where e contains el in the sense that (eq? (selector e) el). Via use of the optional parameter, comparison can be done by use of another function than eq?.
Parameters el The element constituent that we are looking for.
lst The list to search.
selector A function that selects a constituent of an element of the list.
eq-pred The equality predicate on list constituents. Can be used to compare el with (selector e) for any element e in lst. Defaults to eq?.
Returns An element of the list lst, following the element containing el. Of #f in case such an element does not exist.
Examples (element-after 5 '(1 2 3 4 5) id-1 =) => #f
(element-after 3 '(1 2 3 4 5) id-1 =) => 4
See also Scheme source file element-after

list-difference
Form (list-difference lst1 lst2 [is-eq?])
Description Remove the elements of lst2 from lst1. This function is a non-destructive function.
Parameters lst1 The list from which lst1 is subtracted
lst2 The list to subtract from lst1
is-eq? the equalilty function used for element comparison. The default comparison function is eq?
Returns The elements in lst1 which are not member of lst2
Examples (list-difference (list 1 2 3 4 5) (list 1 2)) => (3 4 5)
(list-difference (list 1 2 3 4 5) (list 1 6)) => (2 3 4 5)
(list-difference (list 1 2 3 4 5) '()) => (1 2 3 4 5)
(list-difference '() (list 1 2 3 4 5)) => ()
See also Scheme source file list-difference

sublist-by-rows
Form (sublist-by-rows n lst)
Description Return a list of lists of elements from lst. Each sub list is of length n. Take elements consequtive (by rows) and put them into sublists.
Examples (sublist-by-rows 3 (list 1 2 3 4 5 6)) => ((1 2 3) (4 5 6))
(sublist-by-rows 3 (list 1 2 3 4 5 6 7)) => ((1 2 3) (4 5 6) (7))
(sublist-by-rows 3 (list )) => (())
See also Scheme source file sublist-by-rows
More general function sublist-by-predicate

sublist-by-2columns
Form (sublist-by-2columns lst extra)
Description Return sublists of lst in two column format. Thus each produced sublist is of length 2. Good for presentation of the list in two columns, column by column. In cases there is an uneven number of elements in lst, we add extra (the second parameter).
Examples (sublist-by-2columns (list 1 2 3 4 5 6 7 8) 11) => ((1 5) (2 6) (3 7) (4 8))
(sublist-by-2columns '(1) 11) => ((1 11))
See also Scheme source file sublist-by-2columns

sublist-by-columns
Form (sublist-by-columns n lst extra)
Description Return sublists of lst in an n column format. Thus each produced sublist is of length n (the first parameter). In cases there is not enough elements, we add extra (the last parameter).
Examples (sublist-by-columns 3 (list 1 2 3 4 5 6 7 8) 11) => ((1 4 7) (2 5 8) (3 6 11))
(sublist-by-columns 3 (list 1 2 3 4 5 6 7 8 9) 11) => ((1 4 7) (2 5 8) (3 6 9))
(sublist-by-columns 3 (list 1) 11) => ((1 11 11))
See also Scheme source file sublist-by-columns

multi-pair
Form (multi-pair lst-of-lst)
Description Pair up first elements, second elements of a list of lists. All first elements of the sublists are handled first, whereafter we take all second elements, etc.
Precondition All lists in lst-of-list are of equal lengths.
Parameters lst-of-lst A list of lists.
Examples (multi-pair '((1 2) (3 4) (5 6))) => ((1 3 5) (2 4 6))
(multi-pair '((1 2 3) (4 5 6) (6 7 8))) => ((1 4 6) (2 5 7) (3 6 8))
(multi-pair '(() () ())) => ()
See also Scheme source file multi-pair

sublist-by-predicate
Form (sublist-by-predicate lst p)
Description Return a list of sublists of elements from lst controlled by a predicate p. The sublists are formed by examining elements from lst. The predicate p decides when to start a new sublist. Thus, when p evaluates to true (on some element e and its preceding element c) we start a new sublist (whose first element becomes e). The predicate p is not activated on (car lst). This function generalizes sublist-by-rows.
Parameters lst An arbitrary list.
p A predicate of the form (lambda (cur prev n) ...) where cur is the current element, prev is the preceding element of cur, and n is the number of elements preceding cur in the original list lst.
Examples (sublist-by-predicate '(a b 1 c #f 2 f g) (lambda (c p n) (number? c))) => ((a b) (1 c #f) (2 f g))
(sublist-by-predicate '(a b 1 c #f 2 f g) (lambda (c p n) (boolean? c))) => ((a b 1 c) (#f 2 f g))
(sublist-by-predicate '(a b 1 c d #t f g) (lambda (c p n) (and (number? c) (boolean? p)))) => ((a b 1 c d #t f g))
(sublist-by-predicate '(a b 1 c #t 2 f g) (lambda (c p n) (and (number? c) (boolean? p)))) => ((a b 1 c #t) (2 f g))
(sublist-by-predicate '(a b 1 c #f 2 f g) (lambda (c p n) (and (number? c) (< n 5)))) => ((a b) (1 c #f 2 f g))
See also Scheme source file sublist-by-predicate

remove-duplicates-by-predicate
Form (remove-duplicates-by-predicate lst p)
Description Remove duplicates from lst. A pair of duplicates satisfy the predicate p. In case of duplicates, keep the first one in the result.
Parameters lst A list
p A predicate: element x element -> boolean.
Examples (remove-duplicates-by-predicate '(a b c a) eq?) => (a b c)
(remove-duplicates-by-predicate '(a b a b) eq?) => (a b)
(remove-duplicates-by-predicate '(a a a) eq?) => (a)
(remove-duplicates-by-predicate '() eq?) => ()
(remove-duplicates-by-predicate '(a b c d e) eq?) => (a b c d e)
See also Scheme source file remove-duplicates-by-predicate

duplicates-by-predicate
Form (duplicates-by-predicate lst p)
Description Return the duplicates in lst. The duplicates are returned in the order of their fist occurence in lst. Comparison of elements is done by the predicate p.
Parameters lst A list.
p A predicate element x element -> boolean.
Examples (duplicates-by-predicate '(a b c a b) eq?) => (a b)
(duplicates-by-predicate '(a b c) eq?) => ()
(duplicates-by-predicate '(a a a) eq?) => (a)
(duplicates-by-predicate '(a 1 2 3 a) eq?) => (a)
See also Scheme source file duplicates-by-predicate

member-by-predicate
Form (member-by-predicate el lst p)
Description Is el member of lst by means of the predicate p. If el is member, return the suffix of the list in which the first element (and el) satisfy the predicate. Else return #f. The element el and elements of lst are compared by p, el as the first one.
Parameters el An element.
lst A list.
p A predicate: element x element -> boolean
Examples (member-by-predicate 'a '(1 2 3 a b) eq?) => (a b)
(member-by-predicate 'c '(1 2 3 a b) eq?) => #f
(member-by-predicate 'a '(a 1 2 3 a b) eq?) => (a 1 2 3 a b)
(member-by-predicate 'a '() eq?) => #f
(member-by-predicate 'a '(a) eq?) => (a)
See also Scheme source file member-by-predicate

list-intersection-by-predicate
Form (list-intersection-by-predicate lst1 lst2 pred)
Description Return the elements of lst1 and lst2 which belong to both of the lists. Elements will never occur more than once in the result. Element comparsion is done by pred. Performance: O (length lst1) x (length lst2).
Parameters pred: Element x Element -> Boolean.
lst1 A list.
lst2 A list.
pred An element predicat: Element x Element -> Boolean.
Examples (list-intersection-by-predicate '(a b c d a) '(a d) eq?) => (a d)
(list-intersection-by-predicate '(a b c d a) '(a d c b a) eq?) => (a b c d)
(list-intersection-by-predicate '(a a b b) '(a) eq?) => (a)
(list-intersection-by-predicate '(a a b b) '() eq?) => ()
(list-intersection-by-predicate '() '() eq?) => ()
(list-intersection-by-predicate '(a b c d a) '(a a a a) eq?) => (a)
See also Scheme source file list-intersection-by-predicate

cut-list-by-predicate
Form (cut-list-by-predicate lst pred)
Description Cut the tail of lst; The tail to be cutted starts with an element which fulfils pred. Notice that the first element which fulfils the predicate is not included in the resulting list. If no element in the list fulfils the predicate, a shallow copy of the list is returned.
Parameters lst A list
pred An element predicate: Element -> Boolean.
Examples (cut-list-by-predicate '(a b c 3 d e 4 f) number?) => (a b c)
(cut-list-by-predicate '(a b 4) boolean?) => (a b 4)
(cut-list-by-predicate '() boolean?) => ()
(cut-list-by-predicate '(a b 4) (lambda (x) (eq? x 'b))) => (a)
See also Scheme source file cut-list-by-predicate
Note This is a pure function, which makes a shallow copy of a prefix of the list.

subset-of-by-predicate
Form (subset-of-by-predicate set-list-1 set-list-2 comp)
Description Return whether every element in set-list-1 (a list) is a member of set-list-2, compared by the comparator comp. This corresponds to a subset operations on sets, represented by a list. comp: el x el -> boolean.
Examples (subset-of-by-predicate (list 1 2 3) (list 1 2 3 4) =) => #t
(subset-of-by-predicate (list 1 2 3 4) (list 1 2 3) =) => #f
(subset-of-by-predicate '() (list 1 2) =) => #t
(subset-of-by-predicate (list 1 2) '() =) => #f
See also Scheme source file subset-of-by-predicate

index-in-list-by-predicate
Form (index-in-list-by-predicate lst el c)
Description Return the index position of the fist occurrence of el in list. The first element is counted as element number 0. If the element el is not in the list lst, return #f. Comparison of list elements is done by the binary comparison function c.
Parameters lst A list
el An element in the list.
c A function with the signature: element x element -> boolean.
Examples (index-in-list-by-predicate '(a b c d e) 'c eq?) => 2
(index-in-list-by-predicate '(a b c d e) 'f eq?) => #f
(index-in-list-by-predicate '() 'f eq?) => #f
(index-in-list-by-predicate '(a b c d e) 'a eq?) => 0
(index-in-list-by-predicate '(a b c d e) 'e eq?) => 4
See also Scheme source file index-in-list-by-predicate

sublistify
Form (sublistify lst sublist-length)
Description Divide the elements of lst into sublists of sublist-length. In case that sublist-length does not divide (length lst) the last sublist will be shorter than the others.
Parameters lst A list.
sublist-length A positive integer.
Examples (sublistify '(1 2 3 4 5 6 7 8 9) 4) => ((1 2 3 4) (5 6 7 8) (9))
(sublistify '(1 2 3 4 5 6 7 8 9) 1) => ((1) (2) (3) (4) (5) (6) (7) (8) (9))
(sublistify '(1 2 3 4 5 6 7 8 9) 9) => ((1 2 3 4 5 6 7 8 9))
(sublistify '(1 2 3 4 5 6 7 8 9) 8) => ((1 2 3 4 5 6 7 8) (9))
See also Scheme source file sublistify

front-sublist
Form (front-sublist lst n)
Description Return the first n elements of lst. This function makes a shallow copy of the first n elements of lst. Thus, it allocates n new cons cells. If n is equal or greater than the length of lst, lst is returned without any copying at all.
Parameters lst A list
n A non-negative integer.
Examples (front-sublist '(a b c d e) 2) => (a b)
(front-sublist '(a b c d e) 5) => (a b c d e)
(front-sublist '(a b c d e) 6) => (a b c d e)
(front-sublist '(a b c d e) 0) => ()
(front-sublist '() 0) => ()
(front-sublist '() 1) => ()
See also Scheme source file front-sublist
Note Another function, list-prefix, exists which is almost identical to front-sublist.

front-sublist-while
Form (front-sublist-while lst ok? max-length)
Description Return a list prefix of lst, of which all elements satisfy the predicate ok?. The returned prefix has at most max-length elements. This function makes a shallow copy of at most max-length elements of lst. Thus, it allocates a number of new cons cells.
Parameters lst An arbitrary list.
ok? A list element predicate, which is applied successively on elements of the list.
max-length An integer that gives the maximum number of elements to be returned by this function.
Returns A prefix of lst, of length at most max-length. All elements in the result satisfy the predicate ok?
Examples (front-sublist-while '(1 2 3 a 4 5 b 6) number? 7) => (1 2 3)
(front-sublist-while '(1 2 3 a 4 5 b 6) number? 2) => (1 2)
(front-sublist-while '(1 2 3 a 4 5 b 6) number? 0) => ()
See also Scheme source file front-sublist-while

rear-sublist
Form (rear-sublist lst n)
Description Return the last n elements of lst. This function returns a reference to an appropriate tail of lst, involving only the last n elements. If n is equal to or larger than (length lst), just return lst.
Parameters lst A list.
n A non-negative integer.
Examples (rear-sublist '(a b c d e) 3) => (c d e)
(rear-sublist '(c d e) 3) => (c d e)
(rear-sublist '(c d) 3) => (c d)
(rear-sublist '(c) 3) => (c)
(rear-sublist '() 3) => ()
(rear-sublist '(a b c d e) 0) => ()
(rear-sublist '() 0) => ()
See also Scheme source file rear-sublist

list-prefix-while
Form (list-prefix-while lst predicate)
Description Return a prefix of lst as long as the predicate holds.
Examples (list-prefix-while '(a b c 1 2 d e) symbol?) => (a b c)
(list-prefix-while '(1 2 d e) symbol?) => ()
(list-prefix-while '() symbol?) => ()
See also Scheme source file list-prefix-while

list-part
Form (list-part a b lst)
Description Return the sublist consisting of element a to element b of the list lst. If a is smaller than the length of the list, and b is larger than the length of the list, return from element number a and the rest of the list. If a is larger than the length of the list, return the empty list. Both element number a and b are included in the resulting list. The first element counts as element number 1.
Precondition a >= 1, a <= b and a and b are postive integers.
Examples (list-part 3 5 '(a b c d e f g h)) = (c d e)
(list-part 3 5 '(a b c d e f g h)) => (c d e)
(list-part 3 5 '(a b c d e)) => (c d e)
(list-part 1 5 '(a b c d e)) => (a b c d e)
(list-part 1 5 '()) => ()
(list-part 1 3 '(a b)) => (a b)
(list-part 2 3 '(a b)) => (b)
(list-part 3 4 '(a b)) => ()
(map-bites (lambda (lst . r) (list-part 1 3 lst)) list '(a b c d e f g h i j k l)) => ((a b c) (d e f) (g h i) (j k l))
(map-bites (lambda (lst . r) (list-part 1 3 lst)) list '(a b c d e f g h i j k l)) => ((a b c) (d e f) (g h i) (j k l))
(step-and-map-bites (lambda (lst . rest) (list-part 1 3 lst)) (lambda (bite) (if (even? (apply + bite)) (length bite) -1)) list '(0 1 2 1 2 3 4 0 -2 1 3 4 5)) => (0 (1 2 1) 2 3 (4 0 -2) (1 3 4) 5)
See also Scheme source file list-part
Note Please notice that the sligthly unusual convention that the first element of the list is number 1, not number 0.

sublist-of-list
Form (sublist-of-list lst from-pred end-pred)
Description Returns a sublist of list, controlled by the list element predicates from-pred and end-pred. The first element of the resulting list fullfils from-pred. The last element is the element before the element that fullfils end-pred. If from-pred is true on an element and to-pred is false on every element in list, a suffix of the list is returned. In other cases, if one or both of the predicates return false on every element the empty list is returned.
Parameters lst A list.
from-pred A list element predicate. Selects the first element of the result.
end-pred A list element predicate. Selects the first element after the last element of the result.
Examples (sublist-of-list '(a b c 0 1 2 #t a b c) number? boolean?) => (0 1 2)
(sublist-of-list '(a b c 0 1 2 #t a b c) (lambda (x) #t) number?) => (a b c)
(sublist-of-list '(a b c 0 #t a b c) number? boolean?) => (0)
(sublist-of-list '(a b c #t a b c) number? boolean?) => ()
(sublist-of-list '(a b c 0 1 2 #t a b c) boolean? number?) => ()
(sublist-of-list '(a b c 0 1 2 #t a b c) number? (lambda (x) #f)) => (0 1 2 #t a b c)
(sublist-of-list '(a b c 0 1 2 #t a b c) (lambda (x) #f) number?) => ()
(sublist-of-list '(a b c 0 1 2 #t a b c) (lambda (x) #t) (lambda (x) #f)) => (a b c 0 1 2 #t a b c)
See also Scheme source file sublist-of-list

sublist-until
Form (sublist-until until-fn lst)
Description Return a prefix of lst until, and including, the element accepted by until-fn. More precisely: apply until-fn on successive elements of lst, and return the longest possible prefix of list for which until-fn returns false on all elements followed by the element on which until-fn returns true. If until-fn returns false on all elements, return a shallow copy of lst.
Parameters until-fn An element prediate function. Signature: element-type -> boolean
lst A list.
Examples (sublist-until number? '(a b c 1 d e 2 f)) => (a b c 1)
(sublist-until number? '(1 d e 2 f)) => (1)
(sublist-until number? '(a b c d e)) => (a b c d e)
(sublist-until (lambda (e) #t) '(a b c)) => (a)
(map-bites (lambda (lst . r) (sublist-until number? lst)) (lambda (lst) (list (list-to-string (butlast lst) ","))) '(a b 1 c d 2 e f g h i j 3 k L 4)) => ("a,b" "c,d" "e,f,g,h,i,j" "k,L")
See also Scheme source file sublist-until

list-tail-flex
Form (list-tail-flex lst n)
Description Return the sublist of lst obtained by omitting the first n elements. Returns the empty list if n is larger than the length of lst.
Parameters lst A list
n A non-negative integer.
Examples (list-tail-flex '(a b c) 2) => (c)
(list-tail-flex '(a b c) 0) => (a b c)
(list-tail-flex '(a b c) 4) => ()
(list-tail-flex '() 0) => ()
(list-tail-flex '() 1) => ()
See also Scheme source file list-tail-flex
Note This function is like list-tail, but with a weaker precondition.

find-index-in-list
Form (find-index-in-list lst pred)
Description Find the index of the first element in lst that satisfies the element predicate pred. The first element counts as number 0.
Examples (find-index-in-list '(a b c 1 2 d) number?) => 3
(find-index-in-list '(0 a b c 1 2 d) number?) => 0
(find-index-in-list '() number?) => #f
(find-index-in-list '(a b c) number?) => #f
(find-index-in-list '(0 1) number?) => 0
(find-index-in-list '(a b c 0) number?) => 3
See also Scheme source file find-index-in-list

shallow-copy-list
Form (shallow-copy-list lst)
Description Return a shallow copy of lst. Only the top-level list structure is copied.
See also Scheme source file shallow-copy-list

increasing-list-with-noice?
Form (increasing-list-with-noice? comparator noice-fn lst)
Description Return if lst has increasing elements relative to the comparator. Only elements that do not satisfy noice-fn are taken into account. This function only deliver meaningful results if the non-noice part of lst is of at least length 2. In other cases it just returns #t
See also Scheme source file increasing-list-with-noice?

increasing-list?
Form (increasing-list? comparator lst)
Description Return if lst has increasing elements relative to the comparator. This function only deliver meaningful results if lst is of at least length 2. In other cases it just returns #t
See also Scheme source file increasing-list?

decreasing-list-with-noice?
Form (decreasing-list-with-noice? comparator noice-fn lst)
Description Return if lst has decreasing elements relative to the comparator. Only elements that do not satisfy noice-fn are taken into account. This function only deliver meaningful results if the non-noice part of lst is of at least length 2. In other cases it just returns #t
See also Scheme source file decreasing-list-with-noice?

decreasing-list?
Form (decreasing-list? comparator lst)
Description Return if lst has decreasing elements relative to the comparator. This function only deliver meaningful results if lst is of at least length 2. In other cases it just returns #t
See also Scheme source file decreasing-list?

list-but-ref
Form (list-but-ref lst n)
Description Return a copy of all elements in lst apart from element number n. If n is not between 0 and n-1, this function will return a copy of lst. The first elements is number 0.
Parameters lst A list of arbitrary elements
n An integer number.
Examples (list-but-ref '(a b c d e f g h) 3) => (a b c e f g h)
(list-but-ref '(a b c d e f g h) 0) => (b c d e f g h)
(list-but-ref '(a b c d e f g h) 7) => (a b c d e f g)
(list-but-ref '(a b c d e f g h) 10) => (a b c d e f g h)
(list-but-ref '() 2) => ()
(list-but-ref '() 0) => ()
(list-but-ref '(a a a a) 2) => (a a a)
See also Scheme source file list-but-ref

shuffle-list
Form (shuffle-list lst)
Description Shuffle the elements of the list lst randomly. This function relies on a function (random m), where m is an integer, which returns a number between 0 and m-1. Seeding of random is assumed to take place in the context of a call to suffle-list.
Examples (sort-list (shuffle-list '(1 2 3 4 5 6 7 8 9)) <=) => (1 2 3 4 5 6 7 8 9)
See also Scheme source file shuffle-list


9 Vector functions.

binary-search-in-vector
Form (binary-search-in-vector v el sel el-eq? el-leq?)
Description Search for an element el in the sorted vector v. More specifically, el is compared to (sel ve), where ve is a element from the vector v. Comparison is done by the binary predicate el-eq? which works on selected values. Thus (el-eq? (sel x) el) makes sense for an element x in the vector. Ordering in the vector is defined by the binary 'less-than-equal predicate' el-leq? which compares selected values. Thus (el-leq (sel x) (sel y)) makes sense for x and y being elements in the vector v.
Parameters v The vector to search in.
el The element to search for in the vector. el is comparabel with (sel ve) for a given vector element.
sel A function that can be applied on vector elements.
el-eq? An equality function that can be applied on el and on (sel ve) for a given vector element.
el-leq? A less than or equal function that can be applied on el and vector elements (sel ve).
Returns An element in the vector, if found as described above, or #f.
See also Scheme source file binary-search-in-vector


10 Conversion functions.
In this category we provide a number of useful conversion functions. Several of these are of the form (as-type xxx), where type determines the target type of the conversion.

This section includes a function number-in-base which converts a decimal number to a number in another number system.


char->string
Form (char->string ch)
Description Convert a character to a string
Examples (char->string #\a) => "a"
(char->string #\\) => "\\"
See also Scheme source file char->string

as-string
Form (as-string x)
Description Convert x to a string. Conversion of numbers, symbols, strings, booleans, characters, vectors, proper lists and improper lists are supported.
Examples (as-string "abc") => "abc"
(as-string 'abc) => "abc"
(as-string 123) => "123"
(as-string #t) => "true"
(as-string #f) => "false"
(as-string #\a) => "a"
(as-string (list "abc" 'abc 123 #t #f #\a)) => "(abc abc 123 true false a)"
(as-string #("abc" 'abc 123 #t #f #\a)) => "#(abc (quote abc) 123 true false a)"
(as-string #(1 2 3)) => "#(1 2 3)"
(as-string (cons 1 2)) => "(1 . 2)"
See also Scheme source file as-string

as-quoted-string
Form (as-quoted-string x)
Description Convert x to a string, in which string constituents themselves are quoted. Good for output and messages, in which strings should appear in string quotes.
Examples (as-quoted-string "abc") => "\"abc\""
(as-quoted-string 123) => "123"
(as-quoted-string (list "abc" 'abc 123 #t #f #\a)) => "(\"abc\" abc 123 true false a)"
See also Scheme source file as-quoted-string

as-symbol
Form (as-symbol x)
Description Convert x to a symbol. String, symbols, booleans, and characters are supported
Examples (as-symbol 'sym) => sym
(as-symbol "sym") => sym
(as-symbol #\s) => s
(as-symbol #t) => true
(as-symbol #f) => false
(as-symbol (list 1 2 3)) => #f
(as-symbol #(1 2 3)) => #f
See also Scheme source file as-symbol

as-number
Form (as-number x)
Description Convert x to a number. Strings, numbers, chars and booleans are supported. Strings with digits are converted using string->number, chars are converted with char->integer, true is converted to 1, and false to 0.
Examples (as-number "123") => 123
(as-number "123a") => #f
(as-number #\a) => 97
(as-number #\A) => 65
(as-number #f) => 0
(as-number #t) => 1
(as-number (list 1 2 3)): ERROR
See also Scheme source file as-number

as-char
Form (as-char x)
Description Convert x to a character. Integers, strings, booleans and symbols are supported. If x is an integer between 0 and 255 return ASCII char number x. If x is a string return the first character in the string (which is supposed to be non-empty). If x is a boolean return the character #\t for true and #\f for false. If x is a symbol return the first character of the print name of the string. Else return #\?.
Examples (as-char #\a) => #\a
(as-char 65) => #\A
(as-char "a") => #\a
(as-char "abc") => #\a
(as-char #t) => #\t
(as-char #f) => #\f
(as-char 'xyz) => #\x
(as-char #(a)) => #\?
See also Scheme source file as-char

as-list
Form (as-list x)
Description Convert x to a list. This function converts strings to a list of substring, which in the original string are separated by spaces, newlines, or tabs.
Examples (as-list "xy z abc ") => ("xy" "z" "abc")
(as-list "x y z") => ("x" "y" "z")
(as-list "xyz") => ("xyz")
(as-list (cons 1 2)) => (1 . 2)
(as-list #(1 2 3)) => (1 2 3)
(as-list #f) => (#f)
(as-list #t) => (#t)
See also Scheme source file as-list
more general function string-to-list

string-to-list
Form (string-to-list str element-separator-chars)
Description Convert a string to a list. The second parameter is a list of separator characters.
Examples (string-to-list "abcadefag" (list #\a)) => ("bc" "def" "g")
(string-to-list "123 456 7 8" (list #\space)) => ("123" "456" "7" "8")
See also Scheme source file string-to-list

as-boolean
Form (as-boolean x)
Description Convert x to a boolean. The strings "false", "no", and "NO" are converted to #f. Other strings are converted to #t.
Examples (as-boolean "xxx") => #t
(as-boolean #t) => #t
(as-boolean #f) => #f
(as-boolean "true") => #t
(as-boolean "no") => #f
(as-boolean "Yes") => #t
(as-boolean "YES") => #t
(as-boolean "YESSSS") => #t
(as-boolean "false") => #f
See also Scheme source file as-boolean

turn-into-boolean
Form (turn-into-boolean x)
Description If x is considered true return #t else #f. See also as-boolean which is more versatile. Recall that all values except #f, conveniently, act as a true value.
Examples (turn-into-boolean "x") => #t
(turn-into-boolean #t) => #t
(turn-into-boolean #f) => #f
(turn-into-boolean "false") => #t
(turn-into-boolean "123") => #t
(turn-into-boolean 'abc) => #t
(turn-into-boolean 'nil) => #t
(turn-into-boolean '()) => #t
See also Scheme source file turn-into-boolean

as-01-boolean
Form (as-01-boolean x)
Description Convert x to C-style boolean values, 0 or 1. Numbers are treated in the following way: If x is 0 the result is 0. If x is not 0 the result is 1. Else 1 is returned if x is considered as true in Scheme, and 0 is returned if x is considered as false in Scheme.
Returns Either the integer 0 (for false) or the integer 1 (for true).
Examples (as-01-boolean 0) => 0
(as-01-boolean 1) => 1
(as-01-boolean 12) => 1
(as-01-boolean "x") => 1
(as-01-boolean "0") => 1
(as-01-boolean 'xx) => 1
See also Scheme source file as-01-boolean

list-to-string
Form (list-to-string lst separator)
Description Return a string with the elements of str-lst separated by separator.
Parameters lst A list of elements, each of which is converted to a string by the function as-string.
separator A string which is used to separate the list elements in the resulting string.
Examples (list-to-string (list "a" "b" "cde") "1") => "a1b1cde"
(list-to-string (list "a" "b" "cde") " ") => "a b cde"
(list-to-string (list "a" "b" "cde") 1): ERROR
(list-to-string (list "a" "b" "cde") 'xx): ERROR
(list-to-string '(a "b" 2 #f) ", ") => "a, b, 2, false"
(map-bites (lambda (lst . r) (sublist-until number? lst)) (lambda (lst) (list (list-to-string (butlast lst) ","))) '(a b 1 c d 2 e f g h i j 3 k L 4)) => ("a,b" "c,d" "e,f,g,h,i,j" "k,L")
See also Scheme source file list-to-string

string-append-with-separator
Form (string-append-with-separator str-lst separator)
Description Concatenate the strings in str-lst, and separate them by separator-str.
Parameters str-lst A list of strings
separator A string, a character or anything else that the function as-string can convert to a string.
Returns A string
Examples (string-append-with-separator (list "a" "b" "cde") 'x) => "axbxcde"
(string-append-with-separator (list "a" "b" "cde") 1) => "a1b1cde"
See also Scheme source file string-append-with-separator

number-in-base
Form (number-in-base n base)
Description Return the decimal number n in base.
Parameters n A positive decimal integer.
base The base of the number system. A possitive integer greater than 1.
Returns A string which represents n in the number system with base.
Examples (number-in-base 123 16) => "7b"
(number-in-base 123 123) => "10"
(number-in-base 128 2) => "10000000"
(number-in-base 32 2) => "100000"
See also Scheme source file number-in-base
Note By coincidence equivalent to the native Scheme function number->string.


11 String predicates.

empty-string?
Form (empty-string? str)
Description Is the string str empty
Examples (empty-string? "") => #t
(empty-string? "1") => #f
See also Scheme source file empty-string?

white-space-char-list
Form white-space-char-list
Description A list of characters considered as blank space characters
Examples (find-in-string-by-predicate (lambda (ch) (memv ch white-space-char-list)) "some string") => 4
(find-in-string-by-predicate (lambda (ch) (memv ch white-space-char-list)) "some string" 5) => #f
(find-in-string-by-predicate (lambda (ch) (memv ch white-space-char-list)) "some string" #f) => #f
(filter-string (lambda (ch) (memv ch white-space-char-list)) "a b c d") => "abcd"
(filter-string (lambda (ch) (memv ch white-space-char-list)) (string-append "a b c d" CR "x y")) => "abcdxy"
(filter-string (lambda (ch) (memv ch white-space-char-list)) " ") => ""
(filter-string (lambda (ch) (memv ch white-space-char-list)) "abc") => "abc"
See also Scheme source file white-space-char-list

blank-string?
Form (blank-string? str)
Description Is the string str empty or blank. A blank string is composed of spaces, CRs, line feeds and tabs.
Examples (blank-string? "") => #t
(blank-string? " ") => #t
(blank-string? (list-to-string (list (as-string #\tab) (as-string #\newline) (as-string #\space)) "")) => #t
See also Scheme source file blank-string?

numeric-string?
Form (numeric-string? str [signed?])
Description Returns if the string str is numeric. More specifically, does str consist exclusively of the ciffers 0 through 9. A non-false value of the optional parameter signed? allows an initial '+' or '-' char as well.
Examples (numeric-string? "123") => #t
(numeric-string? "+123") => #f
(numeric-string? "+123" 'signed) => #t
(numeric-string? "-0" 'signed) => #t
See also Scheme source file numeric-string?

string-of-char-list?
Form (string-of-char-list? str char-list)
Description Are all characters in str member of char-list (a list of characters).
Examples (string-of-char-list? "abab" (list #\a #\b)) => #t
(string-of-char-list? "" (list #\a #\b)) => #t
(string-of-char-list? "" (list )) => #t
(string-of-char-list? "car" (list )) => #f
(string-of-char-list? "abba" (list #\a #\b)) => #t
(string-of-char-list? "abbac" (list #\a #\b)) => #f
(string-of-char-list? "aaaa" (list #\a)) => #t
(string-of-char-list? "1 2 3" (list #\1 #\2)) => #f
(string-of-char-list? #\a (list #\a)): ERROR
(string-of-char-list? "1 2 3" (list #\1 #\2 #\3 #\space)) => #t
(string-of-char-list? "1 2 3" (list #\1 #\2 #\3)) => #f
See also Scheme source file string-of-char-list?

string-of-negative-char-list?
Form (string-of-negative-char-list? str char-list)
Description Are all characters in str different from the characters in char list (a list of characters).
Examples (string-of-negative-char-list? "de" (list #\a #\b)) => #t
(string-of-negative-char-list? "car" (list )) => #t
(string-of-negative-char-list? "bde" (list #\a #\b)) => #f
(string-of-negative-char-list? "ababa" (list #\a #\b)) => #f
(string-of-negative-char-list? "" (list #\a #\b)) => #t
See also Scheme source file string-of-negative-char-list?

looking-at-substring?
Form (looking-at-substring? str pos sub-str)
Description Does str contain sub-str as substring, starting at position pos? An efficient implementation without any string copying, only character comparsion.
Parameters str The string to examine.
sub-str The string to look for in str.
pos The position where the match will have to occur (a non-negative integer).
Returns A boolean value.
Examples (looking-at-substring? "care" 1 "ar") => #t
(looking-at-substring? "care" 0 "ar") => #f
(looking-at-substring? "care" 2 "re") => #t
(looking-at-substring? "care" 2 "ree") => #f
(looking-at-substring? "" 0 "") => #t
(looking-at-substring? "" 0 "x") => #f
(looking-at-substring? "x" 1 "x") => #f
See also Scheme source file looking-at-substring?

substring?
Form (substring? s t)
Description Is t a substring of s? This function is almost identical to substring-index which in tells at which position (if any) t occurs in s.
Parameters s The string to examine.
t The string we are looking for as a substring of s.
Returns A boolean value.
Examples (substring? "this is a string" "is") => #t
(substring? "is" "this is a string") => #f
(substring? "this is a string" "this") => #t
(substring? "this is a string" "This") => #f
(substring? "this is a string" "string") => #t
(substring? "this is a string" "string.") => #f
See also Scheme source file substring?
related function substring-index


12 Other string functions.
Among the functions in this section you will find string search and replacement functions.

split-on
Form (split-on ch str)
Description Return a list of two strings taken from str. The first is the prefix of str up to (but excluding) the first occurence of ch. The second is the suffix from (but also excluding) ch to the end of str.
Parameters ch The split character.
str A string.
Examples (split-on #\x "axb") => ("a" "b")
(split-on #\x "aa"): ERROR
(split-on #\x ""): ERROR
(split-on #\x "axbxb") => ("a" "bxb")
(split-on #\x "xxx") => ("" "xx")
See also Scheme source file split-on

split-point
Form (split-point ch str)
Description Return the character position where ch occurs the first time in str. If it does not appear, the procedure returns #f. This function allocates some temporary strings, and as such it is not efficient. Use find-in-string instead.
Parameters ch The split character.
str A string.
Examples (split-point #\x "axb") => 1
(split-point #\x "abx") => 2
(split-point #\x "xab") => 0
(split-point #\x "ab") => #f
(split-point #\x "") => #f
See also Scheme source file split-point
Similar string find function substring-index
Recommended alternative find-in-string

split-string-by-predicate
Form (split-string-by-predicate str pred)
Description Split the string str into a list of strings. Consecutive portions of the strings, in which a character satisfies the char predicate pred, separate the elements of the resulting list. In case that only separators occur in str, an empty list is returned.
Examples (split-string-by-predicate "a,b,c" (lambda (ch) (eqv? ch #\,))) => ("a" "b" "c")
(split-string-by-predicate "a" (lambda (ch) (eqv? ch #\,))) => ("a")
(split-string-by-predicate "" (lambda (ch) (eqv? ch #\,))) => ()
(split-string-by-predicate "a---b---c" (lambda (ch) (eqv? ch #\-))) => ("a" "b" "c")
(split-string-by-predicate ",,,,,," (lambda (ch) (eqv? ch #\,))) => ()
(split-string-by-predicate "a, b, c" (lambda (ch) (eqv? ch #\,))) => ("a" " b" " c")
(split-string-by-predicate "a , b , c" (lambda (ch) (eqv? ch #\,))) => ("a " " b " " c")
See also Scheme source file split-string-by-predicate

find-in-string
Form (find-in-string str ch [start-pos])
Description Search linearly for the character ch in the string str. An optional start postion start-post tells at which position to start the search (default is position 0). Return the index of the first occurence of ch, or #f if it does not exist in str. The index of the first character in a string is 0. If start-pos is boolean false (#f) this function returns #f.
Parameters str The string in which to search.
ch The character we are searching for.
start-pos The optional start-position of the search. Defaults to 0 (start of string). May also be boolean false.
Examples (find-in-string "some string" #\e) => 3
(find-in-string "some string" #\x) => #f
(find-in-string "" #\x) => #f
(find-in-string "xxxxx" #\x) => 0
(find-in-string "some string" #\s 1) => 5
(find-in-string "some string" #\s #f) => #f
See also Scheme source file find-in-string
more general function find-in-string-by-predicate

find-in-string-from-end
Form (find-in-string-from-end str ch)
Description Search linearly for the character ch in the string str, beginning from the rear end of str. Return the index of the last occurence of ch, or #f if it does not exist in str. The index of the first character in a string is 0.
Parameters str The string in which to search.
ch The character we are searching for.
Examples (find-in-string-from-end "some string" #\e) => 3
(find-in-string-from-end "some string" #\s) => 5
(find-in-string-from-end "xxxxx" #\x) => 4
(find-in-string-from-end "yyyyy" #\x) => #f
(find-in-string-from-end "" #\x) => #f
See also Scheme source file find-in-string-from-end

find-in-string-by-predicate
Form (find-in-string-by-predicate pred str [start-pos])
Description Find the first character in str that satisfies the char-predicate pred, and return index of that char. The search starts at position start-pos. If start-pos is a boolean false, this function always returns boolean false. This is a linear search in the string, corresponding to find-in-list for lists.
Parameters pred A character predicate function
str The string in which to search
start-pos The optional start-position of the search. Defaults to 0 (start of string). May also be boolean false.
Examples (find-in-string-by-predicate (lambda (ch) (memv ch white-space-char-list)) "some string") => 4
(find-in-string-by-predicate (lambda (ch) (memv ch white-space-char-list)) "some string" 5) => #f
(find-in-string-by-predicate (lambda (ch) (memv ch white-space-char-list)) "some string" #f) => #f
See also Scheme source file find-in-string-by-predicate
similar function find-in-list

find-in-string-from-end-by-predicate
Form (find-in-string-from-end-by-predicate pred str [start-pos])
Description Find the last character in str that satisfies the char-predicate pred, and return index of that char. The search starts at position start-pos. If start-pos is a boolean false, this function always returns boolean false. This is a rear end, linear search in the string, corresponding to find-in-list for lists.
Parameters pred A string predicate function
str The string in which to search
start-pos The optional start-position of the search. Defaults to the last position in str (end of string). May also be boolean false.
Examples (find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\B)) "B123AbcA") => 0
(find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\A)) "123AbcA") => 6
(find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\A)) "123Abc") => 3
(find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\A)) "") => #f
(find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\A)) "AAA") => 2
(find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\B)) "AAA") => #f
(find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\c)) "abc" 1) => #f
(find-in-string-from-end-by-predicate (lambda (ch) (eqv? ch #\c)) "abc" 2) => 2
See also Scheme source file find-in-string-from-end-by-predicate
similar function find-in-list-by-predicate

skip-chars-in-string
Form (skip-chars-in-string str char-list start-pos)
Description Starting from start-pos, skip characters in string from char-list. Return the first index higher or equal to start-pos, which contains a character which is NOT in char-list. This may be an index out of bound. If start-pos is higher than the maximum legal string index, return start-post.
Parameters str The string on which this function works
char-list A list of characters
start-pos The position of the first character to consider. The index of the first character is 0.
Returns A string index, possibly out of bound (as described above). An integer.
Examples (skip-chars-in-string "xabcyz" (list #\a #\b #\c ) 0) => 0
(skip-chars-in-string "xabcyz" (list #\a #\b #\c ) 1) => 4
(skip-chars-in-string "xabc" (list #\a #\b #\c ) 5) => 5
(skip-chars-in-string "" (list #\a #\b #\c ) 0) => 0
(skip-chars-in-string "abcde" (list ) 0) => 0
(skip-chars-in-string "abcde" (list ) 3) => 3
See also Scheme source file skip-chars-in-string

string-merge
Form (string-merge str-list-1 str-list-2)
Description Merge str-list-1 with str-list-2, returning one string. Strings from the first list are merged with the strings from the second list. In case one list is shorter than the other, the strings from the longests lists are concatenated and appended
Examples (string-merge (list "aa" "bb" "cc") (list "XX" "YY")) => "aaXXbbYYcc"
(string-merge (list) (list "XX" "YY")) => "XXYY"
(string-merge (list "XX" "YY") (list)) => "XXYY"
(string-merge '() '()) => ""
See also Scheme source file string-merge

transliterate
Form (transliterate in-string ch str)
Description In in-string, substitute each occurence of character ch with the string str. If str is the empty string the character ch is eliminated from in-string.
Parameters in-string A string
ch The character to be translated. A Scheme character
str The string to substitute occurrences of ch
Returns A new string with the desired substitutions
Examples (transliterate "abekat" #\a "xyz") => "xyzbekxyzt"
(transliterate "abekat" #\a "") => "bekt"
(transliterate "xx" #\a "x") => "xx"
(transliterate "x" #\x "xx") => "xx"
(transliterate "xx" #\x "xx") => "xxxx"
(transliterate "xx" #\x "") => ""
See also Scheme source file transliterate
Note This is a pure functions which does not mutate in-string.

filter-string
Form (filter-string pred str)
Description Take away all characters in the string str that satisfy pred. Returns a string shorter than or equal to the length of str. This function is a non-destructive function.
Parameters str The string to be filtered.
pred A character predicate function.
Returns The filtered string. All characters in string, in the same order, that do not satisfy pred.
Examples (filter-string (lambda (ch) (memv ch white-space-char-list)) "a b c d") => "abcd"
(filter-string (lambda (ch) (memv ch white-space-char-list)) (string-append "a b c d" CR "x y")) => "abcdxy"
(filter-string (lambda (ch) (memv ch white-space-char-list)) " ") => ""
(filter-string (lambda (ch) (memv ch white-space-char-list)) "abc") => "abc"
See also Scheme source file filter-string
Note An iterative function programmed with a tail-recursive helping function.

delete-string-portion
Form (delete-string-portion str i lgt)
Description Delete the substring of length lgt from index i in the string str. A non-destructive function which returns the result (a shorter string than the input). i is supposed to be a valid index in str. If lgt is too long for str, we just delete to the end of str. The first character is number 0.
See also Scheme source file delete-string-portion

replace-string
Form (replace-string str1 str2 str3)
Description In str1 replace all occurences of str2 with str3 and return the resulting string. str2 is not allowed to be empty. A non-destructive function which leaves all input strings unaffected.
Examples (replace-string "aabbccddee aabbcc" "aa" "") => "bbccddee bbcc"
(replace-string "aabbccddee aabbcc" "aa" "XX") => "XXbbccddee XXbbcc"
(replace-string "" "aa" "XX") => ""
(replace-string "AaBb" "a" "b") => "AbBb"
See also Scheme source file replace-string

put-around-substring
Form (put-around-substring str pre-index pre-putin post-index post-putin)
Description Put pre-putin at pre-index, and post-putit at post-index in the string str. Return the result. Str is not affected.
Precondition pre-index is less than post-index.
See also Scheme source file put-around-substring

put-into-string
Form (put-into-string str index putin-str)
Description Before the character with index put in putin-str into str, and return the resulting, extended string. I.e, make room in the resulting string for putin-str, and slide a suffix of str to the right. Str is left unchanged. The first character is number 0.
See also Scheme source file put-into-string

embed-substring
Form (embed-substring substring str embed-function)
Description Embed the first occurrence of substring, as found in string, into embed-function. A non-destructive function.
Parameters embed-function a string-returning function of one string parameter.
Returns str with the first occurence of substring is embedded into an call of embed-function.
Examples (embed-substring "LAML" "LAML is programmed in Scheme" downcase-string) => "laml is programmed in Scheme"
(embed-substring "LAML" "LAML is programmed in Scheme. LAML is great." downcase-string) => "laml is programmed in Scheme. LAML is great."
(embed-substring "LAML" "LMAL is spell backward." downcase-string) => "LMAL is spell backward."
See also Scheme source file embed-substring

copy-string-into!
Form (copy-string-into! target i source)
Description Copy source into target and overwrite a portion of target. Both target and source are strings, and i is an integer index. The first char of source becomes character number i in the target string. The first character in a string is number 0. Target is mutated by this procedure. If there is not enough room for source in target, only part of the source is copied into a suffix of target.
See also Scheme source file copy-string-into!

substring-index
Form (substring-index str str-index find-str)
Description Return the index of the first occurence of find-str in str. The search starts at str-index. The first character in str has index 0. If find-str is not a substring of str, starting the search at str-index, #f is returned.
Parameters str The string in which to search for find-str.
str-index The zero-based position in str where the search starts.
find-str The string to search for in str.
Examples (substring-index "abekat" 0 "abe") => 0
(substring-index "abekat" 0 "kat") => 3
(substring-index "abekat" 0 "katten") => #f
(substring-index "abekat" 0 "abekat") => 0
(substring-index "abekat" 1 "abekat") => #f
(substring-index "" 0 "") => 0
See also Scheme source file substring-index

extract-substrings
Form (extract-substrings str start-marker end-marker)
Description Extract substrings from str which are enclosed in start-marker and end-marker (both strings). An extraction does not include the marker strings.
Precondition The start-marker and the end-marker are both non-empty strings.
Parameters str A text string in which to identify substrings.
start-marker The start marker - a non-empty text string
end-marker The end marker - a non-empty text string
Returns The list of extracted substrings.
Examples (extract-substrings "This [[is a]] small [[test]]." "[[" "]]") => ("is a" "test")
(extract-substrings "This [[is a]] small test]]." "[[" "]]") => ("is a")
(extract-substrings "This [[is a]] small [[test." "[[" "]]") => ("is a")
(extract-substrings "This [[is a]] small [[test." "[[(" ")]]") => ()
(extract-substrings "This [[(is a]] small [[test)]] of..." "[[(" ")]]") => ("is a]] small [[test")
(extract-substrings "" "[[(" ")]]") => ()
(extract-substrings "Some string" "[[(" ")]]") => ()
(extract-substrings "Some string with some letters" "e" "e") => (" string with som" "tt")
(extract-substrings "aaaa" "a" "a") => ("" "")
(extract-substrings "abababa" "a" "a") => ("b" "b")
See also Scheme source file extract-substrings

first-sentence-in-string
Form (first-sentence-in-string str)
Description Return the first sentence in str (including a point). The first sentence is running up to the first point followed by space or line termination.
See also Scheme source file first-sentence-in-string

but-first-sentence-of-string
Form (but-first-sentence-of-string str)
Description Return all but the first sentence in str.
See also Scheme source file but-first-sentence-of-string

strip-initial-characters
Form (strip-initial-characters char-list string)
Description Strip initial occurences of chars from char-list from string. Returns the empty string if given the empty string. This function makes intermediate substrings, and as such it is not efficient.
See also Scheme source file strip-initial-characters

strip-trailing-characters
Form (strip-trailing-characters char-list string)
Description Strip trailing occurences of the characters in char-list from string.
See also Scheme source file strip-trailing-characters

strip-initial-spaces
Form (strip-initial-spaces string)
Description Strip all initial space characters and lineshifting characters from string.
See also Scheme source file strip-initial-spaces

string-it
Form (string-it x)
Description Embed the string x in double string quotes
See also Scheme source file string-it

string-it-single
Form (string-it-single x)
Description Embed the string x in single string quotes
See also Scheme source file string-it-single

exchange-chars-in-str!
Form (exchange-chars-in-str! str n m)
Description Exchange destructively char n and m in str. First character is number 0. Not a function, thus no return value.
See also Scheme source file exchange-chars-in-str!

ensure-final-character
Form (ensure-final-character str ch)
Description Ensure that the last character in str (a string) is ch (a char)
See also Scheme source file ensure-final-character

repeat-string
Form (repeat-string str n)
Description Repeat the string str n times. If n equals 0, return the empty string. Causes a fatal error if n is negative.
See also Scheme source file repeat-string

unescape-text
Form (unescape-text text esc-char)
Description Unescape text with the escape character esc-char. A pending escape character in text is just ignored. Unescaping is the process of replacing a two-character text sequence ESC CHAR with CHAR.
Parameters text The input text string
esc-char The escape character. A Scheme char.
Examples ab$c -> abc
$.xy -> .xy
$$xy -> $xy
$$$$x -> $$x
xy$ -> xy
See also Scheme source file unescape-text

rotate-string
Form (rotate-string str n)
Description Rotate the string str n positions. The first character of the resulting string will be (string-ref str n), and so on iteratively and cyclic.
See also Scheme source file rotate-string

string-to-list-of-lines
Form (string-to-list-of-lines str)
Description Return the list of lines of the string str. The lines are rinsed for CR characters (char 13).
Parameters str A string
Returns A list of lines (a list of strings)
See also Scheme source file string-to-list-of-lines

list-of-lines-to-string
Form (list-of-lines-to-string line-lst)
Description Concatenate the lines in the string list line-lst
Parameters line-lst A list of strings.
Returns A string of concatenated lines, separated by LF (char 10).
See also Scheme source file list-of-lines-to-string

pad-string-to-length
Form (pad-string-to-length lgt str [justification pad-char])
Description Pad the string str to a total length. Pad with pad-char justification is either left or right (a symbol), and it defaults to 'left.
See also Scheme source file pad-string-to-length


13 Functions that change letter case in string.
Here comes a number of functions which changes the letter case of a string. In general we recommend use of the non-destructive versions of the functions, thus encouraging a clean, functional programming style. Due a difference between mutable and immutable strings, we have experienced problems with the destructive procedures in MzScheme.

capitalize-string
Form (capitalize-string str)
Description Mutate str to have an initial capital character. A destructive procedure. See capitalize-string-nd for a non-destructive variant.
See also Scheme source file capitalize-string
non-destructive variant capitalize-string-nd

capitalize-string-nd
Form (capitalize-string-nd str)
Description Return str with capital, initial character. A non-destructive variant of capitalize-string.
See also Scheme source file capitalize-string-nd
destructive variant capitalize-string

upcase-string
Form (upcase-string str)
Description Upcase all characters in str. This function is non-destructive, i.e., it does not change the parameter str.
See also Scheme source file upcase-string

downcase-string
Form (downcase-string str)
Description Downcase all characters in str. This function is non-destructive, i.e., it does not change the parameter str.
Examples (embed-substring "LAML" "LAML is programmed in Scheme" downcase-string) => "laml is programmed in Scheme"
(embed-substring "LAML" "LAML is programmed in Scheme. LAML is great." downcase-string) => "laml is programmed in Scheme. LAML is great."
(embed-substring "LAML" "LMAL is spell backward." downcase-string) => "LMAL is spell backward."
See also Scheme source file downcase-string

decapitalize-string
Form (decapitalize-string str)
Description Mutate str to have lower case, initial character. A destructive procedure. See decapitalize-string-nd for a non-destructive variant.
See also Scheme source file decapitalize-string
non-destructive variant decapitalize-string-nd

decapitalize-string-nd
Form (decapitalize-string-nd str)
Description Return str with lower case, initial character. A non-destructive variant of decapitalize-string.
See also Scheme source file decapitalize-string-nd
destructive variant decapitalize-string


14 Byte string functions.
In this section we provide low-level functions that access binary data in strings. This section has been added to LAML version 32.

byte-string-to-integer
Form (byte-string-to-integer byte-str)
Description Given a byte string - most significant byte first (big endian byte order) - return the decimal integer which it represents. The inverse function is int10-to-binary.
Precondition byte-str is not empty
Parameters byte-str A string of bytes.
Returns An integer number
Examples (byte-string-to-integer "\0") => 0
(byte-string-to-integer "1") => 49
(byte-string-to-integer "a") => 97
(byte-string-to-integer "aax") => 6381944
See also Scheme source file byte-string-to-integer
Inverse function int10-to-binary

int10-to-binary
Form (int10-to-binary n number-of-bytes)
Description Convert a decimal integer n to a binary quantity, represented as a string of length number-of-bytes. In the resulting binary string, the most significant byte comes first. This corresponds to big endian byte order. If n is too large to be represented in number-of-bytes, an error occurs. The inverse function is byte-string-to-integer.
Parameters n The integer to convert.
number-of-bytes The desired number of bytes.
Examples (int10-to-binary 6381944 3) => "aax"
(int10-to-binary 97 3) => "\0\0a"
(int10-to-binary 97 1) => "a"
(int10-to-binary 0 1) => "\0"
(int10-to-binary 97 1) => "a"
(int10-to-binary 65535 2) => "\377\377"
(int10-to-binary 65536 2): ERROR
See also Scheme source file int10-to-binary
Inverse function byte-string-to-integer

make-char-2-hex
Form (make-char-2-hex hx1 hx2)
Description Make a character from two hex numbers
Parameters hx1 An decimal integer number between 0 and 15
hx2 An decimal integer number between 0 and 15
Returns A character
Examples (make-char-2-hex 0 0) => #\nul
(make-char-2-hex 6 1) => #\a
(make-char-2-hex 0 0) => #\nul
See also Scheme source file make-char-2-hex
Note The name of this function is slightly misleading. It converts two (2) hex numbers (integer decimals) to a character. The -2- part is NOT an abbreviation of -to-.

make-byte-string-from-hex-2
Form (make-byte-string-from-hex-2 hx1 hx2)
Description Make a string, with single character, from two hex numbers.
Parameters hx1 An decimal integer number between 0 and 15
hx2 An decimal integer number between 0 and 15
Returns A string of length one.
Examples (make-byte-string-from-hex-2 6 1) => "a"
(make-byte-string-from-hex-2 0 0) => "\0"
See also Scheme source file make-byte-string-from-hex-2

make-byte-string-from-hex-4
Form (make-byte-string-from-hex-4 hx1 hx2 hx3 hx4)
Description Make a string, with two characters, from four hex numbers.
Parameters hx1 An decimal integer number between 0 and 15
hx2 An decimal integer number between 0 and 15
hx3 An decimal integer number between 0 and 15
hx4 An decimal integer number between 0 and 15
Returns A string of length two
Examples (make-byte-string-from-hex-4 0 0 0 0) => "\0\0"
(make-byte-string-from-hex-4 6 1 6 2) => "ab"
See also Scheme source file make-byte-string-from-hex-4

make-byte-string-from-hex-6
Form (make-byte-string-from-hex-6 hx1 hx2 hx3 hx4 hx5 hx6)
Description Make a string, with three characters, from two six numbers.
Parameters hx1 An decimal integer number between 0 and 15
hx2 An decimal integer number between 0 and 15
hx3 An decimal integer number between 0 and 15
hx4 An decimal integer number between 0 and 15
hx5 An decimal integer number between 0 and 15
hx6 An decimal integer number between 0 and 15
Returns A string of length three
Examples (make-byte-string-from-hex-6 6 1 6 2 6 3) => "abc"
See also Scheme source file make-byte-string-from-hex-6

make-byte-string-from-hex-8
Form (make-byte-string-from-hex-8 hx1 hx2 hx3 hx4 hx5 hx6 hx7 hx8)
Description Make a string, with four characters, from eight hex numbers.
Parameters hx1 An decimal integer number between 0 and 15
hx2 An decimal integer number between 0 and 15
hx3 An decimal integer number between 0 and 15
hx4 An decimal integer number between 0 and 15
hx5 An decimal integer number between 0 and 15
hx6 An decimal integer number between 0 and 15
hx7 An decimal integer number between 0 and 15
hx8 An decimal integer number between 0 and 15
Returns A string of length four.
Examples (make-byte-string-from-hex-8 6 1 6 2 6 3 6 4) => "abcd"
See also Scheme source file make-byte-string-from-hex-8

binary-to-hex-string
Form (binary-to-hex-string byte-string)
Description Given byte-string, which is binary data. Return a non-binary string, of hex codes, space separated (for human readbility). Each byte gives rise to two hex codes. The inverse function of hex-to-binary-string.
Parameters byte-string A string of bytes (binary data).
Returns An ASCII text string with grouped, human readable hexadecimal ciffers.
Examples (binary-to-hex-string (make-byte-string-from-hex-8 6 1 6 2 6 3 6 4)) => "61 62 63 64"
(binary-to-hex-string "") => ""
See also Scheme source file binary-to-hex-string

hex-to-binary-string-relaxed
Form (hex-to-binary-string-relaxed hex-string)
Description Given a human readable hex string, as produced by the sibling function called binary-to-hex-string. Groups of two hex ciffers must be separated by one or more spaces or CRs. Return the corresponding binary string. The inverse function of binary-to-hex-string.
Parameters byte-string A string of bytes (binary data).
Returns An ASCII text string with grouped, human readable hexadecimal ciffers.
Examples (hex-to-binary-string-relaxed (string-append "61 62" CR "63 64")) => "abcd"
See also Scheme source file hex-to-binary-string-relaxed

hex-to-binary-string
Form (hex-to-binary-string hex-string)
Description Given a human readable hex string, as produced by the sibling function called binary-to-hex-string. Groups of two hex ciffers must be separated by exactly one space. Return the corresponding binary string. The inverse function of binary-to-hex-string. This function is like hex-to-binary-string relaxed, but with a stronger precondition.
Parameters byte-string A string of bytes (binary data).
Returns An ASCII text string with grouped, human readable hexadecimal ciffers.
Examples (hex-to-binary-string "00 01") => "\0\1"
(hex-to-binary-string "61 62 63 64") => "abcd"
See also Scheme source file hex-to-binary-string

as-two-complement-signed-number
Form (as-two-complement-signed-number i n)
Description Re-interpret the positive integer i as an n bit two's complement number.
Precondition 0 <= i < (power 2 n)
Parameters i The positive number to convert.
n The number of bits involved.
Examples (as-two-complement-signed-number 0 8) => 0
(as-two-complement-signed-number 127 8) => 127
(as-two-complement-signed-number 128 8) => -128
(as-two-complement-signed-number 255 8) => -1
(as-two-complement-signed-number 256 8): ERROR
See also Scheme source file as-two-complement-signed-number

byte-string-to-bit-list
Form (byte-string-to-bit-list byte-str [number-of-bits])
Description Return the list of bits in byte-str with at least number-of-bits bits. If less than number-of-bits is delivered, patch the list with leading zeros to a total length of number-of-bits.
Parameters byte-str A string of bytes.
number-of-bits The minimum number of bits to be delivered by this function. Defaults to 8.
Returns A list of zeros and ones.
Examples (byte-string-to-bit-list "a") => (0 1 1 0 0 0 0 1)
(byte-string-to-bit-list "a" 16) => (0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 1)
(byte-string-to-bit-list "aaa" 8) => (1 1 0 0 0 0 1 0 1 1 0 0 0 0 1 0 1 1 0 0 0 0 1)
(byte-string-to-bit-list "aaa" 24) => (0 1 1 0 0 0 0 1 0 1 1 0 0 0 0 1 0 1 1 0 0 0 0 1)
(bit-list-to-byte-string (byte-string-to-bit-list "abcdef" (* 6 8))) => "abcdef"
See also Scheme source file byte-string-to-bit-list

bit-list-to-byte-string
Form (bit-list-to-byte-string bit-list)
Description Return a byte string with the bit from bit-list (a list of integer zeros and ones). Assume, as a precondition, that the length of bit-list is a multiplum of 8.
Parameters bit-list A list of zeros or ones.
Returns A string of bytes (a text string in the sense of ASCII text).
Examples (bit-list-to-byte-string '(0 1 1 0 0 0 0 1)) => "a"
(bit-list-to-byte-string '()) => ""
(bit-list-to-byte-string (byte-string-to-bit-list "abcdef" (* 6 8))) => "abcdef"
See also Scheme source file bit-list-to-byte-string


15 Message displaying and error handling procedures.
Most message or error functions accept a list of messages which are string-converted and space separated before outputted.

display-warning
Form (display-warning . messages)
Description Display a warning message line on standard output via the Scheme display function. This is not a fatal error
See also Scheme source file display-warning

display-error
Form (display-error . messages)
Description Display an error message - in terms of messages - and stop the program. This is a fatal event.
See also Scheme source file display-error

display-message
Form (display-message . messages)
Description Display messages on standard output. Not a warning, and not fatal by any means.
See also Scheme source file display-message

laml-error
Form (laml-error . messages)
Description Stop the program with messages. This procedures takes an arbitrary number of parameters, which are string converted and string-appended to the final error message.
See also Scheme source file laml-error

errors-among-conditions
Form (errors-among-conditions . err-condition-message-list)
Description Return a list of error message strings for those conditions err-condition-message-list that are true. The function returns #f in case all error conditions are false. err-condition-message-list is a property list (of even length) of error-condition error message pairs. For each condition and message, this function checks the condition and returns the error message if the condition fails.
Parameters err-condition-message-list a property list of the form cond-1 mes-1 ... cond-n mes-n.
Returns A non-empty error message string, or #f.
See also Scheme source file errors-among-conditions


16 File name, file path and URL functions.
File paths are represented as strings in LAML. As a convention, a non-empty relative file path always ends in a forward slash '/'. The empty string represents the empty relative file path. An absolute file path is recognized in both unix form (for instance "/x/y/") and Windows form (for instance "c:\x\"). Internally in LAML, we work with unix representation of file paths (using forward slashes).

file-name-sans-extension
Form (file-name-sans-extension file-name)
Description Return the filename component sans the final extension. The extension, in a file name, is the part that follows the last `.'. If no dot character is found the function returns file-name.
Examples (file-name-sans-extension "abc.def") => "abc"
(file-name-sans-extension "abc") => "abc"
(file-name-sans-extension "xxx/yyy/abc.def") => "xxx/yyy/abc"
(file-name-sans-extension "abc.def.ghi") => "abc.def"
See also Scheme source file file-name-sans-extension
Note This function does not work well if we use '.' as part of directory names.

file-name-proper
Form (file-name-proper file-name)
Description Return the part of file-name without extension and without an initial path. Is also applicable on relative/absolute file path, and on URLs. Works as expected even there are dots in the initial path.
Examples (file-name-proper "x/y/a.b") => "a"
(file-name-proper "/x/y/a.b") => "a"
(file-name-proper "a.b") => "a"
(file-name-proper "a") => "a"
(file-name-proper "http://a/b/c.d") => "c"
(file-name-proper "x.y.z.w") => "x.y.z"
(file-name-proper "/xxx/yyy.zzz/x.y.z.w") => "x.y.z"
See also Scheme source file file-name-proper

file-name-proper-and-extension
Form (file-name-proper-and-extension file-path)
Description Return the part of file-name, with a possible extension, but without an initial path. Is also applicable on relative/absolute file path, and on URLs.
Examples (file-name-proper-and-extension "x/y/z.w") => "z.w"
(file-name-proper-and-extension "x/y/z") => "z"
(file-name-proper-and-extension "/x/y/z.w") => "z.w"
(file-name-proper-and-extension "z") => "z"
(file-name-proper-and-extension "z.w") => "z.w"
(file-name-proper-and-extension "") => ""
See also Scheme source file file-name-proper-and-extension

file-name-extension
Form (file-name-extension file-name)
Description Return the extension of file-name. Is also applicable on relative/absolute file path, and on URLs. If there is no extension, return the empty string. The extension, in a file name, is the part that follows the last `.'. This function handles dots in the initial path properly.
Examples (file-name-extension "a.b") => "b"
(file-name-extension "a.b.c") => "c"
(file-name-extension "a") => ""
(file-name-extension "x/y/a.b") => "b"
(file-name-extension "/x/y/a.b") => "b"
(file-name-extension "/x/y/a") => ""
(file-name-extension "x/y/a") => ""
See also Scheme source file file-name-extension

file-name-initial-path
Form (file-name-initial-path file-path)
Description Return the initial path of file-path. The initial path of a file path is the prefix of the file path, without the proper file name and without the extension. The initial path ends in a forward or backward slash, or it is empty. Can also be applied on both absolute and relative file paths, and on absolute and relative URLs.
Examples (file-name-initial-path "x/y/a") => "x/y/"
(file-name-initial-path "/x/y/a") => "/x/y/"
(file-name-initial-path "a.b") => ""
(file-name-initial-path "a") => ""
(file-name-initial-path "http://a/b/c.d") => "http://a/b/"
See also Scheme source file file-name-initial-path

absolute-file-path?
Form (absolute-file-path? x)
Description Return whether x represents an absolute path to a file. Works on both Unix and Windows.
Parameters x A file path (a string)
Examples (absolute-file-path? "/x/y/z.w") => #t
(absolute-file-path? "x/y/z.w") => #f
(absolute-file-path? "x") => #f
(absolute-file-path? "/x") => #t
(absolute-file-path? "c:/x/y") => #t
(absolute-file-path? "z:/x/y") => #t
(absolute-file-path? "z:x/y") => #f
See also Scheme source file absolute-file-path?

absolute-url?
Form (absolute-url? x)
Description Does the string x represent an absolute URL.
See also Scheme source file absolute-url?

relative-url?
Form (relative-url? x)
Description Does the string x represen a relative URL.
See also Scheme source file relative-url?
Note Experimental definition.

parent-directory
Form (parent-directory dir)
Description Return the name of the parent directory of dir (a string), or #f if dir is the root directory. Also return #f in case dir is the value #f.
Examples (parent-directory "/x/y/z/") => "/x/y/"
(parent-directory "x/y/z/") => "x/y/"
(parent-directory "x/") => #f
(parent-directory "") => #f
(parent-directory #f) => #f
See also Scheme source file parent-directory

directory-leave-name
Form (directory-leave-name dir)
Description Return the name of the leave directory of the directory dir. In case dir is the absolute root, the value #f, or the empty directory string, this function returns #f.
Parameters dir A relative or absolute directory path (ends with '/').
Examples (directory-leave-name "xxx/yyy/") => "yyy"
(directory-leave-name #f) => #f
See also Scheme source file directory-leave-name

directory-level-difference
Form (directory-level-difference dir1 dir2)
Description Return the number of directory levels in between dir1 and dir2. If dir1 is not a subdirectory of dir2, or dir2 is not a subdirectory of dir1 return #f.
Examples (directory-level-difference "/x/x/z/v/" "/x/x/") = 2
(directory-level-difference "/x/x/" "/x/x/z/v/") = -2
See also Scheme source file directory-level-difference

relative-path-to-path-list
Form (relative-path-to-path-list dir)
Description Given a relative file path, return a list of path constituents. This function supports both forward and backward slashes as separator between directory levels (both unix and windows conventions).
Precondition dir is not an absolute file path.
Examples (relative-path-to-path-list "xxx/yyy/zzz/") = ("xxx" "yyy" "zzz")
(relative-path-to-path-list "xxx/yyy/zzz") = ("xxx" "yyy" "zzz")
(relative-path-to-path-list "xxx") = ("xxx")
See also Scheme source file relative-path-to-path-list

path-list-to-relative-path
Form (path-list-to-relative-path path-list)
Description Return the relative path formed by the element of path-list. The reverse function of relative-path-to-path-list.
Examples (path-list-to-relative-path (list "x" "y" "z")) => "x/y/z/"
(path-list-to-relative-path (list "x")) => "x/"
See also Scheme source file path-list-to-relative-path

ensure-directory-existence!
Form (ensure-directory-existence! prefix-dir dir)
Description Ensure that the directory with path (string-append prefix-dir dir) exists. If necessary, create dir in prefix-dir.
Precondition prefix-dir should be normalized (using for instance normalize-file-path) before calling this function.
Parameters prefix-dir An absolute directory path.
dir A single directory name
See also Scheme source file ensure-directory-existence!

ensure-directory-path-existence!
Form (ensure-directory-path-existence! prefix-dir path)
Description Ensure that the relative path, as represented by the parameter path, exists in prefix-dir. This procedure creates the necessary directories in prefix-dir.
Precondition Both prefix-dir and path should be normalized (using for instance normalize-file-path) before calling this function.
Parameters prefix-dir An absolute directory path.
path A relative file path.
See also Scheme source file ensure-directory-path-existence!

ensure-non-existing-file-in-dir
Form (ensure-non-existing-file-in-dir f d)
Description Ensure that the file f (proper name and extension) is non-existing in the directory d. If not, add a numeric suffix to the proper name of f. Return the possibly modified file name (proper name and extension).
See also Scheme source file ensure-non-existing-file-in-dir

normalize-file-path
Form (normalize-file-path path)
Description Normalizes the abolute or relative file path by removal of redundant ".." levels.
Parameters path An absolute or relative file path.
Returns A normalized absolute or relative file path. Always slash terminated.
Examples (normalize-file-path "xxx/yyy/../zzz") => "xxx/zzz/"
(normalize-file-path "xxx/yyy/..") => "xxx/"
(normalize-file-path "/.."): ERROR
(normalize-file-path "xxx/yyy/zzz") => "xxx/yyy/zzz/"
(normalize-file-path "/xxx/yyy/..") => "/xxx/"
See also Scheme source file normalize-file-path

normalize-relative-file-path
Form (normalize-relative-file-path path)
Description Normalizes the relative file path for redundant ".." levels. Does always return a forward slash terminated relative path, or and empty path (the emtpy string). Does never lead to a fatal error.
Parameters path A relative file path. May be empty (the empty string).
Returns The normalized relative path (a string).
Examples (normalize-relative-file-path "xxx/yyy/../") => "xxx/"
(normalize-relative-file-path "xxx/yyy/../../") => ""
(normalize-relative-file-path "xxx/yyy/../../..") => "../"
(normalize-relative-file-path "") => ""
(normalize-relative-file-path "xxx") => "xxx/"
See also Scheme source file normalize-relative-file-path

normalize-absolute-file-path
Form (normalize-absolute-file-path abs-path)
Description Normalizes the absolute file path for redundant ".." levels. May result in a fatal error in cases where we try to exit through the root level via "..". Returns a forward slash terminated absolute path.
Precondition path is an absolute file path.
Parameters path An absoulte file path.
Returns The normalized absolute path (a string).
Examples (normalize-absolute-file-path "xxx/yyy/.."): ERROR
(normalize-absolute-file-path "/xxx/yyy/..") => "/xxx/"
(normalize-absolute-file-path "/xxx/yyy/../../") => "/"
(normalize-absolute-file-path "/xxx/yyy/../..") => "/"
(normalize-absolute-file-path "/xxx/yyy/../../.."): ERROR
See also Scheme source file normalize-absolute-file-path

relative-part-of-absolute-path
Form (relative-part-of-absolute-path abs-path)
Description Return the suffix part of the absolute file path (the part following the initial "/" for instance).
Precondition abs-path is an absolute file path.
Examples (relative-part-of-absolute-path "/xxx/yyy/") => "xxx/yyy/"
(relative-part-of-absolute-path "c:/xxx/yyy/") => "xxx/yyy/"
(relative-part-of-absolute-path "/x") => "x"
(relative-part-of-absolute-path "xxx"): ERROR
(relative-part-of-absolute-path ""): ERROR
See also Scheme source file relative-part-of-absolute-path

prefix-part-of-absolute-path
Form (prefix-part-of-absolute-path abs-path)
Description Return the prefix part of the absolute file path (the "/" or the "c:\" for instance).
Precondition abs-path is an absolute file path.
Examples (prefix-part-of-absolute-path "/xxx/yyy") => "/"
(prefix-part-of-absolute-path "c:/x") => "c:/"
(prefix-part-of-absolute-path ""): ERROR
(prefix-part-of-absolute-path "c:/x") => "c:/"
(prefix-part-of-absolute-path "/") => "/"
See also Scheme source file prefix-part-of-absolute-path

but-prefix-part-of-absolute-path
Form (but-prefix-part-of-absolute-path abs-path)
Description Return the complementary part of the absolute file path relative to (prefix-part-of-absolute-path abs-path). Notice that (string-append (prefix-part-of-absolute-path abs-path) (but-prefix-part-of-absolute-path abs-path)) equals abs-path.
Precondition abs-path is an absolute file path.
Returns The largest possible relative file path taken from abs-path.
Examples (but-prefix-part-of-absolute-path "c:\\xx/yy") => "xx/yy"
(but-prefix-part-of-absolute-path "/x/y") => "x/y"
(but-prefix-part-of-absolute-path "/xxx/yyy") => "xxx/yyy"
(but-prefix-part-of-absolute-path "/x") => "x"
(but-prefix-part-of-absolute-path "xxx"): ERROR
See also Scheme source file but-prefix-part-of-absolute-path

inverse-return-path
Form (inverse-return-path path dir)
Description Return the inverse file path of path, as taken relative to dir. Given dir as the current directory. If we follow path, and then follow the inverse return path (the result of this function) we are back in dir.
Parameters path A relative file path from dir
dir A directory, identified by an absolute file path
Returns A relative file path.
Examples (inverse-return-path "d" "a/b/c") => "../"
(inverse-return-path ".." "a/b/c") => "c/"
(inverse-return-path "d/e/f/" "a/b/c") => "../../../"
(inverse-return-path "../../../" "a/b/c") => "a/b/c/"
See also Scheme source file inverse-return-path


17 Other functions.
Here follows a set of miscellaneous functions.

type-of
Form (type-of x)
Description Return the type of the value x.
Parameters x An arbitrary value of either type boolean, symbol, char, procedure, pair, number, string or port.
Returns One of boolean, symbol, char, procedure, pair, number, string, port (a symbol).
See also Scheme source file type-of

re-break
Form (re-break str)
Description A quite special HTML line breaking function. Html format str, either with br og p tags between lines. depends on break-at-all from decoding stuff. Should perhaps be in the convenience library???
See also Scheme source file re-break

CR
Form CR
Description Return a CR string
Examples (hex-to-binary-string-relaxed (string-append "61 62" CR "63 64")) => "abcd"
(filter-string (lambda (ch) (memv ch white-space-char-list)) (string-append "a b c d" CR "x y")) => "abcdxy"
See also Scheme source file CR

newline-string
Form (newline-string)
Description Return a CR string. Please notice that there is a conflict between this function and the MzScheme url.ss net stuff. (We should get rid of this function in LAML).
See also Scheme source file newline-string

save-a-list
Form (save-a-list alist filename)
Description Save the alist on a file named filename. Filename is assumed to be a full path to the file.
See also Scheme source file save-a-list

unique-timed-file-name
Form (unique-timed-file-name prefix)
Description Return a unique file name with prefix. The suffic becomes the current-time i seconds representation
See also Scheme source file unique-timed-file-name

file-append
Form (file-append file-name x)
Description Append x to file-name. The file is assumed to contain a Lisp list. x is added (actually pre-pended) to the list on the file, and the file is written back. The ordering of the elements in the file list is not assumed to be important. As a precondition, the file named file-name is assumed to exists.
See also Scheme source file file-append

file-read
Form (file-read file-name [n])
Description Read a Lisp expression from a file named file-name. With an optional second parameter, read form number n from the file. Per default, n is 1.
Precondition Assume that there are at least n forms on file.
Parameters file-name The name of file to read from.
n Skip n-1 expressions and read expression number n. Defaults to 1.
See also Scheme source file file-read

file-read-all
Form (file-read-all file-name)
Description Read all Lisp expression from file-name. This function returns these forms as a list of top level forms from the file.
See also Scheme source file file-read-all

file-write
Form (file-write x file-name)
Description Write the list expression x to the file named file-name. The writing is done using the Scheme write function.
Parameters x An arbitrary value that can be written with write.
filename The name of the file (a string).
See also Scheme source file file-write

save-on-file
Form (save-on-file x filename)
Description Displays the first parameter x on a file named filename. This is a minor convenience function, and an alternative to using the standard Scheme output functions.
Parameters x The string to be written.
filename The name of the file (a string).
See also Scheme source file save-on-file

id-1
Form (id-1 x)
Description The identify function of one parameter
Examples (sort-list (list 3 3 5 5 7 7) (generate-leq (list 5 3 7) id-1 =)) => (5 5 3 3 7 7)
(element-before 4 '(1 2 3 4 5) id-1) => 3
(element-before 1 '(1 2 3 4 5) id-1) => #f
(element-before 6 '(1 2 3 4 5) id-1) => #f
(element-before 5 '(1 2 3 4 5) id-1 =) => 4
(element-after 5 '(1 2 3 4 5) id-1 =) => #f
(element-after 3 '(1 2 3 4 5) id-1 =) => 4
See also Scheme source file id-1

multiplum-of
Form (multiplum-of a b)
Description Is a (the first par) a multiplum of b (the last par)?
See also Scheme source file multiplum-of

copy-text-file
Form (copy-text-file from-path to-path overwrite?)
Description Copy the text file in from-path to the file in to-path. A quick and dirty solution by reading and writing strings to and from files. If the destination file exists you must pass a third parameter, overwrite, with the value #t
See also Scheme source file copy-text-file

copy-files
Form (copy-files files source-dir target-dir [warn-if-non-existing-source])
Description Copy each of the files in the list files from source-dir to target-dir. Both source-dir and target-dir ends in a slash. If the optional boolean parameter warn-if-non-existing-source is #t a non-fatal warning is issued if the source file does not exist. If the boolean parameter is #f, a fatal error will occur.
Parameters files A list of file names (without initial path).
source-dir The source directory in which the files are supposed to exist.
target-dir An existing directory to which the files are copied.
warn-if-non-existing-source A boolean parameter that controls the error reaction. Defaults to #f.
See also Scheme source file copy-files

min-max-limited
Form (min-max-limited x min max)
Description Ensure that the number x is in between min and max, or that min or max is returned. More specifically, if x is not between min and max, the closest of min and max is returned.
Precondition min <= max
See also Scheme source file min-max-limited

log2
Form (log2 x)
Description The base 2 logarithm function.
See also Scheme source file log2

power
Form (power n m)
Description Return n * n * ... n (m times). A quick and dirty recursive version.
See also Scheme source file power

fac
Form (fac n)
Description Return the factorial of n: n * (n-1) * ... 1. A quick and dirty recursive version.
Examples (fac 5) => 120
(fac 0) => 1
(fac 1) => 1
(fac 3) => 6
See also Scheme source file fac


18 Bite Generators.
This section contains higher-order bite generators, which can be used with the functions map-bites, filter-bites, and similar higher-order bite-processing functions, see here . In this context a bite of a non-empty list is a non-empty prefix of the list. Consequtive bites of a list must append-accumulate to the original list. The first parameter of bite functions is the list from which a bite is taken. A second optional parameter denotes the number of this bite (one-based) as supplied by the computational context. Because of this second parameter, all bite functions (programmed or generated) should accept a second parameter, or a rest parameter: (lambda (lst . rest) ....)

bite-of-length
Form (bite-of-length n [noise-element?])
Description Generate and return a function: List -> List, which returns a bite of length n. If the input list is of length shorter than n, just return the list.
Parameters n A integer, n >= 1.
noise-element? An optional predicate with the signature T -> Boolean. Elements that fulfill the predicate are not counted. Such elements are just passed to the resulting bite. The default value of this predicate is (lambda (e) #f).
Returns A bite function of the signature List, int -> List. The integer parameter denotes the number of the bite (supplied by context).
Examples ((bite-of-length 3) '(1 2 3 4 5)) => (1 2 3)
((bite-of-length 3) '(1 2)) => (1 2)
((bite-of-length 3) '()) => ()
((bite-of-length 3 number?) '(a b 1 c 2 3 d e f)) => (a b 1 c)
((bite-of-length 3 number?) ' (1 0 -5 c 2 3 d e f g)) => (1 0 -5 c 2 3 d e)
See also Scheme source file bite-of-length

bite-of-varied-length
Form (bite-of-varied-length f [noise-element?])
Description Generate and return a function: List Int -> List, which returns a bite of length f(n), where n is the bite number (1 based) passed as the second parameter to the generated function. If the input list is of length shorter than f(n) for some n, just return the list.
Parameters f A function of the bite number to the length of the desired bite.
noise-element? An optional predicate with the signature T -> Boolean. Elements that fulfill the predicate are not counted. Such elements are just passed to the resulting bite. The default value of this predicate is (lambda (e) #f).
Returns A bite function of the signature List, int -> List. The integer parameter denotes the number of the bite (supplied by context when applied by functions such as map-bites and filter-bites).
Examples (map-bites (bite-of-varied-length (lambda (n) n)) list '(1 2 3 4 5 6 7 8)) => ((1) (2 3) (4 5 6) (7 8))
(map-bites (bite-of-varied-length (lambda (n) (if (even? n) 2 4))) list '(1 2 3 4 5 6 7 8 9 10 11 12)) => ((1 2 3 4) (5 6) (7 8 9 10) (11 12))
((bite-of-varied-length (lambda (n) (+ n 1))) '(1 2 3 4 5) 2) => (1 2 3)
((bite-of-varied-length (lambda (n) (+ n 1))) '() 1) => ()
(map-bites (bite-of-varied-length (lambda (n) (if (even? n) 3 4))) list (number-interval 1 20)) => ((1 2 3 4) (5 6 7) (8 9 10 11) (12 13 14) (15 16 17 18) (19 20))
See also Scheme source file bite-of-varied-length

bite-while-element
Form (bite-while-element el-pred . attributes)
Description Generate and return a function: List -> List, which returns the longest prefix bite in which each element, appart from sentinel elements, fulfills the prediciate el-pred. The construction of the bite terminates if/when a sentinel element is encountered, which does not satisfy el-pred. Due to the definition of bites, the sentinel elements must (in one way or another) be part of the bites of list. The attribute named sentinel controls the location of sentinel elements relative to non-sentinel elements.
Parameters el-pred: A list element predicate. Signature: List-element -> Boolean.
Attributes
Required: *
sentinel Controls how/if a sentiel element takes part in the contextually formed bites. Possible sentinel-values are first, last, and alone (a string or symbol). Default value: last. The value last prescribes that a bite is terminated by a single sentinel value. The value first prescribes that a bite is starts with a single sentinel value. The value alone prescribes that a single sentinel value forms a bite by itself.
Returns A function of the signature: List -> List, which returns a bit of the input list.
Examples ((bite-while-element number?) '(a b c)) => (a)
((bite-while-element number?) '(1 2 a b c)) => (1 2 a)
((bite-while-element number? 'sentinel "last") '(1 2 a b c)) => (1 2 a)
((bite-while-element number? 'sentinel "first") '(a 1 2 a b c)) => (a 1 2)
((bite-while-element number?) '()) => ()
((bite-while-element number?) '(1 2)) => (1 2)
((bite-while-element number? 'sentinel "alone") '(1 2 a b c)) => (1 2)
((bite-while-element number? 'sentinel "alone") '(a 1 2 b c)) => (a)
See also Scheme source file bite-while-element
Useful in context of map-bites filter-bites

bite-while-element-with-accumulation
Form (bite-while-element-with-accumulation pred accumulator init-acc-val [noise-element?])
Description Generate and return a function: List -> List, which returns the longest prefix bite in which each element, appart from a sentinel element, fulfills the prediciate pred. The predicate pred depends on a single list element together with a value accumulated from all elements prior to (but not including) the current element. A sentinel element is an element which terminates a bites. In functions generated by bite-while-element-with-accumulation, a sentinel element may start a bite (thus this function always 'eats' the first element, without passing it to pred). Elements which fulfill the optional noise-element predicate are not tested by pred, they are not considered as sentinel elements, and they are not accumulated.
Parameters pred A predicate with the signature: T, S -> Boolean. The first parameter is a list element. The second parameter is the accumulated value.
accumulator A function of signature S, T -> S, where S is the type of init-acc-val, and T is the type of list elements in bites.
init-acc-val The initial value (first parameter, of type S) of the accumulated value.
noise-element? An optional predicate with the signature T -> Boolean. Elements that fulfill the predicate are not accumulated. Such elements are just passed to the resulting bite. The default value of this predicate is (lambda (e) #f).
Examples ((bite-while-element-with-accumulation (lambda (e v) (and (number? e) (<= v 5))) (lambda (v e) (+ v e)) 0) '()) => ()
((bite-while-element-with-accumulation (lambda (e v) (and (number? e) (<= v 5))) (lambda (v e) (+ v e)) 0) '(0 1 2 -3 3 4 4 2 2)) => (0 1 2 -3 3 4)
((bite-while-element-with-accumulation (lambda (e v) (and (number? e) (<= v 5))) (lambda (v e) (+ v e)) 0 symbol?) '(a 0 b 1 c d 2 -3 e f g 3 4 4 2 2)) => (a 0 b 1 c d 2 -3 e f g 3 4)
((bite-while-element-with-accumulation (lambda (e v) (and (number? e) (<= v 5))) (lambda (v e) (+ v e)) 0 symbol?) '(a 0 b 2 4 d e 5)) => (a 0 b 2 4 d e)
See also Scheme source file bite-while-element-with-accumulation

bite-while-prefix
Form (bite-while-prefix bite-pred)
Description Generate and return a function: List -> List, which returns the longest bite of the input list, of which each prefix bite satisfies bite-pred. A prefix bite of length one is automatically accepted (bite-pred is not applied on it). This ensures that no empty bite is encountered.
Parameters bite-pred A predicate on List-T, where T is the type of elements in the list. Signature T-List -> Boolean.
See also Scheme source file bite-while-prefix
Note The automatic acceptance of unity bites naturally goes hand in hand with bite predicates that accept such bites. This function does not accept a noise element predicate, because it is more natural (and more efficient) to incorporate it in the bite predicate.

bite-while-accumulate
Form (bite-while-accumulate bin-op init-val pred [noise-element?])
Description Generate and return a function, which returns the shortest (first) non-empty prefix bite that accumulates to a value which fulfills the predicate pred. The last bite of a list is not required to accumulate to a result which fulfills the predicate. The accumulation is carried out by the function bin-op, which initially is applied on init-val and the first element of the list.
Parameters bin-op. A binary accumulator function of signature S x T -> S, where T is the type of the list elements, and S is the type of init-val.
init-val The initial value (of type S).
pred A predicate of signature: S -> Boolean, where S is the type of init-val. The predicate determines if a bite, as accumulated to some value in type S, is satisfactory.
noise-element? An optional predicate with the signature T -> Boolean. Elements that fulfill the predicate are not accumulated. Such elements are just passed to the resulting bite. The default value of this predicate is (lambda (e) #f).
Returns A bite function of the signature: T-List -> T-List.
Examples ((bite-while-accumulate + 0 (lambda (n) (>= n 5))) '(1 1 1 2 3 4 5 6)) => (1 1 1 2)
((bite-while-accumulate + 0 (lambda (n) (>= n 5))) '(1 1 1 1)) => (1 1 1 1)
((bite-while-accumulate + 0 (lambda (n) (>= n 5))) '(6 1 2)) => (6)
((bite-while-accumulate + 0 (lambda (n) (>= n 5))) '()) => ()
((bite-while-accumulate (lambda (x y) (cons y x)) '() (lambda (lst) (= 3 (length lst)))) '(a b c d e f g h)) => (a b c)
((bite-while-accumulate + 0 (lambda (n) (>= n 5)) symbol?) '(a b c 1 2 3 4 5)) => (a b c 1 2 3)
((bite-while-accumulate + 0 (lambda (n) (>= n 5)) symbol?) '(1 a 2 b 3 c 4 d 5)) => (1 a 2 b 3)
((bite-while-accumulate + 0 (lambda (n) (>= n 5)) symbol?) '(a b c)) => (a b c)
See also Scheme source file bite-while-accumulate
Useful in context of map-bites filter-bites
Note This function passes the accumulated value to the predicate. In contrast, bite-while-element-with-accumulation passes both the acculated value and the current list element to its predicate.

bite-while-compare
Form (bite-while-compare el-relation [noise-element?])
Description Generate and return a function, which - when applied on a list - returns the longest bite of the list in which successive elements fulfill the binary relation el-relation.
Parameters el-relation A function of the signature T x T -> Boolean, which compares two elements from the list. T is the type of non-noise (only!) elements in the list on which the generated function is to be applied.
noise-element? An optional predicate with the signature T -> Boolean. Elements that fulfill the predicate are not subject to comparison. Such elements are just passed to the resulting bite. The default value of this predicate is (lambda (e) #f).
Returns A bite function of the signature: T-List -> T-List.
Examples ((bite-while-compare <=) '(2 4 6 6 7 1 2)) => (2 4 6 6 7)
((bite-while-compare <=) '(2 4 6 6 7)) => (2 4 6 6 7)
((bite-while-compare <=) '(3 2 1)) => (3)
((bite-while-compare <=) '()) => ()
((bite-while-compare < symbol?) '(a 0 b c 1 d 2 -1 e f g 7 2 3)) => (a 0 b c 1 d 2)
See also Scheme source file bite-while-compare

bite-while-monotone
Form (bite-while-monotone el-comparator [noise-element?])
Description Generate and return a function, which - when applied on a list - returns the longest bite of the list in which successive elements are monotone measured by the el-comparator function. Being monotone (in the context of this function) means to be either increasing, being decreasing, or being constant. Please notice that no fixed alternation between bites (such as increasing, decreasing, increasing, decreasing, ...) is assured by this function. When applied on a list of at least two element, a function generated by bite-while-monotone will never return a bite of length less than two.
Parameters el-comparator A function of the signature T x T -> Int which compares two elements from the list. T is the type of non-noise (only!) elements in the list on which the generated function is to be applied. (el-comparator x y) returns -1 if x is less than y, 0 if x equals y, and 1 if x is greater than y.
noise-element? An optional predicate with the signature T -> Boolean. Elements that fulfill the predicate are not subject to comparison. Such elements are just passed to the resulting bite. The default value of this predicate is (lambda (e) #f).
Returns A bite function of the signature: T-List -> T-List.
Examples ((bite-while-monotone (make-comparator < >)) '()) => ()
((bite-while-monotone (make-comparator < >)) '(1)) => (1)
((bite-while-monotone (make-comparator < >)) '(1 2)) => (1 2)
((bite-while-monotone (make-comparator < >)) '(1 2 1)) => (1 2)
((bite-while-monotone (make-comparator < >)) '(2 1 2 1)) => (2 1)
((bite-while-monotone (make-comparator < >)) '(1 2 3 4 5 1 2)) => (1 2 3 4 5)
((bite-while-monotone (make-comparator < >)) '(5 4 3 2 1 1)) => (5 4 3 2 1)
((bite-while-monotone (make-comparator < >)) '(1 1 1 2 3)) => (1 1 1)
((bite-while-monotone (make-comparator < >) symbol?) '(a)) => (a)
((bite-while-monotone (make-comparator < >) symbol?) '(a b)) => (a b)
((bite-while-monotone (make-comparator < >) symbol?) '(a 1 b c 2 1 d 1)) => (a 1 b c 2)
(map-bites (bite-while-monotone (make-comparator < >)) list '(1 2 1 2 1 2 3 4)) => ((1 2) (1 2) (1 2 3 4))
See also Scheme source file bite-while-monotone
comparator generation make-comparator

Generated: Monday, November 14, 2011, 09:17:30
Generated by LAML SchemeDoc using LAML Version 38.0 (November 14, 2011, full)