1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
---
title: String.prototype.match()
slug: Web/JavaScript/Reference/Global_Objects/String/match
translation_of: Web/JavaScript/Reference/Global_Objects/String/match
---
<div>{{JSRef}}</div>
<p>The <strong><code>match()</code></strong> method retrieves the matches when matching a <em>string</em> against a <em>regular expression</em>.</p>
<h2 id="Syntax">Syntax</h2>
<pre class="syntaxbox"><var>str</var>.match(<var>regexp</var>)</pre>
<h3 id="Parameters">Parameters</h3>
<dl>
<dt><code>regexp</code></dt>
<dd>一個正規表達式的物件。 若傳入一個非正規表達式的物件<code>obj</code>，則會視為傳入 <code>new RegExp(obj)</code>。若只呼叫<code>match()</code>而沒有傳入任何參數，則會回傳內含一個空字串的陣列，即<code>[""]</code>。</dd>
</dl>
<h3 id="Return_value">Return value</h3>
<p>If the string matches the expression, it will return an {{jsxref("Array")}} containing the entire matched string as the first element, followed by any results captured in parentheses. If there were no matches, {{jsxref("null")}} is returned.</p>
<h2 id="Description">Description</h2>
<p>If the regular expression does not include the <code>g</code> flag, <code>str.match()</code> will return the same result as {{jsxref("RegExp.prototype.exec()", "RegExp.exec()")}}. The returned {{jsxref("Array")}} has an extra <code>input</code> property, which contains the original string that was parsed. In addition, it has an <code>index</code> property, which represents the zero-based index of the match in the string.</p>
<p>If the regular expression includes the <code>g</code> flag, the method returns an {{jsxref("Array")}} containing all matched substrings rather than match objects. Captured groups are not returned. If there were no matches, the method returns {{jsxref("null")}}.</p>
<h3 id="See_also_RegExp_methods">See also: <code>RegExp</code> methods</h3>
<ul>
<li>If you need to know if a string matches a regular expression {{jsxref("RegExp")}}, use {{jsxref("RegExp.prototype.test()", "RegExp.test()")}}.</li>
<li>If you only want the first match found, you might want to use {{jsxref("RegExp.prototype.exec()", "RegExp.exec()")}} instead.</li>
<li>if you want to obtain capture groups and the global flag is set, you need to use {{jsxref("RegExp.prototype.exec()", "RegExp.exec()")}} instead.</li>
</ul>
<h2 id="Examples">Examples</h2>
<h3 id="Using_match()">Using <code>match()</code></h3>
<p>In the following example, <code>match()</code> is used to find <code>'Chapter'</code> followed by 1 or more numeric characters followed by a decimal point and numeric character 0 or more times. The regular expression includes the <code>i</code> flag so that upper/lower case differences will be ignored.</p>
<pre class="brush: js">var str = 'For more information, see Chapter 3.4.5.1';
var re = /see (chapter \d+(\.\d)*)/i;
var found = str.match(re);
console.log(found);
// logs [ 'see Chapter 3.4.5.1',
// 'Chapter 3.4.5.1',
// '.1',
// index: 22,
// input: 'For more information, see Chapter 3.4.5.1' ]
// 'see Chapter 3.4.5.1' is the whole match.
// 'Chapter 3.4.5.1' was captured by '(chapter \d+(\.\d)*)'.
// '.1' was the last value captured by '(\.\d)'.
// The 'index' property (22) is the zero-based index of the whole match.
// The 'input' property is the original string that was parsed.</pre>
<h3 id="Using_global_and_ignore_case_flags_with_match()">Using global and ignore case flags with <code>match()</code></h3>
<p>The following example demonstrates the use of the global and ignore case flags with <code>match()</code>. All letters A through E and a through e are returned, each its own element in the array.</p>
<pre class="brush: js">var str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
var regexp = /[A-E]/gi;
var matches_array = str.match(regexp);
console.log(matches_array);
// ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']
</pre>
<h3 id="Using_match()_with_no_parameter">Using <code>match()</code> with no parameter</h3>
<pre class="brush: js">var str = "Nothing will come of nothing.";
str.match(); // returns [""]</pre>
<h3 id="A_non-RegExp_object_as_the_parameter">A non-RegExp object as the parameter</h3>
<p>When the parameter is a string or a number, it is implicitly converted to a {{jsxref("RegExp")}} by using new RegExp(obj). If it is a positive number with a positive sign,the RegExp() method will ignore the positive sign. </p>
<pre class="brush: js">var str1 = "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.",
str2 = "My grandfather is 65 years old and My grandmother is 63 years old.",
str3 = "The contract was declared null and void.";
str1.match("number"); // "number" is a string. returns ["number"]
str1.match(NaN); // the type of NaN is the number. returns ["NaN"]
str1.match(Infinity); // the type of Infinity is the number. returns ["Infinity"]
str1.match(+Infinity); // returns ["Infinity"]
str1.match(-Infinity); // returns ["-Infinity"]
str2.match(65); // returns ["65"]
str2.match(+65); // A number with a positive sign. returns ["65"]
str3.match(null); // returns ["null"]</pre>
<h2 id="Specifications">Specifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Status</th>
<th scope="col">Comment</th>
</tr>
<tr>
<td>{{SpecName('ES3')}}</td>
<td>{{Spec2('ES3')}}</td>
<td>Initial definition. Implemented in JavaScript 1.2.</td>
</tr>
<tr>
<td>{{SpecName('ES5.1', '#sec-15.5.4.10', 'String.prototype.match')}}</td>
<td>{{Spec2('ES5.1')}}</td>
<td> </td>
</tr>
<tr>
<td>{{SpecName('ES6', '#sec-string.prototype.match', 'String.prototype.match')}}</td>
<td>{{Spec2('ES6')}}</td>
<td> </td>
</tr>
<tr>
<td>{{SpecName('ESDraft', '#sec-string.prototype.match', 'String.prototype.match')}}</td>
<td>{{Spec2('ESDraft')}}</td>
<td> </td>
</tr>
</tbody>
</table>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{Compat("javascript.builtins.String.match")}}</p>
<h2 id="Firefox-specific_notes">Firefox-specific notes</h2>
<ul>
<li><code>flags</code> was a non standard second argument only available in Gecko : <var>str</var>.match(<var>regexp, flags</var>)</li>
<li>Starting with Gecko 27 {{geckoRelease(27)}}, this method has been adjusted to conform with the ECMAScript specification. When <code>match()</code> is called with a global regular expression, the {{jsxref("RegExp.lastIndex")}} property (if specified) will be reset to <code>0</code> ({{bug(501739)}}).</li>
<li>Starting with Gecko 39 {{geckoRelease(39)}}, the non-standard <code>flags</code> argument is deprecated and throws a console warning ({{bug(1142351)}}).</li>
<li>Starting with Gecko 47 {{geckoRelease(47)}}, the non-standard <code>flags</code> argument is no longer supported in non-release builds and will soon be removed entirely ({{bug(1245801)}}).</li>
<li>Starting with Gecko 49 {{geckoRelease(49)}}, the non-standard <code>flags</code> argument is no longer supported ({{bug(1108382)}}).</li>
</ul>
<h2 id="See_also">See also</h2>
<ul>
<li>{{jsxref("RegExp")}}</li>
<li>{{jsxref("RegExp.prototype.exec()")}}</li>
<li>{{jsxref("RegExp.prototype.test()")}}</li>
</ul>
|
