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:

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)