Generated: May 24, 2003, 13:22:56Copyright ©2003, Kurt NørmarkThe 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    

Master index
Source file: lib/general.scm
LAML Version 20.00 (May 24, 2003, 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.
crcrReturn 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)Return the element of lst just after el, or #f if no such element exists.
element-before(element-before el lst selector)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 in terms of shallow copy involving n new cons cells.
generate-leq(generate-leq enumeration-order selector)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)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
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.
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 functions 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.
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-listwhite-space-char-listA 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 functions which converts the key position in an a-lists to a symbol.

Parameters
key-value-paira 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
keyis a symbol.
a-listan association list with symbols as keys.

Returns
the first value of key in a-list.

See also
similar functiondefaulted-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 functionget    


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.

Preconditions
p-list is of even length

Parameters
keyis a symbol.
p-lista property list with symbols as keys.

Returns
the first value of key in p-list

See also
similar functiondefaulted-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.

Preconditions
p-list is of even length

See also
similar functionget-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.

Preconditions
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-listA well-formed property list, in which the property names are symbols.
eliminationsA 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 functionfilter-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 functionfilter    


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)

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

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)

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)

Description
Remove the elements of lst2 from lst1. A non-destructive function. Uses eq? for comparison


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

Preconditions
All lists in lst-of-list are of equal lengths.

Parameters
lst-of-lstA 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 in terms of shallow copy involving n new cons cells. If n is equal or greater than the length of lst, lst is returned without any copying at all.


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.

Preconditions
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
vThe vector to search in.
elThe element to search for in the vector. el is comparabel with (sel ve) for a given vector element.
selA 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).


 

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 functionstring-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-listA list of strings
separatorA 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
nA positive decimal integer.
baseThe 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 functionsubstring-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.

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


 

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


 

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.

Preconditions
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
xAn arbitrary value that can be written with write.
filenameThe 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
xThe string to be written.
filenameThe 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: May 24, 2003, 13:22:56
This documentation has been extracted automatically from the Scheme source file by means of the Schemedoc tool