Справочник

Обзор стандартной библиотеки

Найдите стандартные функции для текста, чисел, коллекций, байтов и файлов и выберите способ обработки отсутствующих значений и ошибок.

Найдите стандартную функцию для своей задачи, от преобразования текста до чтения файла. Компилятор проверяет имена, члены типов и типы аргументов до выполнения.

Для запуска примеров установите Топаз по инструкции «Установка».

Выберите нужную возможность

ЗадачаС чего начатьКакой результат обработать
Вывести текст, разобрать число, проверить UnicodeБазовая библиотекаЗначение или Option
Преобразовать массив, найти ключ, убрать повторыМетоды коллекцийКоллекция, bool или Option
Собрать байты, вычислить контрольную сумму, сжать данныеБазовая библиотекаБайты, число или Result
Прочитать или записать файл целикомФайлы и ресурсыResult от std.fs
Держать файл открытым для нескольких операцийФайлы и ресурсыResult от io.open, затем освобождение через using или defer
Разобраться в выводе чисел, порядке коллекций и ошибках выполненияПоведение среды выполненияЗначение или ошибка, останавливающая выполнение

Повседневный пример

Сохраните код в overview.tpz.

TOPAZ
import std.io

let разобранное: Option<int> = "42".toInt()
let значения: Array<int> = [1, 2, 3]
let удвоенные = значения.map(значение => значение * 2)

io.writeLine("{разобранное}:{удвоенные}")

В каталоге с файлом выполните topaz run --language-version 5.21 overview.tpz.

Вывод
Some(42):[2, 4, 6]

"42".toInt() возвращает Some(42). Если заменить вход на "x", получится None. Оба результата имеют тип Option, поэтому вызывающий код может обработать неудачное преобразование. map удваивает каждый элемент массива, сохраняя порядок.

Используйте Result, когда операция возвращает причину ошибки, например при чтении файла. Ошибка выполнения, или fault, останавливает программу. Неверные имена и типы аргументов отклоняются при проверке. Способы обработки описаны в разделе Null, Option, Result и ошибки выполнения.

Найдите имена и импорты

Методы получателя, например string.toInt(), и конструкторы Some, None, Ok, Err доступны без импорта. Для io.writeLine и io.readStdin импортируйте std.io.

Создавайте значения через конструкторы типов, а операции выполняйте методами получателя. Разбор, сериализация, доступ к файлам и тестовые проверки находятся в соответствующих модулях std.*.

ЗадачаСтандартный API
Хранить упорядоченные элементыArray
Искать значения по ключуMap
Хранить уникальные элементыSet
Читать и записывать форматы данныхstd.json, std.csv, std.toml, URL
Хранить и собирать байтыBytes, ByteBuffer
Кодировать и сжимать данныеstring.encodeUtf8, методы Bytes
Вычислять хеши и контрольные суммыМетоды Bytes
Искать текст по шаблонуRegex, Match
Выполнять вычисления с числамиBigInt, Decimal
Работать с календарными датамиDate
Обращаться к файлам и строить путиstd.fs, Path
Разбирать аргументы командной строкиМетоды Array<string>
Разбивать абзацы на строки для вёрсткиstd.typeset
Проверять утверждения в тестовом профилеstd.test.assert

Код пакета может импортировать модули std.* из инструментария, в том числе функции для генераторов и парсеров. Импортированный модуль с совпадающим именем скрывает встроенное пространство имён в этом файле. Компилятор self и эталонный компилятор на Rust применяют одинаковые правила поиска имён.

Точные границы

Профиль задаёт доступные программе операции. Работа с файлами и другие операции среды также требуют поддержки со стороны окружения, запускающего Топаз. Импорт не даёт разрешений на файловую систему, сеть, процессы, переменные окружения, часы или базы данных.

  • Позиции в строке считают скаляры Unicode. Скаляр соответствует одной кодовой точке Unicode вне диапазона суррогатов. Байтовые API явно указывают подсчёт байтов.
  • Обход коллекций и снимки сохраняют установленный порядок.
  • Разбор и декодирование возвращают объявленный Option или Result.
  • Некорректная арифметика и обращение по недопустимому индексу могут остановить программу с ошибкой выполнения.
  • Тестовый профиль допускает std.test.assert. Остальные операции тестового фреймворка std.test он отклоняет. Проверка без --profile обрабатывает их как обычный импорт.
  • Неизвестные имена, модули и члены отклоняются при проверке. Проверьте написание и API нужного типа.

Куда перейти дальше