Back to index

Catalog of Language Elements # - C

Catalog of Language Elements D - L

Catalog of Language Elements M - R

Alphabetic catalog of Language elements S - Z

scl-enter

scl-enter is posted when a scrollbar is tapped.

Category UI event
Format (scl-enter id)
Parameters
idthe form id of the tapped scrollbar
Description scl-enter is the event posted when the user has tapped a scrollbar but not yet lifted the pen.

scl-exit

scl-exit is posted when a scrollbar has been released.

Category UI event
Format (scl-exit id new)
Parameters
idthe form id of the scrollbar
newthe new scroll value (an integer)
Description scl-exit is posted when the user has finished moving a scrollbar.

scl-get-val

scl-get-val returns the values of a scrollbar.

Category Primitive procedure
Format (scl-get-val id)
Parameters
idthe form id of the scrollbar
Description scl-get-val returns the values of the scrollbar with id id as a list of 4 integers:
  1. the current position of the knob
  2. the minimum (top position)
  3. the maximum (botton) position
  4. the page size (indicates knob size)
The scrollbar is invisible when minimum and maximum are the same.

Have a look at the sample program showing the interaction between fields and scrollbars.

R4RS Compliance LispMe extension
Examples
(scl-get-val 1500) => (4 0 20 8)

scl-repeat

scl-repeat is posted when a scrollbar is dragged.

Category UI event
Format (scl-repeat id new old)
Parameters
idthe form id of the scrollbar
newthe new scroll value (an integer)
oldthe old scroll value (an integer)
Description scl-repeat is posted continuously while the user is moving a scrollbar. You should return #f from your handler to make it work properly.

scl-set-val

scl-set-val sets the values of a UI scrollbar.

The return value is vals.

Have a look at the sample program showing the interaction between fields and scrollbars.

Category Primitive procedure
Format (scl-set-val id vals)
Parameters
idthe form id of the control
valsmust be a list of 4 integers as described below.
Description scl-set-val sets the values of the scrollbar with id id. vals must be a list of 4 integers indicating:
  1. the current position of the knob
  2. the minimum (top position)
  3. the maximum (botton) position
  4. the page size (used for page scrolling)
The scrollbar will be made invisible when minimum and maximum are the same.
R4RS Compliance LispMe extension
Examples
(scl-set-val 1500 '(5 0 10 3)) => (5 0 10 3) and positions the knob of the scrollbar into the middle

set!

set! modifies a variable.

Category Special form
Format (set! var expr)
Parameters
varan identifier
exprany expression
Description set! evaluates expr and assigns the value to var. var must be bound (by define, lambda, let, or letrec), or an error results.

Though R4RS doesn't specify a return value for set!, in LispMe the assigned value is returned.

R4RS Compliance Full
Examples
(let ((a 0)) (set! a 3) a) => 3
(let ((a 0)) (set! b 3) b) => error

set-car!

set-car! modifies the car component of a pair.

Category Primitive procedure
Format (set-car! pair obj)
Parameters
paira pair
objany object
Description set-car! changes the car component of pair to obj and returns the modified pair.
R4RS Compliance Full
Examples
(let ((a '(a b c))) (set-car! a 3) a) => (3 b c)

set-cdr!

set-cdr! modifies the cdr component of a pair.

Category Primitive procedure
Format (set-cdr! pair obj)
Parameters
paira pair
objany object
Description set-cdr! changes the cdr component of pair to obj and returns the modified pair.
R4RS Compliance Full
Examples
(let ((a '(a b c))) (set-cdr! a 3) a) => (a . 3)

set-palette

set-palette modifies a palette entry.

Category Primitive procedure
Format (set-palette index r g b)
Parameters
indexan integer in the range 0-255, the index
ran integer in the range 0-255, red part
gan integer in the range 0-255, green part
ban integer in the range 0-255, blue part
Description set-palette modifies the current colortable (palette) by setting the entry index to the given r g b values. Though according to the SDK, only indexes from 231 to 254 should be used for user-defined colors, you can modify any index using this procedure. The value returned is index.

On systems running older OS versions than 3.5, this procedure does nothing.

R4RS Compliance LispMe extension
Examples
(set-palette 231 35 78 250) => 231 and makes the first user-defined color a nice medium blue

set-resdb

set-resdb sets the name of the resource DB for the user interface.

Category Primitive procedure
Format (set-resdb str)
Parameters
stra string or false
Description set-resdb sets the name of the resource database being used in future calls to user interface functions. Only one resource DB can be active at any time, if another DB is already open, it'll be closed. Note, that the DB name is case-sensitive. The parameter #f closes the current resource DB. The return value is str.
R4RS Compliance LispMe extension
Examples
(set-resdb "demo") => "demo" and sets demo as current resource DB

sin

sin computes the sine of a number.

Category Primitive procedure (MathLib required)
Format (sin z)
Parameters
zany number
Description sin computes the sine of the number z. z is an angle measured in radians.

For complex arguments z = x + yi, the formula

sin z = sinx coshy + i cosx sinhy
is used.
R4RS Compliance Full
Examples
(sin 0) => 0
(sin 1) => 0.841470984807896
(sin 0.5+2i) => 1.80369269553218+3.18286944833715i

sinh

sinh computes the hyperbolic sine of a number.

Category Primitive procedure (MathLib required)
Format (sinh z)
Parameters
zany number
Description sinh computes the hyperbolic sine of the number z.

For complex arguments z = x + yi, the formula

sinh z = sinhx cosy + i coshx siny
is used.
R4RS Compliance LispMe extension
Examples
(sinh 0) => 0
(sinh 1) => 1.1752011936438
(sinh 0.5+2i) => -0.216852162920789+1.02534738858398i

sound

sound plays a (pseudo-)musical sound.

Category Primitive procedure
Format (sound freq time)
Parameters
freqan integer >= 128
timea positive integer
Description sound plays a sound of frequency freq (measured in Hertz) for time milliseconds. time and freqmust be positive or an error results.

Frequencies below 128 seem to be wrongly reproduced by the Pilot, so they're not allowed.

R4RS Compliance LispMe extension
Examples
(sound 440 1000) => #n and plays reference "a" for 1 second

sqrt

sqrt computes the square root of a number.

Category Primitive procedure (MathLib required)
Format (sqrt z)
Parameters
zany number
Description sqrt returns the square root of a number z.
R4RS Compliance Full
Examples
(sqrt 9) => 3
(sqrt 2) => 1.41421356237309
(sqrt -2) => +1.41421356237309i

string->list

string->list converts a string to the list of its characters.

Category Primitive procedure
Format (string->list string)
Parameters
stringa string
Description string->list returns a newly allocated list of the characters in string.
R4RS Compliance Full
Examples
(string->list "Foobar") => (#\F #\o #\o #\b #\a #\r)
(string->list "\\#ff") => (#\\ #\ÿ)
(string->list "") => ()

string->object

string->object parses a string as a LispMe object.

Category Primitive procedure
Format (string->object string)
Parameters
stringa string
Description string->object uses the standard LispMe parser to create an object from its textual representation string, so all kind of syntax errors are possible. The type of the object is solely determined by the contents of string. string must not be larger than 4096 characters.
R4RS Compliance LispMe extension. string->object subsumes R4RS procedures string->symbol and string->number.
Examples
(string->object "Foobar") => foobar
(string->object "\"Foobar\"") => "Foobar"
(string->object "(a (b) c)") => (a (b) c)
(string->object "1E3") => 1000

string-append

string-append concatenates strings.

Category Primitive procedure
Format (string-append stringi ...)
Parameters
stringiany string
Description string-append returns a newly allocated string, which is the concatenation of all the stringi in the order written.
R4RS Compliance Full
Examples
(string-append "foo" " bar" "baz") => "foo barbaz"
(string-append "hello") => "hello" (use this idiom to copy a string)
(string-append) => ""

string-length

string-length counts the characters in a string.

Category Primitive procedure
Format (string-length string)
Parameters
stringa string
Description string-length returns the number of characters in string.
R4RS Compliance Full
Examples
(string-length "Foobar") => 6
(string-length "\\#ff") => 2
(string-length "") => 0

string-ref

string-ref returns a character in a string by index.

Category Primitive procedure
Format (string-ref string index)
Parameters
stringa string
indexan integer
Description string-ref returns the indexth character of string. The index of the first character is 0, and the index of the last character is the length of string minus one.
R4RS Compliance Full
Examples
(string-ref "baz" 1) => #\a
(string-ref "hello" 5) => error

string-set!

string-set! replaces a character in a string.

Category Primitive procedure
Format (string-set! string index char)
Parameters
stringa string
indexan integer
chara character
Description string-set! replaces the indexth character of string by char. The modified string is returned. The index of the first character is 0, and the index of the last character is the length of string minus one. It's no error to modify a constant string in LispMe, as all values are heap-allocated and strings are never shared, so the examples are valid.
R4RS Compliance Full
Examples
(string-set! "baz" 2 #\r) => "bar"
(string-set! "hello" -1 #\x) => error

string=?

string=? compares two strings.

Category Primitive procedure
Format (string=? string1 string2)
Parameters
string1a string
string2a string
Description string=? returns #t, if both strings consist of the same characters at corresponding index positions and both strings have the same length. Otherwise #f is returned.
R4RS Compliance Full
Examples
(string=? "ab" "abc") => #f
(string=? "foo" "foo") => #t
(string=? "Foo" "foo") => #f

string?

string? recognizes strings.

Category Primitive procedure
Format (string? obj)
Parameters
objany object
Description string? returns #t for a string and #f for any other object.
R4RS Compliance Full
Examples
(string? #\x) => #f
(string? "x") => #t
(string? 'x) => #f

substring

substring returns s substring of a string.

Category Primitive procedure
Format (substring string start end)
Parameters
stringa string
startan integer
endan integer
Description substring returns a newly allocated substring of string starting at index start including characters up to index end-1. The index of the first character is 0, and the index of the last character is the length of string minus one. If end is less or equal to start, the empty string is returned. end may be greater than the length of string.
R4RS Compliance It's no error, when the second index end is out of bounds. In this case, the empty string or all characters upto the end of string are returned.
Examples
(substring "foobar" 2 4) => "ob"
(substring "foobar" 3 100) => "bar"
(substring "foobar" 4 1) => ""
(substring "foobar" 7 8) => error

symbol?

symbol? recognizes symbols.

Category Primitive procedure
Format (symbol? obj)
Parameters
objany object
Description symbol? returns #t for a symbol and #f for any other object.
R4RS Compliance Full
Examples
(symbol? 'foo) => #t
(symbol? 42) => #f
(symbol? '()) => #f

tan

tan computes the tangent of a number.

Category Primitive procedure (MathLib required)
Format (tan z)
Parameters
zany number
Description tan computes the tangent of the number z. z is an angle measured in radians.

For complex arguments z = x + yi, the formula

tan z = sin 2x / (cos 2x + cosh 2y) + i sinh 2x / (cos 2x + cosh 2y)
is used.
R4RS Compliance Full
Examples
(tan 0) => 0
(tan 1) => 1.5574077246549
(tan 0.5+2i) => 0.0302159873228775+0.979940849961738i

tanh

tanh computes the hyperbolic tangent of a number.

Category Primitive procedure (MathLib required)
Format (tanh z)
Parameters
zany number
Description tanh computes the hyperbolic tangent of the number z.

For complex arguments z = x + yi, the formula

tanh z = sinh 2x / (cosh 2x + cos 2y) + i sin 2x / (cosh 2x + cos 2y)
is used.
R4RS Compliance LispMe extension
Examples
(tanh 0) => 0
(tanh 1) => 0.761594155955765
(tanh 0.5+2i) => 1.32128658377119-0.850878121144937i

text

text prints an object as graphic text.

Category Primitive procedure
Format (text obj)
Parameters
objany object
Description text formats obj in human-readable format and prints it as graphic text to the graphic screen. Printing uses the graphics state *gstate* for starting coordinates, font, colors and drawing mode. The current point in *gstate* is not updated.

See here for details on the graphic state. The return value is #n to avoid trashing the graphics.

R4RS Compliance LispMe extension
Examples
(text "Hello, world") => #n and prints Hello, world as described above.

truncate

truncate computes the integer component of a number.

Category Primitive procedure (MathLib required)
Format (truncate num)
Parameters
numa number
Description truncate converts num to a floating point number and returns the integer part of it. The result is not a LispMe integer, it's a floating point value.

See also ceiling, floor, integer, and round.

R4RS Compliance Full
Examples
(truncate -4.3) => -4
(truncate 3.5) => 3

unquote

unquote evaluates an expression in a quasiquote template.

Category Special form
Format
(unquote exp)
,exp
Parameters
exp any expression
Description unquote evaluates exp in a quasiquote expression. The result is inserted into the template in place of the unquote expression. It's an error when unquote appears outside of a quasiquote expression. unquote may be abbreviated with a comma ,
R4RS Compliance Full
Examples See quasiquote

unquote-splicing

unquote-splicing evaluates an expression in a quasiquote template and splices it into the template.

Category Special form
Format
(unquote-splicing exp)
,@exp
Parameters
exp any expression
Description unquote-splicing evaluates exp in a quasiquote expression. The expression must evaluate to a list. The opening and closing parentheses of this list are removed and all items are inserted in place of the unquote-splicing expression. It's an error when unquote-splicing appears outside of a quasiquote expression. It's also an error when the context is not a list or a vector. unquote-splicing may be abbreviated with comma at-sign ,@
R4RS Compliance Full
Examples See quasiquote

vector

vector creates a vector from its arguments.

Category Primitive procedure
Format (vector obj1 ...)
Parameters
objiany object
Description vector gathers its arguments into a vector and returns it.
R4RS Compliance Full
Examples
(vector 'a -3 "hello") => #(a -3 "hello")
(vector '()) => #(())
(vector) => #()

vector->list

vector->list converts a vector to a list.

Category Primitive procedure
Format (vector->list vec)
Parameters
veca vector
Description vector->list returns a newly allocated list of the elements of the vector vec.
R4RS Compliance Full
Examples
(vector->list #(foo bar)) => (foo bar)
(vector->list (make-vector 10 42)) => (42 42 42 42 42 42 42 42 42 42)

vector-length

vector-length counts the elements in a vector.

Category Primitive procedure
Format (vector-length vec)
Parameters
veca vector
Description vector-length returns the number of elements in vec.
R4RS Compliance Full
Examples
(vector-length #(foo bar)) => 2
(vector-length (make-vector 97 #n)) => 97
(vector-length (vector)) => 0

vector-ref

vector-ref returns an element of a vector by index.

Category Primitive procedure
Format (vector-ref vec index)
Parameters
veca vector
indexan integer
Description vector-ref returns the indexth element of vec. The index of the first element is 0, and the index of the last element is the length of vec minus one.
R4RS Compliance Full
Examples
(vector-ref #(foo bar) 1) => bar
(vector-ref #(0 1 2 3) 5) => error

vector-set!

vector-set! modifies an element in a vector.

Category Primitive procedure
Format (vector-set! vec index obj)
Parameters
veca vector
indexan integer
objany object
Description vector-set! replaces the indexth element of vec by obj. The modified vector is returned. The index of the first element is 0, and the index of the last element is the length of vec minus one. It's no error to modify a constant vector in LispMe, as all values are heap-allocated and constant vectors are never shared, so the examples are valid.
R4RS Compliance Full
Examples
(vector-set! #(1 2 3) 2 #\r) => #(1 2 #\r)
(vector-set! (make-vector 10 'jamaica) -4 'rum) => error

vector?

vector? recognizes vectors.

Category Primitive procedure
Format (vector? obj)
Parameters
objany object
Description vector? returns #t for a vector and #f for any other object.
R4RS Compliance Full
Examples
(vector? '(1 2 3)) => #f
(vector? '#(1 2 3)) => #t
(vector? 'x) => #f

wait

wait waits for a time given.

Category Primitive procedure
Format (wait time)
Parameters
timea positive integer
Description waits waits for time milliseconds. time must be positive or an error results.
R4RS Compliance LispMe extension
Examples
(wait 1000) => #n after waiting 1 second

wait-pen

wait-pen waits for a pen tap and returns its coordinates.

Category Library procedure
Format (wait-pen)
Parameters none
Description wait-pen waits for a pen tap. When the pen event occurs, the pen coordinates are consed into a pair (x . y), which is returned. Both x and y coordinates are in the range [0..160].
R4RS Compliance LispMe extension
Examples
(wait-pen) => (80 . 80) assuming, you tapped exactly into the center of the screen.

write

write prints an object in machine-readable format.

Category Primitive procedure
Format (write obj [outport])
Parameters
objany object
outport(optional) an output port
Description write prints an object to the output field or to the output port outport in machine-readable format, i.e. strings and chars are escaped as described here. A space character is appended after each object written. write returns obj. For related information, see display and newline.
R4RS Compliance optional port parameter not supported
Examples
(write "Hello, world") => "Hello, world" and prints "Hello, world" to the output area.
(write '((x y))) => "((x y))" and prints ((x y)) to the output area.

write-record

write-record writes a record to an arbitrary Pilot DB.

Category Primitive procedure
Format (write-record dbname recnum obj)
Parameters
dbnamea string naming the database
recnuman integer
objeither a string or #f
Description write-record opens the Pilot database named dbname (case-sensitive!). recnum must be a valid index for the database. If obj is a string, a new record (filled with the string's contents) is tried to be inserted into the database at the position recnum and the actual insertion position is returned as an integer.

If obj is the value false, the record with index recnum is (permanently) deleted from the database (using DmRemoveRecord, not just setting the deleted attribute) and #t is returned on success.

If the database or the index doesn't exist or any other error occurs, #f is returned in both cases.

Warning: Don't try to create records for other apps when you're not absolutely sure about their data layout. Those apps often assume valid data in their databases and can crash badly otherwise!

R4RS Compliance LispMe extension.
Examples
(write-record "foo" 9999 "#01#02#03") => 5 and wrote successfully a record containing the 3 bytes "#01#02#03" to the database foo at the last index (which is 5).

zero?

zero? tests if a number is equal to zero.

Category Library procedure
Format (zero? num)
Parameters
numa number
Description zero? returns #t, if num is equal to zero. Otherwise it returns #f. See also positive? and negative?.
R4RS Compliance Full
Examples
(zero? 42) => #f
(zero? 0) => #t