Модуль StdLabels.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.

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

Возвращает копию аргумента, с переводом всех строчных букв в прописные, включая назаковленные буквы набора символов 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 — порядок байтов big-endian беззнаковое 16-битное целое число объекта b, начинающееся с байтового индекса i.

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

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

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

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

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

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

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

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

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

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

set_uint8 b i v устанавливает беззнаковое 8-битное целое число объекта b, начиная с байтового индекса 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.