[][src]Crate onig

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

CaptureTreeNode

Capture Tree Node

CaptureTreeNodeIter

Caputres 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

MetaChar

Meta Character State

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