rregex 1.10.1 → 1.10.2

package/lib/commonjs.js

@@ -181,6 +181,43 @@ function handleError(f, args) {
 }
 /**
 * A compiled regular expression for matching Unicode strings.
+*
+* A `RRegex` can be used to search haystacks, split haystacks into substrings
+* or replace substrings in a haystack with a different substring. All
+* searching is done with an implicit `(?s:.)*?` at the beginning and end of
+* an pattern. To force an expression to match the whole string (or a prefix
+* or a suffix), you must use an anchor like `^` or `$` (or `\A` and `\z`).
+*
+* While this library will handle Unicode strings (whether in the regular
+* expression or in the haystack), all positions returned are **byte
+* offsets**. Every byte offset is guaranteed to be at a Unicode code point
+* boundary. That is, all offsets returned by the `RRegex` API are guaranteed
+* to be ranges that can slice an `Uint8Array` created with a TextEncoder.
+*
+* # Example: slicing over UTF strings
+*
+* ```typescript
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("ä")
+* const m = re.find("äöü") // { start: 0, end: 2 }
+*
+* const buff = new TextEncoder().encode("äöü")
+* const slice = buff.slice(m.start, m.end)
+* expect(new TextDecoder().decode(slice)).toBe("ä")
+* ```
+*
+* # Example: find the offsets of a US phone number:
+*
+* ```typescript
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("[0-9]{3}-[0-9]{3}-[0-9]{4}");
+* const m = re.find("phone: 111-222-3333");
+* expect(m.start).toBe(7);
+* expect(m.end).toBe(19);
+* ```
+*
 * @see https://docs.rs/regex/latest/regex/
 */
 class RRegex {
@@ -235,6 +272,8 @@ class RRegex {
     * Unicode word characters:
     *
     * ```typescript
+    * import { RRegex } from "rregex"
+    *
     * const text = "I categorically deny having triskaidekaphobia."
     * expect(new RRegex("\\b\\w{13}\\b").is_match(text)).toBe(true)
     * ```
@@ -280,8 +319,10 @@ class RRegex {
     * Unicode word characters:
     *
     * ```typescript
+    * import { RRegex } from "rregex"
+    *
     * const text = "I categorically deny having triskaidekaphobia."
-    * const m = new Regex("\\b\\w{13}\\b").find(text)
+    * const m = new RRegex("\\b\\w{13}\\b").find(text)
     * expect(m.start).toBe(2)
     * expect(m.end).toBe(15)
     * ```
@@ -347,8 +388,10 @@ class RRegex {
     * word characters:
     *
     * ```typescript
+    * import { RRegex } from "rregex"
+    *
     * const text = "Retroactively relinquishing remunerations is reprehensible."
-    * const matches = new Regex("\\b\\w{13}\\b").findAll(text)
+    * const matches = new RRegex("\\b\\w{13}\\b").findAll(text)
     * ```
     *
     * @see https://docs.rs/regex/latest/regex/struct.Regex.html#method.find_iter
@@ -407,7 +450,9 @@ class RRegex {
     * year separately.
     *
     * ```typescript
-    * const re = new Regex("'([^']+)'\\s+\\((\\d{4})\)")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex("'([^']+)'\\s+\\((\\d{4})\)")
     * const text = "Not my favorite movie: 'Citizen Kane' (1941)."
     * const caps = re.captures(text)
     * expect(caps.get[1].value).toBe("Citizen Kane")
@@ -421,7 +466,9 @@ class RRegex {
     * We can make this example a bit clearer by using *named* capture groups:
     *
     * ```typescript
-    * const re = new Regex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\)")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\)")
     * const text = "Not my favorite movie: 'Citizen Kane' (1941)."
     * const caps = re.captures(text)
     * expect(caps.name["title"].value).toBe("Citizen Kane")
@@ -461,7 +508,9 @@ class RRegex {
     * some text, where the movie is formatted like "'Title' (xxxx)":
     *
     * ```typescript
-    * const re = new Regex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\\)")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\\)")
     * const text = "'Citizen Kane' (1941), 'The Wizard of Oz' (1939), 'M' (1931)."
     * for caps of re.captures_iter(text) {
     *     console.log(
@@ -508,6 +557,8 @@ class RRegex {
     * ## Example
     *
     * ```typescript
+    *  import { RRegex } from "rregex"
+    *
     *  const re1 = new RRegex("(?P<y>\\d{4})-(?P<m>\\d{2})-(?P<d>\\d{2})")
     *  expect(re1.capturesLength()).toEqual(4)
     *
@@ -564,7 +615,9 @@ class RRegex {
     * In typical usage, this can just be a normal string:
     *
     * ```typescript
-    * const re = new Regex("[^01]+")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex("[^01]+")
     * expect(re.replace("1078910", "").toBe("1010")
     * ```
     *
@@ -572,7 +625,9 @@ class RRegex {
     * groups:
     *
     * ```typescript
-    * const re = new Regex("(?P<last>[^,\\s]+),\\s+(?P<first>\\S+)")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex("(?P<last>[^,\\s]+),\\s+(?P<first>\\S+)")
     * const result = re.replace("Springsteen, Bruce", "$first $last")
     * expect(result).toBe("Bruce Springsteen")
     * ```
@@ -586,7 +641,9 @@ class RRegex {
     * underscore:
     *
     * ```typescript
-    * const re = new Regex("(?P<first>\\w+)\\s+(?P<second>\\w+)")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex("(?P<first>\\w+)\\s+(?P<second>\\w+)")
     * const result = re.replace("deep fried", "${first}_$second")
     * expect(result).toBe("deep_fried")
     * ```
@@ -700,7 +757,9 @@ class RRegex {
     * To split a string delimited by arbitrary amounts of spaces or tabs:
     *
     * ```typescript
-    * const re = new Regex(r"[ \\t]+")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex(r"[ \\t]+")
     * const fields = re.split("a b \t  c\td    e")
     * expect(fields).toEqual(["a", "b", "c", "d", "e"])
     * ```
@@ -738,7 +797,9 @@ class RRegex {
     * Get the first two words in some text:
     *
     * ```typescript
-    * const re = new Regex(r"\\W+")
+    * import { RRegex } from "rregex"
+    *
+    * const re = new RRegex(r"\\W+")
     * const fields = re.splitn("Hey! How are you?", 3)
     * expect(fields).toEqual(["Hey", "How", "are you?"])
     * ```
@@ -784,8 +845,10 @@ class RRegex {
     * `a`.
     *
     * ```typescript
+    * import { RRegex } from "rregex"
+    *
     * const text = "aaaaa"
-    * const = new Regex("a+").shortest_match(text)
+    * const = new RRegex("a+").shortest_match(text)
     * expect(pos).toBe(1)
     * ```
     *
@@ -909,6 +972,8 @@ class RRegexSet {
     * Create a new regex set from an iterator of strings:
     *
     * ```typescript
+    * import { RegexSet } from "rregex"
+    *
     * const set = new RegexSet(["\\w+", "\\d+"])
     * expect(set.is_match("foo")).toBe(true)
     * ```
@@ -951,6 +1016,8 @@ class RRegexSet {
     * Tests whether a set matches some text:
     *
     * ```typescript
+    * import { RegexSet } from "rregex"
+    *
     * const set = new RegexSet(["\\w+", "\\d+"])
     * expect(set.is_match("foo")).toBe(true)
     * expect(!set.is_match("☃")).toBe(false)
@@ -985,6 +1052,8 @@ class RRegexSet {
     * Tests which regular expressions match the given text:
     *
     * ```typescript
+    * import { RegexSet } from "rregex"
+    *
     * const set = new RegexSet([
     *     "\\w+",
     *     "\\d+",

package/lib/module.d.ts

@@ -11,6 +11,50 @@
 export function escape(text: string): string;
 /**
  * Represents a single match of a regex in a haystack.
+ *
+ * A `Match` contains both the start and end byte offsets of the match and the
+ * actual substring corresponding to the range of those byte offsets. It is
+ * guaranteed that `start <= end`. When `start == end`, the match is empty.
+ *
+ * Since this `Match` can only be produced by the top-level `Regex` APIs
+ * that only support searching UTF-8 encoded strings, the byte offsets for a
+ * `Match` are guaranteed to fall on valid UTF-8 codepoint boundaries. That
+ * is, slicing an `Uint8Array` created with a TextEncoder is guaranteed to never
+ * be out of range.
+ *
+ * # Numbering
+ *
+ * The byte offsets in a `Match` form a half-open interval. That is, the
+ * start of the range is inclusive and the end of the range is exclusive.
+ * For example, given a haystack `abcFOOxyz` and a match of `FOO`, its byte
+ * offset range starts at `3` and ends at `6`. `3` corresponds to `F` and
+ * `6` corresponds to `x`, which is one past the end of the match. This
+ * corresponds to the same kind of slicing that Rust uses.
+ *
+ * For more on why this was chosen over other schemes (aside from being
+ * consistent with how Rust the language works), see [this discussion] and
+ * [Dijkstra's note on a related topic][note].
+ *
+ * [this discussion]: https://github.com/rust-lang/regex/discussions/866
+ * [note]: https://www.cs.utexas.edu/users/EWD/transcriptions/EWD08xx/EWD831.html
+ *
+ * # Example
+ *
+ * This example shows the value of each of the methods on `Match` for a
+ * particular search.
+ *
+ * ```typescript
+ * import { RRegex } from "rregex"
+ *
+ * const re = new RRegex("\\p{Greek}+");
+ * const hay = "Greek: αβγδ";
+ * const m = re.find(hay);
+ * expect(m.start).toBe(7);
+ * expect(m.end).toBe(15);
+ * expect(m.value).toBe("αβγδ");
+ * ```
+ *
+ * @see  @see https://docs.rs/regex/latest/regex/
  */
 export type Match = {
   start: number
@@ -19,14 +63,47 @@ export type Match = {
 }
 
 /**
- * Captures represents a group of captured strings for a single match.
+ * Represents the capture groups for a single match.
+ *
+ * Capture groups refer to parts of a regex enclosed in parentheses. They can
+ * be optionally named. The purpose of capture groups is to be able to
+ * reference different parts of a match based on the original pattern. For
+ * example, say you want to match the individual letters in a 5-letter word:
  *
- * The 0th capture always corresponds to the entire match. Each subsequent index
- * corresponds to the next capture group in the regex. If a capture group is named,
- * then the matched string is also available via the name property. (Note that the
- * 0th capture is always unnamed and so must be accessed with the get property.)
+ * ```text
+ * (?<first>\w)(\w)(?:\w)\w(?<last>\w)
+ * ```
  *
- * Positions returned from a capture group are always byte indices.
+ * This regex has 4 capture groups:
+ *
+ * * The group at index `0` corresponds to the overall match. It is always
+ * present in every match and never has a name.
+ * * The group at index `1` with name `first` corresponding to the first
+ * letter.
+ * * The group at index `2` with no name corresponding to the second letter.
+ * * The group at index `3` with name `last` corresponding to the fifth and
+ * last letter.
+ *
+ * Notice that `(?:\w)` was not listed above as a capture group despite it
+ * being enclosed in parentheses. That's because `(?:pattern)` is a special
+ * syntax that permits grouping but *without* capturing. The reason for not
+ * treating it as a capture is that tracking and reporting capture groups
+ * requires additional state that may lead to slower searches. So using as few
+ * capture groups as possible can help performance. (Although the difference
+ * in performance of a couple of capture groups is likely immaterial.)
+ *
+ * # Example
+ *
+ * ```typescript
+ * import { RRegex } from "rregex"
+ *
+ * const re = new RRegex("(?<first>\\w)(\\w)(?:\\w)\\w(?<last>\\w)");
+ * const caps = re.captures("toady");
+ * expect(caps.get[0].value).toBe("toady");
+ * expect(caps.name["first"].value).toBe("t");
+ * expect(caps.get[2].value).toBe("o");
+ * expect(caps.name["last"].value).toBe("y");
+ * ```
  */
 export type Captures = {
   get: Match[]
@@ -584,6 +661,43 @@ export type Capture = {
 
 /**
 * A compiled regular expression for matching Unicode strings.
+*
+* A `RRegex` can be used to search haystacks, split haystacks into substrings
+* or replace substrings in a haystack with a different substring. All
+* searching is done with an implicit `(?s:.)*?` at the beginning and end of
+* an pattern. To force an expression to match the whole string (or a prefix
+* or a suffix), you must use an anchor like `^` or `$` (or `\A` and `\z`).
+*
+* While this library will handle Unicode strings (whether in the regular
+* expression or in the haystack), all positions returned are **byte
+* offsets**. Every byte offset is guaranteed to be at a Unicode code point
+* boundary. That is, all offsets returned by the `RRegex` API are guaranteed
+* to be ranges that can slice an `Uint8Array` created with a TextEncoder.
+*
+* # Example: slicing over UTF strings
+*
+* ```typescript
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("ä")
+* const m = re.find("äöü") // { start: 0, end: 2 }
+*
+* const buff = new TextEncoder().encode("äöü")
+* const slice = buff.slice(m.start, m.end)
+* expect(new TextDecoder().decode(slice)).toBe("ä")
+* ```
+*
+* # Example: find the offsets of a US phone number:
+*
+* ```typescript
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("[0-9]{3}-[0-9]{3}-[0-9]{4}");
+* const m = re.find("phone: 111-222-3333");
+* expect(m.start).toBe(7);
+* expect(m.end).toBe(19);
+* ```
+*
 * @see https://docs.rs/regex/latest/regex/
 */
 export class RRegex {
@@ -610,6 +724,8 @@ export class RRegex {
 * Unicode word characters:
 *
 * ```typescript
+* import { RRegex } from "rregex"
+*
 * const text = "I categorically deny having triskaidekaphobia."
 * expect(new RRegex("\\b\\w{13}\\b").is_match(text)).toBe(true)
 * ```
@@ -645,8 +761,10 @@ export class RRegex {
 * Unicode word characters:
 *
 * ```typescript
+* import { RRegex } from "rregex"
+*
 * const text = "I categorically deny having triskaidekaphobia."
-* const m = new Regex("\\b\\w{13}\\b").find(text)
+* const m = new RRegex("\\b\\w{13}\\b").find(text)
 * expect(m.start).toBe(2)
 * expect(m.end).toBe(15)
 * ```
@@ -680,8 +798,10 @@ export class RRegex {
 * word characters:
 *
 * ```typescript
+* import { RRegex } from "rregex"
+*
 * const text = "Retroactively relinquishing remunerations is reprehensible."
-* const matches = new Regex("\\b\\w{13}\\b").findAll(text)
+* const matches = new RRegex("\\b\\w{13}\\b").findAll(text)
 * ```
 *
 * @see https://docs.rs/regex/latest/regex/struct.Regex.html#method.find_iter
@@ -712,7 +832,9 @@ export class RRegex {
 * year separately.
 *
 * ```typescript
-* const re = new Regex("'([^']+)'\\s+\\((\\d{4})\)")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("'([^']+)'\\s+\\((\\d{4})\)")
 * const text = "Not my favorite movie: 'Citizen Kane' (1941)."
 * const caps = re.captures(text)
 * expect(caps.get[1].value).toBe("Citizen Kane")
@@ -726,7 +848,9 @@ export class RRegex {
 * We can make this example a bit clearer by using *named* capture groups:
 *
 * ```typescript
-* const re = new Regex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\)")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\)")
 * const text = "Not my favorite movie: 'Citizen Kane' (1941)."
 * const caps = re.captures(text)
 * expect(caps.name["title"].value).toBe("Citizen Kane")
@@ -750,7 +874,9 @@ export class RRegex {
 * some text, where the movie is formatted like "'Title' (xxxx)":
 *
 * ```typescript
-* const re = new Regex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\\)")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("'(?P<title>[^']+)'\\s+\\((?P<year>\\d{4})\\)")
 * const text = "'Citizen Kane' (1941), 'The Wizard of Oz' (1939), 'M' (1931)."
 * for caps of re.captures_iter(text) {
 *     console.log(
@@ -781,6 +907,8 @@ export class RRegex {
 * ## Example
 *
 * ```typescript
+*  import { RRegex } from "rregex"
+*
 *  const re1 = new RRegex("(?P<y>\\d{4})-(?P<m>\\d{2})-(?P<d>\\d{2})")
 *  expect(re1.capturesLength()).toEqual(4)
 *
@@ -834,7 +962,9 @@ export class RRegex {
 * In typical usage, this can just be a normal string:
 *
 * ```typescript
-* const re = new Regex("[^01]+")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("[^01]+")
 * expect(re.replace("1078910", "").toBe("1010")
 * ```
 *
@@ -842,7 +972,9 @@ export class RRegex {
 * groups:
 *
 * ```typescript
-* const re = new Regex("(?P<last>[^,\\s]+),\\s+(?P<first>\\S+)")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("(?P<last>[^,\\s]+),\\s+(?P<first>\\S+)")
 * const result = re.replace("Springsteen, Bruce", "$first $last")
 * expect(result).toBe("Bruce Springsteen")
 * ```
@@ -856,7 +988,9 @@ export class RRegex {
 * underscore:
 *
 * ```typescript
-* const re = new Regex("(?P<first>\\w+)\\s+(?P<second>\\w+)")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex("(?P<first>\\w+)\\s+(?P<second>\\w+)")
 * const result = re.replace("deep fried", "${first}_$second")
 * expect(result).toBe("deep_fried")
 * ```
@@ -913,7 +1047,9 @@ export class RRegex {
 * To split a string delimited by arbitrary amounts of spaces or tabs:
 *
 * ```typescript
-* const re = new Regex(r"[ \\t]+")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex(r"[ \\t]+")
 * const fields = re.split("a b \t  c\td    e")
 * expect(fields).toEqual(["a", "b", "c", "d", "e"])
 * ```
@@ -937,7 +1073,9 @@ export class RRegex {
 * Get the first two words in some text:
 *
 * ```typescript
-* const re = new Regex(r"\\W+")
+* import { RRegex } from "rregex"
+*
+* const re = new RRegex(r"\\W+")
 * const fields = re.splitn("Hey! How are you?", 3)
 * expect(fields).toEqual(["Hey", "How", "are you?"])
 * ```
@@ -969,8 +1107,10 @@ export class RRegex {
 * `a`.
 *
 * ```typescript
+* import { RRegex } from "rregex"
+*
 * const text = "aaaaa"
-* const = new Regex("a+").shortest_match(text)
+* const = new RRegex("a+").shortest_match(text)
 * expect(pos).toBe(1)
 * ```
 *
@@ -1029,6 +1169,8 @@ export class RRegexSet {
 * Create a new regex set from an iterator of strings:
 *
 * ```typescript
+* import { RegexSet } from "rregex"
+*
 * const set = new RegexSet(["\\w+", "\\d+"])
 * expect(set.is_match("foo")).toBe(true)
 * ```
@@ -1055,6 +1197,8 @@ export class RRegexSet {
 * Tests whether a set matches some text:
 *
 * ```typescript
+* import { RegexSet } from "rregex"
+*
 * const set = new RegexSet(["\\w+", "\\d+"])
 * expect(set.is_match("foo")).toBe(true)
 * expect(!set.is_match("☃")).toBe(false)
@@ -1084,6 +1228,8 @@ export class RRegexSet {
 * Tests which regular expressions match the given text:
 *
 * ```typescript
+* import { RegexSet } from "rregex"
+*
 * const set = new RegexSet([
 *     "\\w+",
 *     "\\d+",