1Str(3) OCaml library Str(3)
2
6 Str - Regular expressions and high-level string processing
7
9 Module Str
10
12 Module Str
13 : sig end
14 Regular expressions and high-level string processing
17 === Regular expressions ===
26 type regexp
28 The type of compiled regular expressions.
31 val regexp : string -> regexp
36 Compile a regular expression. The following constructs are recognized:
38 - . Matches any character except newline.
40 - * (postfix) Matches the preceding expression zero, one or several
42 times
43 - + (postfix) Matches the preceding expression one or several times
45 - ? (postfix) Matches the preceding expression once or not at all
47 - [..] Character set. Ranges are denoted with - , as in [a-z] . An
49 initial ^ , as in [^0-9] , complements the set. To include a ] charac‐
50 ter in a set, make it the first character of the set. To include a -
51 character in a set, make it the first or the last character of the set.
52 - ^ Matches at beginning of line (either at the beginning of the
54 matched string, or just after a newline character).
55 - $ Matches at end of line (either at the end of the matched string, or
57 just before a newline character).
58 - \| (infix) Alternative between two expressions.
60 - \(..\) Grouping and naming of the enclosed expression.
62 - \1 The text matched by the first \(...\) expression ( \2 for the sec‐
64 ond expression, and so on up to \9 ).
65 - \b Matches word boundaries.
67 - \ Quotes special characters. The special characters are $^.*+?[] .
69 val regexp_case_fold : string -> regexp
75 Same as regexp , but the compiled expression will match text in a case-
77 insensitive way: uppercase and lowercase letters will be considered
78 equivalent.
79 val quote : string -> string
84 Str.quote s returns a regexp string that matches exactly s and nothing
87 else.
88 val regexp_string : string -> regexp
93 Str.regexp_string s returns a regular expression that matches exactly s
96 and nothing else.
97 val regexp_string_case_fold : string -> regexp
102 Str.regexp_string_case_fold is similar to Str.regexp_string , but the
105 regexp matches in a case-insensitive way.
106 === String matching and searching ===
112 val string_match : regexp -> string -> int -> bool
115 string_match r s start tests whether a substring of s that starts at
118 position start matches the regular expression r . The first character
119 of a string has position 0 , as usual.
120 val search_forward : regexp -> string -> int -> int
125 search_forward r s start searches the string s for a substring matching
128 the regular expression r . The search starts at position start and pro‐
129 ceeds towards the end of the string. Return the position of the first
130 character of the matched substring, or raise Not_found if no substring
131 matches.
132 val search_backward : regexp -> string -> int -> int
137 search_backward r s last searches the string s for a substring matching
140 the regular expression r . The search first considers substrings that
141 start at position last and proceeds towards the beginning of string.
142 Return the position of the first character of the matched substring;
143 raise Not_found if no substring matches.
144 val string_partial_match : regexp -> string -> int -> bool
149 Similar to Str.string_match , but also returns true if the argument
151 string is a prefix of a string that matches. This includes the case of
152 a true complete match.
153 val matched_string : string -> string
158 matched_string s returns the substring of s that was matched by the
161 latest Str.string_match , Str.search_forward or Str.search_backward .
162 The user must make sure that the parameter s is the same string that
163 was passed to the matching or searching function.
164 val match_beginning : unit -> int
169 match_beginning() returns the position of the first character of the
172 substring that was matched by Str.string_match , Str.search_forward or
173 Str.search_backward .
174 val match_end : unit -> int
179 match_end() returns the position of the character following the last
182 character of the substring that was matched by string_match ,
183 search_forward or search_backward .
184 val matched_group : int -> string -> string
189 matched_group n s returns the substring of s that was matched by the n
192 th group \(...\) of the regular expression during the latest
193 Str.string_match , Str.search_forward or Str.search_backward . The
194 user must make sure that the parameter s is the same string that was
195 passed to the matching or searching function. matched_group n s raises
196 Not_found if the n th group of the regular expression was not matched.
197 This can happen with groups inside alternatives \| , options ? or rep‐
198 etitions * . For instance, the empty string will match \(a\)* , but
199 matched_group 1 will raise Not_found because the first group itself was
200 not matched.
201 val group_beginning : int -> int
206 group_beginning n returns the position of the first character of the
209 substring that was matched by the n th group of the regular expression.
210 Raises
212 Not_found if the n th group of the regular expression was not matched.
214 Invalid_argument if there are fewer than n groups in the regular
216 expression.
217 val group_end : int -> int
223 group_end n returns the position of the character following the last
226 character of substring that was matched by the n th group of the regu‐
227 lar expression.
228 Raises
230 Not_found if the n th group of the regular expression was not matched.
232 Invalid_argument if there are fewer than n groups in the regular
234 expression.
235 === Replacement ===
242 val global_replace : regexp -> string -> string -> string
245 global_replace regexp templ s returns a string identical to s , except
248 that all substrings of s that match regexp have been replaced by templ
249 . The replacement template templ can contain \1 , \2 , etc; these
250 sequences will be replaced by the text matched by the corresponding
251 group in the regular expression. \0 stands for the text matched by the
252 whole regular expression.
253 val replace_first : regexp -> string -> string -> string
258 Same as Str.global_replace , except that only the first substring
260 matching the regular expression is replaced.
261 val global_substitute : regexp -> (string -> string) -> string ->
266 string
267 global_substitute regexp subst s returns a string identical to s ,
270 except that all substrings of s that match regexp have been replaced by
271 the result of function subst . The function subst is called once for
272 each matching substring, and receives s (the whole text) as argument.
273 val substitute_first : regexp -> (string -> string) -> string -> string
278 Same as Str.global_substitute , except that only the first substring
280 matching the regular expression is replaced.
281 val replace_matched : string -> string -> string
286 replace_matched repl s returns the replacement text repl in which \1 ,
289 \2 , etc. have been replaced by the text matched by the corresponding
290 groups in the most recent matching operation. s must be the same
291 string that was matched during this matching operation.
292 === Splitting ===
298 val split : regexp -> string -> string list
301 split r s splits s into substrings, taking as delimiters the substrings
304 that match r , and returns the list of substrings. For instance, split
305 (regexp [ \t]+ ) s splits s into blank-separated words. An occurrence
306 of the delimiter at the beginning and at the end of the string is
307 ignored.
308 val bounded_split : regexp -> string -> int -> string list
313 Same as Str.split , but splits into at most n substrings, where n is
315 the extra integer parameter.
316 val split_delim : regexp -> string -> string list
321 Same as Str.split but occurrences of the delimiter at the beginning and
323 at the end of the string are recognized and returned as empty strings
324 in the result. For instance, split_delim (regexp ) abc returns ["";
325 abc ; ] , while split with the same arguments returns ["abc"] .
326 val bounded_split_delim : regexp -> string -> int -> string list
331 Same as Str.bounded_split , but occurrences of the delimiter at the
333 beginning and at the end of the string are recognized and returned as
334 empty strings in the result.
335 type split_result =
339 | Text of string
340 | Delim of string
341 val full_split : regexp -> string -> split_result list
347 Same as Str.split_delim , but returns the delimiters as well as the
349 substrings contained between delimiters. The former are tagged Delim
350 in the result list; the latter are tagged Text . For instance,
351 full_split (regexp [{}] ) {ab} returns [Delim { ; Text ab ; Delim } ] .
352 val bounded_full_split : regexp -> string -> int -> split_result list
357 Same as Str.bounded_split_delim , but returns the delimiters as well as
359 the substrings contained between delimiters. The former are tagged
360 Delim in the result list; the latter are tagged Text .
361 === Extracting substrings ===
367 val string_before : string -> int -> string
370 string_before s n returns the substring of all characters of s that
373 precede position n (excluding the character at position n ).
374 val string_after : string -> int -> string
379 string_after s n returns the substring of all characters of s that fol‐
382 low position n (including the character at position n ).
383 val first_chars : string -> int -> string
388 first_chars s n returns the first n characters of s . This is the same
391 function as Str.string_before .
392 val last_chars : string -> int -> string
397 last_chars s n returns the last n characters of s .
400OCamldoc 2007-05-24 Str(3)