Модуль BytesLabels

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

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.

То же, что BytesLabels.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_string ~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)); ().

То же, что BytesLabels.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.

Возвращает копию аргумента, в котором все строчные буквы преобразуются в прописные, используя 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. Если s пусто, результат — список единственного элемента [empty].

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

• Список не пуст.
• Объединение его элементов с использованием 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 является b беззнаковым 8-битным целым числом, начинающимся с байта с индексом i.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

set_int32_ne b i v устанавливает b 32-битное целое число в собственном порядке байтов, начинающееся с байта с индексом i, в v.

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

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

set_int64_ne b i v устанавливает b 64-битное целое число в собственном порядке байтов, начинающееся с байта с индексом i, в v.

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

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