NIRE

regexp<charT>

Creates a internal object from regular expressions, holds it, and executes a search with it. This class is the core of NIRE, and basically follows the specification of RegExp of ECMAScript (JavaScript).
The following members are defined:

Constructors and flags

There are three ways to pass a string of regular expressions as an argument to a constructor: 1) pass a pointer to a null terminated string, 2) pass a pointer and a length, or 3) pass a const reference to an instance of std::basic_string.
Furthermore, there are two ways to pass flags to each of them: a) pass a value of the nire::flag::type type, or b) pass a pointer to a null terminated string. Thus, 3 x 2 = 6, there are six way to pass regular expressions and flags to the constructor.

regexp();
regexp(const regexp &r);    //  Copies.
regexp(regexp &&r) noexcept;    //  C++11 and later.

//  Pointer
regexp(const charT *const p, const flag::type f = flag::ECMAScript);
regexp(const charT *const p, const charT *const flags);

//  Pointer and length
regexp(const charT *const p, const std::size_t len, const flag::type f);
regexp(const charT *const p, const std::size_t len, const charT *const flags);

//  basic_string
regexp(const std::basic_string<charT> &str, const flag::type f = flag::ECMAScript);
regexp(const std::basic_string<charT> &str, const charT *const flags);
				

The following flags are available:

List of flags

Value of nire::flag::type type	String
nire::flag::global	"g"	Global match. If specified, the next position of the matched substring is stored into the lastIndex member, and the next search will start at the index indicated by lastIndex in the subject.
nire::flag::icase	"i"	Case-insensitive matching.
nire::flag::multiline	"m"	If specified, ^ and $ match the beginning of a line and the end of a line, respectively.
nire::flag::dotall	"s"	If specified, . matches every character including newline characters.
nire::flag::sticky	"y"	If specified, search is executed only at the index indicated by the lastIndex member.
nire::flag::noflags nire::flag::ECMAScript	""	For indicating no flags explicitly.

When passing a value of nire::flag::type, you can specify multiple flags at the same time by separating them by | (or).
When passing a string, you can specify multiple flags at the same time by writing like "im".

assign()

Copies, moves (C++11 and later), or compiles regular expressions.
For compiling, there are six ways to pass a string of regular expressions and flags as arguments, like constructors.

regexp &assign(const regexp &r);
regexp &assign(regexp &&r) noexcept;    //  C++11 and later.

//  Pointer
regexp &assign(const charT *const p, const flag::type f = flag::ECMAScript);
regexp &assign(const charT *const p, const charT *const flags);

//  Pointer and length
regexp &assign(const charT *const p, std::size_t len, const flag::type f);
regexp &assign(const charT *const p, std::size_t len, const charT *const flags);

//  basic_string
regexp &assign(const std::basic_string<charT> &str, const flag::type f = flag::ECMAScript);
regexp &assign(const std::basic_string<charT> &str, const charT *const flags);
				

operator=()

Copies, moves (C++11 and later), or compiles regular expressions.
Unlike constructors and assign(), there are only two ways to pass an argument: 1) pass a pointer to a null terminated string, or 2) pass a const reference to std::basic_string.

regexp &operator=(const regexp &r);
regexp &operator=(regexp &&r) noexcept; //  C++11 and later.

//  Pointer
regexp &operator=(const charT *const p)

//  basic_string
regexp &operator=(const std::basic_string<charT> &str)
				

lastIndex

The index value in a subject at which the next search is to start. This value is used only if the instance has been created with the global or sticky flag set. If either flag is not set, the value of lastIndex is ignored and a search is always executed at the beginning.

If the match succeeds, the next position of the matched substring (i.e., end of [begin, end)) is written into lastIndex. Otherwise lastIndex is reset to 0

Even if the subject string is changed, lastIndex is not reset automatically.

As this member is mutable, it can be written into even if it is in a const instance of regexp.

exec() const

Executes a search for a match with regular expressions in a subject string.
There are three ways to pass the subject: 1) pass a pointer to a null terminated string, 2) pass a pointer and a length, or 3) pass a const reference to std::basic_string.

To receive results, there are two ways: a) pass as an argument the reference to an instance of re_match and let exec() write matching results into it, or b) let exec() write matching results into a a new instance of re_match and return it.
In the former case, exec() returns a boolean value indicating whether any match has been found or not.

//  Pointer
bool exec(
    re_match<charT> &m,
    const charT *const str
) const;

re_match<charT> exec(
    const charT *const str
) const;

//  Pointer and length
bool exec(
    re_match<charT> &m,
    const charT *const str,
    const std::size_t len
) const;

re_match<charT> exec(
    const charT *const str,
    const std::size_t len
) const;

//  basic_string
bool exec(
    re_match<charT> &m,
    const std::basic_string<charT> &str
) const;

re_match<charT> exec(
    const std::basic_string<charT> &str
) const;
				

When the global or sticky flag is set, the search starts at the index indicated by lastIndex (i.e., the lastIndex-th element of a subject string). If a match is found, the next position of the matched substring (end of [begin,end)) is written into lastIndex. Otherwise, lastIndex is reset to 0.

When exec() is called in a loop, it is recommended to use any overload in which a reference to re_match is passed as an argument.

test() const

Behaves as exec(), except that matching results are not written into an instance of re_match. If a match is found, returns true. Otherwise returns false.

//  Pointer
bool test(
    const charT *const str
) const;

//  Pointer and length
bool test(
    const charT *const str,
    const std::size_t len
) const;

//  basic_string
bool test(
    const std::basic_string<charT> &str
) const;
				

replace() const

Behaves like String.prototype.replace(regexp-object, newSubStr|callback-function) of JavaScript.
Replaces a substring in a subject that matches regular expressions with another string. The resulting string is returned and the original string is left unchanged.

There are two ways to specify the string that replaces a matched substring: 1) pass a replacement string, or 2) pass a callback function.

When the global flag is set, all matched substrings in the subject are to be replaced. Otherwise, only the first match is to be replaced.

//  Replacement with a string
//  Pointer
std::basic_string<charT> replace(
    const charT *const str,
    const charT *const fmt
) const;

//  Pointer and length
std::basic_string<charT> replace(
    const charT *const str,
    const std::size_t len,
    const charT *const fmt_text,
    const std::size_t fmt_len
) const;

//  basic_string
std::basic_string<charT> replace(
    const std::basic_string<charT> &str,
    const std::basic_string<charT> &fmt
) const;

//  Replacement by callback function
typedef std::basic_string<charT> (*replace_function)(const re_match<charT> &);

//  Pointer
std::basic_string<charT> replace(
    const charT *const str,
    const replace_function repfunc
) const;

//  Pointer and length
std::basic_string<charT> replace(
    const charT *str,
    const std::size_t len,
    const replace_function repfunc
) const;

//  basic_string
std::basic_string<charT> replace(
    const std::basic_string<charT> &str,
    const replace_function repfunc
) const;
				

Replacement by specifying a string

The replacement string can contain the special symbols defined in the table in the ECMAScript specification, Runtime Semantics: GetSubstitution. Any character that does not exist in the table is copied as is to a new string to be returned.

Special symbols for replacement

Symbol	Inserted string as replacement
$$	$ itself.
$&	The entire matched substring.
$`	The substring that precedes the matched substring.
$'	The substring that follows the matched substring.
$n where n is one of 1 2 3 4 5 6 7 8 9 not followed by a digit.	The substring captured by the pair of nth round bracket (1-based index) in the regular expressions. Replaced with an empty string if nothing is captured. Not replaced if the number n is greater than the number of capturing brackets in the regular expressions.
$nn where nn is any value in the range 01 to 99 inclusive	The substring captured by the pair of nnth round bracket (1-based index) in the regular expressions. Replaced with an empty string if nothing is captured. Not replaced if the number nn is greater than the number of capturing brackets in the regular expressions.
$<NAME>	If any named group does not exist in the regular expressions, replacement does not happen. Otherwise, replaced with the substring captured by the pair of round brackets whose group name is NAME. If any capturing group whose name is NAME does not exist or nothing is capture by that group, replaced with an empty string.

//  Sample of replacement with a string.
#include <cstdio>
#include <string>
#include "nire.hpp"

int main()
{
    const nire::RegExp re("(\\d)(\\d)", "g");   //  Searches for two consecutive digits.
    const std::string rep = re.replace("abc0123456789def", "($2$1)");
        //  Exchanges the order of $1 and $2 and encloses them with a pair of brackets.

    std::printf("Result: %s\n", rep.c_str());
    return 0;
}
---- output ----
Result: abc(10)(32)(54)(76)(98)def
					

Replacement by callback function

When a match is found, the passed callback function is called with the argument that is a const reference to an internal instance of re_match<charT> into which matching results have been written.
The callback function has to return a new string of the std::basic_string<charT> type. Special symbols mentioned above do not apply in this case.

//  Sample of replacement by callback function.
#include <cstdio>
#include <string>
#include "nire.hpp"

std::string repfunc1(const nire::Match &m)
{
    return " [" + m[1].str() + ", " + m[2].str() + "] ";
}

int main()
{
    const nire::RegExp re("(\\d)(\\d)", "g");
    const std::string text("abc0123456789def");
    std::string rep;

    rep = re.replace(text, repfunc1);
    std::printf("Result1(C++98/C++03): %s\n", rep.c_str());

    //  Replacement by lambda of C++11 and later.
    rep = re.replace(text, [](const nire::Match &m) -> std::string {
        return " [" + m[1].str() + ", " + m[2].str() + "] ";
    });
    std::printf("Result2(C++11): %s\n", rep.c_str());

    //  C++14 and later.
    rep = re.replace(text, [](const auto &m) {
        return " [" + m[1].str() + ", " + m[2].str() + "] ";
    });
    std::printf("Result3(C++14): %s\n", rep.c_str());

    return 0;
}
---- output ----
Result1(C++98/C++03): abc [0, 1]  [2, 3]  [4, 5]  [6, 7]  [8, 9] def
Result2(C++11): abc [0, 1]  [2, 3]  [4, 5]  [6, 7]  [8, 9] def
Result3(C++14): abc [0, 1]  [2, 3]  [4, 5]  [6, 7]  [8, 9] def
					

split() const

Behaves like String.prototype.split(regexp-object, limit) of JavaScript.
Splits a string by the occurences that match regular expressions into new instances of std::basic_string and return a container that holds them. If regular expressions contain capturing round brackets, the substrings captured by them are also pushed into the resulting array. When a pair of round brackets does not capture anything, an empty string is pushed instead of skipping pushing.

Any container type can be used to receive results if it has at least clear(), size(), push_back() member functions. The returned value is the number of times push_back() was called.

//  Pointer
template <typename ContainerT>
std::size_t split(
    ContainerT &out,
    const charT *const str,
    const std::size_t limit = static_cast<std::size_t>(-1),
    const bool push_remainder = false
) const;

//  Pointer and length (length comes before pointer for overload resolution)
template <typename ContainerT>
std::size_t split(
    ContainerT &out,
    const std::size_t len,
    const charT *const str,
    const std::size_t limit = static_cast<std::size_t>(-1),
    const bool push_remainder = false
) const;

//  basic_string
template <typename ContainerT>
std::size_t split(
    ContainerT &out,
    const std::basic_string<charT> &str,
    const std::size_t limit = static_cast<std::size_t>(-1),
    const bool push_remainder = false
) const;
				

limit specifies the maximum number of times splitting is performed. For example, given that the specified pattern is /,/ and limit is 5, splitting is finished when the fifth ',' is found in the subject string.

Although the feature of specifying a maximum number like this limit is not rare in script languages, in the case of JavaScript, oddly, when the number of times splitting is executed reaches limit, split() throws away the remainder portion that has not scanned yet and does not push it to the container to be returned.
As I am personally unhappy with this behaviour, the push_remainder flag has been added to NIRE's split() as an extension. When push_remainder is true, the returned container has limit + 1 elements at most. As a result, this behaviour is similar to Python's split().

//  Behaviours of limit and push_remainder.
#include <cstdio>
#include <string>
#include <vector>
#include "nire.hpp"

int main()
{
    const nire::RegExp re(":");
    const std::string text("0:12:345:6789:abcdef");
    std::vector<std::string> res;

    //  Splitting unlimitedly.
    re.split(res, text);
    for (std::size_t i = 0; i < res.size(); ++i)
        std::printf("%s%s", i == 0 ? "[" : ", ", res[i].c_str());
    std::puts("]");

    //  limit=2. Remainder is thrown away.
    re.split(res, text, 2);
    for (std::size_t i = 0; i < res.size(); ++i)
        std::printf("%s%s", i == 0 ? "[" : ", ", res[i].c_str());
    std::puts("]");

    //  limit=2 and push_remainder=true. Remainder is all pushed as the final element.
    re.split(res, text, 2, true);
    for (std::size_t i = 0; i < res.size(); ++i)
        std::printf("%s%s", i == 0 ? "[" : ", ", res[i].c_str());
    std::puts("]");

    return 0;
}
---- output ----
[0, 12, 345, 6789, abcdef]
[0, 12]
[0, 12, 345:6789:abcdef]
				

swap()

Swaps the contents of two instances. re1.swap(re2) and nire::swap(re1, re2) are defined.

Flag functions

The following member functions return a boolean value indicating whether a specific flag was set when regular expressions were passed to compile. They have been named after the property names in JavaScript.

List of flag functions

Name	Return Value
std::basic_string<charT> flags();	Stringified flags that were passed to the pattern compiler.
bool global();	Whether nire::flag::global or "g" was set.
bool ignoreCase();	Whether nire::flag::icase or "i" was set.
bool multiline();	Whether nire::flag::multiline or "m" was set.
bool dotAll();	Whether nire::flag::dotall or "s" was set.
bool unicode();	Returns true always.
bool sticky();	Whether nire::flag::sticky or "y" was set.

re_match<charT>

Receives matching results. This class has been designed based on the return value of RegExp.exec() of JavaScript.

Cast to bool

An instance of re_match can be converted to a boolean value.

std::size_t length() const
std::size_t size() const

When the instance has successful matching results, returns one plus the number of pairs of capturing brackets in the regular expressions. Otherwise (including the case that the instance has not received any matching results after it was created) returns 0. The reason of "plus one" is because the entire match is treated as captured by the implicit 0th pair of brackets.

For getting the number of elements, .size() is a common member function name in C++ classes, whereas using the .length property is common in JavaScript. In NIRE both size() and length() are provided so that either one can be used.

const re_group<charT> &operator[](unsigned int n) const
const re_group<charT> &operator[](const charT *gname) const
const re_group<charT> &operator[](const std::basic_string<charT> &gname) const

Given that an instance of re_match is m, m[0] returns a pair of indices that represent [begin, end) of the entire match in a subject. m[n] where n >= 1 returns a pair of indices [begin, end) of a substring captured by the n-th (1-based index) pair of round brackets.
An argument n must be any value in the range from 0 to length() - 1 inclusive.

Overloads that take as a parameter a pointer or string return a pair of indices that represent [begin, end] of the substring captured by the group named as gname.

As the type of the return value, re_group<charT> can be cast to std::basic_string<charT>, it is possible to receive the matched substring directly instead of indices information. The details of this type is explained in a later section.

std::size_t index(unsigned int n = 0) const
std::size_t index(const charT *gname) const
std::size_t index(const std::basic_string<charT> &gname) const

Returns the 0-based index value of the first element of the entire match (when the argument is omitted or n is 0) or of a substring captured by the pair of the corresponding round brackets (otherwise).

std::size_t endIndex(unsigned int n = 0) const
std::size_t endIndex(const charT *gname) const
std::size_t endIndex(const std::basic_string<charT> &gname) const

Returns the 0-based index value of the next element of the entire match (when the argument is omitted or n is 0) or of a substring captured by the pair of the corresponding round brackets (otherwise).

swap()

Swaps the contents of two instances. re1.swap(re2) and nire::swap(re1, re2) are defined.

re_group<charT>

This struct holds a pair of 0-based indices indicating the range [begin, end) of an entire match or substring set by any member function of NIRE. This type is is_trivially_copyable. You can safely do memcpy.
As this class holds indices only, to get actually the contents of a matched or captured substring, the original subject string has to still exist at that time.

This class has the following members:

Cast to bool

An instance of re_group can be converted to a boolean value indicating whether the instance has valid indices.

Cast to std::basic_string<charT>
std::basic_string<charT> str() const

Creates a new instance of std::basic_string<charT> that contains a matched or captured substring based on the internal indices and returns it.

std::size_t length() const
std::size_t size() const

Returns the length of the range held by the instance. If the instance does not have any valid range, 0 is returned.

Like re_match, re_group has both size() and length().

matched() const

Returns a boolean value indicating whether the instance has valid indices.

Comparison operators

For comparison between two instances of re_group<charT> or with a instance of std::basic_string<charT>, there are ==, !=, <, <=, >, >=.

re_error

When regular expressions are compiled or a search is executed, if any error occurs, nire::re_error is thrown.
nire::re_error is a derived class from std::runtime_error and has the following members:

//  nire::re_error's members.
const char *what() const;       //  Derived from std::runtime_error.
re_error::type code() const;    //  Returns an error code.
		

The list of error codes is as follows:

Additionally, std::bad_alloc is thrown when memory allocation fails.

RegExp of ECMAScript

• ECMAScript Specification, RegExp (Regular Expression) Objects
• ECMAScript 2016+ compatibility table

• Proposal to add support for sequence properties in Unicode property escapes to ECMAScript regular expressions
  Issue #10: Using something other than `\p{…}`, e.g. `\m{…}`?
• ECMAScript RegExp Match Indices