docs/source/RegExp.html

   1 <!DOCTYPE html>
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   5   <title>The source code</title>
   6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   8   <style type="text/css">
   9     .highlight { display: block; background-color: #ddd; }
  10   </style>
  11   <script type="text/javascript">
  12     function highlight() {
  13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
  14     }
  15   </script>
  16 </head>
  17 <body onload="prettyPrint(); highlight();">
  18   <pre class="prettyprint lang-js"><span id='RegExp'>/**
  19 </span> * @class RegExp
  20  *
  21  * Creates a regular expression object for matching text according to a pattern.
  22  *
  23  * When using the constructor function, the normal string escape rules (preceding
  24  * special characters with \ when included in a string) are necessary. For
  25  * example, the following are equivalent:
  26  *
  27  *     var re = new RegExp(&quot;\\w+&quot;);
  28  *     var re = /\w+/;
  29  *
  30  * Notice that the parameters to the literal format do not use quotation marks to
  31  * indicate strings, while the parameters to the constructor function do use
  32  * quotation marks. So the following expressions create the same regular
  33  * expression:
  34  *
  35  *     /ab+c/i;
  36  *     new RegExp(&quot;ab+c&quot;, &quot;i&quot;);
  37  *
  38  * # Special characters in regular expressions
  39  *
  40  * |     Character    | Meaning
  41  * |:-----------------|:--------------------------------------------------------------------------------------
  42  * | `\`              | For characters that are usually treated literally, indicates that the next character
  43  * |                  | is special and not to be interpreted literally.
  44  * |                  | For example, `/b/` matches the character 'b'. By placing a backslash in front of b, that
  45  * |                  | is by using `/\b/`, the character becomes special to mean match a word boundary.
  46  * |                  |
  47  * |                  | _or_
  48  * |                  |
  49  * |                  | For characters that are usually treated specially, indicates that the next character is
  50  * |                  | not special and should be interpreted literally.
  51  * |                  |
  52  * |                  | For example, `*` is a special character that means 0 or more occurrences of the preceding
  53  * |                  | character should be matched; for example, `/a*\/` means match 0 or more &quot;a&quot;s. To match *
  54  * |                  | literally, precede it with a backslash; for example, `/a\*\/` matches 'a*'.
  55  * |                  |
  56  * | `^`              | Matches beginning of input. If the multiline flag is set to true, also matches
  57  * |                  | immediately after a line break character.
  58  * |                  |
  59  * |                  | For example, `/^A/` does not match the 'A' in &quot;an A&quot;, but does match the first 'A' in
  60  * |                  | &quot;An A&quot;.
  61  * |                  |
  62  * | `$`              | Matches end of input. If the multiline flag is set to true, also matches immediately
  63  * |                  | before a line break character.
  64  * |                  |
  65  * |                  | For example, `/t$/` does not match the 't' in &quot;eater&quot;, but does match it in &quot;eat&quot;.
  66  * |                  |
  67  * | `*`              | Matches the preceding item 0 or more times.
  68  * |                  |
  69  * |                  | For example, `/bo*\/` matches 'boooo' in &quot;A ghost booooed&quot; and 'b' in &quot;A bird warbled&quot;,
  70  * |                  | but nothing in &quot;A goat grunted&quot;.
  71  * |                  |
  72  * | `+`              | Matches the preceding item 1 or more times. Equivalent to `{1,}`.
  73  * |                  |
  74  * |                  | For example, `/a+/` matches the 'a' in &quot;candy&quot; and all the a's in &quot;caaaaaaandy&quot;.
  75  * |                  |
  76  * | `?`              | Matches the preceding item 0 or 1 time.
  77  * |                  |
  78  * |                  | For example, `/e?le?/` matches the 'el' in &quot;angel&quot; and the 'le' in &quot;angle.&quot;
  79  * |                  |
  80  * |                  | If used immediately after any of the quantifiers `*`, `+`, `?`, or `{}`, makes the quantifier
  81  * |                  | non-greedy (matching the minimum number of times), as opposed to the default, which is
  82  * |                  | greedy (matching the maximum number of times).
  83  * |                  |
  84  * |                  | Also used in lookahead assertions, described under `(?=)`, `(?!)`, and `(?:)` in this table.
  85  * |                  |
  86  * | `.`              | (The decimal point) matches any single character except the newline characters: \n \r
  87  * |                  | \u2028 or \u2029. (`[\s\S]` can be used to match any character including new lines.)
  88  * |                  |
  89  * |                  | For example, `/.n/` matches 'an' and 'on' in &quot;nay, an apple is on the tree&quot;, but not 'nay'.
  90  * |                  |
  91  * | `(x)`            | Matches `x` and remembers the match. These are called capturing parentheses.
  92  * |                  |
  93  * |                  | For example, `/(foo)/` matches and remembers 'foo' in &quot;foo bar.&quot; The matched substring can
  94  * |                  | be recalled from the resulting array's elements `[1], ..., [n]` or from the predefined RegExp
  95  * |                  | object's properties `$1, ..., $9`.
  96  * |                  |
  97  * | `(?:x)`          | Matches `x` but does not remember the match. These are called non-capturing parentheses.
  98  * |                  | The matched substring can not be recalled from the resulting array's elements `[1], ..., [n]`
  99  * |                  | or from the predefined RegExp object's properties `$1, ..., $9`.
 100  * |                  |
 101  * | `x(?=y)`         | Matches `x` only if `x` is followed by `y`. For example, `/Jack(?=Sprat)/` matches 'Jack' only if
 102  * |                  | it is followed by 'Sprat'. `/Jack(?=Sprat|Frost)/` matches 'Jack' only if it is followed by
 103  * |                  | 'Sprat' or 'Frost'. However, neither 'Sprat' nor 'Frost' is part of the match results.
 104  * |                  |
 105  * | `x(?!y)`         | Matches `x` only if `x` is not followed by `y`. For example, `/\d+(?!\.)/` matches a number only
 106  * |                  | if it is not followed by a decimal point.
 107  * |                  |
 108  * |                  | `/\d+(?!\.)/.exec(&quot;3.141&quot;)` matches 141 but not 3.141.
 109  * |                  |
 110  * | `x|y`            | Matches either `x` or `y`.
 111  * |                  |
 112  * |                  | For example, `/green|red/` matches 'green' in &quot;green apple&quot; and 'red' in &quot;red apple.&quot;
 113  * |                  |
 114  * | `{n}`            | Where `n` is a positive integer. Matches exactly n occurrences of the preceding item.
 115  * |                  |
 116  * |                  | For example, `/a{2}/` doesn't match the 'a' in &quot;candy,&quot; but it matches all of the a's
 117  * |                  | in &quot;caandy,&quot; and the first two a's in &quot;caaandy.&quot;
 118  * |                  |
 119  * | `{n,}`           | Where `n` is a positive integer. Matches at least n occurrences of the preceding item.
 120  * |                  |
 121  * |                  | For example, `/a{2,}/` doesn't match the 'a' in &quot;candy&quot;, but matches all of the a's in
 122  * |                  | &quot;caandy&quot; and in &quot;caaaaaaandy.&quot;
 123  * |                  |
 124  * | `{n,m}`          | Where `n` and `m` are positive integers. Matches at least `n` and at most `m` occurrences of the
 125  * |                  | preceding item.
 126  * |                  |
 127  * |                  | For example, `/a{1,3}/` matches nothing in &quot;cndy&quot;, the 'a' in &quot;candy,&quot; the first two a's
 128  * |                  | in &quot;caandy,&quot; and the first three a's in &quot;caaaaaaandy&quot;. Notice that when matching
 129  * |                  | &quot;caaaaaaandy&quot;, the match is &quot;aaa&quot;, even though the original string had more a's in it.
 130  * |                  |
 131  * | `[xyz]`          | A character set. Matches any one of the enclosed characters. You can specify a range of
 132  * |                  | characters by using a hyphen.
 133  * |                  |
 134  * |                  | For example, `[abcd]` is the same as `[a-d]`. They match the 'b' in &quot;brisket&quot; and the 'c'
 135  * |                  | in &quot;chop&quot;.
 136  * |                  |
 137  * | `[^xyz]`         | A negated or complemented character set. That is, it matches anything that is not
 138  * |                  | enclosed in the brackets. You can specify a range of characters by using a hyphen.
 139  * |                  |
 140  * |                  | For example, `[^abc]` is the same as `[^a-c]`. They initially match 'r' in &quot;brisket&quot; and
 141  * |                  | 'h' in &quot;chop.&quot;
 142  * |                  |
 143  * | `[\b]`           | Matches a backspace. (Not to be confused with `\b`.)
 144  * |                  |
 145  * | `\b`             | Matches a word boundary, such as a space. (Not to be confused with `[\b]`.)
 146  * |                  |
 147  * |                  | For example, `/\bn\w/` matches the 'no' in &quot;noonday&quot;; `/\wy\b/` matches the 'ly' in
 148  * |                  | &quot;possibly yesterday.&quot;
 149  * |                  |
 150  * | `\B`             | Matches a non-word boundary.
 151  * |                  |
 152  * |                  | For example, `/\w\Bn/` matches 'on' in &quot;noonday&quot;, and `/y\B\w/` matches 'ye' in &quot;possibly
 153  * |                  | yesterday.&quot;
 154  * |                  |
 155  * | `\cX`            | Where X is a letter from A - Z. Matches a control character in a string.
 156  * |                  |
 157  * |                  | For example, `/\cM/` matches control-M in a string.
 158  * |                  |
 159  * | `\d`             | Matches a digit character in the basic Latin alphabet. Equivalent to `[0-9]`.
 160  * |                  |
 161  * |                  | For example, `/\d/` or `/[0-9]/` matches '2' in &quot;B2 is the suite number.&quot;
 162  * |                  |
 163  * | `\D`             | Matches any non-digit character in the basic Latin alphabet. Equivalent to `[^0-9]`.
 164  * |                  |
 165  * |                  | For example, `/\D/` or `/[^0-9]/` matches 'B' in &quot;B2 is the suite number.
 166  * |                  |
 167  * | `\f`             | Matches a form-feed.
 168  * |                  |
 169  * | `\n`             | Matches a linefeed.
 170  * |                  |
 171  * | `\r`             | Matches a carriage return.
 172  * |                  |
 173  * | `\s`             | Matches a single white space character, including space, tab, form feed, line feed and
 174  * |                  | other unicode spaces. Equivalent to:
 175  * |                  |
 176  * |                  | `[\t\n\v\f\r \u00a0\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u200b\u2028\u2029\u3000]`
 177  * |                  |
 178  * |                  | For example, `/\s\w*\/` matches ' bar' in &quot;foo bar.&quot;
 179  * |                  |
 180  * | `\S`             | Matches a single character other than white space. Equivalent to:
 181  * |                  |
 182  * |                  | `[^\t\n\v\f\r \u00a0\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u200b\u2028\u2029\u3000]`
 183  * |                  |
 184  * |                  | For example, `/\S\w*\/` matches 'foo' in &quot;foo bar.&quot;
 185  * |                  |
 186  * | `\t`             | Matches a tab.
 187  * |                  |
 188  * | `\v`             | Matches a vertical tab.
 189  * |                  |
 190  * | `\w`             | Matches any alphanumeric character from the basic Latin alphabet, including the
 191  * |                  | underscore. Equivalent to `[A-Za-z0-9_]`.
 192  * |                  |
 193  * |                  | For example, `/\w/` matches 'a' in &quot;apple,&quot; '5' in &quot;$5.28,&quot; and '3' in &quot;3D.&quot;
 194  * |                  |
 195  * | `\W`             | Matches any character that is not a word character from the basic Latin alphabet. Equivalent
 196  * |                  | to `[^A-Za-z0-9_]`.
 197  * |                  |
 198  * |                  | For example, `/\W/` or `/[^A-Za-z0-9_]/` matches '%' in &quot;50%.&quot;
 199  * |                  |
 200  * | `\n`             | Where `n` is a positive integer. A back reference to the last substring matching the n
 201  * |                  | parenthetical in the regular expression (counting left parentheses).
 202  * |                  |
 203  * |                  | For example, `/apple(,)\sorange\1/` matches 'apple, orange,' in &quot;apple, orange, cherry,
 204  * |                  | peach.&quot; A more complete example follows this table.
 205  * |                  |
 206  * | `\0`             | Matches a NULL character. Do not follow this with another digit.
 207  * |                  |
 208  * | `\xhh`           | Matches the character with the code `hh` (two hexadecimal digits)
 209  * |                  |
 210  * | `\uhhhh`         | Matches the character with the Unicode value `hhhh` (four hexadecimal digits)
 211  *
 212  * The literal notation provides compilation of the regular expression when the expression is evaluated. Use
 213  * literal notation when the regular expression will remain constant. For example, if you use literal notation
 214  * to construct a regular expression used in a loop, the regular expression won't be recompiled on each iteration.
 215  *
 216  * The constructor of the regular expression object, for example, new RegExp(&quot;ab+c&quot;), provides runtime
 217  * compilation of the regular expression. Use the constructor function when you know the regular expression
 218  * pattern will be changing, or you don't know the pattern and are getting it from another source, such as user input.
 219  *
 220  * &lt;div class=&quot;notice&quot;&gt;
 221  * Documentation for this class comes from &lt;a href=&quot;https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/RegExp&quot;&gt;MDN&lt;/a&gt;
 222  * and is available under &lt;a href=&quot;http://creativecommons.org/licenses/by-sa/2.0/&quot;&gt;Creative Commons: Attribution-Sharealike license&lt;/a&gt;.
 223  * &lt;/div&gt;
 224  */
 225
 226 <span id='RegExp-method-constructor'>/**
 227 </span> * @method constructor
 228  * Creates new regular expression object.
 229  *
 230  * @param {String} pattern
 231  * The text of the regular expression.
 232  * @param {String} flags
 233  * If specified, flags can have any combination of the following values:
 234  *
 235  * - &quot;g&quot; - global match
 236  * - &quot;i&quot; - ignore case
 237  * - &quot;m&quot; - Treat beginning and end characters (^ and $) as working over multiple lines
 238  *   (i.e., match the beginning or end of _each_ line (delimited by \n or \r), not
 239  *   only the very beginning or end of the whole input string)
 240  */
 241
 242 //Methods
 243
 244 <span id='RegExp-method-exec'>/**
 245 </span> * @method exec
 246  * Executes a search for a match in its string parameter.
 247  *
 248  * If the match succeeds, the `exec` method returns an array and updates properties of the regular
 249  * expression object. The returned array has the matched text as the first item, and then one item for
 250  * each capturing parenthesis that matched containing the text that was captured.  If the match fails,
 251  * the `exec` method returns `null`.
 252  *
 253  * If you are executing a match simply to find true or false, use the `test` method or the `String
 254  * search` method.
 255  *
 256  * Consider the following example:
 257  *
 258  *     // Match one d followed by one or more b's followed by one d
 259  *     // Remember matched b's and the following d
 260  *     // Ignore case
 261  *     var re = /d(b+)(d)/ig;
 262  *     var result = re.exec(&quot;cdbBdbsbz&quot;);
 263  *
 264  * The following table shows the results for this script:
 265  *
 266  * | Object           | Property/Index | Description                                                          | Example
 267  * |:-----------------|:---------------|:---------------------------------------------------------------------|:---------------------
 268  * | `result`         |                | The content of myArray.                                              | `[&quot;dbBd&quot;, &quot;bB&quot;, &quot;d&quot;]`
 269  * |                  | `index`        | The 0-based index of the match in the string                         | `1`
 270  * |                  | `input`        | The original string.                                                 | `cdbDdbsbz`
 271  * |                  | `[0]`          | The last matched characters.                                         | `dbBd`
 272  * |                  | `[1], ...[n]`  | The parenthesized substring matches, if any. The number of possible  | `[1] = bB`
 273  * |                  |                | parenthesized substrings is unlimited.                               | `[2] = d`
 274  * | `re`             | `lastIndex`    | The index at which to start the next match.                          | `5`
 275  * |                  | `ignoreCase`   | Indicates the &quot;`i`&quot; flag was used to ignore case.                    | `true`
 276  * |                  | `global`       | Indicates the &quot;`g`&quot; flag was used for a global match.                | `true`
 277  * |                  | `multiline`    | Indicates the &quot;`m`&quot; flag was used to search in strings across        | `false`
 278  * |                  |                | multiple lines.                                                      |
 279  * |                  | `source`       | The text of the pattern.                                             | d(b+)(d)
 280  *
 281  * If your regular expression uses the &quot;`g`&quot; flag, you can use the `exec` method multiple times to find
 282  * successive matches in the same string. When you do so, the search starts at the substring of `str`
 283  * specified by the regular expression's `lastIndex` property (`test` will also advance the `lastIndex`
 284  * property). For example, assume you have this script:
 285  *
 286  *     var myRe = /ab*\/g;
 287  *     var str = &quot;abbcdefabh&quot;;
 288  *     var myArray;
 289  *     while ((myArray = myRe.exec(str)) != null)
 290  *     {
 291  *         var msg = &quot;Found &quot; + myArray[0] + &quot;.  &quot;;
 292  *         msg += &quot;Next match starts at &quot; + myRe.lastIndex;
 293  *     print(msg);
 294  *     }
 295  *
 296  * This script displays the following text:
 297  *
 298  *     Found abb. Next match starts at 3
 299  *     Found ab. Next match starts at 9
 300  *
 301  * You can also use `exec()` without creating a RegExp object:
 302  *
 303  *     var matches = /(hello \S+)/.exec('This is a hello world!');
 304  *     alert(matches[1]);
 305  *
 306  * This will display an alert containing 'hello world!';
 307  *
 308  * @param {String} str The string against which to match the regular expression.
 309  * @return {Array} Array of results or `NULL`.
 310  */
 311
 312 <span id='RegExp-method-test'>/**
 313 </span> * @method test
 314  * Tests for a match in its string parameter.
 315  *
 316  * When you want to know whether a pattern is found in a string use the test method (similar to the
 317  * `String.search` method); for more information (but slower execution) use the exec method (similar to
 318  * the `String.match` method). As with exec (or in combination with it), test called multiple times on
 319  * the same global regular expression instance will advance past the previous match.
 320  *
 321  * The following example prints a message which depends on the success of the test:
 322  *
 323  *     function testinput(re, str){
 324  *         if (re.test(str))
 325  *             midstring = &quot; contains &quot;;
 326  *         else
 327  *             midstring = &quot; does not contain &quot;;
 328  *         document.write (str + midstring + re.source);
 329  *     }
 330  *
 331  * @param {String} str The string against which to match the regular expression.
 332  * @return {Boolean} true if string contains any matches, otherwise returns false.
 333  */
 334
 335 <span id='RegExp-method-toString'>/**
 336 </span> * @method toString
 337  * Returns a string representing the specified object. Overrides the `Object.prototype.toString`
 338  * method.
 339  *
 340  * The RegExp object overrides the `toString` method of the `Object` object; it does not inherit
 341  * `Object.toString`. For RegExp objects, the `toString` method returns a string representation of the
 342  * regular expression.
 343  *
 344  * The following example displays the string value of a RegExp object:
 345  *
 346  *     myExp = new RegExp(&quot;a+b+c&quot;);
 347  *     alert(myExp.toString());       // displays &quot;/a+b+c/&quot;
 348  *
 349  * @return {String} Regular expression as a string.
 350  */
 351
 352 //Properties
 353
 354 // Note that several of the RegExp properties have both long and short (Perl-like) names.
 355 // Both names always refer to the same value. Perl is the programming language from which
 356 // JavaScript modeled its regular expressions.
 357
 358 <span id='RegExp-property-global'>/**
 359 </span> * @property {Boolean} global
 360  * Whether to test the regular expression against all possible matches in a
 361  * string, or only against the first.
 362  *
 363  * `global` is a property of an individual regular expression object.
 364  *
 365  * The value of `global` is true if the &quot;`g`&quot; flag was used; otherwise, `false`. The &quot;`g`&quot; flag
 366  * indicates that the regular expression should be tested against all possible matches in a string.
 367  *
 368  * You cannot change this property directly.
 369  */
 370
 371 <span id='RegExp-property-ignoreCase'>/**
 372 </span> * @property {Boolean} ignoreCase
 373  * Whether to ignore case while attempting a match in a string.
 374  *
 375  * `ignoreCase` is a property of an individual regular expression object.
 376  *
 377  * The value of `ignoreCase` is true if the &quot;`i`&quot; flag was used; otherwise, false. The &quot;`i`&quot; flag indicates
 378  * that case should be ignored while attempting a match in a string.
 379  *
 380  * You cannot change this property directly.
 381  */
 382
 383 <span id='RegExp-property-lastIndex'>/**
 384 </span> * @property {Number} lastIndex
 385  * The index at which to start the next match. A read/write integer property that specifies the index
 386  * at which to start the next match.
 387  *
 388  * `lastIndex` is a property of an individual regular expression object.
 389  *
 390  * This property is set only if the regular expression used the &quot;`g`&quot; flag to indicate a global search.
 391  * The following rules apply:
 392  *
 393  * -   If `lastIndex` is greater than the length of the string, `regexp.test` and `regexp.exec` fail,
 394  *     and `lastIndex` is set to 0.
 395  * -   If `lastIndex` is equal to the length of the string and if the regular expression matches the
 396  *     empty string, then the regular expression matches input starting at `lastIndex`.
 397  * -   If `lastIndex` is equal to the length of the string and if the regular expression does not match
 398  *     the empty string, then the regular expression mismatches input, and `lastIndex` is reset to 0.
 399  * -   Otherwise, `lastIndex` is set to the next position following the most recent match.
 400  *
 401  * For example, consider the following sequence of statements:
 402  *
 403  * -   `re = /(hi)?/g` Matches the empty string.
 404  * -   `re(&quot;hi&quot;)` Returns `[&quot;hi&quot;, &quot;hi&quot;]` with `lastIndex` equal to 2.
 405  * -   `re(&quot;hi&quot;)` Returns `[&quot;&quot;]`, an empty array whose zeroth element is the match string. In this
 406  *     case, the empty string because `lastIndex` was 2 (and still is 2) and &quot;`hi`&quot; has length 2.
 407  */
 408
 409 <span id='RegExp-property-multiline'>/**
 410 </span> * @property {Boolean} multiline
 411  * Whether or not to search in strings across multiple lines.
 412  *
 413  * `multiline` is a property of an individual regular expression object..
 414  *
 415  * The value of `multiline` is true if the &quot;`m`&quot; flag was used; otherwise, `false`. The &quot;`m`&quot; flag
 416  * indicates that a multiline input string should be treated as multiple lines. For example, if &quot;`m`&quot;
 417  * is used, &quot;`^`&quot; and &quot;`$`&quot; change from matching at only the start or end of the entire string to the
 418  * start or end of any line within the string.
 419  *
 420  * You cannot change this property directly.
 421  */
 422
 423 <span id='RegExp-property-source'>/**
 424 </span> * @property {String} source
 425  * The text of the pattern.
 426  *
 427  * A read-only property that contains the text of the pattern, excluding the forward slashes.
 428  *
 429  * `source` is a property of an individual regular expression object.
 430  *
 431  * You cannot change this property directly.
 432  */</pre>
 433 </body>
 434 </html>