1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
(* arch-tag: slice operators mli file
Copyright (C) 2004 John Goerzen <jgoerzen@complete.org>
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*)
(** Flexible subparts of arrays, lists, and strings
The Sliceoper and Slice modules help you grab parts of arrays, lists, and
strings. For those familiar with Python, this mechanism is patterned after
Python's indexing features. The mechanism is also generalizable to any other
type that provides support for sub and length functions of the same manner
as the Array, String, and List (plus {!Listutil} from this library) modules.
It is recommended the modules that will be using slices should load the
Sliceoper module with:
{[open Sliceoper;;]}
to make the operators conveniently available.
{6 Slice Basics}
A slice via this module
contains two parts: a start position and an end position. Position 0
corresponds to the start of the list (or string, whatever). The end position
is the index of the last item plus one. Therefore, a slice from 0 to 2
would return the first two elements: elements 0 and 1.
The end position can also be negative. In that case, it means to leave off the
given number of items from the end of the list. For instance, if you had the
string "abcdefg" and took the slice from 0 to -1, you would obtain "abcdef".
If you took the slice from 1 to -3, you'd get "bcd".
You can also omit the end position to obtain the entire item starting from the
given start position. There are special operators for this case; see below.
These features, taken together, make it easy to obtain certain internal parts
of arrays, lists, or strings without requiring multiple calls to sub and
manual length calculations. *)
(** {6 Slice Composition Operator} *)
(** |> is the slice composition operator, and is designed to work solely
in conjunction with one of the slice application operators below. That is,
you can {b not} just say [let x = 1 |> 3;;] and expect a valid result (see the
{!Slice} module
if you wish to do this).
An example usage would be:
{["abcdefg" |$ 1 |> 3;;
string = "bc" ]}
*)
val (|>): (int -> 'a) -> int -> 'a
(** {6 Slice Application Operators}
The slice application operators are used to apply a slice to a string,
array, or list. They are designed to be used together with the slice
composition operator documented above.*)
(** String application operator. Example usage:
{[string |$ 1 |> -1;;]}
This strips the first and last characters off the string. *)
val (|$): string -> int -> int -> string
(** List application operator. Example usage:
{[list |@ 1 |> -1;;]}
This strips the first and last elements from the list. *)
val (|@): 'a list -> int -> int -> 'a list
(** Array application operator. Example usage:
{[array |& 1 |> -1;;]}
This strips the first and last elements from the array. *)
val (|&): 'a array -> int -> int -> 'a array
(** {6 Remainder-Of-Items Application Operators}
These operators are designed to take no ending position, instead taking only
a starting position. Therefore, the |> operator should not be used separately.
*)
(** String operator. Example usage:
{[string |$> 1;;]}
This strips the first character from the string. *)
val (|$>): string -> int -> string
(** List operator. Example usage:
{[list |@> 1;;]}
This strips the first character from the list. *)
val (|@>): 'a list -> int -> 'a list
(** Array operator. Example usage:
{[array |&> 1;;]}
This strips the first character from the array. *)
val (|&>): 'a array -> int -> 'a array
|
