Модуль String

module String: 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.

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

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

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

Строки

type t = string

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

val make : int -> char -> string

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

Возбуждает исключение Invalid_argument если n < 0 или n > Sys.max_string_length.

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

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

С тех пор как 4.02
Возбуждает исключение Invalid_argument если n < 0 или n > Sys.max_string_length.

val empty : string

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

С тех пор как 4.13

val length : string -> int

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

val get : string -> int -> char

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

Возбуждает исключение Invalid_argument если i не является индексом строки s.

val of_bytes : bytes -> string

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

С тех пор как 4.13

val to_bytes : string -> bytes

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

С тех пор как 4.13

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

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

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

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

val concat : string -> string list -> string

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

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

val cat : string -> string -> string

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

С тех пор как 4.13
Возбуждает исключение Invalid_argument если результат длиннее, чем Sys.max_string_length байт.

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

val equal : t -> t -> bool

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

С тех пор как 4.03 (4.05 в StringLabels)

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.

С тех пор как 4.13

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

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

С тех пор как 4.13

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

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

Возбуждает исключение Invalid_argument если start не является допустимой позицией в строке s.

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

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

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

val contains : string -> char -> bool

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

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

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

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

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

val split_on_char : char -> string -> string list

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

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

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

С тех пор как 4.04 (4.05 в StringLabels)

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

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

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

С тех пор как 4.00

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

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

С тех пор как 4.02

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

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

С тех пор как 4.13

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

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

С тех пор как 4.13

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

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

С тех пор как 4.13

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

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

С тех пор как 4.13

val trim : string -> string

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

Since 4.00

val escaped : string -> string

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

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

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

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

val uppercase_ascii : string -> string

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

Since 4.03 (4.05 в StringLabels)

val lowercase_ascii : string -> string

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

Since 4.03 (4.05 в StringLabels)

val capitalize_ascii : string -> string

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

Since 4.03 (4.05 в StringLabels)

val uncapitalize_ascii : string -> string

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

Since 4.03 (4.05 в StringLabels)

Перебор

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

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

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

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

Since 4.00

Поиск

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

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

Raises
- 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 (если есть).

Since 4.05
Raises Invalid_argument если i не является корректной позицией в s.

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

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

Raises
- 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 (если есть).

Since 4.05
Raises 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.

Since 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.

Since 4.05

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

val to_seq : t -> char Seq.t

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

Since 4.07

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

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

Since 4.07

val of_seq : char Seq.t -> t

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

Since 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 для декодирования целого числа недоступны.

Маленький порядок байтов (соответственно, большой порядок байтов) означает, что наименее (соответственно, наиболее) значимые байты хранятся первыми. Большой порядок байтов также известен как сетевой порядок байтов. Порядок байтов по умолчанию — это либо маленький порядок байтов, либо большой порядок байтов, в зависимости от 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.

Since 4.13

val get_int8 : string -> int -> int

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

Since 4.13

val get_uint16_ne : string -> int -> int

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

Since 4.13

val get_uint16_be : string -> int -> int

get_uint16_be b i — беззнаковое 16-битное целое число b с большим порядком байтов, начиная с индекса символа i.

Since 4.13

val get_uint16_le : string -> int -> int

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

Since 4.13

val get_int16_ne : string -> int -> int

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

Since 4.13

val get_int16_be : string -> int -> int

get_int16_be b i — знаковое 16-битное целое число b с большим порядком байтов, начиная с индекса символа i.

Since 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