7d49442 · rowtype-yoga/purescript-native

git.iko.soy/rowtype-yoga/purescript-native

on golang help sign in

Merge pull request #933 from purescript/eff-docs

7d49442Phil Freeman12 years ago

prelude/README.md+96−13

compare with golang

unifiedsplit

@@ -252,7 +252,7 @@ types use the type constructor `f` to represent some computational context.

252(<#>) :: forall f a b. (Functor f) => f a -> (a -> b) -> f b

253```

254

255−`(<#>)` is `(<$>)` with its arguments flipped. For example:

255+`(<#>)` is `(<$>)` with its arguments reversed. For example:

256

257```purescript

258[1, 2, 3] <#> \n -> n * n

@@ -878,6 +878,14 @@ instance semigroupArr :: (Semigroup s') => Semigroup (s -> s')

878on :: forall a b c. (b -> b -> c) -> (a -> b) -> a -> a -> c

879```

880

881+The `on` function is used to change the domain of a binary operator.

882+

883+For example, we can create a function which compares two records based on the values of their `x` properties:

884+

885+```purescript

886+compareX :: forall r. { x :: Number | r } -> { x :: Number | r } -> Ordering

887+compareX = compare `on` _.x

888+```

881

889

882#### `Fn0`

890#### `Fn0`

883

891

@@ -885,6 +893,7 @@ on :: forall a b c. (b -> b -> c) -> (a -> b) -> a -> a -> c

885data Fn0 :: * -> *

893data Fn0 :: * -> *

886```

894```

887

895

896+A function of zero arguments

888

897

889#### `Fn1`

898#### `Fn1`

890

899

@@ -892,6 +901,7 @@ data Fn0 :: * -> *

892data Fn1 :: * -> * -> *

901data Fn1 :: * -> * -> *

893```

902```

894

903

904+A function of one argument

895

905

896#### `Fn2`

906#### `Fn2`

897

907

@@ -899,6 +909,7 @@ data Fn1 :: * -> * -> *

899data Fn2 :: * -> * -> * -> *

909data Fn2 :: * -> * -> * -> *

900```

910```

901

911

912+A function of two arguments

902

913

903#### `Fn3`

914#### `Fn3`

904

915

@@ -906,6 +917,7 @@ data Fn2 :: * -> * -> * -> *

906data Fn3 :: * -> * -> * -> * -> *

917data Fn3 :: * -> * -> * -> * -> *

907```

918```

908

919

920+A function of three arguments

909

921

910#### `Fn4`

922#### `Fn4`

911

923

@@ -913,6 +925,7 @@ data Fn3 :: * -> * -> * -> * -> *

913data Fn4 :: * -> * -> * -> * -> * -> *

925data Fn4 :: * -> * -> * -> * -> * -> *

914```

926```

915

927

928+A function of four arguments

916

929

917#### `Fn5`

930#### `Fn5`

918

931

@@ -920,6 +933,7 @@ data Fn4 :: * -> * -> * -> * -> * -> *

920data Fn5 :: * -> * -> * -> * -> * -> * -> *

933data Fn5 :: * -> * -> * -> * -> * -> * -> *

921```

934```

922

935

936+A function of five arguments

923

937

924#### `Fn6`

938#### `Fn6`

925

939

@@ -927,6 +941,7 @@ data Fn5 :: * -> * -> * -> * -> * -> * -> *

927data Fn6 :: * -> * -> * -> * -> * -> * -> * -> *

941data Fn6 :: * -> * -> * -> * -> * -> * -> * -> *

928```

942```

929

943

944+A function of six arguments

930

945

931#### `Fn7`

946#### `Fn7`

932

947

@@ -934,6 +949,7 @@ data Fn6 :: * -> * -> * -> * -> * -> * -> * -> *

934data Fn7 :: * -> * -> * -> * -> * -> * -> * -> * -> *

949data Fn7 :: * -> * -> * -> * -> * -> * -> * -> * -> *

935```

950```

936

951

952+A function of seven arguments

937

953

938#### `Fn8`

954#### `Fn8`

939

955

@@ -941,6 +957,7 @@ data Fn7 :: * -> * -> * -> * -> * -> * -> * -> * -> *

941data Fn8 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> *

957data Fn8 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> *

942```

958```

943

959

960+A function of eight arguments

944

961

945#### `Fn9`

962#### `Fn9`

946

963

@@ -948,6 +965,7 @@ data Fn8 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> *

948data Fn9 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

965data Fn9 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

949```

966```

950

967

968+A function of nine arguments

951

969

952#### `Fn10`

970#### `Fn10`

953

971

@@ -955,6 +973,7 @@ data Fn9 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

955data Fn10 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

973data Fn10 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

956```

974```

957

975

976+A function of ten arguments

958

977

959#### `mkFn0`

978#### `mkFn0`

960

979

@@ -962,6 +981,7 @@ data Fn10 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

962mkFn0 :: forall a. (Unit -> a) -> Fn0 a

981mkFn0 :: forall a. (Unit -> a) -> Fn0 a

963```

982```

964

983

984+Create a function of no arguments

965

985

966#### `mkFn1`

986#### `mkFn1`

967

987

@@ -969,6 +989,7 @@ mkFn0 :: forall a. (Unit -> a) -> Fn0 a

969mkFn1 :: forall a b. (a -> b) -> Fn1 a b

989mkFn1 :: forall a b. (a -> b) -> Fn1 a b

970```

990```

971

991

992+Create a function of one argument

972

993

973#### `mkFn2`

994#### `mkFn2`

974

995

@@ -976,6 +997,7 @@ mkFn1 :: forall a b. (a -> b) -> Fn1 a b

976mkFn2 :: forall a b c. (a -> b -> c) -> Fn2 a b c

997mkFn2 :: forall a b c. (a -> b -> c) -> Fn2 a b c

977```

998```

978

999

1000+Create a function of two arguments from a curried function

979

1001

980#### `mkFn3`

1002#### `mkFn3`

981

1003

@@ -983,6 +1005,7 @@ mkFn2 :: forall a b c. (a -> b -> c) -> Fn2 a b c

983mkFn3 :: forall a b c d. (a -> b -> c -> d) -> Fn3 a b c d

1005mkFn3 :: forall a b c d. (a -> b -> c -> d) -> Fn3 a b c d

984```

1006```

985

1007

1008+Create a function of three arguments from a curried function

986

1009

987#### `mkFn4`

1010#### `mkFn4`

988

1011

@@ -990,6 +1013,7 @@ mkFn3 :: forall a b c d. (a -> b -> c -> d) -> Fn3 a b c d

990mkFn4 :: forall a b c d e. (a -> b -> c -> d -> e) -> Fn4 a b c d e

1013mkFn4 :: forall a b c d e. (a -> b -> c -> d -> e) -> Fn4 a b c d e

991```

1014```

992

1015

1016+Create a function of four arguments from a curried function

993

1017

994#### `mkFn5`

1018#### `mkFn5`

995

1019

@@ -997,6 +1021,7 @@ mkFn4 :: forall a b c d e. (a -> b -> c -> d -> e) -> Fn4 a b c d e

997mkFn5 :: forall a b c d e f. (a -> b -> c -> d -> e -> f) -> Fn5 a b c d e f

1021mkFn5 :: forall a b c d e f. (a -> b -> c -> d -> e -> f) -> Fn5 a b c d e f

998```

1022```

999

1023

1024+Create a function of five arguments from a curried function

1000

1025

1001#### `mkFn6`

1026#### `mkFn6`

1002

1027

@@ -1004,6 +1029,7 @@ mkFn5 :: forall a b c d e f. (a -> b -> c -> d -> e -> f) -> Fn5 a b c d e f

1004mkFn6 :: forall a b c d e f g. (a -> b -> c -> d -> e -> f -> g) -> Fn6 a b c d e f g

1029mkFn6 :: forall a b c d e f g. (a -> b -> c -> d -> e -> f -> g) -> Fn6 a b c d e f g

1005```

1030```

1006

1031

1032+Create a function of six arguments from a curried function

1007

1033

1008#### `mkFn7`

1034#### `mkFn7`

1009

1035

@@ -1011,6 +1037,7 @@ mkFn6 :: forall a b c d e f g. (a -> b -> c -> d -> e -> f -> g) -> Fn6 a b c d

1011mkFn7 :: forall a b c d e f g h. (a -> b -> c -> d -> e -> f -> g -> h) -> Fn7 a b c d e f g h

1037mkFn7 :: forall a b c d e f g h. (a -> b -> c -> d -> e -> f -> g -> h) -> Fn7 a b c d e f g h

1012```

1038```

1013

1039

1040+Create a function of seven arguments from a curried function

1014

1041

1015#### `mkFn8`

1042#### `mkFn8`

1016

1043

@@ -1018,6 +1045,7 @@ mkFn7 :: forall a b c d e f g h. (a -> b -> c -> d -> e -> f -> g -> h) -> Fn7 a

1018mkFn8 :: forall a b c d e f g h i. (a -> b -> c -> d -> e -> f -> g -> h -> i) -> Fn8 a b c d e f g h i

1045mkFn8 :: forall a b c d e f g h i. (a -> b -> c -> d -> e -> f -> g -> h -> i) -> Fn8 a b c d e f g h i

1019```

1046```

1020

1047

1048+Create a function of eight arguments from a curried function

1021

1049

1022#### `mkFn9`

1050#### `mkFn9`

1023

1051

@@ -1025,6 +1053,7 @@ mkFn8 :: forall a b c d e f g h i. (a -> b -> c -> d -> e -> f -> g -> h -> i) -

1025mkFn9 :: forall a b c d e f g h i j. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j) -> Fn9 a b c d e f g h i j

1053mkFn9 :: forall a b c d e f g h i j. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j) -> Fn9 a b c d e f g h i j

1026```

1054```

1027

1055

1056+Create a function of nine arguments from a curried function

1028

1057

1029#### `mkFn10`

1058#### `mkFn10`

1030

1059

@@ -1032,6 +1061,7 @@ mkFn9 :: forall a b c d e f g h i j. (a -> b -> c -> d -> e -> f -> g -> h -> i

1032mkFn10 :: forall a b c d e f g h i j k. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k) -> Fn10 a b c d e f g h i j k

1061mkFn10 :: forall a b c d e f g h i j k. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k) -> Fn10 a b c d e f g h i j k

1033```

1062```

1034

1063

1064+Create a function of ten arguments from a curried function

1035

1065

1036#### `runFn0`

1066#### `runFn0`

1037

1067

@@ -1039,6 +1069,7 @@ mkFn10 :: forall a b c d e f g h i j k. (a -> b -> c -> d -> e -> f -> g -> h ->

1039runFn0 :: forall a. Fn0 a -> a

1069runFn0 :: forall a. Fn0 a -> a

1040```

1070```

1041

1071

1072+Apply a function of no arguments

1042

1073

1043#### `runFn1`

1074#### `runFn1`

1044

1075

@@ -1046,6 +1077,7 @@ runFn0 :: forall a. Fn0 a -> a

1046runFn1 :: forall a b. Fn1 a b -> a -> b

1077runFn1 :: forall a b. Fn1 a b -> a -> b

1047```

1078```

1048

1079

1080+Apply a function of one argument

1049

1081

1050#### `runFn2`

1082#### `runFn2`

1051

1083

@@ -1053,6 +1085,7 @@ runFn1 :: forall a b. Fn1 a b -> a -> b

1053runFn2 :: forall a b c. Fn2 a b c -> a -> b -> c

1085runFn2 :: forall a b c. Fn2 a b c -> a -> b -> c

1054```

1086```

1055

1087

1088+Apply a function of two arguments

1056

1089

1057#### `runFn3`

1090#### `runFn3`

1058

1091

@@ -1060,6 +1093,7 @@ runFn2 :: forall a b c. Fn2 a b c -> a -> b -> c

1060runFn3 :: forall a b c d. Fn3 a b c d -> a -> b -> c -> d

1093runFn3 :: forall a b c d. Fn3 a b c d -> a -> b -> c -> d

1061```

1094```

1062

1095

1096+Apply a function of three arguments

1063

1097

1064#### `runFn4`

1098#### `runFn4`

1065

1099

@@ -1067,6 +1101,7 @@ runFn3 :: forall a b c d. Fn3 a b c d -> a -> b -> c -> d

1067runFn4 :: forall a b c d e. Fn4 a b c d e -> a -> b -> c -> d -> e

1101runFn4 :: forall a b c d e. Fn4 a b c d e -> a -> b -> c -> d -> e

1068```

1102```

1069

1103

1104+Apply a function of four arguments

1070

1105

1071#### `runFn5`

1106#### `runFn5`

1072

1107

@@ -1074,6 +1109,7 @@ runFn4 :: forall a b c d e. Fn4 a b c d e -> a -> b -> c -> d -> e

1074runFn5 :: forall a b c d e f. Fn5 a b c d e f -> a -> b -> c -> d -> e -> f

1109runFn5 :: forall a b c d e f. Fn5 a b c d e f -> a -> b -> c -> d -> e -> f

1075```

1110```

1076

1111

1112+Apply a function of five arguments

1077

1113

1078#### `runFn6`

1114#### `runFn6`

1079

1115

@@ -1081,6 +1117,7 @@ runFn5 :: forall a b c d e f. Fn5 a b c d e f -> a -> b -> c -> d -> e -> f

1081runFn6 :: forall a b c d e f g. Fn6 a b c d e f g -> a -> b -> c -> d -> e -> f -> g

1117runFn6 :: forall a b c d e f g. Fn6 a b c d e f g -> a -> b -> c -> d -> e -> f -> g

1082```

1118```

1083

1119

1120+Apply a function of six arguments

1084

1121

1085#### `runFn7`

1122#### `runFn7`

1086

1123

@@ -1088,6 +1125,7 @@ runFn6 :: forall a b c d e f g. Fn6 a b c d e f g -> a -> b -> c -> d -> e -> f

1088runFn7 :: forall a b c d e f g h. Fn7 a b c d e f g h -> a -> b -> c -> d -> e -> f -> g -> h

1125runFn7 :: forall a b c d e f g h. Fn7 a b c d e f g h -> a -> b -> c -> d -> e -> f -> g -> h

1089```

1126```

1090

1127

1128+Apply a function of seven arguments

1091

1129

1092#### `runFn8`

1130#### `runFn8`

1093

1131

@@ -1095,6 +1133,7 @@ runFn7 :: forall a b c d e f g h. Fn7 a b c d e f g h -> a -> b -> c -> d -> e -

1095runFn8 :: forall a b c d e f g h i. Fn8 a b c d e f g h i -> a -> b -> c -> d -> e -> f -> g -> h -> i

1133runFn8 :: forall a b c d e f g h i. Fn8 a b c d e f g h i -> a -> b -> c -> d -> e -> f -> g -> h -> i

1096```

1134```

1097

1135

1136+Apply a function of eight arguments

1098

1137

1099#### `runFn9`

1138#### `runFn9`

1100

1139

@@ -1102,6 +1141,7 @@ runFn8 :: forall a b c d e f g h i. Fn8 a b c d e f g h i -> a -> b -> c -> d ->

1102runFn9 :: forall a b c d e f g h i j. Fn9 a b c d e f g h i j -> a -> b -> c -> d -> e -> f -> g -> h -> i -> j

1141runFn9 :: forall a b c d e f g h i j. Fn9 a b c d e f g h i j -> a -> b -> c -> d -> e -> f -> g -> h -> i -> j

1103```

1142```

1104

1143

1144+Apply a function of nine arguments

1105

1145

1106#### `runFn10`

1146#### `runFn10`

1107

1147

@@ -1109,6 +1149,7 @@ runFn9 :: forall a b c d e f g h i j. Fn9 a b c d e f g h i j -> a -> b -> c ->

1109runFn10 :: forall a b c d e f g h i j k. Fn10 a b c d e f g h i j k -> a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k

1149runFn10 :: forall a b c d e f g h i j k. Fn10 a b c d e f g h i j k -> a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k

1110```

1150```

1111

1151

1152+Apply a function of ten arguments

1112

1153

1113

1154

1114## Module Prelude.Unsafe

1155## Module Prelude.Unsafe

@@ -1119,6 +1160,9 @@ runFn10 :: forall a b c d e f g h i j k. Fn10 a b c d e f g h i j k -> a -> b ->

1119unsafeIndex :: forall a. [a] -> Number -> a

1160unsafeIndex :: forall a. [a] -> Number -> a

1120```

1161```

1121

1162

1163+Find the element of an array at the specified index.

1164+

1165+Note: this function can cause unpredictable failure at runtime if the index is out-of-bounds.

1122

1166

1123

1167

1124## Module Control.Monad.Eff

1168## Module Control.Monad.Eff

@@ -1129,20 +1173,11 @@ unsafeIndex :: forall a. [a] -> Number -> a

1129data Eff :: # ! -> * -> *

1173data Eff :: # ! -> * -> *

1130```

1174```

1131

1175

1176+The `Eff` type constructor is used to represent _native_ effects.

1132

1177

1133−#### `returnE`

1178+See [Handling Native Effects with the Eff Monad](https://github.com/purescript/purescript/wiki/Handling-Native-Effects-with-the-Eff-Monad) for more details.

1134−

1135−``` purescript

1136−returnE :: forall e a. a -> Eff e a

1137−```

1138−

1139−

1140−#### `bindE`

1141−

1142−``` purescript

1143−bindE :: forall e a b. Eff e a -> (a -> Eff e b) -> Eff e b

1144−```

1145

1179

1180+The first type parameter is a row of effects which represents the contexts in which a computation can be run, and the second type parameter is the return type.

1146

1181

1147#### `Pure`

1182#### `Pure`

1148

1183

@@ -1150,6 +1185,9 @@ bindE :: forall e a b. Eff e a -> (a -> Eff e b) -> Eff e b

1150type Pure a = forall e. Eff e a

1185type Pure a = forall e. Eff e a

1151```

1186```

1152

1187

1188+The `Pure` type synonym represents _pure_ computations, i.e. ones in which all effects have been handled.

1189+

1190+The `runPure` function can be used to run pure computations and obtain their result.

1153

1191

1154#### `runPure`

1192#### `runPure`

1155

1193

@@ -1157,6 +1195,10 @@ type Pure a = forall e. Eff e a

1157runPure :: forall a. Pure a -> a

1195runPure :: forall a. Pure a -> a

1158```

1196```

1159

1197

1198+Run a pure computation and return its result.

1199+

1200+Note: since this function has a rank-2 type, it may cause problems to apply this function using the `$` operator. The recommended approach

1201+is to use parentheses instead.

1160

1202

1161#### `functorEff`

1203#### `functorEff`

1162

1204

@@ -1199,6 +1241,10 @@ instance monadEff :: Monad (Eff e)

1199untilE :: forall e. Eff e Boolean -> Eff e Unit

1241untilE :: forall e. Eff e Boolean -> Eff e Unit

1200```

1242```

1201

1243

1244+Loop until a condition becomes `true`.

1245+

1246+`untilE b` is an effectful computation which repeatedly runs the effectful computation `b`,

1247+until its return value is `true`.

1202

1248

1203#### `whileE`

1249#### `whileE`

1204

1250

@@ -1206,6 +1252,10 @@ untilE :: forall e. Eff e Boolean -> Eff e Unit

1206whileE :: forall e a. Eff e Boolean -> Eff e a -> Eff e Unit

1252whileE :: forall e a. Eff e Boolean -> Eff e a -> Eff e Unit

1207```

1253```

1208

1254

1255+Loop while a condition is `true`.

1256+

1257+`whileE b m` is effectful computation which runs the effectful computation `b`. If its result is

1258+`true`, it runs the effectful computation `m` and loops. If not, the computation ends.

1209

1259

1210#### `forE`

1260#### `forE`

1211

1261

@@ -1213,6 +1263,10 @@ whileE :: forall e a. Eff e Boolean -> Eff e a -> Eff e Unit

1213forE :: forall e. Number -> Number -> (Number -> Eff e Unit) -> Eff e Unit

1263forE :: forall e. Number -> Number -> (Number -> Eff e Unit) -> Eff e Unit

1214```

1264```

1215

1265

1266+Loop over a consecutive collection of numbers.

1267+

1268+`forE lo hi f` runs the computation returned by the function `f` for each of the inputs

1269+between `lo` (inclusive) and `hi` (exclusive).

1216

1270

1217#### `foreachE`

1271#### `foreachE`

1218

1272

@@ -1220,6 +1274,9 @@ forE :: forall e. Number -> Number -> (Number -> Eff e Unit) -> Eff e Unit

1220foreachE :: forall e a. [a] -> (a -> Eff e Unit) -> Eff e Unit

1274foreachE :: forall e a. [a] -> (a -> Eff e Unit) -> Eff e Unit

1221```

1275```

1222

1276

1277+Loop over an array of values.

1278+

1279+`foreach xs f` runs the computation returned by the function `f` for each of the inputs `xs`.

1223

1280

1224

1281

1225## Module Control.Monad.Eff.Unsafe

1282## Module Control.Monad.Eff.Unsafe

@@ -1230,6 +1287,9 @@ foreachE :: forall e a. [a] -> (a -> Eff e Unit) -> Eff e Unit

1230unsafeInterleaveEff :: forall eff1 eff2 a. Eff eff1 a -> Eff eff2 a

1287unsafeInterleaveEff :: forall eff1 eff2 a. Eff eff1 a -> Eff eff2 a

1231```

1288```

1232

1289

1290+Change the type of an effectful computation, allowing it to be run in another context.

1291+

1292+Note: use of this function can result in arbitrary side-effects.

1233

1293

1234

1294

1235## Module Debug.Trace

1295## Module Debug.Trace

@@ -1240,6 +1300,7 @@ unsafeInterleaveEff :: forall eff1 eff2 a. Eff eff1 a -> Eff eff2 a

1240data Trace :: !

1300data Trace :: !

1241```

1301```

1242

1302

1303+The `Trace` effect represents those computations which write to the console.

1243

1304

1244#### `trace`

1305#### `trace`

1245

1306

@@ -1247,6 +1308,7 @@ data Trace :: !

1247trace :: forall r. String -> Eff (trace :: Trace | r) Unit

1308trace :: forall r. String -> Eff (trace :: Trace | r) Unit

1248```

1309```

1249

1310

1311+Write a `String` to the console.

1250

1312

1251#### `print`

1313#### `print`

1252

1314

@@ -1254,6 +1316,7 @@ trace :: forall r. String -> Eff (trace :: Trace | r) Unit

1254print :: forall a r. (Show a) => a -> Eff (trace :: Trace | r) Unit

1316print :: forall a r. (Show a) => a -> Eff (trace :: Trace | r) Unit

1255```

1317```

1256

1318

1319+Write a value to the console, using its `Show` instance to produce a `String`.

1257

1320

1258

1321

1259## Module Control.Monad.ST

1322## Module Control.Monad.ST

@@ -1264,6 +1327,11 @@ print :: forall a r. (Show a) => a -> Eff (trace :: Trace | r) Unit

1264data ST :: * -> !

1327data ST :: * -> !

1265```

1328```

1266

1329

1330+The `ST` effect represents _local mutation_, i.e. mutation which does not "escape" into the surrounding computation.

1331+

1332+An `ST` computation is parameterized by a phantom type which is used to restrict the set of reference cells it is allowed to access.

1333+

1334+The `runST` function can be used to handle the `ST` effect.

1267

1335

1268#### `STRef`

1336#### `STRef`

1269

1337

@@ -1271,6 +1339,7 @@ data ST :: * -> !

1271data STRef :: * -> * -> *

1339data STRef :: * -> * -> *

1272```

1340```

1273

1341

1342+The type `STRef s a` represents a mutable reference holding a value of type `a`, which can be used with the `ST s` effect.

1274

1343

1275#### `newSTRef`

1344#### `newSTRef`

1276

1345

@@ -1278,6 +1347,7 @@ data STRef :: * -> * -> *

1278newSTRef :: forall a h r. a -> Eff (st :: ST h | r) (STRef h a)

1347newSTRef :: forall a h r. a -> Eff (st :: ST h | r) (STRef h a)

1279```

1348```

1280

1349

1350+Create a new mutable reference.

1281

1351

1282#### `readSTRef`

1352#### `readSTRef`

1283

1353

@@ -1285,6 +1355,7 @@ newSTRef :: forall a h r. a -> Eff (st :: ST h | r) (STRef h a)

1285readSTRef :: forall a h r. STRef h a -> Eff (st :: ST h | r) a

1355readSTRef :: forall a h r. STRef h a -> Eff (st :: ST h | r) a

1286```

1356```

1287

1357

1358+Read the current value of a mutable reference.

1288

1359

1289#### `modifySTRef`

1360#### `modifySTRef`

1290

1361

@@ -1292,6 +1363,7 @@ readSTRef :: forall a h r. STRef h a -> Eff (st :: ST h | r) a

1292modifySTRef :: forall a h r. STRef h a -> (a -> a) -> Eff (st :: ST h | r) a

1363modifySTRef :: forall a h r. STRef h a -> (a -> a) -> Eff (st :: ST h | r) a

1293```

1364```

1294

1365

1366+Modify the value of a mutable reference by applying a function to the current value.

1295

1367

1296#### `writeSTRef`

1368#### `writeSTRef`

1297

1369

@@ -1299,6 +1371,7 @@ modifySTRef :: forall a h r. STRef h a -> (a -> a) -> Eff (st :: ST h | r) a

1299writeSTRef :: forall a h r. STRef h a -> a -> Eff (st :: ST h | r) a

1371writeSTRef :: forall a h r. STRef h a -> a -> Eff (st :: ST h | r) a

1300```

1372```

1301

1373

1374+Set the value of a mutable reference.

1302

1375

1303#### `runST`

1376#### `runST`

1304

1377

@@ -1306,6 +1379,12 @@ writeSTRef :: forall a h r. STRef h a -> a -> Eff (st :: ST h | r) a

1306runST :: forall a r. (forall h. Eff (st :: ST h | r) a) -> Eff r a

1379runST :: forall a r. (forall h. Eff (st :: ST h | r) a) -> Eff r a

1307```

1380```

1308

1381

1382+Run an `ST` computation.

1383+

1384+Note: the type of `runST` uses a rank-2 type to constrain the phantom type `s`, such that the computation must not leak any mutable references

1385+to the surrounding computation.

1386+

1387+It may cause problems to apply this function using the `$` operator. The recommended approach is to use parentheses instead.

1309

1388

1310#### `pureST`

1389#### `pureST`

1311

1390

@@ -1313,6 +1392,10 @@ runST :: forall a r. (forall h. Eff (st :: ST h | r) a) -> Eff r a

1313pureST :: forall a. (forall h r. Eff (st :: ST h | r) a) -> a

1392pureST :: forall a. (forall h r. Eff (st :: ST h | r) a) -> a

1314```

1393```

1315

1394

1395+A convenience function which combines `runST` with `runPure`, which can be used when the only required effect is `ST`.

1396+

1397+Note: since this function has a rank-2 type, it may cause problems to apply this function using the `$` operator. The recommended approach

1398+is to use parentheses instead.

1316

1399

1317

1400

1318

1401

prelude/prelude.purs+114−3

@@ -234,7 +234,7 @@ module Prelude

234 class Functor f where

235 (<$>) :: forall a b. (a -> b) -> f a -> f b

236

237− -- | `(<#>)` is `(<$>)` with its arguments flipped. For example:

237+ -- | `(<#>)` is `(<$>)` with its arguments reversed. For example:

238 -- |

239 -- | ```purescript

240 -- | [1, 2, 3] <#> \n -> n * n

@@ -866,21 +866,51 @@ module Prelude

866

867module Data.Function where

868

869+ -- | The `on` function is used to change the domain of a binary operator.

870+ -- |

871+ -- | For example, we can create a function which compares two records based on the values of their `x` properties:

872+ -- |

873+ -- | ```purescript

874+ -- | compareX :: forall r. { x :: Number | r } -> { x :: Number | r } -> Ordering

875+ -- | compareX = compare `on` _.x

876+ -- | ```

869 on :: forall a b c. (b -> b -> c) -> (a -> b) -> a -> a -> c

877 on :: forall a b c. (b -> b -> c) -> (a -> b) -> a -> a -> c

870 on f g x y = g x `f` g y

878 on f g x y = g x `f` g y

871

879

880+ -- | A function of zero arguments

872 foreign import data Fn0 :: * -> *

881 foreign import data Fn0 :: * -> *

882+

883+ -- | A function of one argument

873 foreign import data Fn1 :: * -> * -> *

884 foreign import data Fn1 :: * -> * -> *

885+

886+ -- | A function of two arguments

874 foreign import data Fn2 :: * -> * -> * -> *

887 foreign import data Fn2 :: * -> * -> * -> *

888+

889+ -- | A function of three arguments

875 foreign import data Fn3 :: * -> * -> * -> * -> *

890 foreign import data Fn3 :: * -> * -> * -> * -> *

891+

892+ -- | A function of four arguments

876 foreign import data Fn4 :: * -> * -> * -> * -> * -> *

893 foreign import data Fn4 :: * -> * -> * -> * -> * -> *

894+

895+ -- | A function of five arguments

877 foreign import data Fn5 :: * -> * -> * -> * -> * -> * -> *

896 foreign import data Fn5 :: * -> * -> * -> * -> * -> * -> *

897+

898+ -- | A function of six arguments

878 foreign import data Fn6 :: * -> * -> * -> * -> * -> * -> * -> *

899 foreign import data Fn6 :: * -> * -> * -> * -> * -> * -> * -> *

900+

901+ -- | A function of seven arguments

879 foreign import data Fn7 :: * -> * -> * -> * -> * -> * -> * -> * -> *

902 foreign import data Fn7 :: * -> * -> * -> * -> * -> * -> * -> * -> *

903+

904+ -- | A function of eight arguments

880 foreign import data Fn8 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> *

905 foreign import data Fn8 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> *

906+

907+ -- | A function of nine arguments

881 foreign import data Fn9 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

908 foreign import data Fn9 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

909+

910+ -- | A function of ten arguments

882 foreign import data Fn10 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

911 foreign import data Fn10 :: * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> * -> *

883

912

913+ -- | Create a function of no arguments

884 foreign import mkFn0

914 foreign import mkFn0

885 """

915 """

886 function mkFn0(fn) {

916 function mkFn0(fn) {

@@ -890,6 +920,7 @@ module Data.Function where

890 }

920 }

891 """ :: forall a. (Unit -> a) -> Fn0 a

921 """ :: forall a. (Unit -> a) -> Fn0 a

892

922

923+ -- | Create a function of one argument

893 foreign import mkFn1

924 foreign import mkFn1

894 """

925 """

895 function mkFn1(fn) {

926 function mkFn1(fn) {

@@ -899,6 +930,7 @@ module Data.Function where

899 }

930 }

900 """ :: forall a b. (a -> b) -> Fn1 a b

931 """ :: forall a b. (a -> b) -> Fn1 a b

901

932

933+ -- | Create a function of two arguments from a curried function

902 foreign import mkFn2

934 foreign import mkFn2

903 """

935 """

904 function mkFn2(fn) {

936 function mkFn2(fn) {

@@ -908,6 +940,7 @@ module Data.Function where

908 }

940 }

909 """ :: forall a b c. (a -> b -> c) -> Fn2 a b c

941 """ :: forall a b c. (a -> b -> c) -> Fn2 a b c

910

942

943+ -- | Create a function of three arguments from a curried function

911 foreign import mkFn3

944 foreign import mkFn3

912 """

945 """

913 function mkFn3(fn) {

946 function mkFn3(fn) {

@@ -917,6 +950,7 @@ module Data.Function where

917 }

950 }

918 """ :: forall a b c d. (a -> b -> c -> d) -> Fn3 a b c d

951 """ :: forall a b c d. (a -> b -> c -> d) -> Fn3 a b c d

919

952

953+ -- | Create a function of four arguments from a curried function

920 foreign import mkFn4

954 foreign import mkFn4

921 """

955 """

922 function mkFn4(fn) {

956 function mkFn4(fn) {

@@ -926,6 +960,7 @@ module Data.Function where

926 }

960 }

927 """ :: forall a b c d e. (a -> b -> c -> d -> e) -> Fn4 a b c d e

961 """ :: forall a b c d e. (a -> b -> c -> d -> e) -> Fn4 a b c d e

928

962

963+ -- | Create a function of five arguments from a curried function

929 foreign import mkFn5

964 foreign import mkFn5

930 """

965 """

931 function mkFn5(fn) {

966 function mkFn5(fn) {

@@ -935,6 +970,7 @@ module Data.Function where

935 }

970 }

936 """ :: forall a b c d e f. (a -> b -> c -> d -> e -> f) -> Fn5 a b c d e f

971 """ :: forall a b c d e f. (a -> b -> c -> d -> e -> f) -> Fn5 a b c d e f

937

972

973+ -- | Create a function of six arguments from a curried function

938 foreign import mkFn6

974 foreign import mkFn6

939 """

975 """

940 function mkFn6(fn) {

976 function mkFn6(fn) {

@@ -944,6 +980,7 @@ module Data.Function where

944 }

980 }

945 """ :: forall a b c d e f g. (a -> b -> c -> d -> e -> f -> g) -> Fn6 a b c d e f g

981 """ :: forall a b c d e f g. (a -> b -> c -> d -> e -> f -> g) -> Fn6 a b c d e f g

946

982

983+ -- | Create a function of seven arguments from a curried function

947 foreign import mkFn7

984 foreign import mkFn7

948 """

985 """

949 function mkFn7(fn) {

986 function mkFn7(fn) {

@@ -953,6 +990,7 @@ module Data.Function where

953 }

990 }

954 """ :: forall a b c d e f g h. (a -> b -> c -> d -> e -> f -> g -> h) -> Fn7 a b c d e f g h

991 """ :: forall a b c d e f g h. (a -> b -> c -> d -> e -> f -> g -> h) -> Fn7 a b c d e f g h

955

992

993+ -- | Create a function of eight arguments from a curried function

956 foreign import mkFn8

994 foreign import mkFn8

957 """

995 """

958 function mkFn8(fn) {

996 function mkFn8(fn) {

@@ -962,6 +1000,7 @@ module Data.Function where

962 }

1000 }

963 """ :: forall a b c d e f g h i. (a -> b -> c -> d -> e -> f -> g -> h -> i) -> Fn8 a b c d e f g h i

1001 """ :: forall a b c d e f g h i. (a -> b -> c -> d -> e -> f -> g -> h -> i) -> Fn8 a b c d e f g h i

964

1002

1003+ -- | Create a function of nine arguments from a curried function

965 foreign import mkFn9

1004 foreign import mkFn9

966 """

1005 """

967 function mkFn9(fn) {

1006 function mkFn9(fn) {

@@ -971,6 +1010,7 @@ module Data.Function where

971 }

1010 }

972 """ :: forall a b c d e f g h i j. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j) -> Fn9 a b c d e f g h i j

1011 """ :: forall a b c d e f g h i j. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j) -> Fn9 a b c d e f g h i j

973

1012

1013+ -- | Create a function of ten arguments from a curried function

974 foreign import mkFn10

1014 foreign import mkFn10

975 """

1015 """

976 function mkFn10(fn) {

1016 function mkFn10(fn) {

@@ -980,6 +1020,7 @@ module Data.Function where

980 }

1020 }

981 """ :: forall a b c d e f g h i j k. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k) -> Fn10 a b c d e f g h i j k

1021 """ :: forall a b c d e f g h i j k. (a -> b -> c -> d -> e -> f -> g -> h -> i -> j -> k) -> Fn10 a b c d e f g h i j k

982

1022

1023+ -- | Apply a function of no arguments

983 foreign import runFn0

1024 foreign import runFn0

984 """

1025 """

985 function runFn0(fn) {

1026 function runFn0(fn) {

@@ -987,6 +1028,7 @@ module Data.Function where

987 }

1028 }

988 """ :: forall a. Fn0 a -> a

1029 """ :: forall a. Fn0 a -> a

989

1030

1031+ -- | Apply a function of one argument

990 foreign import runFn1

1032 foreign import runFn1

991 """

1033 """

992 function runFn1(fn) {

1034 function runFn1(fn) {

@@ -996,6 +1038,7 @@ module Data.Function where

996 }

1038 }

997 """ :: forall a b. Fn1 a b -> a -> b

1039 """ :: forall a b. Fn1 a b -> a -> b

998

1040

1041+ -- | Apply a function of two arguments

999 foreign import runFn2

1042 foreign import runFn2

1000 """

1043 """

1001 function runFn2(fn) {

1044 function runFn2(fn) {

@@ -1007,6 +1050,7 @@ module Data.Function where

1007 }

1050 }

1008 """ :: forall a b c. Fn2 a b c -> a -> b -> c

1051 """ :: forall a b c. Fn2 a b c -> a -> b -> c

1009

1052

1053+ -- | Apply a function of three arguments

1010 foreign import runFn3

1054 foreign import runFn3

1011 """

1055 """

1012 function runFn3(fn) {

1056 function runFn3(fn) {

@@ -1020,6 +1064,7 @@ module Data.Function where

1020 }

1064 }

1021 """ :: forall a b c d. Fn3 a b c d -> a -> b -> c -> d

1065 """ :: forall a b c d. Fn3 a b c d -> a -> b -> c -> d

1022

1066

1067+ -- | Apply a function of four arguments

1023 foreign import runFn4

1068 foreign import runFn4

1024 """

1069 """

1025 function runFn4(fn) {

1070 function runFn4(fn) {

@@ -1035,6 +1080,7 @@ module Data.Function where

1035 }

1080 }

1036 """ :: forall a b c d e. Fn4 a b c d e -> a -> b -> c -> d -> e

1081 """ :: forall a b c d e. Fn4 a b c d e -> a -> b -> c -> d -> e

1037

1082

1083+ -- | Apply a function of five arguments

1038 foreign import runFn5

1084 foreign import runFn5

1039 """

1085 """

1040 function runFn5(fn) {

1086 function runFn5(fn) {

@@ -1052,6 +1098,7 @@ module Data.Function where

1052 }

1098 }

1053 """ :: forall a b c d e f. Fn5 a b c d e f -> a -> b -> c -> d -> e -> f

1099 """ :: forall a b c d e f. Fn5 a b c d e f -> a -> b -> c -> d -> e -> f

1054

1100

1101+ -- | Apply a function of six arguments

1055 foreign import runFn6

1102 foreign import runFn6

1056 """

1103 """

1057 function runFn6(fn) {

1104 function runFn6(fn) {

@@ -1071,6 +1118,7 @@ module Data.Function where

1071 }

1118 }

1072 """ :: forall a b c d e f g. Fn6 a b c d e f g -> a -> b -> c -> d -> e -> f -> g

1119 """ :: forall a b c d e f g. Fn6 a b c d e f g -> a -> b -> c -> d -> e -> f -> g

1073

1120

1121+ -- | Apply a function of seven arguments

1074 foreign import runFn7

1122 foreign import runFn7

1075 """

1123 """

1076 function runFn7(fn) {

1124 function runFn7(fn) {

@@ -1092,6 +1140,7 @@ module Data.Function where

1092 }

1140 }

1093 """ :: forall a b c d e f g h. Fn7 a b c d e f g h -> a -> b -> c -> d -> e -> f -> g -> h

1141 """ :: forall a b c d e f g h. Fn7 a b c d e f g h -> a -> b -> c -> d -> e -> f -> g -> h

1094

1142

1143+ -- | Apply a function of eight arguments

1095 foreign import runFn8

1144 foreign import runFn8

1096 """

1145 """

1097 function runFn8(fn) {

1146 function runFn8(fn) {

@@ -1115,6 +1164,7 @@ module Data.Function where

1115 }

1164 }

1116 """ :: forall a b c d e f g h i. Fn8 a b c d e f g h i -> a -> b -> c -> d -> e -> f -> g -> h -> i

1165 """ :: forall a b c d e f g h i. Fn8 a b c d e f g h i -> a -> b -> c -> d -> e -> f -> g -> h -> i

1117

1166

1167+ -- | Apply a function of nine arguments

1118 foreign import runFn9

1168 foreign import runFn9

1119 """

1169 """

1120 function runFn9(fn) {

1170 function runFn9(fn) {

@@ -1140,6 +1190,7 @@ module Data.Function where

1140 }

1190 }

1141 """ :: forall a b c d e f g h i j. Fn9 a b c d e f g h i j -> a -> b -> c -> d -> e -> f -> g -> h -> i -> j

1191 """ :: forall a b c d e f g h i j. Fn9 a b c d e f g h i j -> a -> b -> c -> d -> e -> f -> g -> h -> i -> j

1142

1192

1193+ -- | Apply a function of ten arguments

1143 foreign import runFn10

1194 foreign import runFn10

1144 """

1195 """

1145 function runFn10(fn) {

1196 function runFn10(fn) {

@@ -1169,6 +1220,9 @@ module Data.Function where

1169

1220

1170module Prelude.Unsafe where

1221module Prelude.Unsafe where

1171

1222

1223+ -- | Find the element of an array at the specified index.

1224+ -- |

1225+ -- | Note: this function can cause unpredictable failure at runtime if the index is out-of-bounds.

1172 foreign import unsafeIndex

1226 foreign import unsafeIndex

1173 """

1227 """

1174 function unsafeIndex(xs) {

1228 function unsafeIndex(xs) {

@@ -1178,8 +1232,18 @@ module Prelude.Unsafe where

1178 }

1232 }

1179 """ :: forall a. [a] -> Number -> a

1233 """ :: forall a. [a] -> Number -> a

1180

1234

1181−module Control.Monad.Eff where

1235+module Control.Monad.Eff

1236+ ( Eff()

1237+ , Pure()

1238+ , runPure

1239+ , untilE, whileE, forE, foreachE

1240+ ) where

1182

1241

1242+ -- | The `Eff` type constructor is used to represent _native_ effects.

1243+ -- |

1244+ -- | See [Handling Native Effects with the Eff Monad](https://github.com/purescript/purescript/wiki/Handling-Native-Effects-with-the-Eff-Monad) for more details.

1245+ -- |

1246+ -- | The first type parameter is a row of effects which represents the contexts in which a computation can be run, and the second type parameter is the return type.

1183 foreign import data Eff :: # ! -> * -> *

1247 foreign import data Eff :: # ! -> * -> *

1184

1248

1185 foreign import returnE

1249 foreign import returnE

@@ -1202,8 +1266,15 @@ module Control.Monad.Eff where

1202 }

1266 }

1203 """ :: forall e a b. Eff e a -> (a -> Eff e b) -> Eff e b

1267 """ :: forall e a b. Eff e a -> (a -> Eff e b) -> Eff e b

1204

1268

1269+ -- | The `Pure` type synonym represents _pure_ computations, i.e. ones in which all effects have been handled.

1270+ -- |

1271+ -- | The `runPure` function can be used to run pure computations and obtain their result.

1205 type Pure a = forall e. Eff e a

1272 type Pure a = forall e. Eff e a

1206

1273

1274+ -- | Run a pure computation and return its result.

1275+ -- |

1276+ -- | Note: since this function has a rank-2 type, it may cause problems to apply this function using the `$` operator. The recommended approach

1277+ -- | is to use parentheses instead.

1207 foreign import runPure

1278 foreign import runPure

1208 """

1279 """

1209 function runPure(f) {

1280 function runPure(f) {

@@ -1225,6 +1296,10 @@ module Control.Monad.Eff where

1225

1296

1226 instance monadEff :: Monad (Eff e)

1297 instance monadEff :: Monad (Eff e)

1227

1298

1299+ -- | Loop until a condition becomes `true`.

1300+ -- |

1301+ -- | `untilE b` is an effectful computation which repeatedly runs the effectful computation `b`,

1302+ -- | until its return value is `true`.

1228 foreign import untilE

1303 foreign import untilE

1229 """

1304 """

1230 function untilE(f) {

1305 function untilE(f) {

@@ -1235,6 +1310,10 @@ module Control.Monad.Eff where

1235 }

1310 }

1236 """ :: forall e. Eff e Boolean -> Eff e Unit

1311 """ :: forall e. Eff e Boolean -> Eff e Unit

1237

1312

1313+ -- | Loop while a condition is `true`.

1314+ -- |

1315+ -- | `whileE b m` is effectful computation which runs the effectful computation `b`. If its result is

1316+ -- | `true`, it runs the effectful computation `m` and loops. If not, the computation ends.

1238 foreign import whileE

1317 foreign import whileE

1239 """

1318 """

1240 function whileE(f) {

1319 function whileE(f) {

@@ -1249,6 +1328,10 @@ module Control.Monad.Eff where

1249 }

1328 }

1250 """ :: forall e a. Eff e Boolean -> Eff e a -> Eff e Unit

1329 """ :: forall e a. Eff e Boolean -> Eff e a -> Eff e Unit

1251

1330

1331+ -- | Loop over a consecutive collection of numbers.

1332+ -- |

1333+ -- | `forE lo hi f` runs the computation returned by the function `f` for each of the inputs

1334+ -- | between `lo` (inclusive) and `hi` (exclusive).

1252 foreign import forE

1335 foreign import forE

1253 """

1336 """

1254 function forE(lo) {

1337 function forE(lo) {

@@ -1264,7 +1347,9 @@ module Control.Monad.Eff where

1264 }

1347 }

1265 """ :: forall e. Number -> Number -> (Number -> Eff e Unit) -> Eff e Unit

1348 """ :: forall e. Number -> Number -> (Number -> Eff e Unit) -> Eff e Unit

1266

1349

1267−

1350+ -- | Loop over an array of values.

1351+ -- |

1352+ -- | `foreach xs f` runs the computation returned by the function `f` for each of the inputs `xs`.

1268 foreign import foreachE

1353 foreign import foreachE

1269 """

1354 """

1270 function foreachE(as) {

1355 function foreachE(as) {

@@ -1282,6 +1367,9 @@ module Control.Monad.Eff.Unsafe where

1282

1367

1283 import Control.Monad.Eff

1368 import Control.Monad.Eff

1284

1369

1370+ -- | Change the type of an effectful computation, allowing it to be run in another context.

1371+ -- |

1372+ -- | Note: use of this function can result in arbitrary side-effects.

1285 foreign import unsafeInterleaveEff

1373 foreign import unsafeInterleaveEff

1286 """

1374 """

1287 function unsafeInterleaveEff(f) {

1375 function unsafeInterleaveEff(f) {

@@ -1293,8 +1381,10 @@ module Debug.Trace where

1293

1381

1294 import Control.Monad.Eff

1382 import Control.Monad.Eff

1295

1383

1384+ -- | The `Trace` effect represents those computations which write to the console.

1296 foreign import data Trace :: !

1385 foreign import data Trace :: !

1297

1386

1387+ -- | Write a `String` to the console.

1298 foreign import trace

1388 foreign import trace

1299 """

1389 """

1300 function trace(s) {

1390 function trace(s) {

@@ -1305,6 +1395,7 @@ module Debug.Trace where

1305 }

1395 }

1306 """ :: forall r. String -> Eff (trace :: Trace | r) Unit

1396 """ :: forall r. String -> Eff (trace :: Trace | r) Unit

1307

1397

1398+ -- | Write a value to the console, using its `Show` instance to produce a `String`.

1308 print :: forall a r. (Show a) => a -> Eff (trace :: Trace | r) Unit

1399 print :: forall a r. (Show a) => a -> Eff (trace :: Trace | r) Unit

1309 print o = trace (show o)

1400 print o = trace (show o)

1310

1401

@@ -1312,10 +1403,17 @@ module Control.Monad.ST where

1312

1403

1313 import Control.Monad.Eff

1404 import Control.Monad.Eff

1314

1405

1406+ -- | The `ST` effect represents _local mutation_, i.e. mutation which does not "escape" into the surrounding computation.

1407+ -- |

1408+ -- | An `ST` computation is parameterized by a phantom type which is used to restrict the set of reference cells it is allowed to access.

1409+ -- |

1410+ -- | The `runST` function can be used to handle the `ST` effect.

1315 foreign import data ST :: * -> !

1411 foreign import data ST :: * -> !

1316

1412

1413+ -- | The type `STRef s a` represents a mutable reference holding a value of type `a`, which can be used with the `ST s` effect.

1317 foreign import data STRef :: * -> * -> *

1414 foreign import data STRef :: * -> * -> *

1318

1415

1416+ -- | Create a new mutable reference.

1319 foreign import newSTRef

1417 foreign import newSTRef

1320 """

1418 """

1321 function newSTRef(val) {

1419 function newSTRef(val) {

@@ -1325,6 +1423,7 @@ module Control.Monad.ST where

1325 }

1423 }

1326 """ :: forall a h r. a -> Eff (st :: ST h | r) (STRef h a)

1424 """ :: forall a h r. a -> Eff (st :: ST h | r) (STRef h a)

1327

1425

1426+ -- | Read the current value of a mutable reference.

1328 foreign import readSTRef

1427 foreign import readSTRef

1329 """

1428 """

1330 function readSTRef(ref) {

1429 function readSTRef(ref) {

@@ -1334,6 +1433,7 @@ module Control.Monad.ST where

1334 }

1433 }

1335 """ :: forall a h r. STRef h a -> Eff (st :: ST h | r) a

1434 """ :: forall a h r. STRef h a -> Eff (st :: ST h | r) a

1336

1435

1436+ -- | Modify the value of a mutable reference by applying a function to the current value.

1337 foreign import modifySTRef

1437 foreign import modifySTRef

1338 """

1438 """

1339 function modifySTRef(ref) {

1439 function modifySTRef(ref) {

@@ -1345,6 +1445,7 @@ module Control.Monad.ST where

1345 }

1445 }

1346 """ :: forall a h r. STRef h a -> (a -> a) -> Eff (st :: ST h | r) a

1446 """ :: forall a h r. STRef h a -> (a -> a) -> Eff (st :: ST h | r) a

1347

1447

1448+ -- | Set the value of a mutable reference.

1348 foreign import writeSTRef

1449 foreign import writeSTRef

1349 """

1450 """

1350 function writeSTRef(ref) {

1451 function writeSTRef(ref) {

@@ -1356,6 +1457,12 @@ module Control.Monad.ST where

1356 }

1457 }

1357 """ :: forall a h r. STRef h a -> a -> Eff (st :: ST h | r) a

1458 """ :: forall a h r. STRef h a -> a -> Eff (st :: ST h | r) a

1358

1459

1460+ -- | Run an `ST` computation.

1461+ -- |

1462+ -- | Note: the type of `runST` uses a rank-2 type to constrain the phantom type `s`, such that the computation must not leak any mutable references

1463+ -- | to the surrounding computation.

1464+ -- |

1465+ -- | It may cause problems to apply this function using the `$` operator. The recommended approach is to use parentheses instead.

1359 foreign import runST

1466 foreign import runST

1360 """

1467 """

1361 function runST(f) {

1468 function runST(f) {

@@ -1363,5 +1470,9 @@ module Control.Monad.ST where

1363 }

1470 }

1364 """ :: forall a r. (forall h. Eff (st :: ST h | r) a) -> Eff r a

1471 """ :: forall a r. (forall h. Eff (st :: ST h | r) a) -> Eff r a

1365

1472

1473+ -- | A convenience function which combines `runST` with `runPure`, which can be used when the only required effect is `ST`.

1474+ -- |

1475+ -- | Note: since this function has a rank-2 type, it may cause problems to apply this function using the `$` operator. The recommended approach

1476+ -- | is to use parentheses instead.

1366 pureST :: forall a. (forall h r. Eff (st :: ST h | r) a) -> a

1477 pureST :: forall a. (forall h r. Eff (st :: ST h | r) a) -> a

1367 pureST st = runPure (runST st)

1478 pureST st = runPure (runST st)