Skip to content

Commit ef4719b

Browse files
zthzth
committed
more array docstrings
1 parent a849ac1 commit ef4719b

File tree

1 file changed

+146
-9
lines changed

1 file changed

+146
-9
lines changed

‎src/Core__Array.resi

Lines changed: 146 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -47,9 +47,60 @@ external length: array<'a> => int = "length"
4747
external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = "copyWithin"
4848
@send
4949
external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<'a> = "copyWithin"
50-
@send external fillAllInPlace: (array<'a>, 'a) => unit = "fill"
51-
@send external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill"
52-
@send external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill"
50+
51+
/**
52+
`fillAllInPlace(array, value)` fills the entire provided `array` with the provided `value`.
53+
54+
Beware this will *mutate* the array.
55+
56+
See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN.
57+
58+
## Examples
59+
```rescript
60+
let myArray = [1, 2, 3, 4]
61+
myArray->Array.fillAllInPlace(9)
62+
63+
Console.log(myArray) // [9, 9, 9, 9]
64+
```
65+
*/
66+
@send
67+
external fillAllInPlace: (array<'a>, 'a) => unit = "fill"
68+
69+
/**
70+
`fillInPlaceToEnd` fills the entire provided `array` with the provided `value`, starting from the index provided to `start`.
71+
72+
Beware this will *mutate* the array.
73+
74+
See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN.
75+
76+
## Examples
77+
```rescript
78+
let myArray = [1, 2, 3, 4]
79+
myArray->Array.fillInPlaceToEnd(9, ~start=1)
80+
81+
Console.log(myArray) // [1, 9, 9, 9]
82+
```
83+
*/
84+
@send
85+
external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill"
86+
87+
/**
88+
`fillInPlace` fills the entire provided `array` with the provided `value`, starting from the index provided to `start`, going to the index provided to `end`.
89+
90+
Beware this will *mutate* the array.
91+
92+
See [`Array.fill`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill) on MDN.
93+
94+
## Examples
95+
```rescript
96+
let myArray = [1, 2, 3, 4]
97+
myArray->Array.fillInPlace(9, ~start=1, ~end=2)
98+
99+
Console.log(myArray) // [1, 9, 9, 4]
100+
```
101+
*/
102+
@send
103+
external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill"
53104

54105
/**
55106
`pop(array)` pops off the last item in the array, and returns it.
@@ -107,7 +158,7 @@ Console.log(someArray) // ["hi", "hello", "yay", "wehoo"]
107158
external pushMany: (array<'a>, array<'a>) => unit = "push"
108159

109160
/**
110-
`reverse(array)` reverses the order of the items in the array.
161+
`reverseInPlace(array)` reverses the order of the items in the array.
111162

112163
Beware this will *mutate* the array.
113164

@@ -116,7 +167,7 @@ See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Re
116167
## Examples
117168
```rescript
118169
let someArray = ["hi", "hello"]
119-
someArray->Array.reverse
170+
someArray->Array.reverseInPlace
120171

121172
Console.log(someArray) // ["hello", "h1"]
122173
```
@@ -141,8 +192,39 @@ Console.log(someArray) // ["hello"]. Notice first item is gone.
141192
*/
142193
@send
143194
external shift: array<'a> => option<'a> = "shift"
195+
196+
/**
197+
`sort(array, comparator)` returns a new, sorted array from `array`, using the provided `comparator` function.
198+
199+
See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN.
200+
201+
## Examples
202+
```rescript
203+
let someArray = [3, 2, 1]
204+
let sortedArray = someArray->Array.sort((a, b) => a > b ? 1 : -1)
205+
206+
Console.log(sortedArray) // [1, 2, 3]
207+
```
208+
*/
144209
let sort: (array<'a>, ('a, 'a) => int) => array<'a>
145-
@send external sortInPlace: (array<'a>, ('a, 'a) => int) => unit = "sort"
210+
211+
/**
212+
`sortInPlace(array, comparator)` sorts the provided `array` using the provided `comparator` function.
213+
214+
Beware this will *mutate* the array.
215+
216+
See [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) on MDN.
217+
218+
## Examples
219+
```rescript
220+
let someArray = [3, 2, 1]
221+
someArray->Array.sortInPlace((a, b) => a > b ? 1 : -1)
222+
223+
Console.log(someArray) // [1, 2, 3]
224+
```
225+
*/
226+
@send
227+
external sortInPlace: (array<'a>, ('a, 'a) => int) => unit = "sort"
146228
@variadic @send
147229
external spliceInPlace: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => unit =
148230
"splice"
@@ -285,9 +367,50 @@ let indexOfOpt: (array<'a>, 'a) => option<int>
285367
@send external lastIndexOf: (array<'a>, 'a) => int = "lastIndexOf"
286368
let lastIndexOfOpt: (array<'a>, 'a) => option<int>
287369
@send external lastIndexOfFrom: (array<'a>, 'a, int) => int = "lastIndexOf"
288-
@send external slice: (array<'a>, ~start: int, ~end: int) => array<'a> = "slice"
289-
@send external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice"
290-
@send external copy: array<'a> => array<'a> = "slice"
370+
371+
/**
372+
`slice(array, start, end)` creates a new array from the provided `array`, with all items from `array` starting from `start`, stopping _before_ `end` (`end` is not included).
373+
374+
See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN.
375+
376+
## Examples
377+
```rescript
378+
let myArray = [1, 2, 3, 4]
379+
380+
Console.log(myArray->Array.slice(~start=1, ~end=3)) // [2, 3]
381+
```
382+
*/
383+
@send
384+
external slice: (array<'a>, ~start: int, ~end: int) => array<'a> = "slice"
385+
386+
/**
387+
`sliceToEnd(array, start)` creates a new array from the provided `array`, with all items from `array` starting from `start`.
388+
389+
See [`Array.slice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) on MDN.
390+
391+
## Examples
392+
```rescript
393+
let myArray = [1, 2, 3, 4]
394+
395+
Console.log(myArray->Array.sliceToEnd(~start=1)) // [2, 3, 4]
396+
```
397+
*/
398+
@send
399+
external sliceToEnd: (array<'a>, ~start: int) => array<'a> = "slice"
400+
/**
401+
`copy(array)` makes a shallow copy of the provided `array`.
402+
403+
## Examples
404+
```rescript
405+
let myArray = [1, 2, 3]
406+
let copyOfMyArray = myArray->Array.copy
407+
408+
Console.log(copyOfMyArray) // [1, 2, 3]
409+
Console.log(myArray === copyOfMyArray) // false
410+
```
411+
*/
412+
@send
413+
external copy: array<'a> => array<'a> = "slice"
291414
@send external toString: array<'a> => string = "toString"
292415
@send external toLocaleString: array<'a> => string = "toLocaleString"
293416
@send external every: (array<'a>, 'a => bool) => bool = "every"
@@ -359,6 +482,20 @@ let reduceRightWithIndex: (array<'a>, 'b, ('b, 'a, int) => 'b) => 'b
359482
external getUnsafe: (array<'a>, int) => 'a = "%array_unsafe_get"
360483
external setUnsafe: (array<'a>, int, 'a) => unit = "%array_unsafe_set"
361484
let findIndexOpt: (array<'a>, 'a => bool) => option<int>
485+
486+
/**
487+
`reverse(array)` creates a new array with all items from `array` in reversed order.
488+
489+
See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN.
490+
491+
## Examples
492+
```rescript
493+
let someArray = ["hi", "hello"]
494+
let reversed = someArray->Array.reverse
495+
496+
Console.log(reversed) // ["hello", "h1"]
497+
```
498+
*/
362499
let reverse: array<'a> => array<'a>
363500
let filterMap: (array<'a>, 'a => option<'b>) => array<'b>
364501

0 commit comments

Comments
 (0)