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§

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