1(* ========================================================================= *)
2(* ML UTILITY FUNCTIONS                                                      *)
3(* Copyright (c) 2001 Joe Hurd, distributed under the BSD License            *)
4(* ========================================================================= *)
5
6signature Useful =
7sig
8
9(* ------------------------------------------------------------------------- *)
10(* Exceptions.                                                               *)
11(* ------------------------------------------------------------------------- *)
12
13exception Error of string
14
15exception Bug of string
16
17val total : ('a -> 'b) -> 'a -> 'b option
18
19val can : ('a -> 'b) -> 'a -> bool
20
21(* ------------------------------------------------------------------------- *)
22(* Tracing.                                                                  *)
23(* ------------------------------------------------------------------------- *)
24
25val tracePrint : (string -> unit) ref
26
27val trace : string -> unit
28
29(* ------------------------------------------------------------------------- *)
30(* Combinators.                                                              *)
31(* ------------------------------------------------------------------------- *)
32
33val C : ('a -> 'b -> 'c) -> 'b -> 'a -> 'c
34
35val I : 'a -> 'a
36
37val K : 'a -> 'b -> 'a
38
39val S : ('a -> 'b -> 'c) -> ('a -> 'b) -> 'a -> 'c
40
41val W : ('a -> 'a -> 'b) -> 'a -> 'b
42
43val funpow : int -> ('a -> 'a) -> 'a -> 'a
44
45val exp : ('a * 'a -> 'a) -> 'a -> int -> 'a -> 'a
46
47(* ------------------------------------------------------------------------- *)
48(* Pairs.                                                                    *)
49(* ------------------------------------------------------------------------- *)
50
51val fst : 'a * 'b -> 'a
52
53val snd : 'a * 'b -> 'b
54
55val pair : 'a -> 'b -> 'a * 'b
56
57val swap : 'a * 'b -> 'b * 'a
58
59val curry : ('a * 'b -> 'c) -> 'a -> 'b -> 'c
60
61val uncurry : ('a -> 'b -> 'c) -> 'a * 'b -> 'c
62
63val ## : ('a -> 'c) * ('b -> 'd) -> 'a * 'b -> 'c * 'd
64
65(* ------------------------------------------------------------------------- *)
66(* State transformers.                                                       *)
67(* ------------------------------------------------------------------------- *)
68
69val unit : 'a -> 's -> 'a * 's
70
71val bind : ('s -> 'a * 's) -> ('a -> 's -> 'b * 's) -> 's -> 'b * 's
72
73val mmap : ('a -> 'b) -> ('s -> 'a * 's) -> 's -> 'b * 's
74
75val mjoin : ('s -> ('s -> 'a * 's) * 's) -> 's -> 'a * 's
76
77val mwhile : ('a -> bool) -> ('a -> 's -> 'a * 's) -> 'a -> 's -> 'a * 's
78
79(* ------------------------------------------------------------------------- *)
80(* Equality.                                                                 *)
81(* ------------------------------------------------------------------------- *)
82
83val equal : ''a -> ''a -> bool
84
85val notEqual : ''a -> ''a -> bool
86
87val listEqual : ('a -> 'a -> bool) -> 'a list -> 'a list -> bool
88
89(* ------------------------------------------------------------------------- *)
90(* Comparisons.                                                              *)
91(* ------------------------------------------------------------------------- *)
92
93val mapCompare : ('a -> 'b) -> ('b * 'b -> order) -> 'a * 'a -> order
94
95val revCompare : ('a * 'a -> order) -> 'a * 'a -> order
96
97val prodCompare :
98    ('a * 'a -> order) -> ('b * 'b -> order) -> ('a * 'b) * ('a * 'b) -> order
99
100val lexCompare : ('a * 'a -> order) -> 'a list * 'a list -> order
101
102val optionCompare : ('a * 'a -> order) -> 'a option * 'a option -> order
103
104val boolCompare : bool * bool -> order  (* false < true *)
105
106(* ------------------------------------------------------------------------- *)
107(* Lists: note we count elements from 0.                                     *)
108(* ------------------------------------------------------------------------- *)
109
110val cons : 'a -> 'a list -> 'a list
111
112val hdTl : 'a list -> 'a * 'a list
113
114val append : 'a list -> 'a list -> 'a list
115
116val singleton : 'a -> 'a list
117
118val first : ('a -> 'b option) -> 'a list -> 'b option
119
120val maps : ('a -> 's -> 'b * 's) -> 'a list -> 's -> 'b list * 's
121
122val mapsPartial : ('a -> 's -> 'b option * 's) -> 'a list -> 's -> 'b list * 's
123
124val zipWith : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
125
126val zip : 'a list -> 'b list -> ('a * 'b) list
127
128val unzip : ('a * 'b) list -> 'a list * 'b list
129
130val cartwith : ('a -> 'b -> 'c) -> 'a list -> 'b list -> 'c list
131
132val cart : 'a list -> 'b list -> ('a * 'b) list
133
134val takeWhile : ('a -> bool) -> 'a list -> 'a list
135
136val dropWhile : ('a -> bool) -> 'a list -> 'a list
137
138val divideWhile : ('a -> bool) -> 'a list -> 'a list * 'a list
139
140val groups : ('a * 's -> bool * 's) -> 's -> 'a list -> 'a list list
141
142val groupsBy : ('a * 'a -> bool) -> 'a list -> 'a list list
143
144val groupsByFst : (''a * 'b) list -> (''a * 'b list) list
145
146val groupsOf : int -> 'a list -> 'a list list
147
148val index : ('a -> bool) -> 'a list -> int option
149
150val enumerate : 'a list -> (int * 'a) list
151
152val divide : 'a list -> int -> 'a list * 'a list  (* Subscript *)
153
154val revDivide : 'a list -> int -> 'a list * 'a list  (* Subscript *)
155
156val updateNth : int * 'a -> 'a list -> 'a list  (* Subscript *)
157
158val deleteNth : int -> 'a list -> 'a list  (* Subscript *)
159
160(* ------------------------------------------------------------------------- *)
161(* Sets implemented with lists.                                              *)
162(* ------------------------------------------------------------------------- *)
163
164val mem : ''a -> ''a list -> bool
165
166val insert : ''a -> ''a list -> ''a list
167
168val delete : ''a -> ''a list -> ''a list
169
170val setify : ''a list -> ''a list  (* removes duplicates *)
171
172val union : ''a list -> ''a list -> ''a list
173
174val intersect : ''a list -> ''a list -> ''a list
175
176val difference : ''a list -> ''a list -> ''a list
177
178val subset : ''a list -> ''a list -> bool
179
180val distinct : ''a list -> bool
181
182(* ------------------------------------------------------------------------- *)
183(* Sorting and searching.                                                    *)
184(* ------------------------------------------------------------------------- *)
185
186val minimum : ('a * 'a -> order) -> 'a list -> 'a * 'a list  (* Empty *)
187
188val maximum : ('a * 'a -> order) -> 'a list -> 'a * 'a list  (* Empty *)
189
190val merge : ('a * 'a -> order) -> 'a list -> 'a list -> 'a list
191
192val sort : ('a * 'a -> order) -> 'a list -> 'a list
193
194val sortMap : ('a -> 'b) -> ('b * 'b -> order) -> 'a list -> 'a list
195
196(* ------------------------------------------------------------------------- *)
197(* Integers.                                                                 *)
198(* ------------------------------------------------------------------------- *)
199
200val interval : int -> int -> int list
201
202val divides : int -> int -> bool
203
204val gcd : int -> int -> int
205
206val primes : int -> int list
207
208val primesUpTo : int -> int list
209
210(* ------------------------------------------------------------------------- *)
211(* Strings.                                                                  *)
212(* ------------------------------------------------------------------------- *)
213
214val rot : int -> char -> char
215
216val charToInt : char -> int option
217
218val charFromInt : int -> char option
219
220val nChars : char -> int -> string
221
222val chomp : string -> string
223
224val trim : string -> string
225
226val join : string -> string list -> string
227
228val split : string -> string -> string list
229
230val capitalize : string -> string
231
232val mkPrefix : string -> string -> string
233
234val destPrefix : string -> string -> string
235
236val isPrefix : string -> string -> bool
237
238val stripPrefix : (char -> bool) -> string -> string
239
240val mkSuffix : string -> string -> string
241
242val destSuffix : string -> string -> string
243
244val isSuffix : string -> string -> bool
245
246val stripSuffix : (char -> bool) -> string -> string
247
248(* ------------------------------------------------------------------------- *)
249(* Tables.                                                                   *)
250(* ------------------------------------------------------------------------- *)
251
252type columnAlignment = {leftAlign : bool, padChar : char}
253
254val alignColumn : columnAlignment -> string list -> string list -> string list
255
256val alignTable : columnAlignment list -> string list list -> string list
257
258(* ------------------------------------------------------------------------- *)
259(* Reals.                                                                    *)
260(* ------------------------------------------------------------------------- *)
261
262val percentToString : real -> string
263
264val pos : real -> real
265
266val log2 : real -> real  (* Domain *)
267
268(* ------------------------------------------------------------------------- *)
269(* Sum datatype.                                                             *)
270(* ------------------------------------------------------------------------- *)
271
272datatype ('a,'b) sum = Left of 'a | Right of 'b
273
274val destLeft : ('a,'b) sum -> 'a
275
276val isLeft : ('a,'b) sum -> bool
277
278val destRight : ('a,'b) sum -> 'b
279
280val isRight : ('a,'b) sum -> bool
281
282(* ------------------------------------------------------------------------- *)
283(* Useful impure features.                                                   *)
284(* ------------------------------------------------------------------------- *)
285
286val newInt : unit -> int
287
288val newInts : int -> int list
289
290val withRef : 'r ref * 'r -> ('a -> 'b) -> 'a -> 'b
291
292val cloneArray : 'a Array.array -> 'a Array.array
293
294(* ------------------------------------------------------------------------- *)
295(* The environment.                                                          *)
296(* ------------------------------------------------------------------------- *)
297
298val host : unit -> string
299
300val time : unit -> string
301
302val date : unit -> string
303
304val readDirectory : {directory : string} -> {filename : string} list
305
306val readTextFile : {filename : string} -> string
307
308val writeTextFile : {contents : string, filename : string} -> unit
309
310(* ------------------------------------------------------------------------- *)
311(* Profiling and error reporting.                                            *)
312(* ------------------------------------------------------------------------- *)
313
314val try : ('a -> 'b) -> 'a -> 'b
315
316val chat : string -> unit  (* stdout *)
317
318val chide : string -> unit  (* stderr *)
319
320val warn : string -> unit
321
322val die : string -> 'exit
323
324val timed : ('a -> 'b) -> 'a -> real * 'b
325
326val timedMany : ('a -> 'b) -> 'a -> real * 'b
327
328val executionTime : unit -> real  (* Wall clock execution time *)
329
330end
331