Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Docs] Add examples for Belt.Array #2730

Merged
merged 2 commits into from
Apr 10, 2018
Merged

[Docs] Add examples for Belt.Array #2730

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cdcf959
Remove snarky comment about endsWithFrom.
jdeisenberg Apr 8, 2018
b6738c0
Add examples for Belt.Array.
jdeisenberg Apr 10, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
162 changes: 137 additions & 25 deletions jscomp/others/belt_Array.mli
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,23 @@ external size: 'a array -> int = "%array_length"
(** {b See} {!length} *)

val get: 'a array -> int -> 'a option
(**
[get arr i]

If [i <= 0 <= length arr], returns [Some value] where [value] is the item at index [i]
If [i] is out of range, returns [None]

@example {[
Belt.Array.get [|"a";"b";"c"|] 0 = Some "a";;
Belt.Array.get [|"a";"b";"c"|] 4 = None;;
Belt.Array.get [|"a";"b";"c"|] (-1) = None;;
]}
*)

val getExn: 'a array -> int -> 'a
(** [getExn arr i]

{b raise} an exception if [i] is out of range
{b raise} an exception if [i] is out of range, otherwise return the value at index [i] in [arr]
*)

external getUnsafe: 'a array -> int -> 'a = "%array_unsafe_get"
Expand Down Expand Up @@ -63,23 +75,53 @@ val setExn: 'a array -> int -> 'a -> unit
external setUnsafe: 'a array -> int -> 'a -> unit = "%array_unsafe_set"

val shuffleInPlace: 'a array -> unit
(** [shuffleInPlace arr] randomly re-orders the items in [arr] *)

val shuffle: 'a array -> 'a array
(** [shuffle xs]
@return a fresh array *)
@return a fresh array with items in original array randomly shuffled *)

val reverseInPlace: 'a array -> unit
(** [reverseInPlace arr] reverses items in [arr] in place

@example {[
let arr = [|10;11;12;13;14|];;
let () = reverseInPlace arr;;
arr = [|14;13;12;11;10|];;
]}
*)

val reverse: 'a array -> 'a array
(** [reverse x]
@return a fresh array *)
(** [reverse arr]
@return a fresh array with items in [arr] in reverse order

@example {[
reverse [|10;11;12;13;14|] = [|14;13;12;11;10|];;
]}
*)

external makeUninitialized: int -> 'a Js.undefined array = "Array" [@@bs.new]
(**
[makeUninitialized n] creates an array of length [n] filled with the undefined value.
You must specify the type of data that will eventually fill the array.

@example {[
let arr: string Js.undefined array = makeUninitialized 5;;
getExn arr 0 = Js.undefined;;
]}
*)

external makeUninitializedUnsafe: int -> 'a array = "Array" [@@bs.new]
(** [makeUninitializedUnsafe n]

{b Unsafe}
{b Unsafe}

@example {[
let arr = Belt.Array.makeUninitializedUnsafe 5;;
let () = Js.log(Belt.Array.getExn arr 0);; (* undefined *)
Belt.Array.setExn arr 0 "example";;
let () = Js.log(Belt.Array.getExn arr 0 = "example");;
]}
*)


Expand Down Expand Up @@ -122,7 +164,8 @@ val makeBy: int -> (int -> 'a ) -> 'a array
return an array of size [n] populated by [f i] start from [0] to [n - 1]

@example {[
makeBy 5 (fun i -> i) = [|0;1;2;3;4|]
makeBy 5 (fun i -> i) = [|0;1;2;3;4|];;
makeBy 5 (fun i -> i * i) = [|0;1;4;9;16|]
]}
*)

Expand All @@ -137,10 +180,11 @@ val makeByAndShuffle: int -> (int -> 'a ) -> 'a array
val zip: 'a array -> 'b array -> ('a * 'b) array
(** [zip a b]

Create an array of tuples from corresponding elements of [a] and [b].
Stop with the shorter array

@example {[
zip [|1;2] [|1;2;3|] = [| (1,2); (2;2)|]
zip [|1;2] [|3;4;5|] = [| (1,3); (2;4) |]
]}
*)

Expand All @@ -150,9 +194,14 @@ val zip: 'a array -> 'b array -> ('a * 'b) array
(**
[zipBy xs ys f]

Create an array by applying [f] to corresponding elements of [xs] and [ys]
Stops with shorter array

Equivalent to [map (zip xs ys) (fun (a,b) -> f a b) ]

@example {[
zipBy [|1;2;3|] [|4;5|] (fun a b -> 2 * a + b) = [|6;9|];;
]}
*)

val concat: 'a array -> 'a array -> 'a array
Expand All @@ -161,50 +210,70 @@ val concat: 'a array -> 'a array -> 'a array
@return a fresh array containing the
concatenation of the arrays [v1] and [v2], so even if [v1] or [v2]
is empty, it can not be shared

@example {[
concat [|1;2;3|] [|4;5|] = [|1;2;3;4;5|];;
concat [| |] [|"a";"b";"c"|] = [|"a";"b";"c"|];;
]}
*)

val concatMany: 'a array array -> 'a array
(**
[concatMany xss]

@return a fresh array as the concatenation of [xss]
@return a fresh array as the concatenation of [xss] (an array of arrays)

@example {[
concatMany [| [|1;2;3|]; [|4;5;6|]; [|7;8|] |] = [|1;2;3;4;5;6;7;8|];;
]}
*)

val slice: 'a array -> offset:int -> len:int -> 'a array
(** [slice arr offset len]
(** [slice arr offset len] creates a new array with the [len] elements of [arr] starting at [offset] for

[offset] can be negative,
[offset] can be negative, and is evaluated as [length arr - offset]
[slice arr -1 1] means get the last element as a singleton array

[slice arr -(very_large_index) len] will do a copy of the array
[slice arr (-len) len] will return a copy of the array

if the array does not have enough data, [slice] extracts through
the end of sequence
the end of sequence.

if [len] is negative, returns the empty array.

@example {[
slice [|10;11;12;13;14;15;16|] ~offset: 2 ~len: 3 = [|12;13;14|];;
slice [|10;11;12;13;14;15;16|] ~offset: (-4) ~len: 3 = [|13;14;15|];;
slice [|10;11;12;13;14;15;16|] ~offset:4 ~len:9 = [|14;15;16|];;
]}
*)


val copy: 'a array -> 'a array
(** [copy a]

@return a copy of [a], that is, a fresh array
containing the same elements as [a]. *)
containing the same elements as [a].
*)

val fill: 'a array -> offset:int -> len:int -> 'a -> unit
(** [fill arr ~offset ~len x]

Modifies [arr] in place,
storing [x] in elements number [offset] to [offset + len - 1].

[offset] can be negative
[offset] can be negative, and is evaluated as [length arr - offset]

[fill arr offset:(-1) len:1 ] means fill the last element,
if the array does not have enough data, [fill] will ignore it

@example {[

let arr = makeBy 5 (fun i -> i) ;;
fill arr ~offset:2 ~len:2 0 ;;
arr = [|0;1;0;0;4|];;
fill arr ~offset:2 ~len:2 9 ;;
arr = [|0;1;9;9;4|];;
fill arr ~offset:7 ~len:2 8;;
arr = [|0;1;9;9;4|];;
]}
*)

Expand Down Expand Up @@ -287,7 +356,8 @@ val reduce: 'b array -> 'a -> ('a -> 'b -> 'a ) ->'a
(** [reduce xs init f]

@example {[
reduce [|2;3;4|] 1 (+) = 10
reduce [|2;3;4|] 1 (+) = 10;;
reduce [|"a";"b";"c";"d"|] "" (^) = "abcd";;
]}

*)
Expand All @@ -296,7 +366,7 @@ val reduceReverseU: 'b array -> 'a -> ('a -> 'b -> 'a [@bs]) -> 'a
val reduceReverse: 'b array -> 'a -> ('a -> 'b -> 'a ) -> 'a
(** [reduceReverse xs init f]
@example {[
reduceReverse [|1;2;3;4|] 100 (-) = 90
reduceReverse [|"a";"b";"c";"d"|] "" (^) = "dcba";;
]}
*)

Expand All @@ -305,6 +375,10 @@ val reduceReverse2U:
val reduceReverse2:
'a array -> 'b array -> 'c -> ('c -> 'a -> 'b -> 'c) -> 'c
(**
[reduceReverse2 xs ys init f]
Reduces two arrays [xs] and [ys], taking items starting at [min (length xs) (length ys)]
down to and including zero.

@example {[
reduceReverse2 [|1;2;3|] [|1;2|] 0 (fun acc x y -> acc + x + y) = 6
]}
Expand All @@ -314,18 +388,28 @@ val someU: 'a array -> ('a -> bool [@bs]) -> bool
val some: 'a array -> ('a -> bool) -> bool
(** [some xs p]
@return true if one of element satifies [p]

@example {[
some [|2; 3; 4|] (fun x -> x mod 2 = 1) = true;;
some [|-1; -3; -5|] (fun x -> x > 0) = false;;
]}
*)

val everyU: 'a array -> ('a -> bool [@bs]) -> bool
val every: 'a array -> ('a -> bool ) -> bool
(** [every xs p]
@return true if all elements satisfy [p]

@example {[
every [|1; 3; 5|] (fun x -> x mod 2 = 1) = true;;
every [|1; -3; 5|] (fun x -> x > 0) = false;;
]}
*)

val every2U: 'a array -> 'b array -> ('a -> 'b -> bool [@bs]) -> bool
val every2: 'a array -> 'b array -> ('a -> 'b -> bool ) -> bool
(** [every2 xs ys p] only tests the length of shorter

(** [every2 xs ys p] returns true if [p xi yi] is true for all pairs of elements
up to the shorter length (i.e. [min (length xs) (length ys)])
@example {[
every2 [|1;2;3|] [|0;1|] (>) = true;;
(every2 [||] [|1|] (fun x y -> x > y)) = true;;
Expand All @@ -335,7 +419,8 @@ val every2: 'a array -> 'b array -> ('a -> 'b -> bool ) -> bool

val some2U: 'a array -> 'b array -> ('a -> 'b -> bool [@bs]) -> bool
val some2: 'a array -> 'b array -> ('a -> 'b -> bool ) -> bool
(** [some2 xs ys p] only tests the length of shorter
(** [some2 xs ys p] returns true if [p xi yi] is true for any pair of elements
up to the shorter length (i.e. [min (length xs) (length ys)])

@example {[
some2 [|0;2|] [|1;0;3|] (>) = true ;;
Expand All @@ -348,17 +433,44 @@ val cmpU: 'a array -> 'a array -> ('a -> 'a -> int [@bs]) -> int
val cmp: 'a array -> 'a array -> ('a -> 'a -> int ) -> int
(** [cmp a b]

- Compared by length if [length a <> length b]
- Otherwise compare one by one [f ai bi]
- Compared by length if [length a <> length b], returning -1 if [length a < length b] or 1 if [length a > length b]
- Otherwise compare one by one [f ai bi]. [f] returns
- a negative number if [ai] is “less than” [bi]
- zero if [ai] is “equal to” [bi]
- a positive number if [ai] is “greater than” [bi]
- The comparison returns the first non-zero result of [f], or zero if [f] returns zero for all [ai] and [bi].

@example {[
cmp [|1; 3; 5|] [|1; 4; 2|] (fun a b -> compare a b) = -1;;
cmp [|1; 3; 5|] [|1; 2; 3|] (fun a b -> compare a b) = 1;;
cmp [|1; 3; 5|] [|1; 3; 5|] (fun a b -> compare a b) = 0;;
]}
*)

val eqU: 'a array -> 'a array -> ('a -> 'a -> bool [@bs]) -> bool
val eq: 'a array -> 'a array -> ('a -> 'a -> bool ) -> bool
(** [eq a b]

- return false if length is not the same
- equal one by one using [f ai bi]
- otherwise compare items one by one using [f ai bi], and return true if all results are true, false otherwise

@example {[
eq [|1; 2; 3|] [|-1; -2; -3|] (fun a b -> abs a = abs b) = true
]}
*)

external truncateToLengthUnsafe: 'a array -> int -> unit = "length" [@@bs.set]
(** {b Unsafe} *)
(** {b Unsafe}
[truncateToLengthUnsafe xs n] sets length of array [xs] to [n].

If [n] is greater than the length of [xs], the extra elements are set to [Js.Null_undefined.null]

If [n] is less than zero, raises a [RangeError].

@example {[
let arr = [|"ant", "bee", "cat", "dog", "elk"|] in
let () = truncateToLengthUnsafe arr 3 in
arr = [|"ant", "bee", "cat"|] = true;;
]}

*)
2 changes: 1 addition & 1 deletion jscomp/others/js_string.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ external concatMany : t array -> t = "concat" [@@bs.send.pipe: t] [@@bs.splice]
*)
external endsWith : t -> bool = "" [@@bs.send.pipe: t]

(** [endsWithFrom ending len str] returns [true] if the first [len] characters of [str] end with [ending], [false] otherwise. If [n] is greater than or equal to the length of [str], then it works like [endsWith]. (Honestly, this should have been named [endsWithAt], but oh well.)
(** [endsWithFrom ending len str] returns [true] if the first [len] characters of [str] end with [ending], [false] otherwise. If [n] is greater than or equal to the length of [str], then it works like [endsWith].

@example {[
endsWithFrom "cd" 4 "abcd" = true;;
Expand Down