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

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

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

```lua
table.copy(t: table) -> table
```

Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.

```lua
table.deep_copy(t: table) -> table
```

Функция глубокого копирования создает полную копию исходной таблицы, включая все её вложенные таблицы.

```lua
table.count_pairs(t: table) -> integer
```

Возвращает количество пар в переданной таблице.

```lua
table.random(t: table) -> object
```

Возвращает один элемент из переданной таблицы на случайной позиции.

```lua
table.has(t: table, x: object) -> bool
```

Возвращает **true**, если **x** содержится в **t**.

```lua
table.index(t: table, x: object) -> integer
```

Возвращает индекс обьекта **x** в **t**. Если переданный обьект не содержится в таблице, то функция вернёт значение **-1**.

```lua
table.remove_value(t: table, x: object)
```

Удаляет элемент **x** из **t**.

```lua
table.shuffle(t: table) -> table
```

Перемешивает значения в таблице.

```lua
table.merge(t1: table, t2: table) -> table
```

Добавляет в таблицу **t1** значения из таблицы **t2**. Если в таблице **t2** присутствует ключ из **t1**, то значение ключа не будет изменено.

```lua
table.map(t: table, func: function(indx, value) ) -> table
```

Проходится по таблице и применяет ко всем её элементам **func**, которая возвращает новое значение элемента.

```lua
table.filter(t: table, func: function(indx, value) ) -> table
```

Проходится по таблице с помощью **func**, которая возвращает **true** если элемент надо сохранить и **false**, если его надо удалить.

```lua
table.set_default(t: table, key: number | string, default: any) -> any | default
```

Позволяет безопасно получать значение по указанному ключу. Если ключ существует в таблице, метод вернет его значение. Если ключ отсутствует, метод установит его со значением **default** и вернет его.

```lua
table.flat(t: table) -> table
```

Возвращает "плоскую" версию исходной таблицы.

```lua
table.deep_flat(t: table) -> table
```

Возвращает глубокую "плоскую" версию исходной таблицы.

```lua
table.sub(arr: table, start: number | nil, stop: number | nil) -> table
```

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

```lua
table.insert_unique(t: table, val: any)
table.insert_unique(t: table, pos: number, val: any)
```

Добавляет значение в таблицу, только если его там не было.

```lua
table.tostring(t: table) -> string
```

Конвертирует переданную таблицу в строку.

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

```lua
string.explode(separator: string, str: string, withpattern: bool) -> table[string]
```

Разбивает строку **str** на части по указанному разделителю/выражению **separator** и возвращает результат ввиде таблицы из строк. Если **withpattern** равен **true**, то параметр **separator** будет определяться как регулярное выражение.

```lua
string.split(str: string, delimiter: string) -> table[string]
```

Разбивает строку **str** на части по указанному разделителю **delimiter** и возвращает результат ввиде таблицы из строк.

```lua
string.pattern_safe(str: string)
```

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

```lua
string.formatted_time(seconds: number, format: string) -> string | table
```

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

```lua
string.replace(str: string, tofind: string, toreplace: string) -> string
```

Заменяет все подстроки в **str**, равные **tofind** на **toreplace** и возвращает строку со всеми измененными подстроками.

```lua
string.trim(str: string, char: string) -> string
```

Удаляет все символы, равные **char** из строки **str** с левого и правого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.

```lua
string.trim_left(str: string, char: string) -> string
```

Удаляет все символы, равные **char** из строки **str** с левого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.

```lua
string.trim_right(str: string, char: string) -> string
```

Удаляет все символы, равные **char** из строки **str** с правого конца и возвращает результат. Если параметр **char** не определен, то будут выбраны все пустые символы.

```lua
string.starts_with(str: string, start: string) -> bool
```

Возвращает **true**, если строка **str** начинается на подстроку **start**

```lua
string.ends_with(str: string, endStr: string) -> bool
```

Возвращает **true**, если строка **str** заканчивается на подстроку **endStr**

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

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

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

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

```lua
string.escape(str: string) -> string
```

Экранирует строку. Является псевдонимом `utf8.escape`.

```lua
string.pad(str: string, size: number, [опционально] char: string) -> string
```

Добавляет **char** слева и справа от строки, пока её размер не будет равен **size**. По стандарту **char** равен символу пробела

```lua
string.left_pad(str: string, size: number, [опционально] char: string) -> string
```

Добавляет **char** слева от строки, пока её размер не будет равен **size**. По стандарту **char** равен символу пробела

```lua
string.right_pad(str: string, size: number, [опционально] char: string) -> string
```

Добавляет **char** справа от строки, пока её размер не будет равен **size**. По стандарту **char** равен символу пробела

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

```lua
math.clamp(_in, low, high)
```

Ограничивает число **_in** по лимитам **low** и **high**. Т.е.: Если **_in** больше чем **high** - вернётся **high**, если **_in** меньше чем **low** - вернётся **low**. В противном случае вернётся само число.

```lua
math.rand(low, high)
```

Возвращает случайное дробное число в диапазоне от **low** до **high**.

```lua
math.normalize(num: number, [опционально] conf: num) -> number
```

Возвращает нормализованное значение num относительно conf.

```lua
math.round(num: number, [опционально] places: num) -> number
```

Возвращает округлённое значение num до указанного количества знаков после запятой places.

```lua
math.sum(x: number, ... | t: table) -> number
```

Возвращает сумму всех принимаемых аргументов. Если в качестве аргумента была передана таблица, метод вернёт сумму всех её элементов.

## Дополнительные глобальные функции

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


```lua
is_array(x: table) -> bool
```

Возвращает **true**, если переданная таблица является массивом, тоесть если каждый ключ это целое число больше или равное единице и если каждый ключ следует за прошлым.

```lua
function parse_path(path: string) -> string, string
```

Разбивает путь на две части и возвращает их: входную точку и путь к файлу.

```lua
function timeit(iters: integer, func: func, ...)
```

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

```lua
function sleep(timesec: number)
```

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

```lua
function await(co: coroutine) -> result, error
```

Ожидает завершение переданной корутины, возвращая поток управления. Функция может быть использована только внутри корутины.
Возвращает значения аналогичные возвращаемым значениям *pcall*.

```lua
os.pid -> number
```

Константа, в которой хранится PID текущего инстанса движка