Модуль Bytes

Возвращает длину (количество байтов) аргумента.

get s n возвращает байт с индексом n в аргументе s.

set s n c изменяет s на месте, заменяя байт с индексом n на c.

create n возвращает новую последовательность байтов длиной n. Последовательность неинициализирована и содержит произвольные байты.

make n c возвращает новую последовательность байтов длиной n, заполненную байтом c.

init n f возвращает новую последовательность байтов длиной n, с символом i инициализированным результатом f i (в порядке возрастания индекса).

Последовательность байтов размера 0.

Возвращает новую последовательность байтов, содержащую те же байты, что и аргумент.

Возвращает новую последовательность байтов, содержащую те же байты, что и заданная строка.

Возвращает новую строку, содержащую те же байты, что и заданная последовательность байтов.

sub s pos len возвращает новую последовательность байтов длиной len, содержащую подпоследовательность s, которая начинается с позиции pos и имеет длину len.

То же, что и Bytes.sub, но возвращает строку вместо последовательности байтов.

extend s left right возвращает новую последовательность байтов, содержащую байты s, с left неинициализированными байтами, добавленными в начало и right неинициализированными байтами, добавленными в конец. Если left или right отрицательны, тогда байты удаляются (а не добавляются) с соответствующей стороны s.

fill s pos len c изменяет s на месте, заменяя len символы на c, начиная с pos.

blit src src_pos dst dst_pos len копирует len байтов из последовательности src, начиная с индекса src_pos, в последовательность dst, начиная с индекса dst_pos . Это работает правильно, даже если src и dst — это одна и та же последовательность байтов, а исходный и целевой интервалы перекрываются.

blit src src_pos dst dst_pos len копирует len байтов из строки src, начиная с индекса src_pos, в последовательность байтов dst, начиная с индекса dst_pos.

concat sep sl конкатенирует список последовательностей байтов sl, вставляя разделительную последовательность байтов sep между каждой, и возвращает результат как новую последовательность байтов.

cat s1 s2 конкатенирует s1 и s2 и возвращает результат как новую последовательность байтов.

iter f s применяет функцию f по очереди ко всем байтам s . Это эквивалентно f (get s 0); f (get s 1); ...; f (get s
    (length s - 1)); ().

То же, что и Bytes.iter, но функция применяется к индексу байта в качестве первого аргумента и к самому байту как ко второму аргументу.

map f s применяет функцию f по очереди ко всем байтам s (в порядке возрастания индекса) и сохраняет полученные байты в новой последовательности, которая возвращается в качестве результата.

mapi f s вызывает f с каждым символом s и его индексом (в порядке возрастания индекса) и сохраняет полученные байты в новой последовательности, которая возвращается в качестве результата.

fold_left f x s вычисляет f (... (f (f x (get s 0)) (get s 1)) ...) (get s (n-1)), где n — длина s.

fold_right f s x вычисляет f (get s 0) (f (get s 1) ( ... (f (get s (n-1)) x) ...)), где n — длина s.

for_all p s проверяет, удовлетворяют ли все символы в s предикату p.

exists p s проверяет, удовлетворяет ли хотя бы один символ s предикату p.

Возвращает копию аргумента, без начальных и конечных пробелов. Байты, считающиеся пробелами, это символы ASCII ' ', '\012', '\n', '\r', и '\t'.

Возвращает копию аргумента, с представлением специальных символов в виде последовательностей экранирования, следуя лексическим соглашениям OCaml. Все символы за пределами печатаемого диапазона ASCII (32..126), а также обратная косая черта и двойная кавычка, экранируются.

index s c возвращает индекс первого вхождения байта c в s.

index_opt s c возвращает индекс первого вхождения байта c в s или None если c не встречается в s.

rindex s c возвращает индекс последнего вхождения байта c в s.

rindex_opt s c возвращает индекс последнего вхождения байта c в s или None если c не встречается в s.

index_from s i c возвращает индекс первого вхождения байта c в s после позиции i. index s c эквивалентно index_from s 0 c.

index_from_opt s i c возвращает индекс первого вхождения байта c в s после позиции i или None если c не встречается в s после позиции i. index_opt s c эквивалентно index_from_opt s 0 c.

rindex_from s i c возвращает индекс последнего вхождения байта c в s перед позицией i+1. rindex s c эквивалентно rindex_from s (length s - 1) c.

rindex_from_opt s i c возвращает индекс последнего вхождения байта c в s перед позицией i+1 или None если c не встречается в s перед позицией i+1. rindex_opt s c эквивалентно rindex_from s (length s - 1) c.

contains s c проверяет, появляется ли байт c в s.

contains_from s start c проверяет, появляется ли байт c в s после позиции start. contains s c эквивалентно contains_from
    s 0 c.

rcontains_from s stop c проверяет, появляется ли байт c в s перед позицией stop+1.

Возвращает копию аргумента, с переводом всех строчных букв в заглавные, включая буквы с диакритическими знаками из набора символов ISO Latin-1 (8859-1).

Возвращает копию аргумента, с переводом всех заглавных букв в строчные, включая буквы с диакритическими знаками из набора символов ISO Latin-1 (8859-1).

Возвращает копию аргумента, с первой буквой в заглавном регистре, используя набор символов ISO Latin-1 (8859-1).

Возвращает копию аргумента, с первой буквой в строчном регистре, используя набор символов ISO Latin-1 (8859-1).

Возвращает копию аргумента, с переводом всех строчных букв в заглавные, используя набор символов US-ASCII.

Возвращает копию аргумента, с переводом всех заглавных букв в строчные, используя набор символов US-ASCII.

Возвращает копию аргумента, с первой буквой в заглавном регистре, используя набор символов US-ASCII.

Возвращает копию аргумента, с первой буквой в строчном регистре, используя набор символов US-ASCII.

Псевдоним для типа последовательностей байтов.

Функция сравнения последовательностей байтов, со спецификацией, аналогичной compare. Вместе с типом t, эта функция compare позволяет модулю Bytes быть аргументом для функторов Set.Make и Map.Make.

Функция равенства для последовательностей байтов.

starts_with ~prefix s является true тогда и только тогда, когда s начинается с prefix.

ends_with suffix s является true тогда и только тогда, когда s заканчивается на suffix.

Небезопасно преобразует последовательность байтов в строку.

Для анализа использования unsafe_to_string, удобно рассмотреть дисциплину «владения». Часть кода, которая манипулирует данными, «владеет» ими; существует несколько различных режимов владения, включая:

• Уникальное владение: данные могут быть обработаны и изменены.
• Общее владение: данные имеют несколько владельцев, которые могут только обращаться к ним, но не изменять их.

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

unsafe_to_string s может использоваться только тогда, когда вызывающая сторона владеет последовательностью байтов s — либо уникально, либо как общие неизменяемые данные. Вызывающая сторона отказывается от владения s, и получает владение возвращенной строкой.

Существует два допустимых варианта использования, которые соблюдают эту дисциплину владения:

1. Создание строки путем инициализации и изменения последовательности байтов, которая никогда не изменяется после инициализации.

let string_init len f : string =
  let s = Bytes.create len in
  for i = 0 to len - 1 do Bytes.set s i (f i) done;
  Bytes.unsafe_to_string s
   

Эта функция безопасна, потому что последовательность байтов s никогда не будет обработана или изменена после вызова unsafe_to_string. Код string_init отказывается от владения s, и возвращает владение полученной строкой своему вызывающему объекту.

Обратите внимание, что это было бы небезопасно, если бы s передавался в качестве дополнительного параметра функции f, поскольку он мог бы таким образом выйти за пределы области видимости и быть изменён в будущем — string_init отказался бы от владения s для передачи его в f, и не смог бы безопасно вызвать unsafe_to_string.

Мы предоставили функции String.init, String.map и String.mapi для покрытия большинства случаев построения новых строк. Вы должны отдавать предпочтение этим функциям перед to_string или unsafe_to_string всякий раз, когда это возможно.

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

let bytes_length (s : bytes) =
  String.length (Bytes.unsafe_to_string s)
   

В этом случае мы не гарантируем, что s никогда не будет изменён после вызова функции bytes_length s. Функция String.length временно заимствует уникальное владение последовательностью байтов (и рассматривает её как string), но возвращает это владение обратно вызывающей стороне, которая может предположить, что s по-прежнему является допустимой последовательностью байтов после вызова. Обратите внимание, что это верно только потому, что мы знаем, что String.length не захватывает свой аргумент — он может выйти за пределы области видимости через побочный канал, например, комбиниратор запоминания.

Вызывающая сторона не может изменять s, пока строка заимствуется (она временно отказалась от владения). Это затрагивает конкурентные программы, а также функции высшего порядка: если String.length возвратила замыкание для вызова в будущем, s не должна изменяться до тех пор, пока это замыкание не будет полностью применено и не вернёт владение.

Небезопасно преобразует общую строку в последовательность байтов, которую нельзя изменять.

Такая же дисциплина владения, которая делает unsafe_to_string корректной, применима и к unsafe_of_string: вы можете использовать её, если вы являетесь владельцем значения string, и вы будете владеть возвращаемым значением bytes в том же режиме.

На практике, уникальное владение строковыми значениями чрезвычайно сложно правильно анализировать. Вы всегда должны предполагать, что строки являются общими, а не уникально-владеемыми.

Например, строковые литералы неявно являются общими для компилятора, поэтому вы никогда не владеете ими уникально.

let incorrect = Bytes.unsafe_of_string "hello"
let s = Bytes.of_string "hello"
    

Первое объявление некорректно, так как строковый литерал "hello" может быть общим для компилятора с другими частями программы, и изменение incorrect — это ошибка. Вы всегда должны использовать второй вариант, который выполняет копирование и, следовательно, является правильным.

Предположение об уникальном владении строками, которые не являются строковыми литералами, но частично построены из строковых литералов, также неверно. Например, изменение unsafe_of_string ("foo" ^ s) может изменить общую строку "foo" — предполагая представление строк в виде верёвки. Более общо, функции, работающие со строками, предполагают общее владение, они не сохраняют уникальное владение. Таким образом, неверно предполагать уникальное владение результатом unsafe_of_string.

Единственный случай, в котором мы можем с достаточной уверенностью утверждать безопасность, — это если полученная bytes является общей — используется как неизменяемая последовательность байтов. Это, возможно, полезно для поэтапной миграции низкоуровневых программ, которые обрабатывают неизменяемые последовательности байтов (например, Marshal.from_bytes) и ранее использовали тип string для этой цели.

split_on_char sep s возвращает список всех (возможно, пустых) подпоследовательностей s, которые ограничены символом sep.

Выход функции определяется следующими инвариантами:

• Список не пуст.
• Сцепление его элементов с разделителем sep возвращает последовательность байтов, равную вводу (Bytes.concat (Bytes.make 1 sep)
      (Bytes.split_on_char sep s) = s).
• Ни одна последовательность байтов в результате не содержит символ sep.

Итерирование по строке в порядке возрастания индексов. Изменения в строке во время итерации будут отражены в последовательности.

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

Создание строки из генератора.

get_utf_8_uchar b i декодирует символ UTF-8 по индексу i в b.

set_utf_8_uchar b i u кодирует UTF-8 символ u по индексу i в b и возвращает количество записанных байтов n, начиная с i. Если n равно 0, не было достаточно места для кодирования символа u по индексу i, и b осталось без изменений. В противном случае новый символ может быть закодирован по индексу i + n.

is_valid_utf_8 b равно true, если и только если b содержит допустимые данные UTF-8.

get_utf_16be_uchar b i декодирует символ UTF-16BE по индексу i в b.

set_utf_16be_uchar b i u кодирует UTF-16BE символ u по индексу i в b и возвращает количество записанных байтов n, начиная с i. Если n равно 0, не было достаточно места для кодирования символа u по индексу i, и b осталось без изменений. В противном случае новый символ может быть закодирован по индексу i + n.

is_valid_utf_16be b равно true, если и только если b содержит допустимые данные UTF-16BE.

get_utf_16le_uchar b i декодирует символ UTF-16LE по индексу i в b.

set_utf_16le_uchar b i u кодирует UTF-16LE символ u по индексу i в b и возвращает количество записанных байтов n, начиная с i. Если n равно 0, не было достаточно места для кодирования символа u по индексу i, и b осталось без изменений. В противном случае новый символ может быть закодирован по индексу i + n.

is_valid_utf_16le b равно true, если и только если b содержит допустимые данные UTF-16LE.

get_uint8 b i — беззнаковое 8-битное целое число b, начинающееся с байтового индекса i.

get_int8 b i — это подписанное 8-битное целое число b, начинающееся с байтового индекса i.

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

get_uint16_be b i — это целое беззнаковое 16-битное число b с порядком байт big-endian, начинающееся с байтового индекса i.

get_uint16_le b i — это целое беззнаковое 16-битное число b с порядком байт little-endian, начинающееся с байтового индекса i.

get_int16_ne b i — это подписанное 16-битное целое число b с родным порядком байт, начинающееся с байтового индекса i.

get_int16_be b i — это подписанное 16-битное целое число b с порядком байт big-endian, начинающееся с байтового индекса i.

get_int16_le b i — это подписанное 16-битное целое число b с порядком байт little-endian, начинающееся с байтового индекса i.

get_int32_ne b i — это 32-битное целое число b с родным порядком байт, начинающееся с байтового индекса i.

get_int32_be b i — это 32-битное целое число b с порядком байт big-endian, начинающееся с байтового индекса i.

get_int32_le b i — это 32-битное целое число b с порядком байт little-endian, начинающееся с байтового индекса i.

get_int64_ne b i — это 64-битное целое число b с родным порядком байт, начинающееся с байтового индекса i.

get_int64_be b i — это 64-битное целое число b с порядком байт big-endian, начинающееся с байтового индекса i.

get_int64_le b i — это 64-битное целое число b с порядком байт little-endian, начинающееся с байтового индекса i.

set_uint8 b i v устанавливает b's беззнаковое 8-битное целое число, начинающееся с байтового индекса i, на значение v.

Устанавливает знаковое 8-битное целое число b начиная с индекса байта i в v.

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

Устанавливает 16-битное беззнаковое целое число в порядке big-endian b начиная с индекса байта i в v.

Устанавливает 16-битное беззнаковое целое число в порядке little-endian b начиная с индекса байта i в v.

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

Устанавливает 16-битное знаковое целое число в порядке big-endian b начиная с индекса байта i в v.

Устанавливает 16-битное знаковое целое число в порядке little-endian b начиная с индекса байта i в v.

Устанавливает собственно-порядковое 32-битное целое число b начиная с индекса байта i в v.

Устанавливает 32-битное целое число в порядке big-endian b начиная с индекса байта i в v.

Устанавливает 32-битное целое число в порядке little-endian b начиная с индекса байта i в v.

Устанавливает собственно-порядковое 64-битное целое число b начиная с индекса байта i в v.

Устанавливает 64-битное целое число в порядке big-endian b начиная с индекса байта i в v.

Устанавливает 64-битное целое число в порядке little-endian b начиная с индекса байта i в v.