Generated: July 9, 2004, 14:30:02 Copyright © 2004 , Kurt Nørmark The local LAML software home page

Reference Manual of the General LAML library

Kurt Nørmark © normark@cs.auc.dk Department of Computer Science Aalborg University Denmark

Source file: lib/general.scm
LAML Version 24.00 (July 9 2004, beta 5, full)

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. List selection functions and their generators. 6. List and Sexpr functions. 11. Functions that change letter case in string.
2. Association and property list functions. 7. Vector functions. 12. Message displaying and error handling procedures.
3. Filter and accumulation functions. 8. Conversion functions. 13. File name components.
4. Mapping functions. 9. String predicates. 14. Other functions.
5. Other higher-order functions. 10. Other string functions.

Alphabetic index:
absolute-file-path? (absolute-file-path? x) Return whether x - a string - represents an absolute path to a file.
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-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.
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.
blank-string? (blank-string? str) Is the string str empty or blank (consists of white space)
but-first-sentence-of-string (but-first-sentence-of-string str) Return all but the first sentence in str.
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.
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.
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.
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 (by means of cdr of assq).
delete-string-portion (delete-string-portion str i lgt) Delete the substring of length lgt from index i in the string str.
directory-level-difference (directory-level-difference dir1 dir2) Return the number of directory levels in between dir1 and dir2.
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 . optional-parameter-list) Return the element of lst just after el, or #f if no such element exists.
element-before (element-before el lst selector . optional-parameter-list) Return the element of lst just before el, or #f if no such element exists.
embed-substring (embed-substring substring str embed-function) Embed 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 file-and-ext) exists.
ensure-directory-path-existence! (ensure-directory-path-existence! prefix-dir dir) Ensure that the relative path, as represented by dir, 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 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.
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-name) Return the initial path of the file-name.
file-name-proper (file-name-proper file-name) Return the part of file-name without extension and 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]) redefinition of file-read from general.
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-no-ordering (filter-no-ordering pred lst) Like filter, but the ordering among elements in the resulting list is unknown and arbitrary.
find-in-list (find-in-list pred lst) A simple linear list search function.
find-in-string (find-in-string str ch . start-pos) Search linearly for the character ch in the string str.
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.
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.
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.
id-1 (id-1 x) The identify function of one parameter
index-in-list-by-predicate (index-in-list-by-predicate lst el comparator) Return the index of the first occurrence of el in lst.
laml-error (laml-error . messages) Stop the program with messages.
last (last lst) Return the last element of a list.
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 an lst2 which belongs to both of the lists.
list-part (list-part a b lst) Return the sublist consisting of element a to element b of the list lst.
list-prefix (list-prefix lst n) Return the list of the first n elements of lst.
list-to-string (list-to-string str-lst separator) Return a string with the elements of str-lst separated by separator.
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-list (make-list n el) Return a list of n elements, each being el
make-mutator-function (make-mutator-function n . optional-parameter-list) 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.
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 lst) Map and filter a list lst 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-relative-file-path (normalize-relative-file-path path) Normalize the relative file path, path, for redundant ..
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 numbers from f to t.
numeric-string? (numeric-string? str [signed?]) Returns if the string str is numeric.
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.
proper-part (proper-part lst) Return the proper part of an S-expression
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-path-to-path-list (relative-path-to-path-list dir) Given a relative file path, return a list of path constituents.
remove-duplicates (remove-duplicates lst) Duplicate removal - non-destructive.
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.
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
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
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 char-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.
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.
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 an element predicate p.
sublist-by-rows (sublist-by-rows n lst) Return a list of lists of elements from lst.
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.
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.
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.
turn-into-boolean (turn-into-boolean x) If x is considered true return #t else #f.
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 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.

make-mutator-function
Form (make-mutator-function n . optional-parameter-list)
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 This is used for error message purposes.

first
Form (first lst)
Description Return the first element of a list

second
Form (second lst)
Description Return the second element of a list

third
Form (third lst)
Description Return the third element of a list

fourth
Form (fourth lst)
Description Return the fourth element of a list

fifth
Form (fifth lst)
Description Return the fifth element of a list
Returns The fifth element of the list

sixth
Form (sixth lst)
Description Return the sixth element of a list

seventh
Form (seventh lst)
Description Return the seventh element of a list

eighth
Form (eighth lst)
Description Return the eighth element of a list

nineth
Form (nineth lst)
Description Return the nineth element of a list

2 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.

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")

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.

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.
See also 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.
See also 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
See also similar function defaulted-get-prop
Note Uses the function eq? for key comparions.

defaulted-get-prop
Form (defaulted-get-prop key p-list default)
Description Return the value of key in the property list p-list (by means of cdr of assq). If no association is found return default.
Precondition p-list is of even length
See also similar function get-prop

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.

propertylist-to-alist
Form (propertylist-to-alist plist)
Description Make and return an association list from a property list plist.

alist-to-propertylist
Form (alist-to-propertylist alist)
Description Make and return a property list from an association list.

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.

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.

3 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.
See also 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?
See also similar function filter

mapping-filter
Form (mapping-filter pred lst)
Description Map and filter a list lst by means of the predicate pred. If the predicate pred returns a true value v on the element e in list, return v instead of e (this is the mapping effect). Only return those mapped elements that fullfil pred.
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.
Note This function is iterative.

4 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 does 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.

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.

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.

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.

5 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.

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.

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?

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 the parameters; In this case (curry-generalized f) is equivalent to f.
Example
(define gmap (curry-generalized map))
Example
(define gfilter (curry-generalized filter))

6 List and Sexpr functions.

number-interval
Form (number-interval f t)
Description Return a list of all numbers from f to t. Return the empty list if f is greater than t.

proper-part
Form (proper-part lst)
Description Return the proper part of an S-expression

first-improper-part
Form (first-improper-part lst)
Description Return the first improper part of an S-expression

make-list
Form (make-list n el)
Description Return a list of n elements, each being el

replicate-to-length
Form (replicate-to-length lst lgt)
Description Replicate lst cyclically to a list of length lgt

flatten
Form (flatten lst-of-lst)
Description Flatten a list of lists to one list.

sum-list
Form (sum-list lst)
Description Add all elments in a list of numbers

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

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.
Example
(merge-lists-simple '(a b c d)  '(1 2 3)) => (a 1 b 2 c 3 d)

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.

butlast
Form (butlast lst)
Description Return all but the last element of a list. Quick and dirty version.

last
Form (last lst)
Description Return the last element of a list. Quick and dirty version.

remove-duplicates
Form (remove-duplicates lst)
Description Duplicate removal - non-destructive. This function uses equal for comparison of elements.

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.

element-before
Form (element-before el lst selector . optional-parameter-list)
Description Return the element of lst just before el, or #f if no such element exists. Comparsion is done via application of selector on the elements of lst, and via eq?. More precise return the element e of lst just before f, where (eq? (selector f) el).

element-after
Form (element-after el lst selector . optional-parameter-list)
Description Return the element of lst just after el, or #f if no such element exists. Comparsion is done via application of selector on the elements of lst, and via eq?. More precise return the element e of lst just after f, where (eq? (selector f) el).

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

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.

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.
See also 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).

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).

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.

sublist-by-predicate
Form (sublist-by-predicate lst p)
Description Return a list of sublists of elements from lst controlled by an element predicate p. The sublists are formed consequtively by taking elements from lst. The predicate p decides when to start a new sublist. Thus, when p evaluates to true, we start a new sublist. The predicate p takes as parameters the current elements, the previous element, and the number of elements before the current one, p is not activated on (car lst). This function generalizes sublist-by-rows. p: (cur prev n) -> boolean

remove-duplicates-by-predicate
Form (remove-duplicates-by-predicate lst p)
Description Remove duplicates from lst. A pair of duplicates satisfy the predicate p: (p element element) -> boolean. In case of duplicates, keep the first one in the result.

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 element element) -> boolean.

member-by-predicate
Form (member-by-predicate el lst p)
Description Is el member of lst by means of the predicate p. el is always passed as the first parameter to 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. p: (el1, el2) -> boolean

list-intersection-by-predicate
Form (list-intersection-by-predicate lst1 lst2 pred)
Description Return the elements of lst1 an lst2 which belongs 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.
Example
(list-intersection '(a b c d a) '(a d) eq?) = (a d)

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.

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.

index-in-list-by-predicate
Form (index-in-list-by-predicate lst el comparator)
Description Return the index of the first occurrence of el in lst. Return #f is el is not found in lst. Comparison is done by comparator. The index of the first element is 0.

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.
Example
(sublistify '(1 2 3 4 5 6 7 8 9) 4) = ((1 2 3 4) (5 6 7 8) (9))

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.

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.

list-prefix
Form (list-prefix lst n)
Description Return the list of the first n elements of lst. If n > (length lst) just return lst.

list-part
Form (list-part a b lst)
Description Return the sublist consisting of element a to element b of the list lst. 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, b <= (length lst), and a and b are postive integers.
Example
(list-part 3 5 '(a b c d e f g h)) = (c d e)

7 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.

8 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

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.

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.

as-symbol
Form (as-symbol x)
Description Convert x to a symbol. String, symbols, booleans, and characters are supported

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.

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 #\?.

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.
Example
(as-list "xy z abc ") => ("xy" "z" "abc")
See also 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.

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.

list-to-string
Form (list-to-string str-lst separator)
Description Return a string with the elements of str-lst separated by separator.
Parameters str-list A list of strings
separator A string which is used to separate the list elements in the resulting string.

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.

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.

9 String predicates.

empty-string?
Form (empty-string? str)
Description Is the string str empty

white-space-char-list
Form white-space-char-list
Description A list of characters considered as blank space characters

blank-string?
Form (blank-string? str)
Description Is the string str empty or blank (consists of white space)

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.

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).

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).

10 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. ch is a character. The first is the prefix of str up to the first occurence of ch The second is the suffix from ch to the end of str

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.
See also similar string find function substring-index

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.

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.

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.

skip-chars-in-string
Form (skip-chars-in-string str char-list start-pos)
Description Starting from char-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. If start-pos is higher than the maximum legal string index, return start-post.

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
Example
(string-merge (list "aa" "bb" "cc") (list "XX" "YY")) => "aaXXbbYYcc"

transliterate
Form (transliterate in-string ch str)
Description In in-string, substitute each occurence of character ch with the string str. As a special case, str may be the empty string, in which case occurrences of the character ch is eliminated from str.

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.

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.

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.

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.

embed-substring
Form (embed-substring substring str embed-function)
Description Embed substring, as found in string, into embed-function. A non-destructive function.
Parameters embed-function a function of one parameter, such as em, b.
Returns str with the first occurence of substring embedded into an activation of embed-function.
Example
(embed-substring "LAML" "LAML is programmed in Scheme" em)

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 chararter 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.

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.

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.

but-first-sentence-of-string
Form (but-first-sentence-of-string str)
Description Return all but the first sentence in str.

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.

strip-trailing-characters
Form (strip-trailing-characters char-list string)
Description Strip trailing occurences of the characters in char-list from string.

strip-initial-spaces
Form (strip-initial-spaces string)
Description Strip all initial space characters and lineshifting characters from string.

string-it
Form (string-it x)
Description Embed the string x in double string quotes

string-it-single
Form (string-it-single x)
Description Embed the string x in single string quotes

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.

ensure-final-character
Form (ensure-final-character str ch)
Description Ensure that the last character in str (a string) is ch (a char)

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.

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.
Example
ab$c  -> abc
Example
xy$   -> xy
Example
$$$$x -> $$x
Example
$$xy  -> $xy
Example
$.xy  -> .xy

11 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 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 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.

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.

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 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 destructive variant decapitalize-string

12 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

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

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

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.

errors-among-conditions
Form (errors-among-conditions . err-condition-message-list)
Description Return a list of error message strings for those conditions that are true. The function returns #f in case no errors are found. There are no errors if all conditions evaluate to #f, and in this case returns the #f. err-condition-message-list is a property list (of even length) of error-condition error messages pairs. This function checks the conditions and returns a concatenated list of error messages. If no error conditions are found, return #f.

13 File name components.

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

file-name-proper
Form (file-name-proper file-name)
Description Return the part of file-name without extension and without an initial path. Works as expected even there are dots in the initial path.
Example
(file-name-proper "/xxx/yyy/zzz.eee") = "zzz".

file-name-extension
Form (file-name-extension file-name)
Description Return the extension of file-name. 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.

file-name-initial-path
Form (file-name-initial-path file-name)
Description Return the initial path of the file-name. The initial path of a file name is the prefix of the file name without the proper file name and without the extension. The initial path ends in a forward of backward slash, or it is empty.

absolute-file-path?
Form (absolute-file-path? x)
Description Return whether x - a string - represents an absolute path to a file.

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.

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.
Example
(directory-level-difference "/x/x/z/v/" "/x/x/") = 2
Example
(directory-level-difference "/x/x/" "/x/x/z/v/") = -2

relative-path-to-path-list
Form (relative-path-to-path-list dir)
Description Given a relative file path, return a list of path constituents. A relative file path is not allowed to start with a slash. This function does only support forward slashes.
Example
(relative-path-to-path-list "xxx/yyy/zzz/") = ("xxx" "yyy" "zzz")
Example
(relative-path-to-path-list "xxx") = ("xxx")
Example
(relative-path-to-path-list "xxx/yyy/zzz") = ("xxx" "yyy" "zzz")

ensure-directory-existence!
Form (ensure-directory-existence! prefix-dir dir)
Description Ensure that the directory with path (string-append prefix-dir file-and-ext) exists. If necessary, create dir in prefix-dir.

ensure-directory-path-existence!
Form (ensure-directory-path-existence! prefix-dir dir)
Description Ensure that the relative path, as represented by dir, exists in prefix-dir. Creates the necessary directories in prefix-dir.

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).

normalize-relative-file-path
Form (normalize-relative-file-path path)
Description Normalize the relative file path, path, for redundant .. levels.

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

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???

cr
Form cr
Description Return a CR string

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).

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.

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

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.

file-read
Form (file-read file-name [n])
Description Redefinition of file-read from general. A more general version. Read the first Lisp expression from file-name. With an optional second parameter, read form number n from file.
Precondition Assume that there are at least n forms on file

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.

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).

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).

id-1
Form (id-1 x)
Description The identify function of one parameter

multiplum-of
Form (multiplum-of a b)
Description Is a (the first par) a multiplum of b (the last par)?

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

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. The the boolean parameter is #f, a fatal error will occur.

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.


Generated: July 9, 2004, 14:30:10
Generated by LAML SchemeDoc .