Debian Codegraph @

vendor/re/src/str.mli

raw
1 (***********************************************************************)
2 (* *)
3 (* Objective Caml *)
4 (* *)
5 (* Xavier Leroy, projet Cristal, INRIA Rocquencourt *)
6 (* *)
7 (* Copyright 1996 Institut National de Recherche en Informatique et *)
8 (* en Automatique. All rights reserved. This file is distributed *)
9 (* under the terms of the GNU Library General Public License, with *)
10 (* linking exception. *)
11 (* *)
12 (***********************************************************************)
13
14 (* $Id: re_str.mli,v 1.1 2002/01/16 14:16:04 vouillon Exp $ *)
15
16 (** Module [Str]: regular expressions and high-level string processing *)
17
18 (** {2 Regular expressions} *)
19
20 (** The type of compiled regular expressions. *)
21 type regexp
22
23 (** Compile a regular expression. The syntax for regular expressions
24 is the same as in Gnu Emacs. The special characters are
25 [$^.*+?[]]. The following constructs are recognized:
26 - [. ] matches any character except newline
27 - [* ] (postfix) matches the previous expression zero, one or
28 several times
29 - [+ ] (postfix) matches the previous expression one or
30 several times
31 - [? ] (postfix) matches the previous expression once or
32 not at all
33 - [[..] ] character set; ranges are denoted with [-], as in [[a-z]];
34 an initial [^], as in [[^0-9]], complements the set
35 - [^ ] matches at beginning of line
36 - [$ ] matches at end of line
37 - [\| ] (infix) alternative between two expressions
38 - [\(..\)] grouping and naming of the enclosed expression
39 - [\1 ] the text matched by the first [\(...\)] expression
40 ([\2] for the second expression, etc)
41 - [\b ] matches word boundaries
42 - [\ ] quotes special characters. *)
43 val regexp : string -> regexp
44
45 (** Same as [regexp], but the compiled expression will match text
46 in a case-insensitive way: uppercase and lowercase letters will
47 be considered equivalent. *)
48 val regexp_case_fold : string -> regexp
49
50 (** [Str.quote s] returns a regexp string that matches exactly
51 [s] and nothing else. *)
52 val quote : string -> string
53
54 (** [Str.regexp_string s] returns a regular expression
55 that matches exactly [s] and nothing else. *)
56 val regexp_string : string -> regexp
57
58 (** [Str.regexp_string_case_fold] is similar to [Str.regexp_string], but the regexp
59 matches in a case-insensitive way. *)
60 val regexp_string_case_fold : string -> regexp
61
62 (** {2 String matching and searching} *)
63
64 (** [string_match r s start] tests whether the characters in [s]
65 starting at position [start] match the regular expression [r].
66 The first character of a string has position [0], as usual. *)
67 val string_match : regexp -> string -> int -> bool
68
69 (** [search_forward r s start] searches the string [s] for a substring
70 matching the regular expression [r]. The search starts at position
71 [start] and proceeds towards the end of the string.
72 Return the position of the first character of the matched
73 substring, or raise [Not_found] if no substring matches. *)
74 val search_forward : regexp -> string -> int -> int
75
76 (** Same as [search_forward], but the search proceeds towards the
77 beginning of the string. *)
78 val search_backward : regexp -> string -> int -> int
79
80 (** Similar to [string_match], but succeeds whenever the argument
81 string is a prefix of a string that matches. This includes
82 the case of a true complete match. *)
83 val string_partial_match : regexp -> string -> int -> bool
84
85 (** [matched_string s] returns the substring of [s] that was matched
86 by the latest [string_match], [search_forward] or [search_backward].
87 The user must make sure that the parameter [s] is the same string
88 that was passed to the matching or searching function. *)
89 val matched_string : string -> string
90
91 (** [match_beginning ()] returns the position of the first character
92 of the substring that was matched by [string_match],
93 [search_forward] or [search_backward]. *)
94 val match_beginning : unit -> int
95
96 (** [match_end ()] returns the position of the character following the
97 last character of the substring that was matched by [string_match],
98 [search_forward] or [search_backward]. *)
99 val match_end : unit -> int
100
101 (** [matched_group n s] returns the substring of [s] that was matched
102 by the [n]th group [\(...\)] of the regular expression during
103 the latest [string_match], [search_forward] or [search_backward].
104 The user must make sure that the parameter [s] is the same string
105 that was passed to the matching or searching function.
106 [matched_group n s] raises [Not_found] if the [n]th group
107 of the regular expression was not matched. This can happen
108 with groups inside alternatives [\|], options [?]
109 or repetitions [*]. For instance, the empty string will match
110 [\(a\)*], but [matched_group 1 ""] will raise [Not_found]
111 because the first group itself was not matched. *)
112 val matched_group : int -> string -> string
113
114 (** [group_beginning n] returns the position of the first character
115 of the substring that was matched by the [n]th group of the regular expression.
116 Raises [Not_found] if the [n]th group of the regular expression was not matched. *)
117 val group_beginning : int -> int
118
119 (** [group_end n] returns the position of the character following
120 the last character of the matched substring.
121 Raises [Not_found] if the [n]th group of the regular expression was not matched. *)
122 val group_end : int -> int
123
124 (** {2 Replacement} *)
125
126 (** [global_replace regexp templ s] returns a string identical to [s],
127 except that all substrings of [s] that match [regexp] have been
128 replaced by [templ]. The replacement template [templ] can contain
129 [\1], [\2], etc; these sequences will be replaced by the text
130 matched by the corresponding group in the regular expression.
131 [\0] stands for the text matched by the whole regular expression. *)
132 val global_replace : regexp -> string -> string -> string
133
134 (** Same as [global_replace], except that only the first substring
135 matching the regular expression is replaced. *)
136 val replace_first : regexp -> string -> string -> string
137
138 (** [global_substitute regexp subst s] returns a string identical
139 to [s], except that all substrings of [s] that match [regexp]
140 have been replaced by the result of function [subst]. The
141 function [subst] is called once for each matching substring,
142 and receives [s] (the whole text) as argument. *)
143 val global_substitute : regexp -> (string -> string) -> string -> string
144
145 (** Same as [global_substitute], except that only the first substring
146 matching the regular expression is replaced. *)
147 val substitute_first : regexp -> (string -> string) -> string -> string
148
149 (** [replace_matched repl s] returns the replacement text [repl]
150 in which [\1], [\2], etc. have been replaced by the text
151 matched by the corresponding groups in the most recent matching
152 operation. [s] must be the same string that was matched during
153 this matching operation. *)
154 val replace_matched : string -> string -> string
155
156 (** {2 Splitting} *)
157
158 (** [split r s] splits [s] into substrings, taking as delimiters
159 the substrings that match [r], and returns the list of substrings.
160 For instance, [split (regexp "[ \t]+") s] splits [s] into
161 blank-separated words. An occurrence of the delimiter at the
162 beginning and at the end of the string is ignored. *)
163 val split : regexp -> string -> string list
164
165 (** Same as [split], but splits into at most [n] substrings,
166 where [n] is the extra integer parameter. *)
167 val bounded_split : regexp -> string -> int -> string list
168
169 (** Same as [split], but occurrences of the delimiter at the beginning
170 and at the end of the string are recognized and returned as empty strings
171 in the result.
172 For instance, [split_delim (regexp " ") " abc "] returns [[""; "abc"; ""]],
173 while [split] with the same arguments returns [["abc"]]. *)
174 val split_delim : regexp -> string -> string list
175
176 (** Same as [bounded_split] and [split_delim], but occurrences of
177 the delimiter at the beginning and at the end of the string are recognized
178 and returned as empty strings in the result.
179 For instance, [split_delim (regexp " ") " abc "] returns [[""; "abc"; ""]],
180 while [split] with the same arguments returns [["abc"]]. *)
181 val bounded_split_delim : regexp -> string -> int -> string list
182
183 type split_result =
184 | Text of string
185 | Delim of string
186
187 (** Same as [split_delim], but returns the delimiters
188 as well as the substrings contained between delimiters.
189 The former are tagged [Delim] in the result list;
190 the latter are tagged [Text].
191 For instance, [full_split (regexp "[{}]") "{ab}"] returns
192 [[Delim "{"; Text "ab"; Delim "}"]]. *)
193 val full_split : regexp -> string -> split_result list
194
195 (** Same as [split_delim] and [bounded_split_delim], but returns
196 the delimiters as well as the substrings contained between delimiters.
197 The former are tagged [Delim] in the result list;
198 the latter are tagged [Text].
199 For instance, [full_split (regexp "[{}]") "{ab}"] returns
200 [[Delim "{"; Text "ab"; Delim "}"]]. *)
201 val bounded_full_split : regexp -> string -> int -> split_result list
202
203 (** {2 Extracting substrings} *)
204
205 (** [string_before s n] returns the substring of all characters of [s]
206 that precede position [n] (excluding the character at
207 position [n]). *)
208 val string_before : string -> int -> string
209
210 (** [string_after s n] returns the substring of all characters of [s]
211 that follow position [n] (including the character at
212 position [n]). *)
213 val string_after : string -> int -> string
214
215 (** [first_chars s n] returns the first [n] characters of [s].
216 This is the same function as [string_before]. *)
217 val first_chars : string -> int -> string
218
219 (** [last_chars s n] returns the last [n] characters of [s]. *)
220 val last_chars : string -> int -> string