模組 StringLabels

module StringLabels: sig .. end

字串。

長度為 n 的字串 s 是一個可索引且不可變的 n 個位元組序列。由於歷史原因，這些位元組被稱為字元。

字串函數的語義是根據索引和位置定義的。這些描述如下所示。

positions  0   1   2   3   4    n-1    n
           +---+---+---+---+     +-----+
  indices  | 0 | 1 | 2 | 3 | ... | n-1 |
           +---+---+---+---+     +-----+
  • 字串 s 的索引 i 是一個在範圍 [0; n-1] 中的整數。它表示 s 的第 i 個位元組（字元），可以使用常數時間字串索引運算符 s.[i] 訪問。
  • 字串 s 的位置 i 是一個在範圍 [0; n] 中的整數。它表示字串的開頭、兩個索引之間或字串的結尾。第 i 個位元組索引在位置 i 和 i+1 之間。

如果 len >= 0 且 start、start+len 是 s 的有效位置，則兩個整數 start 和 len 被稱為定義 s 的有效子字串。

Unicode 文字。字串是任意位元組序列，它們可以保存任何種類的文字編碼。但是，建議在 OCaml 字串中儲存 Unicode 文字的編碼是 UTF-8。這是字串文字中 Unicode 轉義序列使用的編碼。例如，字串 "\u{1F42B}" 是 Unicode 字元 U+1F42B 的 UTF-8 編碼。

過去的可變性。在 OCaml 4.02 之前，字串可以像 Bytes.t 可變位元組序列一樣就地修改。OCaml 4 有各種編譯器標誌和配置選項，以支持從可變字串到不可變字串的過渡期。這些選項不再可用，現在字串始終是不可變的。

此模組的標籤版本可以按照 StdLabels 模組中所述使用。

字串

type t = string

字串的類型。

val make : int -> char -> string

make n c 是一個長度為 n 的字串，每個索引都保存字元 c。

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

init n ~f 是一個長度為 n 的字串，索引 i 保存字元 f i（按遞增索引順序調用）。

val empty : string

空字串。

val length : string -> int

length s 是 s 的長度（位元組/字元數）。

val get : string -> int -> char

get s i 是 s 中索引 i 處的字元。這與寫 s.[i] 相同。

val of_bytes : bytes -> string

返回一個包含與給定位元組序列相同位元組的新字串。

val to_bytes : string -> bytes

返回一個包含與給定字串相同位元組的新位元組序列。

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。

val cat : string -> string -> string

cat s1 s2 串接 s1 和 s2（s1 ^ s2）。

斷言和比較

val equal : t -> t -> bool

當且僅當 s0 和 s1 在字元層面相等時，equal s0 s1 才為 true。

val compare : t -> t -> int

compare s0 s1 以詞典順序對 s0 和 s1 進行排序。compare 的行為類似於字串上的 compare，但可能更有效率。

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

當且僅當 s 以 prefix 開頭時，starts_with ~prefix s 才為 true。

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

當且僅當 s 以 suffix 結尾時，ends_with ~suffix s 才為 true。

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

當且僅當 c 出現在 s 中位置 start 之後時，contains_from s start c 才為 true。

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

當且僅當 c 出現在 s 中位置 stop+1 之前時，rcontains_from s stop c 才為 true。

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。

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 字元。

轉換

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

map f s 是將 f 按遞增順序應用於 s 的所有字元而產生的字串。

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

mapi ~f s 與 StringLabels.map 類似，但字元的索引也會傳遞給 f。

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 的長度。

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 的長度。

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

for_all p s 檢查 s 中的所有字元是否都滿足謂詞 p。

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

exists p s 檢查 s 中是否至少有一個字元滿足謂詞 p。

val trim : string -> string

trim s 是 s，不帶前導和尾隨空白。空白字元包括：' '、'\x0C'（換頁）、'\n'、'\r' 和 '\t'。

val escaped : string -> string

escaped s 是 s，其中特殊字元由跳脫序列表示，遵循 OCaml 的詞法約定。

所有在 US-ASCII 可列印範圍 [0x20; 0x7E] 之外的字元以及反斜線 (0x2F) 和雙引號 (0x22) 都會被跳脫。

函數 Scanf.unescaped 是 escaped 的左反函數，即對於任何字串 s，Scanf.unescaped (escaped s) = s （除非 escaped s 失敗）。

val uppercase_ascii : string -> string

uppercase_ascii s 是 s，其中所有小寫字母都使用 US-ASCII 字元集轉換為大寫字母。

val lowercase_ascii : string -> string

lowercase_ascii s 是 s，其中所有大寫字母都使用 US-ASCII 字元集轉換為小寫字母。

val capitalize_ascii : string -> string

capitalize_ascii s 是 s，其中第一個字元使用 US-ASCII 字元集設定為大寫字母。

val uncapitalize_ascii : string -> string

uncapitalize_ascii s 是 s，其中第一個字元使用 US-ASCII 字元集設定為小寫字母。

遍歷

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 類似，但函數也會收到相應的字元索引。

搜尋

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

index_from s i c 是 c 在 s 中位置 i 之後第一次出現的索引。

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

index_from_opt s i c 是 c 在 s 中位置 i 之後第一次出現的索引（如果有的話）。

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

rindex_from s i c 是 c 在 s 中位置 i+1 之前最後一次出現的索引。

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

rindex_from_opt s i c 是 c 在 s 中位置 i+1 之前最後一次出現的索引（如果有的話）。

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。

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。

字串和序列

val to_seq : t -> char Seq.t

to_seq s 是一個由字串的字元依遞增順序組成的序列。在 "unsafe-string" 模式下，迭代期間對字串的修改將會反映在序列中。

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

to_seqi s 類似於 StringLabels.to_seq，但也會將對應的索引作為元組包含在內。

val of_seq : char Seq.t -> t

of_seq s 是一個由序列的字元組成的字串。

UTF 解碼和驗證

UTF-8

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

get_utf_8_uchar b i 解碼在 b 中索引為 i 的 UTF-8 字元。

val is_valid_utf_8 : t -> bool

is_valid_utf_8 b 當且僅當 b 包含有效的 UTF-8 資料時為 true。

UTF-16BE

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

get_utf_16be_uchar b i 解碼在 b 中索引為 i 的 UTF-16BE 字元。

val is_valid_utf_16be : t -> bool

is_valid_utf_16be b 當且僅當 b 包含有效的 UTF-16BE 資料時為 true。

UTF-16LE

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

get_utf_16le_uchar b i 解碼在 b 中索引為 i 的 UTF-16LE 字元。

val is_valid_utf_16le : t -> bool

is_valid_utf_16le b 當且僅當 b 包含有效的 UTF-16LE 資料時為 true。

整數的二進制解碼

本節中的函數從字串中二進制解碼整數。

如果索引 i 處解碼整數所需的字元不可用，則所有以下函數都會引發 Invalid_argument 異常。

小端 (little-endian)（或大端 (big-endian)）編碼表示最小（或最大）有效位元組最先儲存。大端也稱為網路位元組順序。原生端 (native-endian) 編碼是小端或大端，取決於 Sys.big_endian。

32 位元和 64 位元整數由 int32 和 int64 類型表示，可以解釋為有號或無號數字。

8 位元和 16 位元整數由 int 類型表示，該類型具有比二進制編碼更多的位元。對於解碼 8 位元或 16 位元整數並以 int 值表示的函數，這些額外的位元會進行符號擴展（或零擴展）。

val get_uint8 : string -> int -> int

get_uint8 b i 是從字元索引 i 開始的 b 的無號 8 位元整數。

val get_int8 : string -> int -> int

get_int8 b i 是從字元索引 i 開始的 b 的有號 8 位元整數。

val get_uint16_ne : string -> int -> int

get_uint16_ne b i 是從字元索引 i 開始的 b 的原生端無號 16 位元整數。

val get_uint16_be : string -> int -> int

get_uint16_be b i 是從字元索引 i 開始的 b 的大端無號 16 位元整數。

val get_uint16_le : string -> int -> int

get_uint16_le b i 是從字元索引 i 開始的 b 的小端無號 16 位元整數。

val get_int16_ne : string -> int -> int

get_int16_ne b i 是從字元索引 i 開始的 b 的原生端有號 16 位元整數。

val get_int16_be : string -> int -> int

get_int16_be b i 是從字元索引 i 開始的 b 的大端有號 16 位元整數。

val get_int16_le : string -> int -> int

get_int16_le b i 是從字元索引 i 開始的 b 的小端有號 16 位元整數。

val get_int32_ne : string -> int -> int32

get_int32_ne b i 是從字元索引 i 開始的 b 的原生端 32 位元整數。

val hash : t -> int

一個用於字串的未播種雜湊函數，與 Hashtbl.hash 具有相同的輸出值。此函數允許將此模組作為參數傳遞給函子 Hashtbl.Make。

val seeded_hash : int -> t -> int

一個用於字串的播種雜湊函數，與 Hashtbl.seeded_hash 具有相同的輸出值。此函數允許將此模組作為參數傳遞給函子 Hashtbl.MakeSeeded。

val get_int32_be : string -> int -> int32

get_int32_be b i 是從字元索引 i 開始的 b 的大端 32 位元整數。

val get_int32_le : string -> int -> int32

get_int32_le b i 是從字元索引 i 開始的 b 的小端 32 位元整數。

val get_int64_ne : string -> int -> int64

get_int64_ne b i 是從字元索引 i 開始的 b 的原生端 64 位元整數。

val get_int64_be : string -> int -> int64

get_int64_be b i 是從字元索引 i 開始的 b 的大端 64 位元整數。

val get_int64_le : string -> int -> int64

get_int64_le b i 是從字元索引 i 開始的 b 的小端 64 位元整數。