Str(3) OCaml library Str(3)

# [NAME](#NAME)

Str - Regular expressions and high-level string processing

# [Module](#Module)

Module Str

# [Documentation](#Documentation)

Module **Str**  
: **sig end**

Regular expressions and high-level string processing

## [Regular expressions](#Regular_expressions)

The **Str** library provides regular expressions on sequences of bytes. It is, in general, unsuitable to match Unicode characters.

*type regexp*

The type of compiled regular expressions.

*val regexp* : **string -> regexp**

Compile a regular expression. The following constructs are recognized:

\- **.** Matches any character except newline.

\- **\*** (postfix) Matches the preceding expression zero, one or several times

\- **+** (postfix) Matches the preceding expression one or several times

\- **?** (postfix) Matches the preceding expression once or not at all

\- **\[..]** Character set. Ranges are denoted with **-** , as in **\[a-z]** . An initial **^** , as in **\[^0-9]** , complements the set. To include a **]** character in a set, make it the first character of the set. To include a **-** character in a set, make it the first or the last character of the set.

\- **^** Matches at beginning of line: either at the beginning of the matched string, or just after a '\\n' character.

\- **$** Matches at end of line: either at the end of the matched string, or just before a '\\n' character.

\- **\\|** (infix) Alternative between two expressions.

\- **\\(..\\)** Grouping and naming of the enclosed expression.

\- **\\1** The text matched by the first **\\(...\\)** expression ( **\\2** for the second expression, and so on up to **\\9** ).

\- **\\b** Matches word boundaries.

\- **\\** Quotes special characters. The special characters are **$^\\.\*+?\[]** .

In regular expressions you will often use backslash characters; it's easier to use a quoted string literal **{|...|}** to avoid having to escape backslashes.

For example, the following expression:

```
let r = Str.regexp {|hello \([A-Za-z]+\)|} in


      Str.replace_first r {|\1|} "hello world" 
```

returns the string **"world"** .

If you want a regular expression that matches a literal backslash character, you need to double it: **Str.regexp {|\\\\|}** .

You can use regular string literals **"..."** too, however you will have to escape backslashes. The example above can be rewritten with a regular string literal as:

```
let r = Str.regexp "hello \\([A-Za-z]+\\)" in


      Str.replace_first r "\\1" "hello world" 
```

And the regular expression for matching a backslash becomes a quadruple backslash: **Str.regexp "\\\\\\\\"** .

*val regexp\_case\_fold* : **string -> regexp**

Same as **regexp** , but the compiled expression will match text in a case-insensitive way: uppercase and lowercase letters will be considered equivalent.

*val quote* : **string -> string**

**Str.quote s** returns a regexp string that matches exactly **s** and nothing else.

*val regexp\_string* : **string -> regexp**

**Str.regexp\_string s** returns a regular expression that matches exactly **s** and nothing else.

*val regexp\_string\_case\_fold* : **string -> regexp**

**Str.regexp\_string\_case\_fold** is similar to **Str.regexp\_string** , but the regexp matches in a case-insensitive way.

## [String matching and searching](#String_matching_and_searching)

*val string\_match* : **regexp -> string -> int -> bool**

**string\_match r s start** tests whether a substring of **s** that starts at position **start** matches the regular expression **r** . The first character of a string has position **0** , as usual.

*val search\_forward* : **regexp -> string -> int -> int**

**search\_forward r s start** searches the string **s** for a substring matching the regular expression **r** . The search starts at position **start** and proceeds towards the end of the string. Return the position of the first character of the matched substring.

**Raises Not\_found** if no substring matches.

*val search\_backward* : **regexp -> string -> int -> int**

**search\_backward r s last** searches the string **s** for a substring matching the regular expression **r** . The search first considers substrings that start at position **last** and proceeds towards the beginning of string. Return the position of the first character of the matched substring.

**Raises Not\_found** if no substring matches.

*val string\_partial\_match* : **regexp -> string -> int -> bool**

Similar to **Str.string\_match** , but also returns true if the argument string is a prefix of a string that matches. This includes the case of a true complete match.

*val matched\_string* : **string -> string**

**matched\_string s** returns the substring of **s** that was matched by the last call to one of the following matching or searching functions:

\- **Str.string\_match**

\- **Str.search\_forward**

\- **Str.search\_backward**

\- **Str.string\_partial\_match**

\- **Str.global\_substitute**

\- **Str.substitute\_first**

provided that none of the following functions was called in between:

\- **Str.global\_replace**

\- **Str.replace\_first**

\- **Str.split**

\- **Str.bounded\_split**

\- **Str.split\_delim**

\- **Str.bounded\_split\_delim**

\- **Str.full\_split**

\- **Str.bounded\_full\_split**

Note: in the case of **global\_substitute** and **substitute\_first** , a call to **matched\_string** is only valid within the **subst** argument, not after **global\_substitute** or **substitute\_first** returns.

The user must make sure that the parameter **s** is the same string that was passed to the matching or searching function.

*val match\_beginning* : **unit -> int**

**match\_beginning()** returns the position of the first character of the substring that was matched by the last call to a matching or searching function (see **Str.matched\_string** for details).

*val match\_end* : **unit -> int**

**match\_end()** returns the position of the character following the last character of the substring that was matched by the last call to a matching or searching function (see **Str.matched\_string** for details).

*val matched\_group* : **int -> string -> string**

**matched\_group n s** returns the substring of **s** that was matched by the **n** th group **\\(...\\)** of the regular expression that was matched by the last call to a matching or searching function (see **Str.matched\_string** for details). When **n** is **0** , it returns the substring matched by the whole regular expression. The user must make sure that the parameter **s** is the same string that was passed to the matching or searching function.

**Raises Not\_found** if the **n** th group of the regular expression was not matched. This can happen with groups inside alternatives **\\|** , options **?** or repetitions **\*** . For instance, the empty string will match **\\(a\\)\*** , but **matched\_group 1 ""** will raise **Not\_found** because the first group itself was not matched.

*val group\_beginning* : **int -> int**

**group\_beginning n** returns the position of the first character of the substring that was matched by the **n** th group of the regular expression that was matched by the last call to a matching or searching function (see **Str.matched\_string** for details).

**Raises Not\_found** if the **n** th group of the regular expression was not matched.

**Raises Invalid\_argument** if there are fewer than **n** groups in the regular expression.

*val group\_end* : **int -> int**

**group\_end n** returns the position of the character following the last character of substring that was matched by the **n** th group of the regular expression that was matched by the last call to a matching or searching function (see **Str.matched\_string** for details).

**Raises Not\_found** if the **n** th group of the regular expression was not matched.

**Raises Invalid\_argument** if there are fewer than **n** groups in the regular expression.

## [Replacement](#Replacement)

*val global\_replace* : **regexp -> string -> string -> string**

**global\_replace regexp templ s** returns a string identical to **s** , except that all substrings of **s** that match **regexp** have been replaced by **templ** . The replacement template **templ** can contain **\\1** , **\\2** , etc; these sequences will be replaced by the text matched by the corresponding group in the regular expression. **\\0** stands for the text matched by the whole regular expression.

*val replace\_first* : **regexp -> string -> string -> string**

Same as **Str.global\_replace** , except that only the first substring matching the regular expression is replaced.

*val global\_substitute* : **regexp -> (string -> string) -> string -> string**

**global\_substitute regexp subst s** returns a string identical to **s** , except that all substrings of **s** that match **regexp** have been replaced by the result of function **subst** . The function **subst** is called once for each matching substring, and receives **s** (the whole text) as argument.

*val substitute\_first* : **regexp -> (string -> string) -> string -> string**

Same as **Str.global\_substitute** , except that only the first substring matching the regular expression is replaced.

*val replace\_matched* : **string -> string -> string**

**replace\_matched repl s** returns the replacement text **repl** in which **\\1** , **\\2** , etc. have been replaced by the text matched by the corresponding groups in the regular expression that was matched by the last call to a matching or searching function (see **Str.matched\_string** for details). **s** must be the same string that was passed to the matching or searching function.

## [Splitting](#Splitting)

*val split* : **regexp -> string -> string list**

**split r s** splits **s** into substrings, taking as delimiters the substrings that match **r** , and returns the list of substrings. For instance, **split (regexp "\[ \\t]+") s** splits **s** into blank-separated words. An occurrence of the delimiter at the beginning or at the end of the string is ignored.

*val bounded\_split* : **regexp -> string -> int -> string list**

Same as **Str.split** , but splits into at most **n** substrings, where **n** is the extra integer parameter.

*val split\_delim* : **regexp -> string -> string list**

Same as **Str.split** but occurrences of the delimiter at the beginning and at the end of the string are recognized and returned as empty strings in the result. For instance, **split\_delim (regexp " ") " abc "** returns **\[""; "abc"; ""]** , while **split** with the same arguments returns **\["abc"]** .

*val bounded\_split\_delim* : **regexp -> string -> int -> string list**

Same as **Str.bounded\_split** , but occurrences of the delimiter at the beginning and at the end of the string are recognized and returned as empty strings in the result.

*type split\_result* =  
| Text **of** **string**  
| Delim **of** **string**

*val full\_split* : **regexp -> string -> split\_result list**

Same as **Str.split\_delim** , but returns the delimiters as well as the substrings contained between delimiters. The former are tagged **Delim** in the result list; the latter are tagged **Text** . For instance, **full\_split (regexp "\[{}]") "{ab}"** returns **\[Delim "{"; Text "ab"; Delim "}"]** .

*val bounded\_full\_split* : **regexp -> string -> int -> split\_result list**

Same as **Str.bounded\_split\_delim** , but returns the delimiters as well as the substrings contained between delimiters. The former are tagged **Delim** in the result list; the latter are tagged **Text** .

## [Extracting substrings](#Extracting_substrings)

*val string\_before* : **string -> int -> string**

**string\_before s n** returns the substring of all characters of **s** that precede position **n** (excluding the character at position **n** ).

*val string\_after* : **string -> int -> string**

**string\_after s n** returns the substring of all characters of **s** that follow position **n** (including the character at position **n** ).

*val first\_chars* : **string -> int -> string**

**first\_chars s n** returns the first **n** characters of **s** . This is the same function as **Str.string\_before** .

*val last\_chars* : **string -> int -> string**

**last\_chars s n** returns the last **n** characters of **s** .

2026-10-01 OCamldoc

---

Document: Str(3o) from ocaml 5.5.1-r1 (Chainguard OS)
Source: https://github.com/ocaml/ocaml