IoTSS Standard Library
v1.0.0 by wu5@hekr.me 8/7/2015 6:49:38 PM
Hangzhou District Nine Technology Co., Ltd. © 2015. All Rights Reserved.
Bitwise
Bitwise operations
bitwise-ior
(bitwise-ior n:integer ...):integer
Compute the bitwise inclusive or of all given integers. If no argument is given, returns 0.
Examples:
(bitwise-ior 1 2) ;; 3
(bitwise-ior -32 1) ;; -31
bitwise-and
(bitwise-and n:integer ...):integer
Compute the bitwise and of all given integers. If no argument is given, returns -1.
Examples:
(bitwise-and 1 2) ;; 0
(bitwise-and -32 -1) ;; -32
bitwise-xor
(bitwise-xor n:integer ...):integer
Compute the bitwise exclusive or of all given integers. If no argument is given, returns 0.
Examples:
(bitwise-xor 1 5) ;; 4
(bitwise-xor -32 -1) ;; 31
bitwise-not
(bitwise-not n:integer):integer
Compute the bitwise not of a given integer.
Examples:
(bitwise-not 5) ;; -6
(bitwise-not -1) ;; 0
bitwise-bit-set?
(bitwise-bit-set? n:integer m:integer):boolean
Detect if a bit in an integer has been set.
Examples:
(bitwise-bit-set? 5 0) ;; #t
(bitwise-bit-set? 5 2) ;; #t
arithmetic-shift
(arithmetic-shift n:integer m:integer):integer
Do specified times of arithmetic shift m on an integer n, if m is 0, no shift operations performs, if m is positive, the left shift performs, otherwise, if m is negative, the right shift performs.
Examples:
(arithmetic-shift 1 10) ;; 1024
(arithmetic-shift 255 -3) ;; 31
Bytevector
Operations on Bytevectors.
bytevector?
(bytevector? obj:any):boolean
Detect if a given value is a bytevector.
Examples:
(bytevector? (make-bytevector 0)) ;; #t
(bytevector? 123) ;; #f
make-bytevector
(make-bytevector length:integer [fill:integer]):bytevector
Return an allocated bytevector with the specified number of elements and preset value of each element.
The length of the new created bytevector should be a non-negative integer because a bytevector could be either empty or contains some elements.
The preset element is optional, when fill isn't provided, the integer 0 will be use as the present element.
Examples:
(make-bytevector 3 1) ;; #vu8(1 1 1)
bytevector-length
(bytevector-length v:bytevector):integer
Get the length of the bytevector.
Examples:
(bytevector-length (make-bytevector 3)) ;; 3
bytevector-fill!
(bytevector-fill! v:bytevector fill:anything):void
Set every element in the v bytevector to the same value as fill.
(define v (make-bytevector 3 0)) ;; #vu8(0 0 0)
(bytevector-fill! v 1)
v ;; -> #vu8(1 1 1)
bytevector=?
(bytevector=? v1:bytevector v2:bytevector ...):boolean
Return if the given bytevectors are equals.
The procedure accepts at least 2 arguments to compare, and extra arguments are optional, if more then 2 arguments are given, will compare them pair by pair and returns #f when inequal.
Examples:
(bytevector=? v1:bytevector v2:bytevector ...):boolean
bytevector-copy
(bytevector-copy v:bytevector [start:integer [end:integer]]):bytevector
Returns the clone of a part of bytevector, the start and end arguments are optional. If only provided the bytevector, the procedure will returns the clone of the entire bytevector. If the bytevector and the start argument are provided, the part of bytevector starts from the index of start will be cloned and returned. If the start and the end arguments are provided along with the bytevector, the content of range from start to end will be cloned and returned.
the start and end arguments should be in reasonable range. For example, the start and end should be non-negative integers and should not be out of range of the length of the bytevector.
Examples:
(define v #vu8(1 2 3))
(bytevector-copy v) ;; #vu8(1 2 3)
(bytevector-copy v 0) ;; #vu8(1 2 3)
(bytevector-copy v 1) ;; #vu8(2 3)
(bytevector-copy v 2) ;; #vu8(3)
(bytevector-copy v 0 2) ;; #vu8(1 2)
(bytevector-copy v 1 2) ;; #vu8(2)
(bytevector-copy v 2 2) ;; #vu8()
bytevector-u8-ref
(bytevector-u8-ref v:bytevector index:integer):integer
Get the element of an bytevector with the specified index.
The index should be in in reasonable range, larger than or equals to 0 and lessthan the bytevector size.
The return value is a unsigned integer in range from 0 to 255.
Examples:
(define v #vu8(1 2 3))
(bytevector-u8-ref v 0) ;; 1
(bytevector-u8-ref v 1) ;; 2
(bytevector-u8-ref v 2) ;; 3
bytevector-s8-ref
(bytevector-s8-ref v:bytevector index:integer):integer
Get the element of an bytevector with the specified index.
The index should be in in reasonable range, larger than or equals to 0 and lessthan the bytevector size.
The return value is a signed integer in range from 0 to 255.
Examples:
(define v #vu8(1 2 3))
(bytevector-s8-ref v 0) ;; 1
(bytevector-s8-ref v 1) ;; 2
(bytevector-s8-ref v 2) ;; 3
bytevector-u8-set!
(bytevector-u8-set! v:bytevector index:bytevector value:integer):void
Set the value in the specified index of a bytevector.
The index should be a reasonable value, larger or equals to 0 and less than the bytevector size.
Examples:
(define v #vu(0 0 0))
(bytevector-u8-set! v 0 1)
(bytevector-u8-set! v 1 2)
(bytevector-u8-set! v 2 3)
v ;; #vu8(1 2 3)
bytevector-s8-set!
(bytevector-s8-set! v:bytevector index:bytevector value:integer):void
Set the value in the specified index of a bytevector.
The index should be a reasonable value, larger or equals to 0 and less than the bytevector size.
Examples:
(define v #vu(0 0 0))
(bytevector-s8-set! v 0 1)
(bytevector-s8-set! v 1 2)
(bytevector-s8-set! v 2 3)
v ;; #vu8(1 2 3)
u8-list->bytevector
(u8-list->bytevector lst:(list of integer))
Return the bytevector which converted from list of integer.
Examples:
(u8-list->bytevector '(1 2 3)) ;; #vu8(1 2 3)
bytevector->u8-list
(bytevector->u8-list v:vector):(list of integer)
Return the list of integers which converted from bytevector.
Examples:
(bytevector->u8-list #vu8(1 2 3)) ;; '(1 2 3)
bytevector-u8-checksum
(bytevector-u8-checksum v:bytevector)
Compute the checksum of a bytevector.
(bytevector-u8-checksum #vu8(1 2 3)) ;; 6
Environment
Operations on Environments.
null-environment
(null-environment)
Return an empty environment. The new created environment will contains no binding and has no a previous environment.
Examples:
(null-environment) ;; An empty environment
environment-bindings
(environment-bindings)
Returns a list of the all symbols of bindings in the specified environment.
Examples:
(define e (null-environment)) ;; An empty environment
(environment-bindings e) ;; '()
environment-assign!
(environment-assign! env:environment name:symbol value:any):void
Assign a value with a symbol to a specified environment.
Examples:
(define e (null-environment))
(environment-assign! e 'plus (lambda (a b) (+ a b)))
eval
(eval exp:any [env:environment]):any
Evaluate an expression in the environment, the environment is optional, if absent, will evaluate in the current environment.
Examples:
(define e (null-environment))
(environment-assign! e 'plus (lambda (a b) (+ a b)))
(eval '(plus 1 2) e) ;; 3
Error
Operations on Errors.
error
(error [sym:symbol [desc:string]]):error
Return an error value.
An error value consists with two part, the symbol part and the description part, both parts are optional.
Examples:
(error 'divide-by-zero)
(error 'file-not-found "/tmp/not_exist.txt")
error?
(error? val:any):boolean
Detect if a value is an error object.
Examples:
(error? (error)) ;; #t
(error? 123) ;; #f
Functional
Functional Operations.
map
(map proc:procedure lst:list ...):list
Apply a procedure to each element of given lists and return the results as a list.
Examples:
(map (lambda (x) (+ 1 x)) '(1 2 3)) ;; '(2 3 4)
(map (lambda (x y) (+ x y)) '(1 2 3) '(10 100 1000)) ;; '(11 102 1003)
filter
(filter proc:procedure lst:list):list
Apply a procedure to each element of given lists, the procedure accepts an argument of each element in the list and returns a boolean to confirm if it leaves in the final result.
Examples:
(filter (lambda (x) (= (modulo x 2) 0)) '(1 2 3 4)) ;; (2 4)
Future
The procedures will be introduced in the future.
make-remote-procedure
(make-remote-procedure url:string)
Make a remote procedure with the given URL.
The term remote here is not mean the procedure stored on a remote machine, just provides a way of accessing procedure like accessing a remote procedure via URL.
The explicit list of supported method and format of the URL are depend on the implementation of IoTSS.
Examples:
((make-remote-procedure "lib://math/sqrt") 9) ;; 3
Input/Output
Input/Output operations.
output-port?
(output-port val:any):boolean
Return if the value is a output port.
Examples:
(output-port (open-output-file "filename")) ;; #t
input-port?
(input-port val:any):boolean
Return if the value is an input port.
Examples:
(input-port (open-input-file "filename")) ;; #t
display
(display val:any [p:port]):void
Display the value in the form of readable format with a line feed followed.
If the port not been specified, the current default port will be used.
Examples:
(display 123) ;; 123
(display "Hello") ;; Hello
displayln
(display val:any [p:port]):void
Display the value in the form of readable format with a line feed followed.
If the port not been specified, the current default port will be used.
Examples:
(display 123) ;; 123
(display "Hello") ;; Hello
format
(format fmt:string ...):string
Return a formatted string in the given format.
fmt is the format in string, it specifies the basic format of the output but contains some special escapes that will be replaced with values given after the fmt argument.
The special escapes are listen below:
-
~n,~%output a line feed. -
~~output a tilde char. -
~a,~Aoutput the value in readable form. -
~v,~Voutput the value in code form.
Examples:
(format "Hello") ;; "Hello"
(format "~a" "Hello") ;; "Hello"
(format "~v" "Hello") ;; "\"Hello\""
printf
(printf fmt:string ...):void
Output a formatted string to the default output port in the given format.
fmt is the format in string, it specifies the basic format of the output but contains some special escapes that will be replaced with values given after the fmt argument.
The special cases are covered in previous sections.
Examples:
(printf "Hello") ;; Hello
(printf "~a" "Hello") ;; Hello
(printf "~v" "Hello") ;; \"Hello\"
fprintf
(fprintf p:port fmt:string ...):void
Output a formatted string to a specified default output port in the given format.
fmt is the format in string, it specifies the basic format of the output but contains some special escapes that will be replaced with values given after the fmt argument.
The special cases are covered in previous sections.
Examples:
(fprintf default-output-port "Hello") ;; Hello
(fprintf default-output-port "~a" "Hello") ;; Hello
(fprintf default-output-port "~v" "Hello") ;; \"Hello\"
printfn
(printfn p:port fmt:string ...):void
The same function as printf but print an additional line feed followed.
fprintfn
(fprintfn p:port fmt:string ...):void
The same function as fprintf but print an additional line feed followed.
newline
(newline [p:port]):void
Output a line feed to the output port. If a port is specified, output the line feed to the specified port.
read
(read [p:port]):string
Read data from a given input port, if the port is absent, read from the default input port.
Examples:
(read default-input-port)
write
(write [p:port] data:string)
Read data from a given input port, if the port is absent, write to the default output port.
Examples:
(write default-output-port "Hello World")
open-output-file
(open-output-file path:string):port
Open a file for writing which represented as a port.
Examples:
(open-output-file "/tmp/test/txt")
close-output-file
(close-output-file p:port)
Close an output port.
The port provided should be able to close such as it is a port of an opened file.
Examples:
(close-output-file port)
open-input-file
(open-input-file path:string):port
Open a file for reading which represented as a port.
Examples:
(open-input-file "/tmp/test/txt")
close-input-file
(close-input-file p:port)
Close an input port.
The port provided should be able to close such as it is a port of an opened file.
Examples:
(close-output-file port)
get-bytevector-n
(get-bytevector-n p:port n:integer):bytevector
Read the specified length of data from a given port and return a bytevector. The argument n specifies the length of reading buffer, means the maximum length of data could be read is n. It is possible that the number of read data less than n, then a bytevector in the length of the actual read data will be returned.
Examples:
(get-bytevector-n p 128)
get-bytevector-n!
(get-bytevector-n p:port bv:bytevector start:integer end:integer):integer
Read the data from a given port and fill into a bytevector and returns the length of read data. The argument startand end specifies the offset of where data started to be filled and where it stops, the end and start also implies the maximum length of data could be read. It is possible that the number of read data less than the length specified by start and end, then an integer of the length of actual read data will be returned.
Examples:
(get-bytevector-n p 128)
get-bytevector-all
(get-bytevector-all p:port):bytevector
Read as many bytes as possible from a given port.
Examples:
(get-bytevector-all p)
Serialize
Converting the object between the objects and string form.
serialize
(serialize val:any):string
Convert a given object into string format for transporting.
Serialize part of shares the same routines as the print, in other words, serialize converts the value in readable code format.
Not all data types are able to be serialized, values in some data types contain things like native procedures which contain the compiled machine code that could be impossible to serialized.
Examples:
(serialize 123) ;; "123"
(serialize "str") ;; "\"str\""
deserialize
(deserialize s:string):any
Deserialize the serialized data.
Examples:
(deserialize "123") ;; 123
Standard
cons
(cons car-part:any cdr-part:any):pair
Construct a pair with the given car part and cdr part, this is also the most common way to construct lists.
Examples:
(cons 1 2) ;; (1 . 2)
(cons 1 (cons 2 '())) ;; (1 2)
car
(car p:pair):any
Return the car part of a pair, it is a common way to get the first element of a list.
Examples:
(car (cons 1 2)) ;; 1
(car '(1 2 3 4)) ;; 1
cdr
(cdr p:pair):any
Return the cdr part of a pair, it is a common way to get the rest elements of a list.
Examples:
(cdr (cons 1 2)) ;; 2
(cdr '(1 2 3 4)) ;; '(2 3 4)
set-car!
(set-car! p:pair v:value):void
Examples:
(define p (cons 1 2))
(set-car! p 3) ;; p : (3 . 2)
Note: set-car! is not recommended to use.
set-cdr!
(set-cdr! p:pair v:value):void
Examples:
(define p (cons 1 2))
(set-cdr! p 3) ;; p : (1 . 3)
Note: set-cdr! is not recommended to use.
list
(list ...):list
Construct list with given elements provided as arguments. If no argument provided, an empty list will be returned.
Examples:
(list 1 2 3) ; '(1 2 3)
(list) ; '()
list-ref
(list-ref lst:list index:integer):any
Return the element of a list with the proviced index.
The index should be an reasonable value that larger than 0 and less than the length of the list.
Examples:
(list-ref '(1 2 3) 0) ;; 1
(list-ref '(1 2 3) 1) ;; 2
(list-ref '(1 2 3) 2) ;; 3
append
(append ...):list
Concatenate lists into one list.
If no argument given, an empty list will be returned.
Examples:
(append '(1 2 3) '(4 5 6) ;; '(1 2 3 4 5 6)
length
(length lst:list):integer
Returns the length of a given list.
Examples:
(length '()) ;; 0
(length '(1 2 3)) ;; 3
null?
(null? lst:list)
Return if a list is empty.
Examples:
(null? '()) ;; #t
(null? '(1 2 3)) ;; #f
member
(member v:any lst:list):any
Locate to the first element of a list equals to the given value.
Return #f if there is not such a value.
Examples:
(member 3 '(1 2 3 4)) ;; '(3 4)
(member 8 '(1 2 3 4)) ;; #f
memv
(memv v:any lst:list):any
The same as member but compare with eqv? instead of equal?.
Examples:
(memv 3 '(1 2 3 4)) ;; '(3 4)
(memv 8 '(1 2 3 4)) ;; #f
memq
(memq v:any lst:list):any
The same as member but compare with eq? instead of equal?.
Examples:
(memq 3 '(1 2 3 4)) ;; '(3 4)
(memq 8 '(1 2 3 4)) ;; #f
memf
(memf p:procedure lst:list):any
The same as member but compare with a given procedure, the procedure accepts an argument and returns a boolean value to indicate if the position has the value of the list should be returned.
Examples:
(memf (lambda (x) (= x 3)) '(1 2 3 4)) ;; '(3 4)
(memf (lambda (x) (= x 8)) '(1 2 3 4)) ;; #f
reverse
(reverse lst:list)
Return the reversed list.
Examples:
(reverse '()) ;; '()
(reverse '(1 2 3 4)) ;; '(4 3 2 1)
+
-
*
/
quotient
modulo
(+ ...)
(- ...)
(* ...)
(/ ...)
(quotient ...)
(modulo ...)
Arithmatic operations to all parameters on all arguments.
+ and * accepts any number of arguments. If + applies on 0 argument, the value 0 will be returned. If * applies on 0 argument, the value 1 will be returned.
-, /, quotient and modulo accepts at least 1 argument, if - applies on one argument, the negative number of the only argument will be returned, otherwise the substruction will be performed in order (the first argument will be substructed by the rest arguments).
sqrt
(sqrt v:number):number
Return the square root of a number.
Examples:
(sqrt 9) ;; 3
(sqrt 100) ;; 10
(sqrt 3) ;; 1
not
(not b:boolean)
Return an opposite value of a boolean value.
Examples:
(not #f) ;; #t
(not #t) ;; #f
eq?, eqv?, equal?
(eq? ...)
(eqv? ...)
(equal? ...)
Test the equality with the given values. The difference between these 3 procedures are listed below:
eq?: Only compares primitive values, it also compares reference values are reference to the same object.
eqv?: Compares the values of both primitive values and reference values, but not including values in composite data type such as list or vector.
equals?: Compares the values of primitive values
Examples:
(eq? 123 123) ;; #t
(eq? "abc" "abc") ;; #f
(eqv? "abc" "abc") ;; #t
(eqv? '(1 2 3) '(1 2 3)) ;; #f
(equal? '(1 2 3) '(1 2 3)) ;; #t
=, >, <, >=, <=
(= ...)
Compare the given numbers in order, return #f is any of the comparings fails, otherwise return #t
Examples:
(= 3 3) ;; #t
(= 3 3 3) ;; #t
(= 3 3 3 4) ;; #f
(< 3 4) ;; #t
(< 3 2) ;; #f
(<= 3 3) ;; #t
String
Strings Operations.
str-len
(str-len s:string):integer
Return the length of a string.
Examples:
(str-len "abc") ;; 3
str-append
(str-append ...):string
Concatenate given Strings.
Examples:
(str-append "abc" "def") ;; "abcdef"
str-ref
(str-ref s:string index:integer):str
Get the specified char of a string and return it as string.
Examples:
(str-ref "abc" 1) ;; "b"
str-sub
(str-sub s:string start:integer end:integer):string
Return a clip of a string, with the given index of start and end.
Examples:
(str-sub "abc" 0 1) ;;"a"
(str-sub "abc" 0 2) ;;"ab"
str->uni
(str->uni ch:string):integer
Return the code of unicode char given as a string.
Examples:
(str->uni "A") ;; 65
uni->str
(uni->str ch:integer):string
Return the string of unicode char given as an integer.
Examples:
(uni->str 65) ;; "A"
str->sym
(str->sym s:string):symbol
Return the symbol converted from a string.
Examples:
(str->sym "test") ;; 'test
sym->str
(sym->str s:symbol):string
Return the string converted from a symbol.
Examples:
(sym->str "test") ;; "test"
Types
Type predictions.
boolean?
(boolean? v:any):boolean
Return if a value is a boolean type value.
Examples:
(boolean? #f) ;; #t
(boolean? #t) ;; #t
(boolean? 123) ;; #f
(boolean? "abc") ;; #f
pair?
(pair? v:any):boolean
Return if a value is a pair type value.
(pair? '(1 2 3)) ;; #f
(pair? (cons 1 2)) ;; #t
symbol?
(symbol? v:any):boolean
Return if a value is a symbol type value.
Examples:
(symbol? 'abc) ;; #t
(symbol? "abc") ;; #f
number?
(number? v:any):boolean
Return if a value is a number type value.
Examples:
(number? 123) ;; #t
(number? "abc") ;; #f
string?
(string? v:any):boolean
Return if a value is a string type value.
Examples:
(string? 123) ;; #f
(string? "abc") ;; #t
vector?
(vector? v:any):boolean
Return if a value is a vector type value.
Examples:
(vector? #(1 2 3)) ;; #t
(vector? "abc") ;; #f
port?
(port? v:any):boolean
Return if a value is a port type value.
Examples:
(port? default-output-port) ;; #t
(port? "abc") ;; #f
procedure?
(procedure? v:any):boolean
Return if a value is a procedure type value.
Both native procedures and non-native procedures are considered procedures.
Examples:
(procedure? (lambda (x) (+ 1 x))) ;; #t
(procedure? display) ;; #t
integer?
(integer? v:any):boolean
Return if a value is an integer type value.
Examples:
(integer? 123) ;; #t
(integer? "abc") ;; #f
eof?
(eof? v:any):boolean
Return if a value is an eof type value.
Examples:
(eof? (read whole-read-port)) ;; #t
Vector
vector
(vector ...):vector
Return a vector which has the elements given in the arguments.
Examples:
(vector 1 2 3) ;; '#(1 2 3)
make-vector
(make-vector size:integer [val:any]):vector
Return a vector with size elements, if val is provided, then use the value of val, if val is absent, use 0 as default element.
Examples;
(make-vector 0) ;; '#()
(make-vector 3) ;; '#(0 0 0)
(make-vector 3 123) ;; '#(123 123 123)
(make-vector 3 "str") ;; '#("str" "str" "str")
vector-length
(vector-length v:vector):integer
Return the length of a vector.
Examples:
(vector-length '#(1 2 3)) ;; 3
vector-ref
(vector-ref v:vector index:index):any
Return the specified element of a vector.
Examples:
(vector-ref '#(1 2 3) 0) ;; 1
(vector-ref '#(1 2 3) 1) ;; 2
(vector-ref '#(1 2 3) 2) ;; 3
vector-set!
(vector-set! v:vector index:integer value:any):void
Set the element of a vector.
Examples:
(define v '#(0 0 0))
(vector-set! v 0 1) ;; '#(1 0 0)
(vector-set! v 1 2) ;; '#(1 2 0)
(vector-set! v 2 3) ;; '#(1 2 3)
vector-fill!
(vector-fill! v:vector val:any):void
Set all elements of a vector to a given value.
Examples:
(define v '#(1 2 3))
(vector-fill! v 4) ;; '#(4 4 4)
vector->list
(vector->list v:vector):list
Return the list of a vector.
Examples:
(vector->list '#(1 2 3)) ;; '(1 2 3)
list->vector
(list->vector lst:list):vector
Return the vector of a list.
Examples:
(list->vector '(1 2 3)) ;; '#(1 2 3)