What is re2?
The re2 npm package is a wrapper around Google's RE2 regular expression library, which is designed to be fast and safe. It provides a way to perform regular expression operations without the risk of catastrophic backtracking, which can occur with some other regular expression engines.
What are re2's main functionalities?
Basic Matching
This feature allows you to perform basic matching operations using regular expressions. The code sample demonstrates how to create a new RE2 instance with a pattern and test a string against it.
const RE2 = require('re2');
const re = new RE2('hello');
console.log(re.test('hello world')); // true
Capturing Groups
This feature allows you to use capturing groups in your regular expressions. The code sample shows how to capture groups of digits separated by a hyphen and access the captured groups.
const RE2 = require('re2');
const re = new RE2('(\d+)-(\d+)');
const match = re.exec('123-456');
console.log(match[1]); // 123
console.log(match[2]); // 456
Global Matching
This feature allows you to perform global matching to find all occurrences of a pattern in a string. The code sample demonstrates how to find all sequences of digits in a string.
const RE2 = require('re2');
const re = new RE2('\d+', 'g');
const matches = '123 456 789'.match(re);
console.log(matches); // ['123', '456', '789']
Replacing
This feature allows you to replace parts of a string that match a pattern with a replacement string. The code sample shows how to replace 'world' with 'RE2' in a given string.
const RE2 = require('re2');
const re = new RE2('world');
const result = 'hello world'.replace(re, 'RE2');
console.log(result); // 'hello RE2'
Other packages similar to re2
regexp
The 'regexp' package provides a simple interface for working with regular expressions in JavaScript. It is similar to re2 but does not offer the same level of performance and safety guarantees against catastrophic backtracking.
xregexp
The 'xregexp' package extends JavaScript's native RegExp with additional features and syntax. It offers more functionality than re2 but may not be as performant or safe in terms of avoiding catastrophic backtracking.
pcre-to-regexp
The 'pcre-to-regexp' package allows you to convert Perl-compatible regular expressions (PCRE) to JavaScript RegExp objects. While it provides compatibility with PCRE syntax, it does not offer the same performance and safety benefits as re2.
node-re2
This project provides bindings for RE2:
fast, safe alternative to backtracking regular expression engines written by Russ Cox.
To learn more about RE2, start with an overview
Regular Expression Matching in the Wild. More resources can be found
at his Implementing Regular Expressions page.
RE2's regular expression language is almost a superset of what is provided by RegExp
(see Syntax),
but it lacks one feature: backreferences. See below for more details.
RE2
object emulates standard RegExp
making it a practical drop-in replacement in most cases.
RE2
is extended to provide String
-based regular expression methods as well. To help converting
RegExp
objects to RE2
its constructor can take RegExp
directly honoring all properties.
It can work with node.js buffers directly reducing overhead
on recoding and copying characters, and making processing/parsing long files fast.
Standard features
RE2
object can be created just like RegExp
:
Supported properties:
Supported methods:
Extensions
Shortcut construction
RE2
object can be created from a regular expression:
var re1 = new RE2(/ab*/ig);
var re2 = new RE2(re1);
String
methods
Standard String
defines four more methods that can use regular expressions. RE2
provides them as methods
exchanging positions of a string, and a regular expression:
re2.match(str)
re2.replace(str, newSubStr|function)
re2.search(str)
re2.split(str[, limit])
Buffer
support
In order to support Buffer
directly, most methods can accept buffers instead of strings. It speeds up all operations.
Following signatures are supported:
re2.exec(buf)
re2.test(buf)
re2.match(buf)
re2.search(buf)
re2.split(buf[, limit])
re2.replace(buf, replacer)
Differences with their string-based versions:
- All buffers are assumed to be encoded as UTF-8
(ASCII is a proper subset of UTF-8).
- Instead of strings they return
Buffer
objects, even in composite objects. A buffer can be converted to a string with
buf.toString()
. - All offsets and lengths are in bytes, rather than characters (each UTF-8 character can occupy from 1 to 4 bytes).
This way users can properly slice buffers without costly recalculations from characters to bytes.
When re2.replace()
is used with a replacer function, the replacer can return a buffer, or a string. But all arguments
(except for an input object) will be strings, and an offset will be in characters. If you prefer to deal
with buffers and byte offsets in a replacer function, set a property useBuffers
to true
on the function:
function strReplacer(match, offset, input) {
return "<= " + offset + " characters|";
}
RE2("б").replace("абв", strReplacer);
function bufReplacer(match, offset, input) {
return "<= " + offset + " bytes|";
}
bufReplacer.useBuffers = true;
RE2("б").replace("абв", bufReplacer);
This feature works for string and buffer inputs. If a buffer was used as an input, its output will be returned as
a buffer too, otherwise a string will be returned.
Calculate length
Two functions to calculate string sizes between
UTF-8 and
UTF-16 are exposed on RE2
:
RE2.getUtf8Length(str)
— calculates a buffer size in bytes to encode a UTF-16 string as
a UTF-8 buffer.RE2.getUtf16Length(buf)
— calculates a string size in characters to encode a UTF-8 buffer as
a UTF-16 string.
JavaScript supports UCS-2 strings with 16-bit characters, while node.js 0.11 supports full UTF-16 as
a default string.
How to install
Installation:
npm install re2
How to use
It is used just like a RegExp
object.
var RE2 = require("re2");
var re = new RE2("a(b*)");
var result = re.exec("abbc");
console.log(result[0]);
console.log(result[1]);
result = re.exec("aBbC");
console.log(result[0]);
console.log(result[1]);
re = new RE2("a(b*)", "i");
result = re.exec("aBbC");
console.log(result[0]);
console.log(result[1]);
var regexp = new RegExp("a(b*)", "i");
re = new RE2(regexp);
result = re.exec("aBbC");
console.log(result[0]);
console.log(result[1]);
re = new RE2(/a(b*)/i);
result = re.exec("aBbC");
console.log(result[0]);
console.log(result[1]);
var rex = new RE2(re);
result = rex.exec("aBbC");
console.log(result[0]);
console.log(result[1]);
result = new RE2("ab*").exec("abba");
result = RE2("ab*").exec("abba");
Backreferences
Unlike RegExp
, RE2
doesn't support backreferences, which are numbered references to previously
matched groups, like so: \1
, \2
, and so on. Example of backrefrences:
/(cat|dog)\1/.test("catcat");
/(cat|dog)\1/.test("dogdog");
/(cat|dog)\1/.test("catdog");
/(cat|dog)\1/.test("dogcat");
If your application uses this kind of matching, you should continue to use RegExp
.
Release history
- 1.4.0 Use re2 as a git submodule. Thx Ben James!
- 1.3.3 Refreshed dependencies.
- 1.3.2 Updated references in README (re2 was moved to github).
- 1.3.1 Refreshed dependencies, new Travis-CI config.
- 1.3.0 Upgraded NAN to 1.6.3, now we support node.js 0.10.36, 0.12.0, and io.js 1.3.0. Thx @reid!
- 1.2.0 Documented getUtfXLength() functions. Added support for
\c
and \u
commands. - 1.1.1 Minor corrections in README.
- 1.1.0 Buffer-based API is public. Unicode is fully supported.
- 1.0.0 Implemented all
RegExp
methods, and all relevant String
methods. - 0.9.0 The initial public release.
License
BSD