Skip to content

Commit 64c2668

Browse files
garybgaryb
committed
Separate docs
1 parent 79af9a3 commit 64c2668

File tree

5 files changed

+189
-171
lines changed

5 files changed

+189
-171
lines changed

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![Build Status](https://travis-ci.org/purescript/purescript-arrays.svg?branch=master)](https://travis-ci.org/purescript/purescript-arrays)
44

5-
Optional values.
5+
Instances and utility functions for the `Array` type - JavaScript's native arrays.
66

77
## Installation
88

@@ -12,4 +12,6 @@ bower install purescript-arrays
1212

1313
## Module documentation
1414

15-
[`docs/MODULE.md`](docs/MODULE.md)
15+
- [Data.Array](docs/Data.Array.md)
16+
- [Data.Array.ST](docs/Data.Array.ST.md)
17+
- [Data.Array.Unsafe](docs/Data.Array.Unsafe.md)

‎docs/Data.Array.ST.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Module Documentation
2+
3+
## Module Data.Array.ST
4+
5+
6+
Helper functions for working with mutable arrays using the `ST` effect.
7+
8+
This module can be used when performance is important and mutation is a local effect.
9+
10+
#### `STArray`
11+
12+
``` purescript
13+
data STArray :: * -> * -> *
14+
```
15+
16+
A reference to a mutable array.
17+
18+
The first type parameter represents the memory region which the array belongs to.
19+
The second type parameter defines the type of elements of the mutable array.
20+
21+
The runtime representation of a value of type `STArray h a` is the same as that of `[a]`,
22+
except that mutation is allowed.
23+
24+
#### `Assoc`
25+
26+
``` purescript
27+
type Assoc a = { index :: Int, value :: a }
28+
```
29+
30+
An element and its index
31+
32+
#### `runSTArray`
33+
34+
``` purescript
35+
runSTArray :: forall a r. (forall h. Eff (st :: ST h | r) (STArray h a)) -> Eff r [a]
36+
```
37+
38+
Freeze a mutable array, creating an immutable array. Use this function as you would use
39+
`runST` to freeze a mutable reference.
40+
41+
The rank-2 type prevents the reference from escaping the scope of `runSTArray`.
42+
43+
#### `emptySTArray`
44+
45+
``` purescript
46+
emptySTArray :: forall a h r. Eff (st :: ST h | r) (STArray h a)
47+
```
48+
49+
Create an empty mutable array.
50+
51+
#### `peekSTArray`
52+
53+
``` purescript
54+
peekSTArray :: forall a h r. STArray h a -> Int -> Eff (st :: ST h | r) (Maybe a)
55+
```
56+
57+
Read the value at the specified index in a mutable array.
58+
59+
#### `pokeSTArray`
60+
61+
``` purescript
62+
pokeSTArray :: forall a h r. STArray h a -> Int -> a -> Eff (st :: ST h | r) Boolean
63+
```
64+
65+
Change the value at the specified index in a mutable array.
66+
67+
#### `pushAllSTArray`
68+
69+
``` purescript
70+
pushAllSTArray :: forall a h r. STArray h a -> [a] -> Eff (st :: ST h | r) Int
71+
```
72+
73+
Append the values in an immutable array to the end of a mutable array.
74+
75+
#### `pushSTArray`
76+
77+
``` purescript
78+
pushSTArray :: forall a h r. STArray h a -> a -> Eff (st :: ST h | r) Int
79+
```
80+
81+
Append an element to the end of a mutable array.
82+
83+
#### `spliceSTArray`
84+
85+
``` purescript
86+
spliceSTArray :: forall a h r. STArray h a -> Int -> Int -> [a] -> Eff (st :: ST h | r) [a]
87+
```
88+
89+
Remove and/or insert elements from/into a mutable array at the specified index.
90+
91+
#### `freeze`
92+
93+
``` purescript
94+
freeze :: forall a h r. STArray h a -> Eff (st :: ST h | r) [a]
95+
```
96+
97+
Create an immutable copy of a mutable array.
98+
99+
#### `thaw`
100+
101+
``` purescript
102+
thaw :: forall a h r. [a] -> Eff (st :: ST h | r) (STArray h a)
103+
```
104+
105+
Create a mutable copy of an immutable array.
106+
107+
#### `toAssocArray`
108+
109+
``` purescript
110+
toAssocArray :: forall a h r. STArray h a -> Eff (st :: ST h | r) [Assoc a]
111+
```
112+
113+
Create an immutable copy of a mutable array, where each element
114+
is labelled with its index in the original array.
115+
116+
117+

‎docs/Data.Array.Unsafe.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Module Documentation
2+
3+
## Module Data.Array.Unsafe
4+
5+
6+
Unsafe helper functions for working with immutable arrays.
7+
8+
_Note_: these functions should be used with care, and may result in unspecified
9+
behavior, including runtime exceptions.
10+
11+
#### `head`
12+
13+
``` purescript
14+
head :: forall a. [a] -> a
15+
```
16+
17+
Get the first element of a non-empty array.
18+
19+
Running time: `O(1)`.
20+
21+
#### `tail`
22+
23+
``` purescript
24+
tail :: forall a. [a] -> [a]
25+
```
26+
27+
Get all but the first element of a non-empty array.
28+
29+
Running time: `O(n)`, where `n` is the length of the array.
30+
31+
#### `last`
32+
33+
``` purescript
34+
last :: forall a. [a] -> a
35+
```
36+
37+
Get the last element of a non-empty array.
38+
39+
Running time: `O(1)`.
40+
41+
#### `init`
42+
43+
``` purescript
44+
init :: forall a. [a] -> [a]
45+
```
46+
47+
Get all but the last element of a non-empty array.
48+
49+
Running time: `O(n)`, where `n` is the length of the array.
50+
51+
52+

‎docs/MODULE.md‎ renamed to ‎docs/Data.Array.md‎

Lines changed: 0 additions & 163 deletions
Original file line numberDiff line numberDiff line change
@@ -502,167 +502,4 @@ instance monadPlusArray :: MonadPlus Prim.Array
502502

503503

504504

505-
## Module Data.Array.ST
506-
507-
508-
Helper functions for working with mutable arrays using the `ST` effect.
509-
510-
This module can be used when performance is important and mutation is a local effect.
511-
512-
#### `STArray`
513-
514-
``` purescript
515-
data STArray :: * -> * -> *
516-
```
517-
518-
A reference to a mutable array.
519-
520-
The first type parameter represents the memory region which the array belongs to.
521-
The second type parameter defines the type of elements of the mutable array.
522-
523-
The runtime representation of a value of type `STArray h a` is the same as that of `[a]`,
524-
except that mutation is allowed.
525-
526-
#### `Assoc`
527-
528-
``` purescript
529-
type Assoc a = { index :: Int, value :: a }
530-
```
531-
532-
An element and its index
533-
534-
#### `runSTArray`
535-
536-
``` purescript
537-
runSTArray :: forall a r. (forall h. Eff (st :: ST h | r) (STArray h a)) -> Eff r [a]
538-
```
539-
540-
Freeze a mutable array, creating an immutable array. Use this function as you would use
541-
`runST` to freeze a mutable reference.
542-
543-
The rank-2 type prevents the reference from escaping the scope of `runSTArray`.
544-
545-
#### `emptySTArray`
546-
547-
``` purescript
548-
emptySTArray :: forall a h r. Eff (st :: ST h | r) (STArray h a)
549-
```
550-
551-
Create an empty mutable array.
552-
553-
#### `peekSTArray`
554-
555-
``` purescript
556-
peekSTArray :: forall a h r. STArray h a -> Int -> Eff (st :: ST h | r) (Maybe a)
557-
```
558-
559-
Read the value at the specified index in a mutable array.
560-
561-
#### `pokeSTArray`
562-
563-
``` purescript
564-
pokeSTArray :: forall a h r. STArray h a -> Int -> a -> Eff (st :: ST h | r) Boolean
565-
```
566-
567-
Change the value at the specified index in a mutable array.
568-
569-
#### `pushAllSTArray`
570-
571-
``` purescript
572-
pushAllSTArray :: forall a h r. STArray h a -> [a] -> Eff (st :: ST h | r) Int
573-
```
574-
575-
Append the values in an immutable array to the end of a mutable array.
576-
577-
#### `pushSTArray`
578-
579-
``` purescript
580-
pushSTArray :: forall a h r. STArray h a -> a -> Eff (st :: ST h | r) Int
581-
```
582-
583-
Append an element to the end of a mutable array.
584-
585-
#### `spliceSTArray`
586-
587-
``` purescript
588-
spliceSTArray :: forall a h r. STArray h a -> Int -> Int -> [a] -> Eff (st :: ST h | r) [a]
589-
```
590-
591-
Remove and/or insert elements from/into a mutable array at the specified index.
592-
593-
#### `freeze`
594-
595-
``` purescript
596-
freeze :: forall a h r. STArray h a -> Eff (st :: ST h | r) [a]
597-
```
598-
599-
Create an immutable copy of a mutable array.
600-
601-
#### `thaw`
602-
603-
``` purescript
604-
thaw :: forall a h r. [a] -> Eff (st :: ST h | r) (STArray h a)
605-
```
606-
607-
Create a mutable copy of an immutable array.
608-
609-
#### `toAssocArray`
610-
611-
``` purescript
612-
toAssocArray :: forall a h r. STArray h a -> Eff (st :: ST h | r) [Assoc a]
613-
```
614-
615-
Create an immutable copy of a mutable array, where each element
616-
is labelled with its index in the original array.
617-
618-
619-
## Module Data.Array.Unsafe
620-
621-
622-
Unsafe helper functions for working with immutable arrays.
623-
624-
_Note_: these functions should be used with care, and may result in unspecified
625-
behavior, including runtime exceptions.
626-
627-
#### `head`
628-
629-
``` purescript
630-
head :: forall a. [a] -> a
631-
```
632-
633-
Get the first element of a non-empty array.
634-
635-
Running time: `O(1)`.
636-
637-
#### `tail`
638-
639-
``` purescript
640-
tail :: forall a. [a] -> [a]
641-
```
642-
643-
Get all but the first element of a non-empty array.
644-
645-
Running time: `O(n)`, where `n` is the length of the array.
646-
647-
#### `last`
648-
649-
``` purescript
650-
last :: forall a. [a] -> a
651-
```
652-
653-
Get the last element of a non-empty array.
654-
655-
Running time: `O(1)`.
656-
657-
#### `init`
658-
659-
``` purescript
660-
init :: forall a. [a] -> [a]
661-
```
662-
663-
Get all but the last element of a non-empty array.
664-
665-
Running time: `O(n)`, where `n` is the length of the array.
666-
667-
668505

‎gulpfile.js‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,22 @@ gulp.task("jsvalidate", ["make"], function () {
2424
.pipe(jsvalidate());
2525
});
2626

27-
gulp.task("docs", function () {
28-
return gulp.src("src/**/*.purs")
29-
.pipe(plumber())
30-
.pipe(purescript.pscDocs())
31-
.pipe(gulp.dest("docs/MODULE.md"));
32-
});
27+
var docTasks = [];
28+
29+
var docTask = function(name) {
30+
var taskName = "docs-" + name.toLowerCase();
31+
gulp.task(taskName, function () {
32+
return gulp.src("src/" + name.replace(/\./g, "/") + ".purs")
33+
.pipe(plumber())
34+
.pipe(purescript.pscDocs())
35+
.pipe(gulp.dest("docs/" + name + ".md"));
36+
});
37+
docTasks.push(taskName);
38+
};
39+
40+
["Data.Array", "Data.Array.ST", "Data.Array.Unsafe"].forEach(docTask);
41+
42+
gulp.task("docs", docTasks);
3343

3444
gulp.task("test", function() {
3545
return gulp.src(paths)

0 commit comments

Comments
 (0)