Модуль Buffer

module Buffer: sig .. end

Расширяемые буферы.

Этот модуль реализует буферы, которые автоматически расширяются при необходимости. Он обеспечивает конкатенацию строк с накоплением за линейное время (вместо квадратичного времени при попарной конкатенации строк). Например:

     let concat_strings ss =
       let b = Buffer.create 16 in
         List.iter (Buffer.add_string b) ss;
         Buffer.contents b

Предупреждение unsynchronized_access. Несинхронизированный доступ к буферам является ошибкой программирования.

Ёмкость и стратегия перераспределения памяти

Внутри буфер использует резервное хранилище (последовательность байтов), размер которого, называемый ёмкостью, больше или равен числу символов, хранящихся в буфере (его длине).

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

Buffer.clear сохраняет текущее резервное хранилище (то есть память не освобождается), тогда как Buffer.reset освобождает текущее резервное хранилище, высвобождая память ценой возможного повторного выделения памяти в дальнейшем.

Несинхронизированный доступ

Несинхронизированный доступ к буферу может привести к его некорректному состоянию. Поэтому параллельный доступ к буферу необходимо синхронизировать (например, с помощью Mutex.t).

type t

Абстрактный тип буферов.

val create : int -> t

create n возвращает новый пустой буфер. Параметр n задаёт начальный размер внутренней последовательности байтов, в которой хранится содержимое буфера. Эта последовательность байтов автоматически перераспределяется, когда в буфере хранится больше n символов, но уменьшается до n символов при вызове reset. Для наилучшей производительности значение n должно быть того же порядка величины, что и ожидаемое число символов в буфере (например, 80 для буфера, хранящего одну строку вывода). Однако ничего плохого не произойдёт, если буфер превысит это ограничение. Если вы сомневаетесь, выберите, например, n = 16. Если значение n не находится в диапазоне от 1 до Sys.max_string_length, оно будет ограничено этим диапазоном.

val contents : t -> string

Возвращает копию текущего содержимого буфера. Сам буфер не изменяется.

val to_bytes : t -> bytes

Возвращает копию текущего содержимого буфера. Сам буфер не изменяется.

С версии 4.02

val sub : t -> int -> int -> string

Buffer.sub b off len возвращает копию из len байтов текущего содержимого буфера b, начиная со смещения off.

Вызывает исключение Invalid_argument, если off и len не задают допустимый диапазон в b.

val blit : t -> int -> bytes -> int -> int -> unit

Buffer.blit src srcoff dst dstoff len копирует len символов из текущего содержимого буфера src, начиная со смещения srcoff, в dst, начиная с символа dstoff.

С версии 3.11.2
Вызывает исключение Invalid_argument, если srcoff и len не задают допустимый диапазон в src либо если dstoff и len не задают допустимый диапазон в dst.

val nth : t -> int -> char

Получить n-й символ буфера.

Вызывает исключение Invalid_argument, если индекс выходит за границы

val length : t -> int

Возвращает число символов, содержащихся в буфере в данный момент.

val clear : t -> unit

Очищает буфер.

val reset : t -> unit

Очищает буфер и освобождает внутреннюю последовательность байтов, хранящую содержимое буфера, заменяя её начальной внутренней последовательностью длины n, выделенной вызовом Buffer.create n. Для долгоживущих буферов, которые могли значительно вырасти, reset позволяет быстрее освободить занятую буфером память.

val output_buffer : out_channel -> t -> unit

output_buffer oc b записывает текущее содержимое буфера b в канал вывода oc.

val truncate : t -> int -> unit

truncate b len усекает длину b до len. Примечание: внутренняя последовательность байтов не укорачивается.

С версии 4.05
Вызывает исключение Invalid_argument, если len < 0 или len > length b.

Добавление

Примечание: все операции add_* могут вызвать исключение Failure, если внутреннюю последовательность байтов буфера потребуется увеличить сверх Sys.max_string_length.

val add_char : t -> char -> unit

add_char b c добавляет символ c в конец буфера b.

val add_utf_8_uchar : t -> Uchar.t -> unit

add_utf_8_uchar b u добавляет кодировку u в формате UTF-8 в конец буфера b.

С версии 4.06

val add_utf_16le_uchar : t -> Uchar.t -> unit

add_utf_16le_uchar b u добавляет кодировку u в формате UTF-16LE в конец буфера b.

С версии 4.06

val add_utf_16be_uchar : t -> Uchar.t -> unit

add_utf_16be_uchar b u добавляет кодировку u в формате UTF-16BE в конец буфера b.

С версии 4.06

val add_string : t -> string -> unit

add_string b s добавляет строку s в конец буфера b.

val add_bytes : t -> bytes -> unit

add_bytes b s добавляет последовательность байтов s в конец буфера b.

С версии 4.02

val add_substring : t -> string -> int -> int -> unit

add_substring b s ofs len берёт len символов со смещения ofs в строке s и добавляет их в конец буфера b.

Вызывает исключение Invalid_argument, если ofs и len не задают допустимый диапазон в s.

val add_subbytes : t -> bytes -> int -> int -> unit

add_subbytes b s ofs len берёт len символов со смещения ofs в последовательности байтов s и добавляет их в конец буфера b.

С версии 4.02
Вызывает исключение Invalid_argument, если ofs и len не задают допустимый диапазон в s.

val add_substitute : t -> (string -> string) -> string -> unit

add_substitute b f s добавляет шаблон строки s в конец буфера b, выполняя подстановку. В процессе подстановки шаблон проверяется на наличие ссылок на переменные, и каждая такая ссылка заменяется значением переменной, полученным применением отображения f к имени переменной. В шаблоне строки ссылка на переменную — это неэкранированный символ $, за которым непосредственно следует имя переменной, которое может быть одним из следующих вариантов:

непустая последовательность буквенно-цифровых символов или символов _;
произвольная последовательность символов, заключённая в пару совпадающих круглых или фигурных скобок. Экранированный символ $ — это символ $, которому непосредственно предшествует обратная косая черта; эти два символа вместе обозначают обычный символ $.

val add_buffer : t -> t -> unit

add_buffer b1 b2 добавляет текущее содержимое буфера b2 в конец буфера b1. b2 не изменяется.

val add_channel : t -> in_channel -> int -> unit

add_channel b ic n считывает не более n символов из входного канала ic и помещает их в конец буфера b.

Вызывает исключение
- End_of_file, если канал содержит меньше n символов. В этом случае символы всё равно добавляются в буфер, чтобы избежать потери данных.
- Invalid_argument, если len < 0 или len > Sys.max_string_length.

Буферы и последовательности

val to_seq : t -> char Seq.t

Итерирует по буферу в порядке возрастания.

Поведение не определено, если буфер изменяется во время итерации.

С версии 4.07

val to_seqi : t -> (int * char) Seq.t

Итерирует по буферу в порядке возрастания, возвращая индексы вместе с символами.

Поведение не определено, если буфер изменяется во время итерации.

С версии 4.07

val add_seq : t -> char Seq.t -> unit

Добавляет символы в буфер

С версии 4.07

val of_seq : char Seq.t -> t

Создаёт буфер из генератора

С версии 4.07

Двоичное кодирование целых чисел

Функции в этом разделе добавляют в буферы двоичные представления целых чисел.

Кодирование с прямым порядком байтов (соответственно, с обратным порядком байтов) означает, что первыми сохраняются младшие (соответственно, старшие) байты. Обратный порядок байтов также известен как сетевой порядок байтов. Порядок байтов, зависящий от архитектуры, может быть прямым или обратным в зависимости от значения Sys.big_endian.

32- и 64-разрядные целые числа представлены типами int32 и int64, которые можно интерпретировать как числа со знаком или без знака.

8- и 16-разрядные целые числа представлены типом int, в котором больше битов, чем в двоичном представлении. Функции кодирования этих значений отбрасывают старшие байты входных значений.

val add_uint8 : t -> int -> unit

add_uint8 b i добавляет в b двоичное представление беззнакового 8-разрядного целого числа i.

С версии 4.08

val add_int8 : t -> int -> unit

add_int8 b i добавляет в b двоичное представление знакового 8-разрядного целого числа i.

С версии 4.08

val add_uint16_ne : t -> int -> unit

add_uint16_ne b i добавляет в b двоичное представление беззнакового 16-разрядного целого числа с порядком байтов, зависящим от архитектуры, i.

С версии 4.08

val add_uint16_be : t -> int -> unit

add_uint16_be b i добавляет в b двоичное представление беззнакового 16-разрядного целого числа с обратным порядком байтов i.

С версии 4.08

val add_uint16_le : t -> int -> unit

add_uint16_le b i добавляет в b двоичное представление беззнакового 16-разрядного целого числа с прямым порядком байтов i.

С версии 4.08

val add_int16_ne : t -> int -> unit

add_int16_ne b i добавляет в b двоичное представление знакового 16-разрядного целого числа с порядком байтов, зависящим от архитектуры, i.

С версии 4.08

val add_int16_be : t -> int -> unit

add_int16_be b i добавляет в b двоичное представление знакового 16-разрядного целого числа с обратным порядком байтов i.

С версии 4.08

val add_int16_le : t -> int -> unit

add_int16_le b i добавляет в b двоичное представление знакового 16-разрядного целого числа с прямым порядком байтов i.

С версии 4.08

val add_int32_ne : t -> int32 -> unit

add_int32_ne b i добавляет в b двоичное представление 32-разрядного целого числа с порядком байтов, зависящим от архитектуры, i.

С версии 4.08

val add_int32_be : t -> int32 -> unit

add_int32_be b i добавляет в b двоичное представление 32-разрядного целого числа с обратным порядком байтов i.

С версии 4.08

val add_int32_le : t -> int32 -> unit

add_int32_le b i добавляет в b двоичное представление 32-разрядного целого числа с прямым порядком байтов i.

С версии 4.08

val add_int64_ne : t -> int64 -> unit

add_int64_ne b i добавляет в b двоичное представление 64-разрядного целого числа с порядком байтов, зависящим от архитектуры, i.

С версии 4.08

val add_int64_be : t -> int64 -> unit

add_int64_be b i добавляет в b двоичное представление 64-разрядного целого числа с обратным порядком байтов i.

С версии 4.08

val add_int64_le : t -> int64 -> unit

add_int64_le b i добавляет в b двоичное представление 64-разрядного целого числа с прямым порядком байтов i.

С версии 4.08