@grain/stdlib 0.6.6 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/LICENSE +1 -1
  3. package/README.md +2 -2
  4. package/array.gr +55 -7
  5. package/array.md +123 -77
  6. package/bigint.md +30 -30
  7. package/buffer.gr +20 -53
  8. package/buffer.md +47 -47
  9. package/bytes.gr +111 -35
  10. package/bytes.md +111 -32
  11. package/char.gr +201 -99
  12. package/char.md +361 -34
  13. package/exception.gr +11 -11
  14. package/exception.md +26 -1
  15. package/float32.gr +327 -3
  16. package/float32.md +606 -19
  17. package/float64.gr +320 -3
  18. package/float64.md +606 -19
  19. package/fs.gr +1082 -0
  20. package/fs.md +630 -0
  21. package/hash.gr +142 -88
  22. package/hash.md +102 -14
  23. package/int16.md +23 -23
  24. package/int32.gr +25 -4
  25. package/int32.md +65 -30
  26. package/int64.gr +26 -1
  27. package/int64.md +65 -30
  28. package/int8.md +23 -23
  29. package/json.gr +366 -51
  30. package/json.md +418 -2
  31. package/list.gr +328 -31
  32. package/list.md +492 -69
  33. package/map.gr +20 -12
  34. package/map.md +44 -38
  35. package/marshal.gr +41 -40
  36. package/marshal.md +2 -2
  37. package/number.gr +159 -30
  38. package/number.md +215 -38
  39. package/option.md +21 -21
  40. package/package.json +5 -3
  41. package/path.gr +48 -0
  42. package/path.md +103 -12
  43. package/pervasives.gr +2 -2
  44. package/pervasives.md +37 -37
  45. package/priorityqueue.gr +7 -7
  46. package/priorityqueue.md +19 -19
  47. package/queue.gr +183 -29
  48. package/queue.md +296 -40
  49. package/random.md +6 -6
  50. package/range.gr +4 -4
  51. package/range.md +6 -6
  52. package/rational.md +16 -16
  53. package/regex.gr +52 -51
  54. package/regex.md +11 -11
  55. package/result.md +16 -16
  56. package/runtime/atof/common.md +39 -39
  57. package/runtime/atof/decimal.gr +6 -6
  58. package/runtime/atof/decimal.md +8 -8
  59. package/runtime/atof/lemire.gr +5 -5
  60. package/runtime/atof/lemire.md +1 -1
  61. package/runtime/atof/parse.gr +16 -16
  62. package/runtime/atof/parse.md +2 -2
  63. package/runtime/atof/slow.md +1 -1
  64. package/runtime/atof/table.md +2 -2
  65. package/runtime/atoi/parse.gr +3 -3
  66. package/runtime/atoi/parse.md +1 -1
  67. package/runtime/bigint.gr +15 -47
  68. package/runtime/bigint.md +54 -60
  69. package/runtime/compare.gr +2 -2
  70. package/runtime/compare.md +1 -1
  71. package/runtime/dataStructures.md +33 -33
  72. package/runtime/debugPrint.gr +4 -1
  73. package/runtime/debugPrint.md +9 -9
  74. package/runtime/equal.gr +99 -77
  75. package/runtime/equal.md +1 -1
  76. package/runtime/exception.gr +62 -82
  77. package/runtime/exception.md +62 -11
  78. package/runtime/gc.gr +39 -45
  79. package/runtime/gc.md +4 -4
  80. package/runtime/malloc.gr +7 -7
  81. package/runtime/malloc.md +4 -4
  82. package/runtime/math/kernel/cos.gr +70 -0
  83. package/runtime/math/kernel/cos.md +14 -0
  84. package/runtime/math/kernel/sin.gr +65 -0
  85. package/runtime/math/kernel/sin.md +14 -0
  86. package/runtime/math/kernel/tan.gr +136 -0
  87. package/runtime/math/kernel/tan.md +14 -0
  88. package/runtime/math/rempio2.gr +244 -0
  89. package/runtime/math/rempio2.md +14 -0
  90. package/runtime/math/trig.gr +130 -0
  91. package/runtime/math/trig.md +28 -0
  92. package/runtime/math/umuldi.gr +26 -0
  93. package/runtime/math/umuldi.md +14 -0
  94. package/runtime/numberUtils.gr +29 -29
  95. package/runtime/numberUtils.md +12 -12
  96. package/runtime/numbers.gr +373 -381
  97. package/runtime/numbers.md +79 -73
  98. package/runtime/string.gr +37 -105
  99. package/runtime/string.md +3 -9
  100. package/runtime/unsafe/constants.md +24 -24
  101. package/runtime/unsafe/conv.md +13 -13
  102. package/runtime/unsafe/memory.gr +24 -20
  103. package/runtime/unsafe/memory.md +27 -7
  104. package/runtime/unsafe/offsets.gr +36 -0
  105. package/runtime/unsafe/offsets.md +88 -0
  106. package/runtime/unsafe/panic.gr +28 -0
  107. package/runtime/unsafe/panic.md +14 -0
  108. package/runtime/unsafe/tags.md +32 -32
  109. package/runtime/unsafe/wasmf32.md +28 -28
  110. package/runtime/unsafe/wasmf64.md +28 -28
  111. package/runtime/unsafe/wasmi32.md +47 -47
  112. package/runtime/unsafe/wasmi64.md +50 -50
  113. package/runtime/utf8.gr +189 -0
  114. package/runtime/utf8.md +117 -0
  115. package/runtime/wasi.gr +4 -2
  116. package/runtime/wasi.md +138 -138
  117. package/set.gr +18 -11
  118. package/set.md +42 -36
  119. package/stack.gr +171 -2
  120. package/stack.md +297 -15
  121. package/string.gr +352 -557
  122. package/string.md +77 -34
  123. package/uint16.md +22 -22
  124. package/uint32.gr +25 -4
  125. package/uint32.md +63 -28
  126. package/uint64.gr +25 -5
  127. package/uint64.md +63 -28
  128. package/uint8.md +22 -22
  129. package/uri.gr +57 -53
  130. package/uri.md +11 -12
  131. package/wasi/file.gr +67 -59
  132. package/wasi/file.md +39 -39
  133. package/wasi/process.md +5 -5
  134. package/wasi/random.md +3 -3
  135. package/wasi/time.md +4 -4
  136. package/runtime/utils/printing.gr +0 -60
  137. package/runtime/utils/printing.md +0 -26
package/list.md CHANGED
@@ -25,6 +25,31 @@ from "list" include List
25
25
 
26
26
  Functions and constants included in the List module.
27
27
 
28
+ ### List.**reverse**
29
+
30
+ <details disabled>
31
+ <summary tabindex="-1">Added in <code>0.1.0</code></summary>
32
+ No other changes yet.
33
+ </details>
34
+
35
+ ```grain
36
+ reverse: (list: List<a>) => List<a>
37
+ ```
38
+
39
+ Creates a new list with all elements in reverse order.
40
+
41
+ Parameters:
42
+
43
+ |param|type|description|
44
+ |-----|----|-----------|
45
+ |`list`|`List<a>`|The list to reverse|
46
+
47
+ Returns:
48
+
49
+ |type|description|
50
+ |----|-----------|
51
+ |`List<a>`|The new list|
52
+
28
53
  ### List.**init**
29
54
 
30
55
  <details disabled>
@@ -33,7 +58,7 @@ No other changes yet.
33
58
  </details>
34
59
 
35
60
  ```grain
36
- init : (length: Number, fn: (Number => a)) => List<a>
61
+ init: (length: Number, fn: (Number => a)) => List<a>
37
62
  ```
38
63
 
39
64
  Creates a new list of the specified length where each element is
@@ -74,7 +99,7 @@ List.init(5, n => n + 3) // [3, 4, 5, 6, 7]
74
99
  </details>
75
100
 
76
101
  ```grain
77
- length : (list: List<a>) => Number
102
+ length: (list: List<a>) => Number
78
103
  ```
79
104
 
80
105
  Computes the length of the input list.
@@ -99,7 +124,7 @@ No other changes yet.
99
124
  </details>
100
125
 
101
126
  ```grain
102
- isEmpty : (list: List<a>) => Bool
127
+ isEmpty: (list: List<a>) => Bool
103
128
  ```
104
129
 
105
130
  Determines if the list contains no elements.
@@ -116,31 +141,6 @@ Returns:
116
141
  |----|-----------|
117
142
  |`Bool`|`true` if the list is empty and `false` otherwise|
118
143
 
119
- ### List.**reverse**
120
-
121
- <details disabled>
122
- <summary tabindex="-1">Added in <code>0.1.0</code></summary>
123
- No other changes yet.
124
- </details>
125
-
126
- ```grain
127
- reverse : (list: List<a>) => List<a>
128
- ```
129
-
130
- Creates a new list with all elements in reverse order.
131
-
132
- Parameters:
133
-
134
- |param|type|description|
135
- |-----|----|-----------|
136
- |`list`|`List<a>`|The list to reverse|
137
-
138
- Returns:
139
-
140
- |type|description|
141
- |----|-----------|
142
- |`List<a>`|The new list|
143
-
144
144
  ### List.**append**
145
145
 
146
146
  <details disabled>
@@ -149,7 +149,7 @@ No other changes yet.
149
149
  </details>
150
150
 
151
151
  ```grain
152
- append : (list1: List<a>, list2: List<a>) => List<a>
152
+ append: (list1: List<a>, list2: List<a>) => List<a>
153
153
  ```
154
154
 
155
155
  Creates a new list with the elements of the first list followed by
@@ -176,7 +176,7 @@ No other changes yet.
176
176
  </details>
177
177
 
178
178
  ```grain
179
- contains : (search: a, list: List<a>) => Bool
179
+ contains: (search: a, list: List<a>) => Bool
180
180
  ```
181
181
 
182
182
  Checks if the value is an element of the input list.
@@ -211,7 +211,7 @@ Returns:
211
211
  </details>
212
212
 
213
213
  ```grain
214
- reduce : (fn: ((a, b) => a), initial: a, list: List<b>) => a
214
+ reduce: (fn: ((a, b) => a), initial: a, list: List<b>) => a
215
215
  ```
216
216
 
217
217
  Combines all elements of a list using a reducer function,
@@ -258,7 +258,7 @@ List.reduce((a, b) => a + b, 0, [1, 2, 3]) // 6
258
258
  </details>
259
259
 
260
260
  ```grain
261
- reduceRight : (fn: ((a, b) => b), initial: b, list: List<a>) => b
261
+ reduceRight: (fn: ((a, b) => b), initial: b, list: List<a>) => b
262
262
  ```
263
263
 
264
264
  Combines all elements of a list using a reducer function,
@@ -297,7 +297,7 @@ No other changes yet.
297
297
  </details>
298
298
 
299
299
  ```grain
300
- map : (fn: (a => b), list: List<a>) => List<b>
300
+ map: (fn: (a => b), list: List<a>) => List<b>
301
301
  ```
302
302
 
303
303
  Produces a new list initialized with the results of a mapper function
@@ -324,7 +324,7 @@ No other changes yet.
324
324
  </details>
325
325
 
326
326
  ```grain
327
- mapi : (fn: ((a, Number) => b), list: List<a>) => List<b>
327
+ mapi: (fn: ((a, Number) => b), list: List<a>) => List<b>
328
328
  ```
329
329
 
330
330
  Produces a new list initialized with the results of a mapper function
@@ -343,6 +343,78 @@ Returns:
343
343
  |----|-----------|
344
344
  |`List<b>`|The new list with mapped values|
345
345
 
346
+ ### List.**filterMap**
347
+
348
+ <details disabled>
349
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
350
+ No other changes yet.
351
+ </details>
352
+
353
+ ```grain
354
+ filterMap: (fn: (a => Option<b>), list: List<a>) => List<b>
355
+ ```
356
+
357
+ Produces a new list initialized with the results of a mapper function
358
+ called on each element of the input list.
359
+ The mapper function can return `None` to exclude the element from the new list.
360
+
361
+ Parameters:
362
+
363
+ |param|type|description|
364
+ |-----|----|-----------|
365
+ |`fn`|`a => Option<b>`|The mapper function to call on each element, where the value returned will be used to initialize the element in the new list|
366
+ |`list`|`List<a>`|The list to iterate|
367
+
368
+ Returns:
369
+
370
+ |type|description|
371
+ |----|-----------|
372
+ |`List<b>`|The new list with filtered mapped values|
373
+
374
+ Examples:
375
+
376
+ ```grain
377
+ List.filterMap(x => if (x % 2 == 0) Some(toString(x)) else None, [1, 2, 3, 4]) == ["2", "4"]
378
+ ```
379
+
380
+ ### List.**filterMapi**
381
+
382
+ <details disabled>
383
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
384
+ No other changes yet.
385
+ </details>
386
+
387
+ ```grain
388
+ filterMapi: (fn: ((a, Number) => Option<b>), list: List<a>) => List<b>
389
+ ```
390
+
391
+ Produces a new list initialized with the results of a mapper function
392
+ called on each element of the input list and its index.
393
+ The mapper function can return `None` to exclude the element from the new list.
394
+
395
+ Parameters:
396
+
397
+ |param|type|description|
398
+ |-----|----|-----------|
399
+ |`fn`|`(a, Number) => Option<b>`|The mapper function to call on each element, where the value returned will be used to initialize the element in the new list|
400
+ |`list`|`List<a>`|The list to iterate|
401
+
402
+ Returns:
403
+
404
+ |type|description|
405
+ |----|-----------|
406
+ |`List<b>`|The new list with filtered mapped values|
407
+
408
+ Examples:
409
+
410
+ ```grain
411
+ List.filterMapi((x, i) => if (x % 2 == 0) Some(toString(x)) else None, [1, 2, 3, 4]) == ["2", "4"]
412
+ ```
413
+
414
+ ```grain
415
+ List.filterMapi((x, i) => if (i == 0) Some(toString(x)) else None, [1, 2, 3, 4]) == ["1"]
416
+ ```
417
+
346
418
  ### List.**flatMap**
347
419
 
348
420
  <details disabled>
@@ -351,7 +423,7 @@ No other changes yet.
351
423
  </details>
352
424
 
353
425
  ```grain
354
- flatMap : (fn: (a => List<b>), list: List<a>) => List<b>
426
+ flatMap: (fn: (a => List<b>), list: List<a>) => List<b>
355
427
  ```
356
428
 
357
429
  Produces a new list by calling a function on each element
@@ -380,7 +452,7 @@ No other changes yet.
380
452
  </details>
381
453
 
382
454
  ```grain
383
- every : (fn: (a => Bool), list: List<a>) => Bool
455
+ every: (fn: (a => Bool), list: List<a>) => Bool
384
456
  ```
385
457
 
386
458
  Checks that the given condition is satisfied for all
@@ -397,7 +469,7 @@ Returns:
397
469
 
398
470
  |type|description|
399
471
  |----|-----------|
400
- |`Bool`|`true` if all elements satify the condition or `false` otherwise|
472
+ |`Bool`|`true` if all elements satisfy the condition or `false` otherwise|
401
473
 
402
474
  ### List.**some**
403
475
 
@@ -407,7 +479,7 @@ No other changes yet.
407
479
  </details>
408
480
 
409
481
  ```grain
410
- some : (fn: (a => Bool), list: List<a>) => Bool
482
+ some: (fn: (a => Bool), list: List<a>) => Bool
411
483
  ```
412
484
 
413
485
  Checks that the given condition is satisfied **at least
@@ -424,7 +496,7 @@ Returns:
424
496
 
425
497
  |type|description|
426
498
  |----|-----------|
427
- |`Bool`|`true` if one or more elements satify the condition or `false` otherwise|
499
+ |`Bool`|`true` if one or more elements satisfy the condition or `false` otherwise|
428
500
 
429
501
  ### List.**forEach**
430
502
 
@@ -434,7 +506,7 @@ No other changes yet.
434
506
  </details>
435
507
 
436
508
  ```grain
437
- forEach : (fn: (a => Void), list: List<a>) => Void
509
+ forEach: (fn: (a => Void), list: List<a>) => Void
438
510
  ```
439
511
 
440
512
  Iterates a list, calling an iterator function on each element.
@@ -454,7 +526,7 @@ No other changes yet.
454
526
  </details>
455
527
 
456
528
  ```grain
457
- forEachi : (fn: ((a, Number) => Void), list: List<a>) => Void
529
+ forEachi: (fn: ((a, Number) => Void), list: List<a>) => Void
458
530
  ```
459
531
 
460
532
  Iterates a list, calling an iterator function on each element.
@@ -475,7 +547,7 @@ No other changes yet.
475
547
  </details>
476
548
 
477
549
  ```grain
478
- filter : (fn: (a => Bool), list: List<a>) => List<a>
550
+ filter: (fn: (a => Bool), list: List<a>) => List<a>
479
551
  ```
480
552
 
481
553
  Produces a new list by calling a function on each element of
@@ -503,7 +575,7 @@ No other changes yet.
503
575
  </details>
504
576
 
505
577
  ```grain
506
- filteri : (fn: ((a, Number) => Bool), list: List<a>) => List<a>
578
+ filteri: (fn: ((a, Number) => Bool), list: List<a>) => List<a>
507
579
  ```
508
580
 
509
581
  Produces a new list by calling a function on each element of
@@ -531,7 +603,7 @@ No other changes yet.
531
603
  </details>
532
604
 
533
605
  ```grain
534
- reject : (fn: (a => Bool), list: List<a>) => List<a>
606
+ reject: (fn: (a => Bool), list: List<a>) => List<a>
535
607
  ```
536
608
 
537
609
  Produces a new list by calling a function on each element of
@@ -568,7 +640,7 @@ Returns:
568
640
  </details>
569
641
 
570
642
  ```grain
571
- head : (list: List<a>) => Option<a>
643
+ head: (list: List<a>) => Option<a>
572
644
  ```
573
645
 
574
646
  Provides `Some(element)` containing the first element, or "head", of
@@ -603,7 +675,7 @@ Returns:
603
675
  </details>
604
676
 
605
677
  ```grain
606
- tail : (list: List<a>) => Option<List<a>>
678
+ tail: (list: List<a>) => Option<List<a>>
607
679
  ```
608
680
 
609
681
  Provides `Some(tail)` containing all list items except the first element, or "tail", of
@@ -637,7 +709,7 @@ Returns:
637
709
  </details>
638
710
 
639
711
  ```grain
640
- nth : (index: Number, list: List<a>) => Option<a>
712
+ nth: (index: Number, list: List<a>) => Option<a>
641
713
  ```
642
714
 
643
715
  Provides `Some(element)` containing the element in the list at the specified index
@@ -664,7 +736,7 @@ No other changes yet.
664
736
  </details>
665
737
 
666
738
  ```grain
667
- flatten : (list: List<List<a>>) => List<a>
739
+ flatten: (list: List<List<a>>) => List<a>
668
740
  ```
669
741
 
670
742
  Flattens nested lists.
@@ -702,7 +774,7 @@ List.flatten([[1, 2], [3, 4]]) // [1, 2, 3, 4]
702
774
  </details>
703
775
 
704
776
  ```grain
705
- insert : (index: Number, value: a, list: List<a>) => List<a>
777
+ insert: (index: Number, value: a, list: List<a>) => List<a>
706
778
  ```
707
779
 
708
780
  Inserts a new value into a list at the specified index.
@@ -743,7 +815,7 @@ Throws:
743
815
  </details>
744
816
 
745
817
  ```grain
746
- count : (fn: (a => Bool), list: List<a>) => Number
818
+ count: (fn: (a => Bool), list: List<a>) => Number
747
819
  ```
748
820
 
749
821
  Counts the number of elements in a list that satisfy the given condition.
@@ -769,7 +841,7 @@ No other changes yet.
769
841
  </details>
770
842
 
771
843
  ```grain
772
- part : (count: Number, list: List<a>) => (List<a>, List<a>)
844
+ part: (count: Number, list: List<a>) => (List<a>, List<a>)
773
845
  ```
774
846
 
775
847
  Split a list into two, with the first list containing the required number of elements.
@@ -809,7 +881,7 @@ Throws:
809
881
  </details>
810
882
 
811
883
  ```grain
812
- rotate : (n: Number, list: List<a>) => List<a>
884
+ rotate: (n: Number, list: List<a>) => List<a>
813
885
  ```
814
886
 
815
887
  Rotates list elements by the specified amount to the left, such that `n`th
@@ -855,7 +927,7 @@ List.rotate(-7, [1, 2, 3, 4, 5]) // [4, 5, 1, 2, 3]
855
927
  </details>
856
928
 
857
929
  ```grain
858
- unique : (list: List<a>) => List<a>
930
+ unique: (list: List<a>) => List<a>
859
931
  ```
860
932
 
861
933
  Produces a new list with any duplicates removed.
@@ -881,7 +953,7 @@ No other changes yet.
881
953
  </details>
882
954
 
883
955
  ```grain
884
- zip : (list1: List<a>, list2: List<b>) => List<(a, b)>
956
+ zip: (list1: List<a>, list2: List<b>) => List<(a, b)>
885
957
  ```
886
958
 
887
959
  Produces a new list filled with tuples of elements from both given lists.
@@ -922,7 +994,7 @@ No other changes yet.
922
994
  </details>
923
995
 
924
996
  ```grain
925
- zipWith : (fn: ((a, b) => c), list1: List<a>, list2: List<b>) => List<c>
997
+ zipWith: (fn: ((a, b) => c), list1: List<a>, list2: List<b>) => List<c>
926
998
  ```
927
999
 
928
1000
  Produces a new list filled with elements defined by applying a function on
@@ -966,7 +1038,7 @@ No other changes yet.
966
1038
  </details>
967
1039
 
968
1040
  ```grain
969
- unzip : (list: List<(a, b)>) => (List<a>, List<b>)
1041
+ unzip: (list: List<(a, b)>) => (List<a>, List<b>)
970
1042
  ```
971
1043
 
972
1044
  Produces two lists by splitting apart a list of tuples.
@@ -991,7 +1063,7 @@ No other changes yet.
991
1063
  </details>
992
1064
 
993
1065
  ```grain
994
- drop : (count: Number, list: List<a>) => List<a>
1066
+ drop: (count: Number, list: List<a>) => List<a>
995
1067
  ```
996
1068
 
997
1069
  Produces a new list with the specified number of elements removed from
@@ -1024,7 +1096,7 @@ No other changes yet.
1024
1096
  </details>
1025
1097
 
1026
1098
  ```grain
1027
- dropWhile : (fn: (a => Bool), list: List<a>) => List<a>
1099
+ dropWhile: (fn: (a => Bool), list: List<a>) => List<a>
1028
1100
  ```
1029
1101
 
1030
1102
  Produces a new list with the elements removed from the beginning
@@ -1052,7 +1124,7 @@ No other changes yet.
1052
1124
  </details>
1053
1125
 
1054
1126
  ```grain
1055
- take : (count: Number, list: List<a>) => List<a>
1127
+ take: (count: Number, list: List<a>) => List<a>
1056
1128
  ```
1057
1129
 
1058
1130
  Produces a new list with–at most—the specified amount elements from
@@ -1085,7 +1157,7 @@ No other changes yet.
1085
1157
  </details>
1086
1158
 
1087
1159
  ```grain
1088
- takeWhile : (fn: (a => Bool), list: List<a>) => List<a>
1160
+ takeWhile: (fn: (a => Bool), list: List<a>) => List<a>
1089
1161
  ```
1090
1162
 
1091
1163
  Produces a new list with elements from the beginning of the input list
@@ -1121,10 +1193,10 @@ Returns:
1121
1193
  </details>
1122
1194
 
1123
1195
  ```grain
1124
- find : (fn: (a => Bool), list: List<a>) => Option<a>
1196
+ find: (fn: (a => Bool), list: List<a>) => Option<a>
1125
1197
  ```
1126
1198
 
1127
- Finds the first element in a list that satifies the given condition.
1199
+ Finds the first element in a list that satisfies the given condition.
1128
1200
 
1129
1201
  Parameters:
1130
1202
 
@@ -1155,10 +1227,10 @@ Returns:
1155
1227
  </details>
1156
1228
 
1157
1229
  ```grain
1158
- findIndex : (fn: (a => Bool), list: List<a>) => Option<Number>
1230
+ findIndex: (fn: (a => Bool), list: List<a>) => Option<Number>
1159
1231
  ```
1160
1232
 
1161
- Finds the first index in a list where the element satifies the given condition.
1233
+ Finds the first index in a list where the element satisfies the given condition.
1162
1234
 
1163
1235
  Parameters:
1164
1236
 
@@ -1173,6 +1245,41 @@ Returns:
1173
1245
  |----|-----------|
1174
1246
  |`Option<Number>`|`Some(index)` containing the index of the first element found or `None` otherwise|
1175
1247
 
1248
+ ### List.**findMap**
1249
+
1250
+ <details disabled>
1251
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1252
+ No other changes yet.
1253
+ </details>
1254
+
1255
+ ```grain
1256
+ findMap: (fn: (a => Option<b>), list: List<a>) => Option<b>
1257
+ ```
1258
+
1259
+ Finds the first element in a list that satisfies the given condition and
1260
+ returns the result of applying a mapper function to it.
1261
+
1262
+ Parameters:
1263
+
1264
+ |param|type|description|
1265
+ |-----|----|-----------|
1266
+ |`fn`|`a => Option<b>`|The function to call on each element, where the returned value indicates if the element satisfies the condition|
1267
+ |`list`|`List<a>`|The list to search|
1268
+
1269
+ Returns:
1270
+
1271
+ |type|description|
1272
+ |----|-----------|
1273
+ |`Option<b>`|`Some(mapped)` containing the first value found with the given mapping or `None` otherwise|
1274
+
1275
+ Examples:
1276
+
1277
+ ```grain
1278
+ let jsonObject = [(1, 'a'), (2, 'b'), (1, 'c')]
1279
+ let getItem = (key, obj) => List.findMap(((k, v)) => if (k == key) Some(v) else None, obj)
1280
+ assert getItem(1, jsonObject) == Some('a')
1281
+ ```
1282
+
1176
1283
  ### List.**product**
1177
1284
 
1178
1285
  <details disabled>
@@ -1181,7 +1288,7 @@ No other changes yet.
1181
1288
  </details>
1182
1289
 
1183
1290
  ```grain
1184
- product : (list1: List<a>, list2: List<b>) => List<(a, b)>
1291
+ product: (list1: List<a>, list2: List<b>) => List<(a, b)>
1185
1292
  ```
1186
1293
 
1187
1294
  Combines two lists into a Cartesian product of tuples containing
@@ -1208,7 +1315,7 @@ No other changes yet.
1208
1315
  </details>
1209
1316
 
1210
1317
  ```grain
1211
- sub : (start: Number, length: Number, list: List<a>) => List<a>
1318
+ sub: (start: Number, length: Number, list: List<a>) => List<a>
1212
1319
  ```
1213
1320
 
1214
1321
  Provides the subset of a list given zero-based start index and amount of elements
@@ -1243,7 +1350,7 @@ No other changes yet.
1243
1350
  </details>
1244
1351
 
1245
1352
  ```grain
1246
- join : (separator: String, list: List<String>) => String
1353
+ join: (separator: String, list: List<String>) => String
1247
1354
  ```
1248
1355
 
1249
1356
  Combine the given list of strings into one string with the specified
@@ -1270,7 +1377,7 @@ No other changes yet.
1270
1377
  </details>
1271
1378
 
1272
1379
  ```grain
1273
- revAppend : (list1: List<a>, list2: List<a>) => List<a>
1380
+ revAppend: (list1: List<a>, list2: List<a>) => List<a>
1274
1381
  ```
1275
1382
 
1276
1383
  Reverses the first list and appends the second list to the end.
@@ -1303,7 +1410,7 @@ Returns:
1303
1410
  </details>
1304
1411
 
1305
1412
  ```grain
1306
- sort : (?compare: ((num1: a, num2: a) => Number), list: List<a>) => List<a>
1413
+ sort: (?compare: ((num1: a, num2: a) => Number), list: List<a>) => List<a>
1307
1414
  ```
1308
1415
 
1309
1416
  Sorts the given list based on a given comparator function. The resulting list is sorted in increasing order.
@@ -1323,3 +1430,319 @@ Returns:
1323
1430
  |----|-----------|
1324
1431
  |`List<a>`|The sorted list|
1325
1432
 
1433
+ ## List.Associative
1434
+
1435
+ Utilities for working with lists of key-key value pairs.
1436
+
1437
+ <details disabled>
1438
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1439
+ No other changes yet.
1440
+ </details>
1441
+
1442
+ ```grain
1443
+ let data = [
1444
+ ("name", "Alice"),
1445
+ ("age", "30"),
1446
+ ]
1447
+ assert List.Associative.get("name", data) == Some("Alice")
1448
+ ```
1449
+
1450
+ ### Values
1451
+
1452
+ Functions and constants included in the List.Associative module.
1453
+
1454
+ #### List.Associative.**has**
1455
+
1456
+ <details disabled>
1457
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1458
+ No other changes yet.
1459
+ </details>
1460
+
1461
+ ```grain
1462
+ has: (key: a, list: List<(a, b)>) => Bool
1463
+ ```
1464
+
1465
+ Checks if the given key is present in the list of key-value pairs.
1466
+
1467
+ Parameters:
1468
+
1469
+ |param|type|description|
1470
+ |-----|----|-----------|
1471
+ |`key`|`a`|The key to search for|
1472
+ |`list`|`List<(a, b)>`|The list of key-value pairs|
1473
+
1474
+ Returns:
1475
+
1476
+ |type|description|
1477
+ |----|-----------|
1478
+ |`Bool`|`true` if the key is found or `false` otherwise|
1479
+
1480
+ Examples:
1481
+
1482
+ ```grain
1483
+ let data = [
1484
+ ("name", "Alice"),
1485
+ ("age", "30"),
1486
+ ]
1487
+ assert List.Associative.has("name", data) == true
1488
+ ```
1489
+
1490
+ ```grain
1491
+ List.Associative.has("age", []) == false
1492
+ ```
1493
+
1494
+ #### List.Associative.**get**
1495
+
1496
+ <details disabled>
1497
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1498
+ No other changes yet.
1499
+ </details>
1500
+
1501
+ ```grain
1502
+ get: (key: a, list: List<(a, b)>) => Option<b>
1503
+ ```
1504
+
1505
+ Retrieves the first value in the list of key-value pairs that matches the given key.
1506
+
1507
+ Parameters:
1508
+
1509
+ |param|type|description|
1510
+ |-----|----|-----------|
1511
+ |`key`|`a`|The key to search for|
1512
+ |`list`|`List<(a, b)>`|The list of key-value pairs|
1513
+
1514
+ Returns:
1515
+
1516
+ |type|description|
1517
+ |----|-----------|
1518
+ |`Option<b>`|`Some(value)` if the key is found or `None` otherwise|
1519
+
1520
+ Examples:
1521
+
1522
+ ```grain
1523
+ let data = [
1524
+ ("name", "Alice"),
1525
+ ("name", "Bob"),
1526
+ ("age", "30"),
1527
+ ]
1528
+ assert List.Associative.get("name", data) == Some("Alice")
1529
+ ```
1530
+
1531
+ ```grain
1532
+ List.Associative.get("age", []) == None
1533
+ ```
1534
+
1535
+ #### List.Associative.**getAll**
1536
+
1537
+ <details disabled>
1538
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1539
+ No other changes yet.
1540
+ </details>
1541
+
1542
+ ```grain
1543
+ getAll: (key: a, list: List<(a, b)>) => List<b>
1544
+ ```
1545
+
1546
+ Retrieves all values in the list of key-value pairs that match the given key.
1547
+
1548
+ Parameters:
1549
+
1550
+ |param|type|description|
1551
+ |-----|----|-----------|
1552
+ |`key`|`a`|The key to search for|
1553
+ |`list`|`List<(a, b)>`|The list of key-value pairs|
1554
+
1555
+ Returns:
1556
+
1557
+ |type|description|
1558
+ |----|-----------|
1559
+ |`List<b>`|An array of values matching the given key|
1560
+
1561
+ Examples:
1562
+
1563
+ ```grain
1564
+ let data = [
1565
+ ("name", "Alice"),
1566
+ ("name", "Bob"),
1567
+ ("age", "30"),
1568
+ ]
1569
+ assert List.Associative.getAll("name", data) == [
1570
+ "Alice",
1571
+ "Bob"
1572
+ ]
1573
+ ```
1574
+
1575
+ ```grain
1576
+ List.Associative.getAll("age", []) == []
1577
+ ```
1578
+
1579
+ #### List.Associative.**set**
1580
+
1581
+ <details disabled>
1582
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1583
+ No other changes yet.
1584
+ </details>
1585
+
1586
+ ```grain
1587
+ set: (key: a, value: b, list: List<(a, b)>) => List<(a, b)>
1588
+ ```
1589
+
1590
+ Creates a new list with the first value in the list of key-value pairs that matches the key replaced.
1591
+ If the key is not found the item is appended to the list.
1592
+
1593
+ Parameters:
1594
+
1595
+ |param|type|description|
1596
+ |-----|----|-----------|
1597
+ |`key`|`a`|The key to replace|
1598
+ |`value`|`b`|The new value to set|
1599
+ |`list`|`List<(a, b)>`|The list of key-value pairs|
1600
+
1601
+ Returns:
1602
+
1603
+ |type|description|
1604
+ |----|-----------|
1605
+ |`List<(a, b)>`|A new list with the key-value pair replaced|
1606
+
1607
+ Examples:
1608
+
1609
+ ```grain
1610
+ let data = [
1611
+ ("name", "Alice"),
1612
+ ("name", "Bob"),
1613
+ ("age", "30"),
1614
+ ]
1615
+ assert List.Associative.set("name", "Charlie", data) == [("name", "Charlie"), ("name", "Bob"), ("age", "30")]
1616
+ ```
1617
+
1618
+ ```grain
1619
+ List.Associative.set("age", "30", [("name", "Alice")]) == [("name", "Alice"), ("age", "30")]
1620
+ ```
1621
+
1622
+ #### List.Associative.**setAll**
1623
+
1624
+ <details disabled>
1625
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1626
+ No other changes yet.
1627
+ </details>
1628
+
1629
+ ```grain
1630
+ setAll: (key: a, value: b, list: List<(a, b)>) => List<(a, b)>
1631
+ ```
1632
+
1633
+ Creates a new list with all values in the list of key-value pairs that match the key replaced.
1634
+ If the key is not found the item is appended to the list.
1635
+
1636
+ Parameters:
1637
+
1638
+ |param|type|description|
1639
+ |-----|----|-----------|
1640
+ |`key`|`a`|The key to replace|
1641
+ |`value`|`b`|The new value to set|
1642
+ |`list`|`List<(a, b)>`|The list of key-value pairs|
1643
+
1644
+ Returns:
1645
+
1646
+ |type|description|
1647
+ |----|-----------|
1648
+ |`List<(a, b)>`|A new list with the key-value pairs replaced|
1649
+
1650
+ Examples:
1651
+
1652
+ ```grain
1653
+ let data = [
1654
+ ("name", "Alice"),
1655
+ ("name", "Bob"),
1656
+ ("age", "30"),
1657
+ ]
1658
+ assert List.Associative.setAll("name", "Charlie", data) == [("name", "Charlie"), ("name", "Charlie"), ("age", "30")]
1659
+ ```
1660
+
1661
+ ```grain
1662
+ List.Associative.setAll("age", "30", [("name", "Alice")]) == [("name", "Alice"), ("age", "30")]
1663
+ ```
1664
+
1665
+ #### List.Associative.**remove**
1666
+
1667
+ <details disabled>
1668
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1669
+ No other changes yet.
1670
+ </details>
1671
+
1672
+ ```grain
1673
+ remove: (key: a, list: List<(a, b)>) => List<(a, b)>
1674
+ ```
1675
+
1676
+ Creates a new list with the first value in the list of key-value pairs that matches the key removed.
1677
+ If the key is not found, the list is returned unchanged.
1678
+
1679
+ Parameters:
1680
+
1681
+ |param|type|description|
1682
+ |-----|----|-----------|
1683
+ |`key`|`a`|The key to remove|
1684
+ |`list`|`List<(a, b)>`|The list of key-value pairs|
1685
+
1686
+ Returns:
1687
+
1688
+ |type|description|
1689
+ |----|-----------|
1690
+ |`List<(a, b)>`|The new list with the key-value pair removed|
1691
+
1692
+ Examples:
1693
+
1694
+ ```grain
1695
+ let data = [
1696
+ ("name", "Alice"),
1697
+ ("name", "Bob"),
1698
+ ("age", "30"),
1699
+ ]
1700
+ assert List.Associative.remove("name", data) == [("name", "Bob"), ("age", "30")]
1701
+ ```
1702
+
1703
+ ```grain
1704
+ List.Associative.remove("age", [("name", "Alice")]) == []
1705
+ ```
1706
+
1707
+ #### List.Associative.**removeAll**
1708
+
1709
+ <details disabled>
1710
+ <summary tabindex="-1">Added in <code>0.7.0</code></summary>
1711
+ No other changes yet.
1712
+ </details>
1713
+
1714
+ ```grain
1715
+ removeAll: (key: a, list: List<(a, b)>) => List<(a, b)>
1716
+ ```
1717
+
1718
+ Creates a new list with all values in the list of key-value pairs matching the key removed.
1719
+ If the key is not found, the list is returned unchanged.
1720
+
1721
+ Parameters:
1722
+
1723
+ |param|type|description|
1724
+ |-----|----|-----------|
1725
+ |`key`|`a`|The key to remove|
1726
+ |`list`|`List<(a, b)>`|The list of key-value pairs|
1727
+
1728
+ Returns:
1729
+
1730
+ |type|description|
1731
+ |----|-----------|
1732
+ |`List<(a, b)>`|The new list with the key-value pairs removed|
1733
+
1734
+ Examples:
1735
+
1736
+ ```grain
1737
+ let data = [
1738
+ ("name", "Alice"),
1739
+ ("name", "Bob"),
1740
+ ("age", "30"),
1741
+ ]
1742
+ assert List.Associative.removeAll("name", data) == [("age", "30")]
1743
+ ```
1744
+
1745
+ ```grain
1746
+ List.Associative.removeAll("age", [("name", "Alice")]) == [("name", "Alice")]
1747
+ ```
1748
+