模組 Stdlib.Array

module Array: Array

type 'a t = 'a array 

陣列型別的別名。

val length : 'a array -> int

傳回給定陣列的長度(元素數量)。

val get : 'a array -> int -> 'a

get a n 傳回陣列 a 的第 n 個元素。第一個元素的編號為 0。最後一個元素的編號為 length a - 1。您也可以使用 a.(n) 來取代 get a n

val set : 'a array -> int -> 'a -> unit

set a n x 就地修改陣列 a,將第 n 個元素替換為 x。您也可以使用 a.(n) <- x 來取代 set a n x

val make : int -> 'a -> 'a array

make n x 傳回一個長度為 n 的新陣列,並以 x 初始化。這個新陣列的所有元素最初在物理上都等於 x(在 == 謂詞的意義上)。因此,如果 x 是可變的,則它在陣列的所有元素之間共享,並且透過陣列條目之一修改 x 將同時修改所有其他條目。

val create_float : int -> float array

create_float n 傳回一個長度為 n 的新浮點數陣列,並包含未初始化的資料。

val init : int -> (int -> 'a) -> 'a array

init n f 傳回一個長度為 n 的新陣列,其中第 i 個元素初始化為 f i 的結果。換句話說,init n f 以遞增順序將 f 應用於整數 0n-1,並將結果製成表格。

val make_matrix : int -> int -> 'a -> 'a array array

make_matrix dimx dimy e 傳回一個二維陣列(陣列的陣列),其中第一維為 dimx,第二維為 dimy。這個新矩陣的所有元素最初在物理上都等於 e。矩陣 m 的元素 (x,y) 使用符號 m.(x).(y) 存取。

val init_matrix : int -> int -> (int -> int -> 'a) -> 'a array array

init_matrix dimx dimy f 傳回一個二維陣列(陣列的陣列),其中第一維為 dimx,第二維為 dimy,索引為 (x,y) 的元素以 f x y 初始化。矩陣 m 的元素 (x,y) 使用符號 m.(x).(y) 存取。

val append : 'a array -> 'a array -> 'a array

append v1 v2 傳回一個新的陣列,其中包含陣列 v1v2 的串聯。

val concat : 'a array list -> 'a array

Array.append 相同,但串聯的是陣列的列表。

val sub : 'a array -> int -> int -> 'a array

sub a pos len 傳回一個長度為 len 的新陣列,其中包含陣列 a 的第 pospos + len - 1 個元素。

val copy : 'a array -> 'a array

copy a 傳回 a 的副本,也就是說,一個包含與 a 相同元素的新陣列。

val fill : 'a array -> int -> int -> 'a -> unit

fill a pos len x 就地修改陣列 a,將 x 儲存在第 pospos + len - 1 個元素中。

val blit : 'a array -> int -> 'a array -> int -> int -> unit

blit src src_pos dst dst_pos len 從陣列 src(從第 src_pos 個元素開始)複製 len 個元素到陣列 dst(從第 dst_pos 個元素開始)。即使 srcdst 是同一個陣列,且來源和目的地區塊重疊,它也能正確運作。

val to_list : 'a array -> 'a list

to_list a 傳回 a 的所有元素的列表。

val of_list : 'a list -> 'a array

of_list l 傳回一個新的陣列,其中包含 l 的元素。

迭代器

val iter : ('a -> unit) -> 'a array -> unit

iter f a 輪流將函數 f 應用於 a 的所有元素。它等效於 f a.(0); f a.(1); ...; f a.(length a - 1); ()

val iteri : (int -> 'a -> unit) -> 'a array -> unit

Array.iter 相同,但函數的第一個引數是元素的索引,第二個引數是元素本身。

val map : ('a -> 'b) -> 'a array -> 'b array

map f a 將函數 f 應用於 a 的所有元素,並使用 f 傳回的結果來建立一個陣列:[| f a.(0); f a.(1); ...; f a.(length a - 1) |]

val map_inplace : ('a -> 'a) -> 'a array -> unit

map_inplace f a 將函數 f 應用於 a 的所有元素,並就地更新它們的值。

val mapi : (int -> 'a -> 'b) -> 'a array -> 'b array

Array.map 相同,但函數的第一個引數是元素的索引,第二個引數是元素本身。

val mapi_inplace : (int -> 'a -> 'a) -> 'a array -> unit

Array.map_inplace 相同,但函數的第一個引數是元素的索引,第二個引數是元素本身。

val fold_left : ('acc -> 'a -> 'acc) -> 'acc -> 'a array -> 'acc

fold_left f init a 計算 f (... (f (f init a.(0)) a.(1)) ...) a.(n-1),其中 n 是陣列 a 的長度。

val fold_left_map : ('acc -> 'a -> 'acc * 'b) -> 'acc -> 'a array -> 'acc * 'b array

fold_left_mapArray.fold_leftArray.map 的組合,它透過呼叫 f 來傳遞累加器。

val fold_right : ('a -> 'acc -> 'acc) -> 'a array -> 'acc -> 'acc

fold_right f a init 計算 f a.(0) (f a.(1) ( ... (f a.(n-1) init) ...)),其中 n 是陣列 a 的長度。

兩個陣列的迭代器

val iter2 : ('a -> 'b -> unit) -> 'a array -> 'b array -> unit

iter2 f a b 將函數 f 應用於 ab 的所有元素。

val map2 : ('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array

map2 f a b 將函數 f 應用於 ab 的所有元素,並使用 f 傳回的結果來建立一個陣列:[| f a.(0) b.(0); ...; f a.(length a - 1) b.(length b - 1)|]

陣列掃描

val for_all : ('a -> bool) -> 'a array -> bool

for_all f [|a1; ...; an|] 檢查陣列的所有元素是否都滿足謂詞 f。也就是說,它會傳回 (f a1) && (f a2) && ... && (f an)

val exists : ('a -> bool) -> 'a array -> bool

exists f [|a1; ...; an|] 檢查陣列中是否至少有一個元素滿足謂詞 f。也就是說,它會傳回 (f a1) || (f a2) || ... || (f an)

val for_all2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> bool

Array.for_all 相同,但使用兩個引數的謂詞。

val exists2 : ('a -> 'b -> bool) -> 'a array -> 'b array -> bool

Array.exists 相同,但使用兩個引數的謂詞。

val mem : 'a -> 'a array -> bool

mem a set 成立,當且僅當 a 在結構上等於 set 的元素時(也就是說,set 中存在 x 使得 compare a x = 0)。

val memq : 'a -> 'a array -> bool

Array.mem 相同,但使用物理相等性而不是結構相等性來比較陣列元素。

val find_opt : ('a -> bool) -> 'a array -> 'a option

find_opt f a 傳回陣列 a 中第一個滿足謂詞 f 的元素,如果陣列 a 中沒有滿足 f 的值,則傳回 None

val find_index : ('a -> bool) -> 'a array -> int option

find_index f a 傳回 Some i,其中 i 是陣列 a 中第一個滿足 f x 的元素的索引(如果存在這樣的元素)。

如果沒有這樣的元素,則傳回 None

val find_map : ('a -> 'b option) -> 'a array -> 'b option

find_map f a 依序將 f 應用於 a 的元素,並傳回第一個 Some v 形式的結果,如果沒有,則傳回 None

val find_mapi : (int -> 'a -> 'b option) -> 'a array -> 'b option

find_map 相同,但謂詞的第一個引數是元素的索引(從 0 開始計數),第二個引數是元素本身。

成對陣列

val split : ('a * 'b) array -> 'a array * 'b array

split [|(a1,b1); ...; (an,bn)|]([|a1; ...; an|], [|b1; ...; bn|])

val combine : 'a array -> 'b array -> ('a * 'b) array

combine [|a1; ...; an|] [|b1; ...; bn|][|(a1,b1); ...; (an,bn)|]。如果兩個陣列長度不同,則引發 Invalid_argument

排序和洗牌

val sort : ('a -> 'a -> int) -> 'a array -> unit

根據比較函數,以遞增順序對陣列進行排序。比較函數必須在參數相等時返回 0,第一個參數較大時返回正整數,第一個參數較小時返回負整數(完整規範請見下文)。例如,compare 是一個合適的比較函數。調用 sort 後,陣列會原地以遞增順序排序。sort 保證在常數堆疊空間和(最多)對數堆疊空間中執行。

目前的實作使用堆積排序。它在常數堆疊空間中執行。

比較函數的規範:假設 a 是陣列,cmp 是比較函數。對於 a 中的所有 xyz,以下必須為真:

  • cmp x y > 0 若且唯若 cmp y x < 0
  • 如果 cmp x y >= 0 且 cmp y z >= 0,則 cmp x z >= 0

sort 返回時,a 包含與之前相同的元素,但重新排序,使得對於 a 的所有有效索引 i 和 j

  • cmp a.(i) a.(j) >= 0 若且唯若 i >= j
val stable_sort : ('a -> 'a -> int) -> 'a array -> unit

Array.sort 相同,但排序演算法是穩定的(即比較相等的元素會保持其原始順序),且不保證在常數堆疊空間中執行。

目前的實作使用合併排序。它使用長度為 n/2 的臨時陣列,其中 n 是陣列的長度。它通常比目前的 Array.sort 實作更快。

val fast_sort : ('a -> 'a -> int) -> 'a array -> unit

Array.sortArray.stable_sort 相同,取決於哪一個在典型輸入上更快。

val shuffle : rand:(int -> int) -> 'a array -> unit

shuffle rand a 使用 rand 隨機置換 a 的元素。置換的分佈是均勻的。

rand 必須是這樣的,呼叫 rand n 會返回範圍 [0;n-1] 中均勻分佈的隨機數。Random.int 可以用於此(不要忘記 初始化 產生器)。

陣列和序列

val to_seq : 'a array -> 'a Seq.t

以遞增順序迭代陣列。在迭代期間修改陣列將反映在序列中。

val to_seqi : 'a array -> (int * 'a) Seq.t

以遞增順序迭代陣列,並同時產生索引和元素。在迭代期間修改陣列將反映在序列中。

val of_seq : 'a Seq.t -> 'a array

從產生器建立陣列

陣列和並發安全性

當從多個網域並行存取陣列時,必須小心:存取陣列永遠不會導致程式崩潰,但未同步的存取可能會產生令人驚訝的(非循序一致的)結果。

原子性

每個存取多個陣列元素的陣列操作都不是原子操作。這包括迭代、掃描、排序、分割和組合陣列。

例如,考慮以下程式碼

let size = 100_000_000
let a = Array.make size 1
let d1 = Domain.spawn (fun () ->
   Array.iteri (fun i x -> a.(i) <- x + 1) a
)
let d2 = Domain.spawn (fun () ->
  Array.iteri (fun i x -> a.(i) <- 2 * x + 1) a
)
let () = Domain.join d1; Domain.join d2

執行此程式碼後,陣列 a 的每個欄位都是 2345。如果需要原子性,則使用者必須實作自己的同步(例如,使用 Mutex.t)。

資料競爭

如果兩個網域僅存取陣列的不相交部分,則觀察到的行為等同於來自兩個網域的操作的一些循序交錯。

當兩個網域在沒有同步的情況下存取相同的陣列元素,並且至少有一個存取是寫入時,就會發生資料競爭。在沒有資料競爭的情況下,觀察到的行為等同於來自不同網域的操作的一些循序交錯。

應盡可能避免資料競爭,方法是使用同步來調解對陣列元素的存取。

事實上,在存在資料競爭的情況下,程式不會崩潰,但觀察到的行為可能不等同於來自不同網域的操作的任何循序交錯。然而,即使在存在資料競爭的情況下,讀取操作也會返回先前寫入該位置的值(對於浮點數陣列有一些例外)。

浮點數陣列

在存在資料競爭的情況下,浮點數陣列有兩個額外的注意事項。

首先,blit 操作可能會逐位元組複製陣列。由於撕裂,此類 blit 操作與另一個操作之間的資料競爭可能會產生令人驚訝的值:與其他操作交錯的部分寫入可以建立在循序執行中不存在的浮點數值。

例如,在

let zeros = Array.make size 0.
let max_floats = Array.make size Float.max_float
let res = Array.copy zeros
let d1 = Domain.spawn (fun () -> Array.blit zeros 0 res 0 size)
let d2 = Domain.spawn (fun () -> Array.blit max_floats 0 res 0 size)
let () = Domain.join d1; Domain.join d2

之後,res 陣列可能包含既不是 0. 也不是 max_float 的值。

其次,在 32 位元架構上,取得或設定欄位涉及兩個單獨的記憶體存取。在存在資料競爭的情況下,使用者可能會在任何操作上觀察到撕裂。