Crate onig [−] [src]

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)
    }
}

Match vs Search

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::capturess 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

CaptureNames	CaptureNames is an iterator over named groups as a tuple with the group name and group indexes.
CaptureTreeNode
CaptureTreeNodeIter
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.
MetaCharType
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
SyntaxBehavior
SyntaxOperator
TraverseCallbackAt

Enums

MetaChar

Traits

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

Functions

copyright	Get Copyright
define_user_property	Create a User Defined Proeprty
version	Get Version