mirror of
https://github.com/MihailRis/voxelcore.git
synced 2026-10-06 19:41:51 +00:00
Improved docs (#708)
* начало переписи доков * extensions update * libapp update * libfile update * io_stream update * Update io_stream.md * io_stream update x3 * io_stream update x4 * libtime update * libgui update + make bytearray.md * libinput update * Update libapp.md * Update libapp.md * libgui update * events.md ru fix * да ну не надо так делать --> не имеет смысла, ибо гитхаб -> показывает адекватно * types refactoring * fixes * Update libblock.md * Update libblock.md * Update libbyteutil.md
This commit is contained in:
Xertis
MihailRis
parent
8b31bdeb78
commit
ac02bc0c8e
43 changed files with 1107 additions and 1314 deletions
|
|
@ -2,174 +2,73 @@
|
|||
|
||||
В скрипте ядра **stdmin.lua** определены функции, расширяющие и дополняющие некоторые из стандартных библиотек **Lua**
|
||||
|
||||
## Содержание:
|
||||
- [расширения для table](#расширения-для-table)
|
||||
- [расширения для string](#расширения-для-string)
|
||||
- [расширения для math](#расширения-для-math)
|
||||
- [расширения для bit](#расширения-для-bit)
|
||||
- [Дополнительные глобальные функции](#дополнительные-глобальные-функции)
|
||||
|
||||
## Расширения для table
|
||||
|
||||
```lua
|
||||
-- Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.
|
||||
table.copy(t: table) -> table
|
||||
```
|
||||
|
||||
Создаёт и возвращает копию переданной таблицы путём создания новой и копирования в неё всех элементов из переданной.
|
||||
|
||||
```lua
|
||||
-- Функция глубокого копирования создает полную копию исходной таблицы, включая все её вложенные таблицы.
|
||||
table.deep_copy(t: table) -> table
|
||||
```
|
||||
|
||||
Функция глубокого копирования создает полную копию исходной таблицы, включая все её вложенные таблицы.
|
||||
-- Возвращает количество пар в переданной таблице.
|
||||
table.count_pairs(t: table) -> int
|
||||
|
||||
```lua
|
||||
table.count_pairs(t: table) -> integer
|
||||
```
|
||||
-- Возвращает один элемент из переданной таблицы на случайной позиции.
|
||||
table.random(t: table) -> any
|
||||
|
||||
Возвращает количество пар в переданной таблице.
|
||||
-- Возвращает true, если x содержится в t.
|
||||
table.has(t: table, x: any) -> boolean
|
||||
|
||||
```lua
|
||||
table.random(t: table) -> object
|
||||
```
|
||||
-- Возвращает индекс объекта x в t. Если переданный объект не содержится в таблице, то функция вернёт значение -1.
|
||||
table.index(t: table, x: any) -> int
|
||||
|
||||
Возвращает один элемент из переданной таблицы на случайной позиции.
|
||||
-- Удаляет элемент x из t.
|
||||
table.remove_value(t: table, x: any)
|
||||
|
||||
```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
|
||||
-- Добавляет в таблицу t1 значения из таблицы t2. Если в таблице t2 присутствует ключ из t1, то значение ключа не будет изменено.
|
||||
table.merge(t1: table, t2: table) -> table
|
||||
```
|
||||
|
||||
Добавляет в таблицу **t1** значения из таблицы **t2**. Если в таблице **t2** присутствует ключ из **t1**, то значение ключа не будет изменено.
|
||||
-- Проходится по таблице и применяет ко всем её элементам func, которая возвращает новое значение элемента.
|
||||
table.map(t: table, func: function(indx, value)) -> table
|
||||
|
||||
```lua
|
||||
table.map(t: table, func: function(indx, value) ) -> table
|
||||
```
|
||||
-- Проходится по таблице с помощью func, которая возвращает true если элемент надо сохранить и false, если его надо удалить.
|
||||
table.filter(t: table, func: function(indx, value)) -> table
|
||||
|
||||
Проходится по таблице и применяет ко всем её элементам **func**, которая возвращает новое значение элемента.
|
||||
-- Позволяет безопасно получать значение по указанному ключу. Если ключ существует в таблице, метод вернет его значение.
|
||||
-- Если ключ отсутствует, метод установит его со значением default и вернет его.
|
||||
table.set_default(t: table, key: int | string, default: any) -> any
|
||||
|
||||
```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
|
||||
-- Возвращает обрезанную версию таблицы с индекса start до индекса stop включительно, при этом пары ключ-значение
|
||||
-- не сохраняются в новой таблице. При значениях nil начинает с 1 и заканчивает #arr соответственно.
|
||||
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)
|
||||
```
|
||||
table.insert_unique(t: table, pos: int, 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** можно использовать как мета-методы на экземплярах строк, т.е.:
|
||||
Важно подметить, что все ниже перечисленные функции, расширяющие **string** можно использовать как мета-методы на экземплярах строк, т.е.:
|
||||
|
||||
```lua
|
||||
local str = "ABA str BAB"
|
||||
|
|
@ -179,108 +78,126 @@ if str:starts_with("ABA") and str:ends_with("BAB") then
|
|||
end
|
||||
```
|
||||
|
||||
Также функции `string.lower` и `string.upper` переопределены на `utf8.lower` и `utf8.upper`
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Экранирует строку. Является псевдонимом `utf8.escape`.
|
||||
|
||||
```lua
|
||||
string.escape_xml(text: str) -> str
|
||||
```
|
||||
|
||||
Экранирует спец-символы XML. Является псевдонимом `utf8.escape_xml`.
|
||||
|
||||
```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 <= _in <= high
|
||||
-- Иначе возвращает границу, к которой ближе всего находится значение _in.
|
||||
math.clamp(_in: number, low: number, high: number) -> number
|
||||
|
||||
Ограничивает число **_in** по лимитам **low** и **high**. Т.е.: Если **_in** больше чем **high** - вернётся **high**, если **_in** меньше чем **low** - вернётся **low**. В противном случае вернётся само число.
|
||||
-- Возвращает случайное дробное число в диапазоне от low до high.
|
||||
math.rand(low: number, high: number) -> number
|
||||
|
||||
```lua
|
||||
math.rand(low, high)
|
||||
```
|
||||
-- Возвращает нормализованное значение num относительно conf.
|
||||
math.normalize(num: number, [опционально] conf: number) -> number
|
||||
|
||||
Возвращает случайное дробное число в диапазоне от **low** до **high**.
|
||||
-- Возвращает округлённое значение num до указанного количества знаков после запятой places.
|
||||
math.round(num: number, [опционально] places: number) -> number
|
||||
|
||||
```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
|
||||
|
||||
```
|
||||
|
||||
Возвращает сумму всех принимаемых аргументов. Если в качестве аргумента была передана таблица, метод вернёт сумму всех её элементов.
|
||||
## Расширения для 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
|
||||
is_array(x: table) -> bool
|
||||
```
|
||||
-- Возвращает true, если переданная таблица является массивом, то есть если каждый ключ — это целое число больше или равное единице
|
||||
-- и если каждый ключ следует за прошлым.
|
||||
is_array(x: table) -> boolean
|
||||
|
||||
Возвращает **true**, если переданная таблица является массивом, тоесть если каждый ключ это целое число больше или равное единице и если каждый ключ следует за прошлым.
|
||||
-- Разбивает путь на две части и возвращает их: входную точку и путь к файлу.
|
||||
parse_path(path: string) -> string, string
|
||||
|
||||
```lua
|
||||
function parse_path(path: string) -> string, string
|
||||
```
|
||||
-- Вызывает функцию func iters раз, передавая ей аргументы ..., а после выводит в консоль время в микросекундах,
|
||||
-- которое прошло с момента вызова timeit.
|
||||
timeit(iters: int, func: function, ...)
|
||||
|
||||
Разбивает путь на две части и возвращает их: входную точку и путь к файлу.
|
||||
-- Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в timesec.
|
||||
-- Функция может быть использована только внутри корутины.
|
||||
sleep(timesec: number)
|
||||
|
||||
```lua
|
||||
function timeit(iters: integer, func: func, ...)
|
||||
```
|
||||
-- Ожидает завершение переданной корутины, возвращая поток управления. Функция может быть использована только внутри корутины.
|
||||
-- Возвращает значения аналогичные возвращаемым значениям pcall.
|
||||
await(co: coroutine) -> result, error
|
||||
|
||||
Вызывает функцию **func** **iters** раз, передавая ей аргументы `...`, а после выводит в консоль время в микросекундах, которое прошло с момента вызова **timeit**.
|
||||
|
||||
```lua
|
||||
function sleep(timesec: number)
|
||||
```
|
||||
|
||||
Вызывает остановку корутины до тех пор, пока не пройдёт количество секунд, указанное в **timesec**. Функция может быть использована только внутри корутины.
|
||||
|
||||
```lua
|
||||
function await(co: coroutine) -> result, error
|
||||
```
|
||||
|
||||
Ожидает завершение переданной корутины, возвращая поток управления. Функция может быть использована только внутри корутины.
|
||||
Возвращает значения аналогичные возвращаемым значениям *pcall*.
|
||||
|
||||
```lua
|
||||
-- Константа, в которой хранится PID текущего инстанса движка.
|
||||
os.pid -> number
|
||||
```
|
||||
|
||||
Константа, в которой хранится PID текущего инстанса движка
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue