# Расширения стандартных библиотек

В скрипте ядра **stdmin.lua** определены функции, расширяющие и дополняющие некоторые из стандартных библиотек **Lua**

## Содержание:
- [расширения для table](#расширения-для-table)
- [расширения для string](#расширения-для-string) 
- [расширения для math](#расширения-для-math)
- [расширения для bit](#расширения-для-bit)
- [Дополнительные глобальные функции](#дополнительные-глобальные-функции)

## Расширения для table
```lua
-- Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.
table.copy(t: table) -> table

-- Функция глубокого копирования создает полную копию исходной таблицы, включая все её вложенные таблицы.
table.deep_copy(t: table) -> table

-- Возвращает количество пар в переданной таблице.
table.count_pairs(t: table) -> int

-- Возвращает один элемент из переданной таблицы на случайной позиции.
table.random(t: table) -> any

-- Возвращает true, если x содержится в t.
table.has(t: table, x: any) -> boolean

-- Возвращает индекс объекта x в t. Если переданный объект не содержится в таблице, то функция вернёт значение -1.
table.index(t: table, x: any) -> int

-- Удаляет элемент x из t.
table.remove_value(t: table, x: any)

-- Перемешивает значения в таблице.
table.shuffle(t: table) -> table

-- Добавляет в таблицу t1 значения из таблицы t2. Если в таблице t2 присутствует ключ из t1, то значение ключа не будет изменено.
table.merge(t1: table, t2: table) -> table

-- Проходится по таблице и применяет ко всем её элементам func, которая возвращает новое значение элемента.
table.map(t: table, func: function(indx, value)) -> table

-- Проходится по таблице с помощью func, которая возвращает true если элемент надо сохранить и false, если его надо удалить.
table.filter(t: table, func: function(indx, value)) -> table

-- Позволяет безопасно получать значение по указанному ключу. Если ключ существует в таблице, метод вернет его значение. 
-- Если ключ отсутствует, метод установит его со значением default и вернет его.
table.set_default(t: table, key: int | string, default: any) -> any

-- Возвращает "плоскую" версию исходной таблицы.
table.flat(t: table) -> table

-- Возвращает глубокую "плоскую" версию исходной таблицы.
table.deep_flat(t: table) -> table

-- Возвращает обрезанную версию таблицы с индекса start до индекса stop включительно, при этом пары ключ-значение 
-- не сохраняются в новой таблице. При значениях nil начинает с 1 и заканчивает #arr соответственно.
table.sub(arr: table, start: number | nil, stop: number | nil) -> table

-- Добавляет значение в таблицу, только если его там изначально не было.
table.insert_unique(t: table, val: any)
table.insert_unique(t: table, pos: int, val: any)

-- Конвертирует переданную таблицу в строку.
table.tostring(t: table) -> string
```

## Расширения для string

Важно подметить, что все ниже перечисленные функции, расширяющие **string** можно использовать как мета-методы на экземплярах строк, т.е.: 

```lua
local str = "ABA str BAB"

if str:starts_with("ABA") and str:ends_with("BAB") then
	print(str:replace("BA", "DC"))
end
```

```lua
-- Разбивает строку str на части по указанному разделителю/выражению separator и возвращает результат ввиде таблицы из строк. Если withpattern равен true, то параметр separator будет определяться как регулярное выражение.
string.explode(separator: string, str: string, withpattern: boolean) -> table<string>

-- Разбивает строку str на части по указанному разделителю delimiter и возвращает результат ввиде таблицы из строк.
string.split(str: string, delimiter: string) -> table<string>

-- Экранирует специальные символы в строке, такие как `()[]+-.$%^?*` в формате `%символ`. Символ `NUL` (`\0`) будет преобразован в `%z`.
string.pattern_safe(str: string) -> string

-- Разбивает секунды на часы, минуты и миллисекунды и форматирует в format с следующим порядком параметров: `минуты, секунды, миллисекунды` и после возвращает результат. Если format не указан, то возвращает таблицу, где: 
-- h - hours, 
-- m - minutes, 
-- s - seconds, 
-- ms - milliseconds.
string.formatted_time(seconds: number, format: string) -> string | table

-- Заменяет все подстроки в str, равные tofind на toreplace и возвращает строку со всеми измененными подстроками.
string.replace(str: string, tofind: string, toreplace: string) -> string

-- Удаляет все символы, равные char из строки str с левого и правого конца и возвращает результат. 
-- Если параметр char не определен, то будут выбраны все пустые символы.
string.trim(str: string, char: string) -> string

-- Удаляет все символы, равные char из строки str с левого конца и возвращает результат. 
-- Если параметр char не определен, то будут выбраны все пустые символы.
string.trim_left(str: string, char: string) -> string

-- Удаляет все символы, равные char из строки str с правого конца и возвращает результат. 
-- Если параметр char не определен, то будут выбраны все пустые символы.
string.trim_right(str: string, char: string) -> string

-- Возвращает true, если строка str начинается на подстроку start.
string.starts_with(str: string, start: string) -> boolean

-- Возвращает true, если строка str заканчивается на подстроку endStr.
string.ends_with(str: string, endStr: string) -> boolean

-- Также функции string.lower и string.upper переопределены на utf8.lower и utf8.upper.

-- Экранирует строку. Является псевдонимом utf8.escape.
string.escape(str: string) -> string

-- Экранирует спец-символы XML. Является псевдонимом utf8.escape_xml.
string.escape_xml(text: string) -> string

-- Добавляет char слева и справа от строки, пока её размер не будет равен size. 
-- По стандарту char равен символу пробела.
string.pad(str: string, size: int, char: string) -> string

-- Добавляет char слева от строки, пока её размер не будет равен size. 
-- По стандарту char равен символу пробела.
string.left_pad(str: string, size: int, char: string) -> string

-- Добавляет char справа от строки, пока её размер не будет равен size. 
-- По стандарту char равен символу пробела.
string.right_pad(str: string, size: int, char: string) -> string
```

## Расширения для math

```lua
-- Возвращает _in, если оно находится в диапозоне low <= _in <= high
-- Иначе возвращает границу, к которой ближе всего находится значение _in.
math.clamp(_in: number, low: number, high: number) -> number

-- Возвращает случайное дробное число в диапазоне от low до high.
math.rand(low: number, high: number) -> number

-- Возвращает нормализованное значение num относительно conf.
math.normalize(num: number, [опционально] conf: number) -> number

-- Возвращает округлённое значение num до указанного количества знаков после запятой places.
math.round(num: number, [опционально] places: number) -> number

-- Возвращает сумму всех принимаемых аргументов. Если в качестве аргумента была передана таблица, метод вернёт сумму всех её элементов.
math.sum(x: number, ... | t: table) -> number

-- Возвращает целое число, указывающее знак числа (-1/0/1)
math.sign(x: number) -> int
```

## Расширения для bit
```lua

-- Общие аргументы:
-- * expr: Строка с побитовым выражением, соответствует формату побитовых операций в Lua 5.3
-- * args: Список имён аргументов выражения. Если nil, список автоматически формируется на основе обнаруженных идентификаторов.

-- Компилирует функцию для выполнения побитовых операций
-- * asFunction: при значении true возвращает функцию, иначе строку кода функции
bit.compile(expr: string, args: table | nil, asFunction: boolean=true) -> function | string


-- Компилирует функцию для выполнения побитовых операций и на месте выполняет её
-- * ...: Значения, которые будут переданы в скомпилированную функцию.
bit.execute(expr: string, args: table | nil, ...) -> number
```
## Дополнительные глобальные функции

В этом же скрипте также определены и другие глобальные функции которые доступны для использования. Ниже их список

```lua
-- Возвращает true, если переданная таблица является массивом, то есть если каждый ключ — это целое число больше или равное единице 
-- и если каждый ключ следует за прошлым.
is_array(x: table) -> boolean

-- Разбивает путь на две части и возвращает их: входную точку и путь к файлу.
parse_path(path: string) -> string, string

-- Вызывает функцию func iters раз, передавая ей аргументы ..., а после выводит в консоль время в микросекундах, 
-- которое прошло с момента вызова timeit.
timeit(iters: int, func: function, ...)

-- Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в timesec. 
-- Функция может быть использована только внутри корутины.
sleep(timesec: number)

-- Ожидает завершение переданной корутины, возвращая поток управления. Функция может быть использована только внутри корутины.
-- Возвращает значения аналогичные возвращаемым значениям pcall.
await(co: coroutine) -> result, error

-- Константа, в которой хранится PID текущего инстанса движка.
os.pid -> number
```