## 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
```
```