Модуль StringLabels

module StringLabels: sig .. end

Строки.

Строка s длиной n — это индексируемая и неизменяемая последовательность n байтов. По историческим причинам эти байты называются символами.

Семантика функций для строк определяется в терминах индексов и позиций. Они изображены и описаны следующим образом.

positions  0   1   2   3   4    n-1    n
           +---+---+---+---+     +-----+
  indices  | 0 | 1 | 2 | 3 | ... | n-1 |
           +---+---+---+---+     +-----+

Индекс i строки s — это целое число в диапазоне [0;n-1]. Он представляет собой i-й байт (символ) строки s, к которому можно обратиться с помощью оператора индексирования строк за постоянное время s.[i].
Позиция i строки s — это целое число в диапазоне [0;n]. Она представляет собой либо точку в начале строки, либо точку между двумя индексами, либо точку в конце строки. Индекс i-го байта находится между позициями i и i+1.

Два целых числа start и len определяют валидный подстроку строки s тогда и только тогда, когда len >= 0 и start, start+len — это позиции в строке s.

Текст Unicode. Строки представляют собой произвольные последовательности байтов, поэтому могут хранить любой тип кодировки текста. Однако рекомендуемая кодировка для хранения текстовой информации Unicode в OCaml-строках — UTF-8. Это кодировка, используемая в строковых литералах с экранированными символами Unicode. Например, строка "\u{1F42B}" представляет собой кодировку UTF-8 символа Unicode U+1F42B.

Прежняя изменчивость. До OCaml 4.02 строки могли изменяться непосредственно, как, например, Bytes.t — изменяемая последовательность байтов. В OCaml 4 были различные флаги компилятора и параметры конфигурации для поддержки переходного периода от изменяемых к неизменяемым строкам. Эти параметры больше недоступны, и строки всегда неизменяемы.

Метка данного модуля может быть использована, как описано в модуле StdLabels.

Строки

type t = string

Тип для строк.

val make : int -> char -> string

make n c — это строка длиной n с каждым индексом, содержащим символ c.

Raises Invalid_argument если n < 0 или n > Sys.max_string_length.

val init : int -> f:(int -> char) -> string

init n ~f — это строка длиной n с индексом i, содержащим символ f i (в порядке возрастания индекса).

Since 4.02
Raises Invalid_argument если n < 0 или n > Sys.max_string_length.

val empty : string

Пустая строка.

Since 4.13

val length : string -> int

length s — это длина (количество байтов/символов) строки s.

val get : string -> int -> char

get s i — это символ с индексом i в строке s. Это то же самое, что и s.[i].

Raises Invalid_argument если i не является индексом в строке s.

val of_bytes : bytes -> string

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

Since 4.13

val to_bytes : string -> bytes

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

Since 4.13

val blit : src:string -> src_pos:int -> dst:bytes -> dst_pos:int -> len:int -> unit

То же, что и Bytes.blit_string, что предпочтительнее использовать.

Конкатенация

Примечание. Бинарный оператор (^) выполняет конкатенацию двух строк.

val concat : sep:string -> string list -> string

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

Raises Invalid_argument если результат длиннее, чем Sys.max_string_length байтов.

val cat : string -> string -> string

cat s1 s2 конкатенирует s1 и s2 (s1 ^ s2).

Since 4.13
Raises Invalid_argument если результат длиннее, чем Sys.max_string_length байтов.

Предикаты и сравнения

val equal : t -> t -> bool

equal s0 s1 равна true тогда и только тогда, когда s0 и s1 равны посимвольно.

Since 4.05

val compare : t -> t -> int

compare s0 s1 сортирует s0 и s1 в лексикографическом порядке. compare ведет себя подобно compare для строк, но может быть более эффективным.

val starts_with : prefix:string -> string -> bool

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

Since 4.13

val ends_with : suffix:string -> string -> bool

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

Since 4.13

val contains_from : string -> int -> char -> bool

contains_from s start c равна true тогда и только тогда, когда c встречается в s после позиции start.

Raises Invalid_argument если start не является валидной позицией в строке s.

val rcontains_from : string -> int -> char -> bool

rcontains_from s stop c равна true тогда и только тогда, когда c встречается в s перед позицией stop+1.

Raises Invalid_argument если stop < 0 или stop+1 не являются валидными позициями в строке s.

val contains : string -> char -> bool

contains s c равно String.contains_from s 0 c.

Извлечение подстрок

val sub : string -> pos:int -> len:int -> string

sub s ~pos ~len — это строка длиной len, содержащая подстроку строки s, которая начинается с позиции pos и имеет длину len.

Raises Invalid_argument если pos и len не обозначают валидную подстроку строки s.

val split_on_char : sep:char -> string -> string list

split_on_char ~sep s — это список всех (возможно пустых) подстрок строки s, которые ограничены символом sep. Если s пуста, результатом будет одноэлементный список [""].

Результат функции задается следующими инвариантами:

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

Since 4.05

Преобразования

val map : f:(char -> char) -> string -> string

map f s — это строка, полученная путем применения функции f ко всем символам строки s в порядке возрастания индексов.

Since 4.00

val mapi : f:(int -> char -> char) -> string -> string

mapi ~f s подобно StringLabels.map, но индекс символа также передается в функцию f.

Since 4.02

val fold_left : f:('acc -> char -> 'acc) -> init:'acc -> string -> 'acc

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

Since 4.13

val fold_right : f:(char -> 'acc -> 'acc) -> string -> init:'acc -> 'acc

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

Since 4.13

val for_all : f:(char -> bool) -> string -> bool

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

Since 4.13

val exists : f:(char -> bool) -> string -> bool

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

Since 4.13

val trim : string -> string

trim s представляет собой s без ведущих и завершающих пробелов. Символами пробела являются: ' ', '\x0C' (подача страницы), '\n', '\r' и '\t'.

С версии 4.00

val escaped : string -> string

escaped s представляет собой s со специальными символами, представленными escape-последовательностями, в соответствии с лексическими соглашениями OCaml.

Все символы за пределами диапазона печатных символов US-ASCII [0x20;0x7E] экранируются, а также обратная косая черта (0x2F) и двойные кавычки (0x22).

Функция Scanf.unescaped является левой обратной функцией для escaped, т.е. Scanf.unescaped (escaped s) = s для любой строки s (если escaped s не завершится ошибкой).

Вызывает исключение Invalid_argument, если результат длиннее, чем Sys.max_string_length байт.

val uppercase_ascii : string -> string

uppercase_ascii s представляет собой s со всеми строчными буквами, переведенными в прописные, используя кодировку US-ASCII.

С версии 4.05

val lowercase_ascii : string -> string

lowercase_ascii s представляет собой s со всеми прописными буквами, переведенными в строчные, используя кодировку US-ASCII.

С версии 4.05

val capitalize_ascii : string -> string

capitalize_ascii s представляет собой s с первым символом, переведенным в прописную букву, используя кодировку US-ASCII.

С версии 4.05

val uncapitalize_ascii : string -> string

uncapitalize_ascii s представляет собой s с первым символом, переведенным в строчную букву, используя кодировку US-ASCII.

С версии 4.05

Обход

val iter : f:(char -> unit) -> string -> unit

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

val iteri : f:(int -> char -> unit) -> string -> unit

iteri похожа на StringLabels.iter, но функция также получает соответствующий индекс символа.

С версии 4.00

Поиск

val index_from : string -> int -> char -> int

index_from s i c — это индекс первого вхождения c в s после позиции i.

Вызывает исключение
- Not_found, если c не встречается в s после позиции i.
- Invalid_argument, если i не является допустимой позицией в s.

val index_from_opt : string -> int -> char -> int option

index_from_opt s i c — это индекс первого вхождения c в s после позиции i (если таковое имеется).

С версии 4.05
Вызывает исключение Invalid_argument, если i не является допустимой позицией в s.

val rindex_from : string -> int -> char -> int

rindex_from s i c — это индекс последнего вхождения c в s до позиции i+1.

Вызывает исключение
- Not_found, если c не встречается в s до позиции i+1.
- Invalid_argument, если i+1 не является допустимой позицией в s.

val rindex_from_opt : string -> int -> char -> int option

rindex_from_opt s i c — это индекс последнего вхождения c в s до позиции i+1 (если таковое имеется).

С версии 4.05
Вызывает исключение Invalid_argument, если i+1 не является допустимой позицией в s.

val index : string -> char -> int

index s c — это String.index_from s 0 c.

val index_opt : string -> char -> int option

index_opt s c — это String.index_from_opt s 0 c.

С версии 4.05

val rindex : string -> char -> int

rindex s c — это String.rindex_from s (length s - 1) c.

val rindex_opt : string -> char -> int option

rindex_opt s c — это String.rindex_from_opt s (length s - 1) c.

С версии 4.05

Строки и последовательности

val to_seq : t -> char Seq.t

to_seq s — это последовательность, состоящая из символов строки в порядке возрастания. В режиме "unsafe-string" изменения строки во время итерации будут отражаться в последовательности.

С версии 4.07

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

to_seqi s похожа на StringLabels.to_seq, но также включает в кортеж соответствующий индекс.

С версии 4.07

val of_seq : char Seq.t -> t

of_seq s — это строка, состоящая из символов последовательности.

С версии 4.07

UTF-декодирование и валидация

UTF-8

val get_utf_8_uchar : t -> int -> Uchar.utf_decode

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

val is_valid_utf_8 : t -> bool

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

UTF-16BE

val get_utf_16be_uchar : t -> int -> Uchar.utf_decode

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

val is_valid_utf_16be : t -> bool

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

UTF-16LE

val get_utf_16le_uchar : t -> int -> Uchar.utf_decode

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

val is_valid_utf_16le : t -> bool

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

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

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

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

Кодировка little-endian (соответственно, big-endian) означает, что наименее (соответственно, наиболее) значимые байты хранятся первыми. Big-endian также известен как сетевой порядок байтов. Кодировка native-endian является либо little-endian, либо big-endian в зависимости от Sys.big_endian.

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

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

val get_uint8 : string -> int -> int

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

С версии 4.13

val get_int8 : string -> int -> int

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

С версии 4.13

val get_uint16_ne : string -> int -> int

get_uint16_ne b i — это 16-битное беззнаковое целое число native-endian из b, начиная с индекса символа i.

С версии 4.13

val get_uint16_be : string -> int -> int

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

С версии 4.13

val get_uint16_le : string -> int -> int

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

С версии 4.13

val get_int16_ne : string -> int -> int

get_int16_ne b i — это 16-битное знаковое целое число native-endian из b, начиная с индекса символа i.

С версии 4.13

val get_int16_be : string -> int -> int

get_int16_be b i — это 16-битное знаковое целое число big-endian из b, начиная с индекса символа i.

С версии 4.13

val get_int16_le : string -> int -> int

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

Since 4.13

val get_int32_ne : string -> int -> int32

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

Since 4.13

val hash : t -> int

Функция хеширования строк без начального значения, с тем же значением вывода, что и Hashtbl.hash. Эта функция позволяет передать этот модуль в качестве аргумента в функтор Hashtbl.Make.

Since 5.0

val seeded_hash : int -> t -> int

Функция хеширования строк с начальным значением, с тем же значением вывода, что и Hashtbl.seeded_hash. Эта функция позволяет передать этот модуль в качестве аргумента в функтор Hashtbl.MakeSeeded.

Since 5.0

val get_int32_be : string -> int -> int32

get_int32_be b i — это целое 32-битное число со знаком big-endian структуры b, начиная с символа с индексом i.

Since 4.13

val get_int32_le : string -> int -> int32

get_int32_le b i — это целое 32-битное число со знаком little-endian структуры b, начиная с символа с индексом i.

Since 4.13

val get_int64_ne : string -> int -> int64

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

Since 4.13

val get_int64_be : string -> int -> int64

get_int64_be b i — это целое 64-битное число со знаком big-endian структуры b, начиная с символа с индексом i.

Since 4.13

val get_int64_le : string -> int -> int64

get_int64_le b i — это целое 64-битное число со знаком little-endian структуры b, начиная с символа с индексом i.

Since 4.13