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 ===
25 type regexp
28 The type of compiled regular expressions.
31 val regexp : string -> regexp
35 Compile a regular expression. The following constructs are recognized:
37 - . Matches any character except newline.
39 - * (postfix) Matches the preceding expression zero, one or several
41 times
42 - + (postfix) Matches the preceding expression one or several times
44 - ? (postfix) Matches the preceding expression once or not at all
46 - [..] Character set. Ranges are denoted with - , as in [a-z] . An
48 initial ^ , as in [^0-9] , complements the set. To include a ] charac‐
49 ter in a set, make it the first character of the set. To include a -
50 character in a set, make it the first or the last character of the set.
51 - ^ Matches at beginning of line: either at the beginning of the
53 matched string, or just after a '\n' character.
54 - $ Matches at end of line: either at the end of the matched string, or
56 just before a '\n' character.
57 - \| (infix) Alternative between two expressions.
59 - \(..\) Grouping and naming of the enclosed expression.
61 - \1 The text matched by the first \(...\) expression ( \2 for the sec‐
63 ond expression, and so on up to \9 ).
64 - \b Matches word boundaries.
66 - \ Quotes special characters. The special characters are $^\.*+?[] .
68 Note: the argument to regexp is usually a string literal. In this case,
70 any backslash character in the regular expression must be doubled to
71 make it past the OCaml string parser. For example, the following
72 expression: let r = Str.regexp hello \\([A-Za-z]+\\) in
73 Str.replace_first r \\1 hello world returns the string world .
74 In particular, if you want a regular expression that matches a single
76 backslash character, you need to quote it in the argument to regexp
77 (according to the last item of the list above) by adding a second back‐
78 slash. Then you need to quote both backslashes (according to the syntax
79 of string constants in OCaml) by doubling them again, so you need to
80 write four backslash characters: Str.regexp \\\\ .
81 val regexp_case_fold : string -> regexp
85 Same as regexp , but the compiled expression will match text in a
87 case-insensitive way: uppercase and lowercase letters will be consid‐
88 ered equivalent.
89 val quote : string -> string
93 Str.quote s returns a regexp string that matches exactly s and nothing
96 else.
97 val regexp_string : string -> regexp
101 Str.regexp_string s returns a regular expression that matches exactly s
104 and nothing else.
105 val regexp_string_case_fold : string -> regexp
109 Str.regexp_string_case_fold is similar to Str.regexp_string , but the
112 regexp matches in a case-insensitive way.
113 === String matching and searching ===
118 val string_match : regexp -> string -> int -> bool
121 string_match r s start tests whether a substring of s that starts at
124 position start matches the regular expression r . The first character
125 of a string has position 0 , as usual.
126 val search_forward : regexp -> string -> int -> int
130 search_forward r s start searches the string s for a substring matching
133 the regular expression r . The search starts at position start and pro‐
134 ceeds towards the end of the string. Return the position of the first
135 character of the matched substring.
136 Raises Not_found if no substring matches.
139 val search_backward : regexp -> string -> int -> int
143 search_backward r s last searches the string s for a substring matching
146 the regular expression r . The search first considers substrings that
147 start at position last and proceeds towards the beginning of string.
148 Return the position of the first character of the matched substring.
149 Raises Not_found if no substring matches.
152 val string_partial_match : regexp -> string -> int -> bool
156 Similar to Str.string_match , but also returns true if the argument
158 string is a prefix of a string that matches. This includes the case of
159 a true complete match.
160 val matched_string : string -> string
164 matched_string s returns the substring of s that was matched by the
167 last call to one of the following matching or searching functions:
168 - Str.string_match
170 - Str.search_forward
173 - Str.search_backward
176 - Str.string_partial_match
179 - Str.global_substitute
182 - Str.substitute_first
185 provided that none of the following functions was called inbetween:
187 - Str.global_replace
189 - Str.replace_first
192 - Str.split
195 - Str.bounded_split
198 - Str.split_delim
201 - Str.bounded_split_delim
204 - Str.full_split
207 - Str.bounded_full_split
210 Note: in the case of global_substitute and substitute_first , a call to
212 matched_string is only valid within the subst argument, not after
213 global_substitute or substitute_first returns.
214 The user must make sure that the parameter s is the same string that
216 was passed to the matching or searching function.
217 val match_beginning : unit -> int
221 match_beginning() returns the position of the first character of the
224 substring that was matched by the last call to a matching or searching
225 function (see Str.matched_string for details).
226 val match_end : unit -> int
230 match_end() returns the position of the character following the last
233 character of the substring that was matched by the last call to a
234 matching or searching function (see Str.matched_string for details).
235 val matched_group : int -> string -> string
239 matched_group n s returns the substring of s that was matched by the n
242 th group \(...\) of the regular expression that was matched by the last
243 call to a matching or searching function (see Str.matched_string for
244 details). The user must make sure that the parameter s is the same
245 string that was passed to the matching or searching function.
246 Raises Not_found if the n th group of the regular expression was not
249 matched. This can happen with groups inside alternatives \| , options
250 ? or repetitions * . For instance, the empty string will match \(a\)*
251 , but matched_group 1 will raise Not_found because the first group
252 itself was not matched.
253 val group_beginning : int -> int
257 group_beginning n returns the position of the first character of the
260 substring that was matched by the n th group of the regular expression
261 that was matched by the last call to a matching or searching function
262 (see Str.matched_string for details).
263 Raises Not_found if the n th group of the regular expression was not
266 matched.
267 Raises Invalid_argument if there are fewer than n groups in the regular
270 expression.
271 val group_end : int -> int
275 group_end n returns the position of the character following the last
278 character of substring that was matched by the n th group of the regu‐
279 lar expression that was matched by the last call to a matching or
280 searching function (see Str.matched_string for details).
281 Raises Not_found if the n th group of the regular expression was not
284 matched.
285 Raises Invalid_argument if there are fewer than n groups in the regular
288 expression.
289 === Replacement ===
294 val global_replace : regexp -> string -> string -> string
297 global_replace regexp templ s returns a string identical to s , except
300 that all substrings of s that match regexp have been replaced by templ
301 . The replacement template templ can contain \1 , \2 , etc; these
302 sequences will be replaced by the text matched by the corresponding
303 group in the regular expression. \0 stands for the text matched by the
304 whole regular expression.
305 val replace_first : regexp -> string -> string -> string
309 Same as Str.global_replace , except that only the first substring
311 matching the regular expression is replaced.
312 val global_substitute : regexp -> (string -> string) -> string ->
316 string
317 global_substitute regexp subst s returns a string identical to s ,
320 except that all substrings of s that match regexp have been replaced by
321 the result of function subst . The function subst is called once for
322 each matching substring, and receives s (the whole text) as argument.
323 val substitute_first : regexp -> (string -> string) -> string -> string
327 Same as Str.global_substitute , except that only the first substring
329 matching the regular expression is replaced.
330 val replace_matched : string -> string -> string
334 replace_matched repl s returns the replacement text repl in which \1 ,
337 \2 , etc. have been replaced by the text matched by the corresponding
338 groups in the regular expression that was matched by the last call to a
339 matching or searching function (see Str.matched_string for details). s
340 must be the same string that was passed to the matching or searching
341 function.
342 === Splitting ===
347 val split : regexp -> string -> string list
350 split r s splits s into substrings, taking as delimiters the substrings
353 that match r , and returns the list of substrings. For instance, split
354 (regexp [ \t]+ ) s splits s into blank-separated words. An occurrence
355 of the delimiter at the beginning or at the end of the string is
356 ignored.
357 val bounded_split : regexp -> string -> int -> string list
361 Same as Str.split , but splits into at most n substrings, where n is
363 the extra integer parameter.
364 val split_delim : regexp -> string -> string list
368 Same as Str.split but occurrences of the delimiter at the beginning and
370 at the end of the string are recognized and returned as empty strings
371 in the result. For instance, split_delim (regexp ) abc returns ["";
372 abc ; ] , while split with the same arguments returns ["abc"] .
373 val bounded_split_delim : regexp -> string -> int -> string list
377 Same as Str.bounded_split , but occurrences of the delimiter at the
379 beginning and at the end of the string are recognized and returned as
380 empty strings in the result.
381 type split_result =
384 | Text of string
385 | Delim of string
386 val full_split : regexp -> string -> split_result list
392 Same as Str.split_delim , but returns the delimiters as well as the
394 substrings contained between delimiters. The former are tagged Delim
395 in the result list; the latter are tagged Text . For instance,
396 full_split (regexp [{}] ) {ab} returns [Delim { ; Text ab ; Delim } ] .
397 val bounded_full_split : regexp -> string -> int -> split_result list
401 Same as Str.bounded_split_delim , but returns the delimiters as well as
403 the substrings contained between delimiters. The former are tagged
404 Delim in the result list; the latter are tagged Text .
405 === Extracting substrings ===
410 val string_before : string -> int -> string
413 string_before s n returns the substring of all characters of s that
416 precede position n (excluding the character at position n ).
417 val string_after : string -> int -> string
421 string_after s n returns the substring of all characters of s that fol‐
424 low position n (including the character at position n ).
425 val first_chars : string -> int -> string
429 first_chars s n returns the first n characters of s . This is the same
432 function as Str.string_before .
433 val last_chars : string -> int -> string
437 last_chars s n returns the last n characters of s .
440OCamldoc 2019-02-02 Str(3)