Skip to content

Commit b72f335

Browse files
committed
Use more optional args in stdlib and deprecate some functions
1 parent 39e90c7 commit b72f335

16 files changed

+211
-133
lines changed

runtime/Stdlib_Array.res

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,12 @@ external unsafe_get: (array<'a>, int) => 'a = "%array_unsafe_get"
1313
@val
1414
external fromArrayLikeWithMap: (arrayLike<'a>, 'a => 'b) => array<'b> = "Array.from"
1515

16-
@send external fillAll: (array<'a>, 'a) => unit = "fill"
16+
@deprecated("Use `fill` instead") @send external fillAll: (array<'a>, 'a) => unit = "fill"
1717

18-
@send external fillToEnd: (array<'a>, 'a, ~start: int) => unit = "fill"
18+
@deprecated("Use `fill` instead") @send
19+
external fillToEnd: (array<'a>, 'a, ~start: int) => unit = "fill"
1920

20-
@send external fill: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill"
21+
@send external fill: (array<'a>, 'a, ~start: int=?, ~end: int=?) => unit = "fill"
2122

2223
let make = (~length, x) =>
2324
if length <= 0 {
@@ -83,13 +84,15 @@ let compare = (a, b, cmp) => {
8384
: compareFromIndex(a, b, 0, cmp, lenA)
8485
}
8586

86-
@send external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin"
87+
@deprecated("Use `copyWithin` instead") @send
88+
external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin"
8789

88-
@send
90+
@deprecated("Use `copyWithin` instead") @send
8991
external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = "copyWithin"
9092

9193
@send
92-
external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin"
94+
external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int=?) => array<'a> =
95+
"copyWithin"
9396

9497
@send external pop: array<'a> => option<'a> = "pop"
9598

@@ -124,13 +127,14 @@ external removeInPlace: (array<'a>, int, @as(1) _) => unit = "splice"
124127

125128
@send external includes: (array<'a>, 'a) => bool = "includes"
126129

127-
@send external indexOf: (array<'a>, 'a) => int = "indexOf"
130+
@send external indexOf: (array<'a>, 'a, ~from: int=?) => int = "indexOf"
128131
let indexOfOpt = (arr, item) =>
129132
switch arr->indexOf(item) {
130133
| -1 => None
131134
| index => Some(index)
132135
}
133-
@send external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf"
136+
@deprecated("Use `indexOf` instead") @send
137+
external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf"
134138

135139
@send external join: (array<string>, string) => string = "join"
136140

@@ -142,16 +146,19 @@ external joinWith: (array<string>, string) => string = "join"
142146
@deprecated("Use `joinUnsafe` instead") @send
143147
external joinWithUnsafe: (array<'a>, string) => string = "join"
144148

145-
@send external lastIndexOf: (array<'a>, 'a) => int = "lastIndexOf"
149+
@send external lastIndexOf: (array<'a>, 'a, ~from: int=?) => int = "lastIndexOf"
146150
let lastIndexOfOpt = (arr, item) =>
147151
switch arr->lastIndexOf(item) {
148152
| -1 => None
149153
| index => Some(index)
150154
}
151-
@send external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf"
155+
@deprecated("Use `lastIndexOf` instead") @send
156+
external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf"
157+
158+
@send external slice: (array<'a>, ~start: int=?, ~end: int=?) => array<'a> = "slice"
159+
@deprecated("Use `slice` instead") @send
160+
external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice"
152161

153-
@send external slice: (array<'a>, ~start: int, ~end: int) => array<'a> = "slice"
154-
@send external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice"
155162
@send external copy: array<'a> => array<'a> = "slice"
156163

157164
@send external sort: (array<'a>, ('a, 'a) => Stdlib_Ordering.t) => unit = "sort"

runtime/Stdlib_Array.resi

Lines changed: 62 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -81,15 +81,33 @@ someArray->Array.length == 2
8181
external length: array<'a> => int = "length"
8282

8383
// TODO: Docs
84-
@send external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin"
84+
@deprecated("Use `copyWithin` instead") @send
85+
external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin"
8586

8687
// TODO: Docs
87-
@send
88+
@deprecated("Use `copyWithin` instead") @send
8889
external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = "copyWithin"
8990

90-
// TODO: Docs
91+
/**
92+
`copyWithin(array, ~target, ~start, ~end)` copies the sequence of array elements within the array to the position starting at `target`. The copy is taken from the index positions `start` to `end`.
93+
94+
Beware this will *mutate* the array.
95+
96+
See [`Array.copyWithin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) on MDN.
97+
98+
## Examples
99+
100+
```rescript
101+
let myArray = [1, 2, 3, 4, 5]
102+
myArray->Array.copyWithin(~target=0, ~start=3) == [4, 5, 3, 4, 5]
103+
104+
let myArray = [1, 2, 3, 4, 5]
105+
myArray->Array.copyWithin(~target=1, ~start=3, ~end=4) == [1, 4, 3, 4, 5]
106+
```
107+
*/
91108
@send
92-
external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin"
109+
external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int=?) => array<'a> =
110+
"copyWithin"
93111

94112
/**
95113
`fillAll(array, value)` fills the entire `array` with `value`.
@@ -106,7 +124,7 @@ myArray->Array.fillAll(9)
106124
myArray == [9, 9, 9, 9]
107125
```
108126
*/
109-
@send
127+
@deprecated("Use `fill` instead") @send
110128
external fillAll: (array<'a>, 'a) => unit = "fill"
111129

112130
/**
@@ -124,7 +142,7 @@ myArray->Array.fillToEnd(9, ~start=1)
124142
myArray == [1, 9, 9, 9]
125143
```
126144
*/
127-
@send
145+
@deprecated("Use `fill` instead") @send
128146
external fillToEnd: (array<'a>, 'a, ~start: int) => unit = "fill"
129147

130148
/**
@@ -139,13 +157,18 @@ See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer
139157
```rescript
140158
let myArray = [1, 2, 3, 4]
141159
142-
myArray->Array.fill(9, ~start=1, ~end=3)
160+
myArray->Array.fill(9)
161+
myArray == [9, 9, 9, 9]
162+
163+
myArray->Array.fill(0, ~start=1)
164+
myArray == [9, 0, 0, 0]
143165
144-
myArray == [1, 9, 9, 4]
166+
myArray->Array.fill(5, ~start=1, ~end=3)
167+
myArray == [9, 5, 5, 0]
145168
```
146169
*/
147170
@send
148-
external fill: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill"
171+
external fill: (array<'a>, 'a, ~start: int=?, ~end: int=?) => unit = "fill"
149172

150173
/**
151174
`pop(array)` removes the last item from `array` and returns it.
@@ -416,9 +439,9 @@ See [`Array.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/R
416439
external includes: (array<'a>, 'a) => bool = "includes"
417440

418441
/**
419-
`indexOf(array, item)` returns the index of the provided `item` in `array`. Uses [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) when comparing items.
442+
`indexOf(array, item, ~from)` returns the index of the provided `item` in `array`, starting the search at `from`. Uses [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) when comparing items.
420443
421-
Returns `-1` if the item doesn not exist. Check out `Array.indexOfOpt` for a version that returns `None` instead of `-1` if the item does not exist.
444+
Returns `-1` if the item isn't found. Check out `Array.indexOfOpt` for a version that returns `None` instead of `-1` if the item does not exist.
422445
423446
See [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) on MDN.
424447
@@ -427,12 +450,13 @@ See [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Re
427450
```rescript
428451
[1, 2]->Array.indexOf(2) == 1
429452
[1, 2]->Array.indexOf(3) == -1
453+
[1, 2, 1, 2]->Array.indexOf(2, ~from=2) == 3
430454
431455
[{"language": "ReScript"}]->Array.indexOf({"language": "ReScript"}) == -1 // -1, because of strict equality
432456
```
433457
*/
434458
@send
435-
external indexOf: (array<'a>, 'a) => int = "indexOf"
459+
external indexOf: (array<'a>, 'a, ~from: int=?) => int = "indexOf"
436460

437461
/**
438462
`indexOfOpt(array, item)` returns an option of the index of the provided `item` in `array`. Uses [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) when comparing items.
@@ -448,7 +472,8 @@ See [`Array.indexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Re
448472
```
449473
*/
450474
let indexOfOpt: (array<'a>, 'a) => option<int>
451-
@send external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf"
475+
@deprecated("Use `indexOf` instead") @send
476+
external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf"
452477

453478
/**
454479
`join(array, separator)` produces a string where all items of `array` are printed, separated by `separator`. Array items must be strings, to join number or other arrays, use `joinUnsafe`. Under the hood this will run JavaScript's `toString` on all the array items.
@@ -501,9 +526,27 @@ external joinUnsafe: (array<'a>, string) => string = "join"
501526
*/
502527
@deprecated("Use `joinUnsafe` instead") @send
503528
external joinWithUnsafe: (array<'a>, string) => string = "join"
504-
@send external lastIndexOf: (array<'a>, 'a) => int = "lastIndexOf"
529+
/**
530+
`lastIndexOf(array, item, ~from)` returns the last index of the provided `item` in `array`, searching backwards from `from`. Uses [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality) when comparing items.
531+
532+
Returns `-1` if the item isn't found. Check out `Array.lastIndexOfOpt` for a version that returns `None` instead of `-1` if the item does not exist.
533+
534+
See [`Array.lastIndexOf`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) on MDN.
535+
536+
## Examples
537+
538+
```rescript
539+
[1, 2, 1, 2]->Array.lastIndexOf(2) == 3
540+
[1, 2]->Array.lastIndexOf(3) == -1
541+
[1, 2, 1, 2]->Array.lastIndexOf(2, ~from=2) == 1
542+
543+
[{"language": "ReScript"}]->Array.lastIndexOf({"language": "ReScript"}) == -1 // -1, because of strict equality
544+
```
545+
*/
546+
@send external lastIndexOf: (array<'a>, 'a, ~from: int=?) => int = "lastIndexOf"
505547
let lastIndexOfOpt: (array<'a>, 'a) => option<int>
506-
@send external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf"
548+
@deprecated("Use `lastIndexOf` instead") @send
549+
external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf"
507550

508551
/**
509552
`slice(array, ~start, ~end)` creates a new array of items copied from `array` from `start` until (but not including) `end`.
@@ -514,10 +557,12 @@ See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe
514557
515558
```rescript
516559
[1, 2, 3, 4]->Array.slice(~start=1, ~end=3) == [2, 3]
560+
[1, 2, 3, 4]->Array.slice(~start=1) == [2, 3, 4]
561+
[1, 2, 3, 4]->Array.slice == [1, 2, 3, 4]
517562
```
518563
*/
519564
@send
520-
external slice: (array<'a>, ~start: int, ~end: int) => array<'a> = "slice"
565+
external slice: (array<'a>, ~start: int=?, ~end: int=?) => array<'a> = "slice"
521566

522567
/**
523568
`sliceToEnd(array, start)` creates a new array from `array`, with all items from `array` starting from `start`.
@@ -530,7 +575,7 @@ See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe
530575
[1, 2, 3, 4]->Array.sliceToEnd(~start=1) == [2, 3, 4]
531576
```
532577
*/
533-
@send
578+
@deprecated("Use `slice` instead") @send
534579
external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice"
535580
/**
536581
`copy(array)` makes a copy of the array with the items in it, but does not make copies of the items themselves.

runtime/Stdlib_BigInt64Array.res

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,40 +16,42 @@ external fromArray: array<bigint> => t = "BigInt64Array"
1616

1717
/** `fromBuffer` creates a `BigInt64Array` from an `ArrayBuffer.t`. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array/BigInt64Array)
1818
19-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
19+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
2020
*/
2121
@new
22-
external fromBuffer: Stdlib_ArrayBuffer.t => t = "BigInt64Array"
22+
external fromBuffer: (Stdlib_ArrayBuffer.t, ~byteOffset: int=?, ~length: int=?) => t =
23+
"BigInt64Array"
2324

2425
/** `fromBufferToEnd` creates a `BigInt64Array` from an `ArrayBuffer.t`, starting at a particular offset and continuing through to the end. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array/BigInt64Array)
2526
26-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
27+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
2728
*/
28-
@new
29+
@deprecated("Use `fromBuffer` instead") @new
2930
external fromBufferToEnd: (Stdlib_ArrayBuffer.t, ~byteOffset: int) => t = "BigInt64Array"
3031

3132
/** `fromBufferWithRange` creates a `BigInt64Array` from an `ArrayBuffer.t`, starting at a particular offset and consuming `length` **bytes**. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array/BigInt64Array)
3233
33-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
34+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
3435
*/
35-
@new
36+
@deprecated("Use `fromBuffer` instead") @new
3637
external fromBufferWithRange: (Stdlib_ArrayBuffer.t, ~byteOffset: int, ~length: int) => t =
3738
"BigInt64Array"
3839

3940
/** `fromLength` creates a zero-initialized `BigInt64Array` to hold the specified count of numbers; this is **not** a byte length. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt64Array/BigInt64Array)
4041
41-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
42+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
4243
*/
4344
@new
4445
external fromLength: int => t = "BigInt64Array"
4546

4647
/** `fromArrayLikeOrIterable` creates a `BigInt64Array` from an array-like or iterable object. See [TypedArray.from on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/from)
4748
*/
4849
@val
49-
external fromArrayLikeOrIterable: 'a => t = "BigInt64Array.from"
50+
external fromArrayLikeOrIterable: ('a, ~map: ('b, int) => bigint=?) => t = "BigInt64Array.from"
5051

5152
/** `fromArrayLikeOrIterableWithMap` creates a `BigInt64Array` from an array-like or iterable object and applies the mapping function to each item. The mapping function expects (value, index). See [TypedArray.from on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/from)
5253
*/
54+
@deprecated("Use `fromArrayLikeOrIterable` instead")
5355
@val
5456
external fromArrayLikeOrIterableWithMap: ('a, ('b, int) => bigint) => t = "BigInt64Array.from"
5557

runtime/Stdlib_BigUint64Array.res

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,40 +16,42 @@ external fromArray: array<bigint> => t = "BigUint64Array"
1616

1717
/** `fromBuffer` creates a `BigUint64Array` from an `ArrayBuffer.t`. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array/BigUint64Array)
1818
19-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
19+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
2020
*/
2121
@new
22-
external fromBuffer: Stdlib_ArrayBuffer.t => t = "BigUint64Array"
22+
external fromBuffer: (Stdlib_ArrayBuffer.t, ~byteOffset: int=?, ~length: int=?) => t =
23+
"BigUint64Array"
2324

2425
/** `fromBufferToEnd` creates a `BigUint64Array` from an `ArrayBuffer.t`, starting at a particular offset and continuing through to the end. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array/BigUint64Array)
2526
26-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
27+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
2728
*/
28-
@new
29+
@deprecated("Use `fromBuffer` instead") @new
2930
external fromBufferToEnd: (Stdlib_ArrayBuffer.t, ~byteOffset: int) => t = "BigUint64Array"
3031

3132
/** `fromBufferWithRange` creates a `BigUint64Array` from an `ArrayBuffer.t`, starting at a particular offset and consuming `length` **bytes**. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array/BigUint64Array)
3233
33-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
34+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
3435
*/
35-
@new
36+
@deprecated("Use `fromBuffer` instead") @new
3637
external fromBufferWithRange: (Stdlib_ArrayBuffer.t, ~byteOffset: int, ~length: int) => t =
3738
"BigUint64Array"
3839

3940
/** `fromLength` creates a zero-initialized `BigUint64Array` to hold the specified count of numbers; this is **not** a byte length. See [TypedArray constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigUint64Array/BigUint64Array)
4041
41-
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
42+
**Note:** This is a potentially unsafe operation. Ensure the buffer is large enough and only accessed within its bounds.
4243
*/
4344
@new
4445
external fromLength: int => t = "BigUint64Array"
4546

4647
/** `fromArrayLikeOrIterable` creates a `BigUint64Array` from an array-like or iterable object. See [TypedArray.from on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/from)
4748
*/
4849
@val
49-
external fromArrayLikeOrIterable: 'a => t = "BigUint64Array.from"
50+
external fromArrayLikeOrIterable: ('a, ~map: ('b, int) => bigint=?) => t = "BigUint64Array.from"
5051

5152
/** `fromArrayLikeOrIterableWithMap` creates a `BigUint64Array` from an array-like or iterable object and applies the mapping function to each item. The mapping function expects (value, index). See [TypedArray.from on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/from)
5253
*/
54+
@deprecated("Use `fromArrayLikeOrIterable` instead")
5355
@val
5456
external fromArrayLikeOrIterableWithMap: ('a, ('b, int) => bigint) => t = "BigUint64Array.from"
5557

0 commit comments

Comments
 (0)