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

Текст 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 -> (int -> char) -> string

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

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

val empty : string

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

Since 4.13.0

val of_bytes : bytes -> string

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

Since 4.13.0

val to_bytes : string -> bytes

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

Since 4.13.0

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 concat : 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.0
Raises Invalid_argument если результат длиннее, чем Sys.max_string_length байтов.

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

val equal : t -> t -> bool

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

Since 4.03.0 (4.05.0 в 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.

Since 4.13.0

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

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

Since 4.13.0

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 -> int -> int -> string

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

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

val split_on_char : char -> string -> string list

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

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

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

Since 4.04.0 (4.05.0 в StringLabels)

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

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

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

Since 4.00.0

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

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

Since 4.02.0

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

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

Since 4.13.0

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

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

Since 4.13.0

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

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

Since 4.13.0

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

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

Since 4.13.0

val trim : string -> string

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

Since 4.00.0

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 не терпит неудачу).

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

val uppercase_ascii : string -> string

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

С версии 4.03.0 (4.05.0 в StringLabels)

val lowercase_ascii : string -> string

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

С версии 4.03.0 (4.05.0 в StringLabels)

val capitalize_ascii : string -> string

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

С версии 4.03.0 (4.05.0 в StringLabels)

val uncapitalize_ascii : string -> string

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

С версии 4.03.0 (4.05.0 в 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, но функция также получает соответствующий индекс символа.

С версии 4.00.0

Поиск

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 подобна String.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.

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

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

Возвращает исключение Invalid_argument если src_pos и len не обозначают допустимый диапазон в src, или если dst_pos и len не обозначают допустимый диапазон в dst.

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

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

Все следующие функции возвращают исключение 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.

С версии 4.13.0

val get_int8 : string -> int -> int

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

С версии 4.13.0

val get_uint16_ne : string -> int -> int

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

С версии 4.13.0

val get_uint16_be : string -> int -> int

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

С версии 4.13.0

val get_uint16_le : string -> int -> int

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

С версии 4.13.0

val get_int16_ne : string -> int -> int

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

С версии 4.13.0

val get_int16_be : string -> int -> int

END_OF_DOCUMENT_MARKER

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

Since 4.13.0

val get_int16_le : string -> int -> int

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

Since 4.13.0

val get_int32_ne : string -> int -> int32

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

Since 4.13.0

val hash : t -> int

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

Since 5.0.0

val seeded_hash : int -> t -> int

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

Since 5.0.0

val get_int32_be : string -> int -> int32

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

Since 4.13.0

val get_int32_le : string -> int -> int32

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

Since 4.13.0

val get_int64_ne : string -> int -> int64

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

Since 4.13.0

val get_int64_be : string -> int -> int64

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

Since 4.13.0

val get_int64_le : string -> int -> int64

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

Since 4.13.0