Chapter 7. The Standard Library

The standard library provides functions for a range of tasks, including mathematical functions, functions for file and other input/ouput operations and introspection functions.

All functions from the standard library are contained in a list in the global variable lib. You are, of course, free to assign the functions you use most to other, more convenient, global variables.

Functions from the standard library are generally lax as to what they accept as arguments. It is up to you, the programmer, to make sure that you call the functions as described in the documentation. Generally, extra arguments, as well as named arguments, are ignored.

Functions will generally return nil instead of the specified return value when they are unsuccessful.

Mathematical functions

The mathematical functions are contained in the list lib.math.

lib.math.int(value, ...)
lib.math.round(value, ...)

These two functions return the integer value of an argument. If value is a floating-point number, it is rounded down by lib.math.int and rounded to the nearest integer by lib.math.round. However, if value is a large floating-point value that cannot be represented as an integer, or infinity, the original value is returned.

If value is a string or list, its integer value is its length. If value is a function or object, it is first called with no arguments to get its value.

Yewslip> print lib.math.int(2.7), lib.math.int(-0.1)
2 -1

Yewslip> print lib.math.round(0.5), lib.math.round(-0.5)
1 -1

Yewslip> print lib.math.int(nil, true, inf)
[0, 1, +(inf)]

Yewslip> print lib.math.round([], "string", func() return 42)
[0, 6, 42]

lib.math.min(value, ...)
lib.math.max(value, ...)

Return the minimum or maximum of the given arguments. Comparisons are performed in the same way as with the comparison operators. If no arguments are given, infinity is returned.

Some of the arguments may be lists, in which case each of their values is included in the comparison. If an argument is a function or object, it is first called with no arguments to get its value.

Yewslip> print lib.math.min(-1, [2, -3]), lib.math.min("abc", [1, 2, 3]), lib.math.min()
-3 1 +(inf)

Yewslip> print lib.math.max(3, [1, 1.2]), lib.math.max(7, func() return []), lib.math.max()
3 [] -(inf)

lib.math.mean(value, ...)

Returns the the sum of several values divided by their number, or nil if no values are given.

Some of the arguments may be lists, in which case each of their values is included in the sum. If an argument is a function or an object, it is first called with no arguments to get its value.

Yewslip> print lib.math.mean(), lib.math.mean(5), lib.math.mean([5:20])
(nil) 5 12

Yewslip> print lib.math.mean(123, "string")
123st

lib.math.log(value, ...)
lib.math.abs(value, ...)
lib.math.sin(value, ...)
lib.math.cos(value, ...)
lib.math.tan(value, ...)
lib.math.asin(value, ...)
lib.math.acos(value, ...)
lib.math.atan(value, ...)

lib.math.log returns the natural logarithm of an argument. lib.math.abs returns the absolute value of an argument. lib.math.sin, lib.math.cos and lib.math.tan return, respectively, the sine, cosine and tangent of an argument. lib.math.asin, lib.math.acos and lib.math.atan return, respectively, the arc sine, arc cosine and arc tangent of an argument.

The arguments to the trigonometric functions are given in radians. If an argument is not in the function domain, the functions return nil.

Each of these functions can take several arguments and return a list of results.

The value of π is available in the variable lib.math.pi. The base of the natural logarithm is available in lib.math.e.

Yewslip> print lib.math.log(1000) / lib.math.log(10), lib.math.log(lib.math.e)
3. 1.

Yewslip> print lib.math.abs(*[-3:3+1])
[3, 2, 1, 0, 1, 2, 3]

Yewslip> print lib.math.sin(lib.math.pi / 4), lib.math.cos(lib.math.pi)
0.707106781186547 -1.

Yewslip> print lib.math.tan(lib.math.pi / 4), lib.math.asin(-.5)
1. -0.523598775598299

Yewslip> print lib.math.acos(2), lib.math.atan(-1)
(nil) -0.785398163397448

lib.math.random(value, ...)

Returns a pseudo-random number. Without any arguments, a number between 0 and 1 is returned. If an integer argument is given, a pseudo-random non-negative integer number smaller than it is returned. If a floating-point argument is given, a pseudo-random non-negative floating-point number smaller than it is returned. If a string is given, a random character from it is returned. If a list is given, a random value from it is returned.

Yewslip> print lib.math.random(), lib.math.random(1000), lib.math.random(1000.)
0.44028807125999 649 747.477076364438

Yewslip> print lib.math.random("ABCDE", [-50:0])
[E, -7]

lib.math.and(value, ...)
lib.math.or(value, ...)
lib.math.xor(value, ...)

These functions perform, respectively, bitwise and, or and xor operations on their integer arguments.

Yewslip> print lib.math.and(7, 10), lib.math.and(-2, -3), lib.math.and(-2, 15, 13)
2 -4 12

Yewslip> print lib.math.or(7, 10), lib.math.or(-2, -3), lib.math.or(1, 2, 5)
15 -1 7

Yewslip> print lib.math.xor(7, 10), lib.math.xor(-2, -3), lib.math.xor(1, 2, 5)
13 3 6

lib.math.not(value, ...)

Returns the bitwise complement of the integer argument.

Yewslip> print lib.math.not(1, 17)
[-2, -18]

lib.math.shift(value, shift, size)
lib.math.ashift(value, shift, size)
lib.math.rotate(value, shift, size)

Returns the integer value, shifted or rotated by shift bits. A positive shift indicates a left-shift, while a negative shift indicates a right-shift. lib.math.shift performs a bitwise shift, lib.math.ashift performs an arithmetic shift and lib.math.rotate performs a bitwise rotation.

If size is specified, it limits the operation to the lower size bits of the argument.

Yewslip> print lib.math.shift(3, 2), lib.math.shift(7, -1)
0 0

Yewslip> print lib.math.ashift(-5, -1)
-1

Yewslip> print lib.math.rotate(12, 1, 4)
9