Standard library reference

The library sits next to the compiler and is written in flang itself. Every function in it goes through the same path your program does: parsing, types, termination, examples. Below is a section per module and a table of all its functions.

использует is the import. A module is attached by name — no path needed:

модуль «Моя программа»
  использует «Lists»

The WHOLE module comes in, and the printed code carries all of it. Need a single function — name it:

  использует «Lists» только «Сумма»

только does not pull in what the named function calls. Ask for «Двоичный поиск» without «Поиск в диапазоне» and the compiler answers:

FLANG_UNKNOWN_NAME, строка 569, столбец 3: неизвестная функция «Поиск в диапазоне»
FLANG_NOT_TOTAL, строка 569, столбец 3: тотальная функция «Двоичный поиск» вызывает неизвестную функцию «Поиск в диапазоне»: завершение доказать нельзя

Add the missing name after a comma — or take the module whole.

In the tables below, “takes” and “returns” are the signature from the source, word for word. “What it does” is the function’s postcondition — the обеспечивает line of its declaration — also word for word, and in Russian like the code. Hence the author’s turns of phrase inside it: «довод» means argument, «октеты» means bytes.

Where to start

Nine modules cover almost everything written day to day. Each comes with a whole program you can copy and check.

Lists

Lists of any values and lists of numbers: length, slice, range, search, folds, sorting.

Import: использует «Lists».

A whole program — checked by flang check:

модуль «Проба списков»
  использует «Lists»

тотальная функция «Сумма чисел до предела»
  принимает предел: число
  возвращает число
  пример «До пяти»
    дано предел равно 5
    ожидается 15
  «Сумма» от («Числа до» от предел)

Strings

Strings as data: split, replace, case, prefix and suffix, character tests, padding to width.

Import: использует «Strings».

A whole program — checked by flang check:

модуль «Проба строк»
  использует «Strings»

тотальная функция «Слово задом наперёд»
  принимает текст: строка
  возвращает строка
  пример «Слово»
    дано текст равно " шалаш "
    ожидается "шалаш"
  «Обратить строку» от («Обрезать пробелы» от текст)

Numbers

Numbers: sign, absolute value, integer division, GCD and LCM, power, factorial, digits.

Import: использует «Numbers».

A whole program — checked by flang check:

модуль «Проба чисел»
  использует «Numbers»

тотальная функция «Доля в процентах»
  принимает часть: число, целое: число
  возвращает число
  пример «Половина»
    дано часть равно 1
    дано целое равно 2
    ожидается 50
  «Ограничить» от («Целочисленное деление» от (часть умножить на 100) и целое) и 0 и 100

Optional

A value that may be missing: present or absent, over any type.

Import: использует «Optional».

Types: «Возможно».

A whole program — checked by flang check:

модуль «Проба опции»
  использует «Optional»

тотальная функция «Первое или ноль»
  принимает элементы: список числа
  возвращает число
  пример «Пустой список»
    дано элементы равно пустой список
    ожидается 0
  «Первый элемент или запасное» от элементы и 0

Result

The outcome of a computation: success with a value, or an error with a reason.

Import: использует «Result».

Types: «Результат».

A whole program — checked by flang check:

модуль «Проба результата»
  использует «Result»

тотальная функция «Деление на ноль не роняет»
  принимает делимое: число, делитель: число
  возвращает число
  пример «Ноль в делителе»
    дано делимое равно 10
    дано делитель равно 0
    ожидается -1
  «Деление или запасное» от делимое и делитель и -1

Higher order

Functions as values: map, filter, fold, sort by your own order.

Import: использует «Higher order».

A whole program — checked by flang check:

модуль «Проба высшего порядка»
  использует «Higher order»

тотальная функция «Сумма квадратов»
  принимает элементы: список числа
  возвращает число
  пример «Три числа»
    дано элементы равно [1, 2, 3]
    ожидается 14
  «Свернуть» от функция «Сложить» и 0 и («Отобразить» от функция «Возвести в квадрат» и элементы)

Dictionary

A string → string map built as a list of pairs. Lookup is linear: a thousand keys behave like a thousand-element list.

Import: использует «Dictionary».

Types: «Связь».

A whole program — checked by flang check:

модуль «Проба словаря»
  использует «Dictionary»

тотальная функция «Значение по ключу связью»
  принимает ключ: строка
  возвращает строка
  пример «Ключа нет»
    дано ключ равно "рост"
    ожидается "нет"
  пусть словарь равно («Положить» от пустой список и "цвет" и "синий")
  «Взять или запасное» от словарь и ключ и "нет"

Hash map

A string → string map with constant-time access: a trie over hash digits.

Import: использует «Hash map».

Types: «Звено», «Узел хеша».

A whole program — checked by flang check:

модуль «Проба словаря хешем»
  использует «Hash map»

тотальная функция «Значение по ключу»
  принимает ключ: строка
  возвращает строка
  пример «Ключ найден»
    дано ключ равно "цвет"
    ожидается "синий"
  пусть словарь равно («Положить в словарь» от («Словарь из ключей» от пустой список) и "цвет" и "синий")
  «Найти в словаре» от словарь и ключ и "нет"

JSON

JSON as a value: tokenizing, parsing, printing. It never touches the outside world.

Import: использует «JSON».

Types: «Значение json», «Поле json», «Итог json», «Знак json», «Разметка json», «Счёт json», «Исход числа json», «Рамка json», «Ход json».

A whole program — checked by flang check:

модуль «Проба json»
  использует «JSON»

тотальная функция «Разобрать и напечатать»
  принимает текст: строка
  возвращает строка
  пример «Массив печатается обратно»
    дано текст равно "[1,2]"
    ожидается "[1,2]"
  разбор («Разобрать json» от текст)
    случай вариант «Разобран json» с значение как значение
      то «Напечатать json» от значение
    случай вариант «Не разобран json» с причина как причина
      то причина

Written most recently

Five modules are younger than the rest. For each one: what it can do and what it cannot.

AES

The AES-128 cipher: a single block, counter mode (CTR) and GCM with tag verification.

Import: использует «AES».

Types: «Ход шифра», «Ход счёта», «Ход гаммы», «Ход поля», «Ход сдвига», «Ход GHASH», «Ход гаммы GCM», «Печать GCM», «Исход GCM».

X25519

X25519 key exchange on Curve25519 — RFC 7748.

Import: использует «X25519».

Types: «Ход переноса», «Ход займа», «Ход лестницы».

DER

Parsing DER — the binary ASN.1 encoding from X.690, the one certificates are written in.

Import: использует «DER».

X.509

Parsing an X.509 certificate — RFC 5280: fields, names, validity, key.

Import: использует «X.509».

SQLite

Reading a SQLite 3 database file: header, pages, cells, values.

Import: использует «SQLite».

Types: «Варинт», «Сбор варинтов», «Сбор указателей», «Значение», «Ряд», «Таблица».

The module reads октеты — the list of bytes of the file. It cannot open a file and is not meant to: the bytes are brought in by a plan. A plan is a program that hands one piece of work with the world at a time to the host (flang io) and gets a reply back; here there is one order — «Прочитать октеты из файла».

Make a sample file with a third-party sqlite3, so there is something to check against. The page size is set explicitly so that the numbers below match yours:

python3 -c "import sqlite3; c=sqlite3.connect('база.db'); \
  c.execute('pragma page_size=1024'); c.execute('vacuum'); \
  c.execute('create table люди(имя text, лет integer)'); \
  c.executemany('insert into люди values (?,?)', [('Аня',31),('Боря',44),('Вера',7)]); \
  c.commit()"

модуль «Заголовок базы»
  использует «SQLite»

тип «Ход»
  вариант «Начало»
  вариант «Ждём октеты»

тотальная функция «Начало хода»
  возвращает «Ход»
  вариант «Начало»

тотальная функция «Отчёт»
  принимает октеты: список числа
  возвращает строка
  соединить [
      "это база SQLite: ", (если («Это база SQLite» от октеты) то "да" иначе "нет"),
      "\nразмер страницы: ", (к строке («Размер страницы» от октеты)),
      "\nстраниц: ", (к строке («Страниц в базе» от октеты)),
      "\nтаблицы: ", (соединить («Имена таблиц» от октеты) по ", ")
    ] по ""

тотальная функция «Дальше»
  принимает ход: «Ход», отклик: «Отклик»
  возвращает «Продолжение»
  разбор ход
    случай вариант «Начало»
      то вариант «Сделать» с поручение равным (вариант «Прочитать октеты из файла» с путь равным "база.db") и потом равным (вариант «Ждём октеты»)
    случай вариант «Ждём октеты»
      то разбор отклик
        случай вариант «Октеты» с октеты как октеты
          то вариант «Конец работы» с значение равным («Отчёт» от октеты)
        случай любое
          то вариант «Провал» с код равным "FLANG_IO_ORDER" и сообщение равным "ждали октетов"

план «Заголовок»
  состояние «Ход»
  начинает с «Начало хода»
  обрабатывает «Дальше»

flang io заголовок.flang

{"plan":"Заголовок","result":"это база SQLite: да\nразмер страницы: 1024\nстраниц: 2\nтаблицы: люди","orders":1}

What this module will not give you today. The header, the schema and the table names read fine; on row values the evaluation runs into the step limit. The plan examples/db/sqlite-read.flang, which also prints the rows of a table, answers this on a 2 KiB database:

FLANG_RECURSION_LIMIT: функция «Кодовые точки из байтов» исчерпала лимит шагов (10000000) на глубине вызовов 19

UTF-8 decoding walks one byte at a time by recursion, and starts over on every cell. While that is so, read the header and the schema through this module, not the contents.

The rest of the modules

Key derivation

Deriving a key from a password: PBKDF2-HMAC-SHA256, RFC 8018.

Import: использует «Key derivation».

Types: «Ход вывода».

Date and time

Dates and times as values: ISO-8601 parsing, addition, difference, leap years, weekdays. It never asks what time it is — time arrives as an argument.

Import: использует «Date and time».

Types: «Календарный день», «Часы», «Отметка», «Итог даты».

Requests and responses

The pure half of HTTP: parsing and printing requests and responses, headers, status codes, URLs, percent-encoding.

Import: использует «Requests and responses».

Types: «Заголовок», «Запрос», «Ответ», «Разбор запроса», «Разбор заголовков», «Разбор тела», «Длина тела», «Целое из строки», «Ход раскодирования».

Logic

Operations over booleans: and, or, not, exclusive or, implication, plus “all true” and “any true” over a list.

Import: использует «Logic».

String sets

A set of strings: add, remove, union, intersection, difference, subset.

Import: использует «String sets».

Base64

Base64 per RFC 4648: the standard alphabet and the URL-safe one.

Import: использует «Base64».

Types: «Ход кодирования 64», «Ход раскодирования 64».

Wire

The shared half of a binary protocol: octets, network-order integers, zero-terminated strings, cutting a stream into pieces.

Import: использует «Wire».

Types: «Печать», «Набор байтов», «Разбор целого», «Разбор строки», «Разбор числа».

Postgres

The PostgreSQL 3.0 protocol, pure half: building client messages and parsing server ones. No socket here.

Import: использует «Postgres».

Types: «Поле», «Беда базы», «Весть», «Разбор вести», «Разбор потока», «Значение».

Redis

The Redis protocol (RESP 2), pure half: building commands and parsing replies.

Import: использует «Redis».

Types: «Ответ Redis», «Разбор Redis», «Край Redis», «Поток Redis».

Tree map

A string → string map as a search tree: O(log n) access.

Import: использует «Tree map».

Types: «Дерево».

String lists

Lists of strings: first, last, tail, join, access by index, common prefix.

Import: использует «String lists».

Number tree

An ordered tree of numbers: insert, search, sort by traversal.

Import: использует «Number tree».

Types: «Дерево чисел».

HMAC

HMAC-SHA256 signatures — RFC 2104 and RFC 4231.

Import: использует «HMAC».

Types: «Ход начала», «Ход слияния».

SCRAM

Client-side SCRAM-SHA-256 login — RFC 5802 and RFC 7677.

Import: использует «SCRAM».

SHA-1

SHA-1, HMAC-SHA1 and PBKDF2-HMAC-SHA1. The hash is obsolete: take it only where somebody else’s protocol demands exactly it.

Import: использует «SHA-1».

Types: «Свод SHA-1», «Ход блока SHA-1», «Ход хеша SHA-1», «Ход вывода SHA-1».

SHA-256

The SHA-256 hash — FIPS 180-4.

Import: использует «SHA-256».

Types: «Свод sha256», «Расписание», «Ход блока», «Сбор слов», «Ход хеша».

UTF-8

Text into bytes and bytes back into code points — UTF-8, RFC 3629.

Import: использует «UTF-8».

Types: «Ход разбора utf8».

Next

• Language reference — how the language itself is written
• Operations — a task → what solves it