Provided by: ocaml-man_4.14.1-1ubuntu1_all bug

NAME

       Str - Regular expressions and high-level string processing

Module

       Module   Str

Documentation

       Module Str
        : sig end

       Regular expressions and high-level string processing

   Regular expressions
       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
       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
       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
       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
       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 .