Crate onig

source ·
Expand description

This crate provides a safe wrapper around the Oniguruma regular expression library.

§Examples

use onig::Regex;

let regex = Regex::new("e(l+)").unwrap();
for (i, pos) in regex.captures("hello").unwrap().iter_pos().enumerate() {
    match pos {
         Some((beg, end)) =>
             println!("Group {} captured in position {}:{}", i, beg, end),
         None =>
             println!("Group {} is not captured", i)
    }
}

There are two basic things you can do with a Regex pattern; test if the pattern matches the whole of a given string, and search for occurences of the pattern within a string. Oniguruma exposes these two concepts with the match and search APIs.

In addition two these two base Onigurma APIs this crate exposes a third find API, built on top of the search API.

let pattern = Regex::new("hello").unwrap();
assert_eq!(true, pattern.find("hello world").is_some());
assert_eq!(false, pattern.is_match("hello world"));

§The Match API

Functions in the match API check if a pattern matches the entire string. The simplest of these is Regex::is_match. This retuns a true if the pattern matches the string. For more complex useage then Regex::match_with_options and Regex::match_with_encoding can be used. These allow the capture groups to be inspected, matching with different options, and matching sub-sections of a given text.

§The Search API

Function in the search API search for a pattern anywhere within a string. The simplist of these is Regex::find. This returns the offset of the first occurence of the pattern within the string. For more complex useage Regex::search_with_options and Regex::search_with_encoding can be used. These allow capture groups to be inspected, searching with different options and searching within subsections of a given text.

§The Find API

The find API is built on top of the search API. Functions in this API allow iteration across all matches of the pattern within a string, not just the first one. The functions deal with some of the complexities of this, such as zero-length matches.

The simplest step-up from the basic search API Regex::find is getting the captures relating to a match with the Regex::captures method. To find capture information for all matches within a string Regex::find_iter and Regex::captures_iter can be used. The former exposes the start and end of the match as Regex::find does, the latter exposes the whole capture group information as Regex::captures does.

§The std::pattern API

In addition to the main Oniguruma API it is possible to use the Regex object with the std::pattern API. To enable support compile with the std-pattern feature. If you’re using Cargo you can do this by adding the following to your Cargo.toml:

[dependencies.onig]
version = "1.2"
features = ["std-pattern"]

Structs§

  • CaptureTreeNode
    Capture Tree Node
  • CaptureTreeNodeIter
    Captures iterator
  • Captures
    Captures represents a group of captured strings for a single match.
  • EncodedBytes
    Byte Buffer
  • Error
    This struture represents an error from the underlying Oniguruma libray.
  • FindCaptures
    An iterator that yields all non-overlapping capture groups matching a particular regular expression.
  • FindMatches
    An iterator over all non-overlapping matches for a particular string.
  • MatchParam
    Parameters for a Match or Search.
  • MetaCharType
    Syntax meta character types
  • Regex
    This struct is a wrapper around an Oniguruma regular expression pointer. This represents a compiled regex which can be used in search and match operations.
  • RegexOptions
    Regex parsing and compilation options.
  • RegexSplits
    Yields all substrings delimited by a regular expression match.
  • RegexSplitsN
    Yields at most N substrings delimited by a regular expression match.
  • Region
    Represents a set of capture groups found in a search or match.
  • SearchOptions
    Regex evaluation options.
  • SubCaptures
    An iterator over capture groups for a particular match of a regular expression.
  • SubCapturesPos
    An iterator over capture group positions for a particular match of a regular expression.
  • Syntax
    Onig Syntax Wrapper
  • SyntaxBehavior
    Defines the behaviour of regex operators.
  • SyntaxOperator
    Defines the different operators allowed within a regex syntax.
  • TraverseCallbackAt
    The order in which traverse callbacks are invoked

Enums§

Traits§

  • EncodedChars
    Encoded String Buffer
  • Replacer
    Replacer describes types that can be used to replace matches in a string.

Functions§