Начинайте с задачи, а не с перечня API. Стандартная библиотека предоставляет небольшой проверяемый набор средств для работы со значениями, коллекциями, файлами и окружением. Неизвестное имя или метод отклоняется при проверке, а не разрешается динамически в языке целевой платформы.
Выберите нужную возможность
| Задача | С чего начать | Вид неудачи |
|---|---|---|
| Вывести текст, преобразовать значение, разобрать Unicode или применить функцию к значениям | Базовая библиотека | Значение, Option или объявленный функцией Result |
| Хранить упорядоченные элементы, искать ключи или убирать повторы | Операции с коллекциями | Обычно значение, bool или Option |
| Прочитать или записать файл целиком | FS.readText, FS.writeText, FS.readBytes или FS.writeBytes | Result |
| Держать файл открытым для нескольких операций | open вместе с using или defer | Result и лексическое освобождение ресурса |
| Понять вывод, числа, порядок или аварийную остановку | Поведение среды выполнения | Определённое значение или явная ошибка выполнения |
Для упорядоченных элементов выбирайте Array, для поиска значения по ключу — Map, а для множества уникальных значений — Set.
Используйте Option, когда отсутствие значения — нормальный результат, например при поиске по ключу. Используйте Result, когда внешние данные или операция среды могут завершиться с содержательной ошибкой. Fault означает нарушение контракта во время выполнения, а неверный вызов или тип даёт статическую диагностику.
Повседневный пример
Программа разбирает текст и преобразует массив. toInt возвращает Option, поскольку в тексте может отсутствовать целое число. map создаёт новый массив с сохранением порядка исходных элементов.
let разобранное: Option<int> = toInt("42")
let значения: Array<int> = Array.of(1, 2, 3)
let удвоенные = map(значения, значение => значение * 2)
print("{разобранное}:{удвоенные}")Some(42):[2, 4, 6]Some(42) явно указывает на успешное преобразование. Если текст не содержит целого числа, первая часть принимает значение None. Библиотека не подставляет ноль и не бросает перехватываемое исключение.
Как устроена библиотека
Функции и конструкторы print, toInt, Some, None, Ok, Err, map, filter и reduce доступны без импорта. Встроенные пространства имён объединяют специализированные семейства API, такие как Math, Bytes, Hash, FS и Path. В пакетах также доступны фиксированные модули std.* текущего инструментария. Это проверяемые экспорты, а не динамические пространства имён платформы.
Расширенная поверхность API включает кодировки, хеши, пути, аргументы командной строки, регулярные выражения, CSV, TOML, JSON, URL, даты, большие целые и десятичные числа, генераторы, парсеры и ограниченные возможности среды. Точную сигнатуру и целевые ограничения смотрите на соответствующей странице и не предполагайте наличия аналогичного API платформы.
Частая ошибка: сам по себе импорт стандартного модуля не даёт доступ к файловой системе, сети, часам, переменным окружения, процессам или базе данных. Операции со средой работают только в профиле и окружении с соответствующей возможностью.
Точные границы
- Позиции в строке отсчитываются в скалярах Unicode, если API явно не указывает на байты.
- Итерация по коллекциям и снимки состояния сохраняют документированный порядок.
- Разбор и декодирование сохраняют объявленный способ обработки ошибок
OptionилиResult. - Некорректная арифметика и нарушения контрактов не превращаются неявно в другое значение.
Test.*, свободная функцияassertиstd.testдоступны только в тестовом профиле.- Неизвестные имена, виртуальные модули и методы дают статическую диагностику.