Справочник по стандартной библиотеке

Стандартная библиотека YaoXiang (std) организована по модулям; каждый модуль импортируется через use и затем вызывается как имя_модуля.имя_функции(...). Данный раздел представляет собой справочную документацию по API, разделённую по модулям.

Индекс модулей

Модуль	Экспортов	Описание
std.convert	11	Преобразование произвольного значения в String
std.dict	11	Чтение/запись словаря, представления ключей/значений и слияние
std.io	7	Стандартный вывод, стандартный ввод и чтение/запись файлов целиком
std.math	18	Целочисленные, вещественные и тригонометрические функции, включая константы PI/E/TAU
std.string	19	Поиск в строках, разбиение, форматирование и разбор
std.time	14	Метки времени, форматирование и доступ к полям DateTime
std.result	9	Конструирование и распаковка Result и Error
std.range	10	Итерация по диапазонам, предикаты и ленивые адаптеры
std.assert	1	Утверждения
std.net	4	HTTP-запросы и URL percent-encoding
std.concurrent	3	Засыпание, уступка планировщику и идентификатор потока
std.os	22	Файловые дескрипторы, каталоги, переменные среды и рабочий каталог
std.weak	2	Слабые ссылки Arc / Weak

Соглашения об импорте

Импорт модуля целиком:

use std.list
use std.string

main: () -> Void = {
    parts = string.split("a,b,c", ",")
    println(list.len(parts))
}

Также можно импортировать из модуля по имени, включая константы:

use std.assert
use std.math.{E, PI, TAU}

main: () -> Void = {
    assert(PI > 3.14)
}

Соглашения о заимствовании параметров

Символ & в сигнатуре обозначает автоматическое заимствование только для чтения (RFC-009 §2.8): переменная, переданная вызывающей стороной, не перемещается и остаётся доступной после вызова. Это форма по умолчанию для большого числа функций только-для-чтения в стандартной библиотеке.

use std.assert
use std.list

main: () -> Void = {
    nums = [1, 2, 3]

    // 三处调用都只读借用 nums，之后仍可用
    assert(list.len(nums) == 3)
    assert(list.len(nums) == 3)
    assert(list.contains(nums, 2))
}

Параметры без & означают передачу по значению. Поэтому большинство «модифицирующих» функций имеют функциональную форму, поглощающую исходное значение и возвращающую новое, а не изменение на месте:

use std.assert
use std.list

main: () -> Void = {
    base = [1, 2]
    extended = list.push(base, 3)   // 返回新列表；base 已被移动
    assert(list.len(extended) == 3)
}

Раздел «Семантическая классификация» на странице каждого модуля перечисляет, какие функции модуля заимствуют, какие поглощают, а какие изменяют на месте. Есть один момент, требующий особого внимания:

• сигнатуры list.pop / list.remove_at помечены как &List(A), однако изменяют список на месте

Модель ошибок

В стандартной библиотеке есть два вида сбоев; в описаниях функций они отмечаются соответственно как «ошибка» и «возвращает …»:

Вид	Поведение	Типичный сценарий
Выброс ошибки выполнения	Прерывает текущее выполнение с кодом E6xxx	Отсутствующий ключ словаря E6008, выход за границы индекса E6003, сбой утверждения
Возврат контрольного значения	Не прерывает, возвращает Void / -1 / ""	Чтение списка за границами, взятие первого элемента пустого списка, отсутствующая переменная среды

Распространённые коды ошибок выполнения:

Код	Значение	Пример срабатывания
E6003	Выход за границы индекса	list.set(l, 99, v)
E6005	Сбой утверждения	assert(false)
E6007	Общая ошибка выполнения	Файл не существует, сбой result.unwrap
E6008	Отсутствующий ключ	dict.get(d, "nope")
E6010	Сбой разбора целого числа (как значение Err)	string.parse_int("abc")
E6011	Сбой разбора вещественного числа (как значение Err)	string.parse_float("abc")

Полную таблицу кодов ошибок см. в Справочнике по кодам ошибок.

string.parse_int / string.parse_float относятся к третьему виду: не выбрасывают ошибку, а упаковывают сбой в значение Err типа Result, которое можно распаковать с помощью std.result или распространить через ?.

use std.assert
use std.result
use std.string

main: () -> Void = {
    assert(result.is_ok(string.parse_int("42")))
    assert(result.is_err(string.parse_int("abc")))
}

Протокол итерации

std.list и std.range предоставляют один и тот же протокол итераторов. Сам итератор является носителем состояния типа Tuple.

Семантика перемещения: и next, и has_next перемещают итератор (в сигнатуре нет &), поэтому при каждом использовании его нужно создавать заново либо сразу использовать for ... in.

use std.assert
use std.list

main: () -> Void = {
    it = list.iter([1, 2, 3])
    assert(list.has_next(it))

    // has_next 移动了 it，重新创建后再取元素
    it2 = list.iter([1, 2, 3])
    assert(list.next(it2) == 1)
}

Для повседневного обхода сразу используйте for ... in:

use std.assert

main: () -> Void = {
    mut sum = 0
    for x in [1, 2, 3] {
        sum = sum + x
    }
    assert(sum == 6)
}

range.map / range.filter возвращают ленивые адаптеры, которые выдают результат только после потребления через collect / reduce / for_each / for ... in:

use std.assert
use std.list
use std.range
use std.result

main: () -> Void = {
    doubled = range.collect(range.map(result.unwrap(range.iter(1..4)), x => x * 2))
    assert(list.get(doubled, 0) == 2)
    assert(list.len(doubled) == 3)
}

Доступность по платформам

Следующее содержимое зависит от возможностей ОС и не экспортируется на целевой платформе wasm32:

Область	Требует
std.os целиком, std.net целиком, std.weak целиком	Файлы/сеть
std.concurrent целиком	Потоки
std.io.read_line / read_file / write_file / append_file	Стандартный ввод-вывод
std.time.sleep	Засыпание потока

std.string / std.list / std.dict / std.math / std.convert / std.result / std.range / std.assert, а также std.io.print / println / format_fallback доступны на всех целевых платформах.

Реализованные пробелы

Следующие проблемы были поочерёдно подтверждены реальным запуском примеров при написании документации, для всех открыты issue для отслеживания.

Исправлено (2026-09-19): все четыре пункта #337 / #338 / #339 / #340 исправлены, основной текст соответствующих страниц синхронно переписан под нормальное использование:

Расположение	Исходная проблема	Исправление
os.open	Дескриптор одноразовый, open→write→close не компилируется	Дескриптор передаётся по ссылке ✅
time.datetime_*	8 аксессоров нельзя вызвать из исходного кода (имя экспорта содержит ::)	Переход на плоские имена datetime_year и т. д. ✅
time.parse_time	Параметр fmt игнорировался; возвращаемое значение нельзя использовать дальше	Пошаговый разбор по fmt ✅
math.clamp	При min > max интерпретатор паниковал вместо возврата ошибки	Возвращает E6007 ✅

Всё ещё открыто:

Расположение	Проблема	Отслеживание
net.http_get / http_post	Заглушка, не отправляет запрос, возвращает строку-описание	#56

Поддержка документации

Данный раздел представляет собой гибридную структуру сгенерированного и написанного вручную контента:

• Сгенерированная область (между маркерами <!-- stdlib:KEY start/end -->): сводные таблицы функций и блоки сигнатур, порождённые из StdModule::exports(). Сигнатуры побайтово берутся из NativeExport::signature и не могут расходиться с реализацией.
• Написанная вручную область (вне маркеров): обзоры модулей, семантика заимствования/перемещения, модель ошибок, известные пробелы и примеры.

Контрольные проверки (запускаются в CI вместе с cargo test --lib):

Проверка	Тест	Назначение
Обнаружение расхождений	test_stdlib_docs_match_generation	Сгенерированная область должна совпадать с exports()
Обнаружение сирот	test_stdlib_docs_has_no_orphan_module_pages	Страниц модулей не должно быть больше, чем выдаёт генератор
Покрытие	test_stdlib_docs_covers_interface_modules	Набор документированных модулей должен покрывать представление интерфейсов
Примеры запускаемы	test_stdlib_docs_examples_run	Каждый yaoxiang-пример должен действительно запускаться

После изменения exports() используйте инструмент лечения для перезаписи сгенерированной области:

cargo run --example gen-stdlib-docs

Аналогично gen-std-interfaces (представление интерфейсов RFC-037), tools/code-tables --fix (таблица кодов RFC-013).

Связанные документы

• Спецификация стандартной библиотеки — соглашения о проектировании стандартной библиотеки на уровне языка
• Спецификация FFI — пользовательские native-расширения и привязки к C ABI
• Справочник по кодам ошибок — полная таблица кодов ошибок выполнения E6xxx