# str.match()

{% hint style="info" %}
str.match() 的<mark style="color:orange;">**回傳值**</mark>有<mark style="color:red;">**三種模式**</mark>：

```
-----------------------------------------------
   matched   /g    return value    capture groups
-----------------------------------------------
1. ✅ 	     ✅     all matches	   ❌
2. ✅        ❌     first match     ✅
3. ❌               null
-----------------------------------------------
```

1. **global mode** (with <mark style="color:red;">**/g set**</mark>): \
   return <mark style="color:purple;">**array**</mark> of <mark style="color:red;">**all matches**</mark> (<mark style="color:red;">**without**</mark> info about **capturing groups**)
2. **non-global mode** (with <mark style="color:red;">**/g not set**</mark>): \
   return <mark style="color:purple;">**array**</mark> of <mark style="color:red;">**first match**</mark> (<mark style="color:red;">**including**</mark> additional info about <mark style="color:red;">**capturing groups**</mark>)
3. **no match**: return <mark style="color:yellow;">**null**</mark>.
   {% endhint %}

{% tabs %}
{% tab title="💾 程式" %}
:point\_right: [replit](https://replit.com/@pegasusroe/strmatchregex#index.js)

```javascript
//                       first match ↴
//             0         1         2         3         4
//      index: 01234567890123456789012345678901234567890
//                                   ╭── first match ──╮
const found = 'For more information, see Chapter 3.4.5.1'.match(
//                                       ╰─── group ───╯
    /see (chapter \d+(\.\d)*)/i     // ignore case, non-global
);

// ⭐️ three modes of str.match(regex) method's return value

log(found);
// ⭐️ 2. non-gloabl mode:
//   (return array of informations about first match)
// [
//   'see Chapter 3.4.5.1',         // whole match
//   'Chapter 3.4.5.1',             // first capture group ⭐️
//   '.1',                          // last value captured by '(\.\d)'
//   index: 22,                     // index of the whole match
//   input: 'For more information, see Chapter 3.4.5.1',    // original string
//   groups: undefined              // object of named capturing groups
// ]

let str = "We will, we will rock you";

// ⭐️ 1. global mode:
//   (return array of all matches, no capturing groups)
str.match(/we/gi),      // [ 'We', 'we' ]

// ⭐️ 3. no match:
//    (return null)
str.match(/they/),      // null ⭐️
```

{% endtab %}

{% tab title="💈範例" %}

* [split-into-course-names](https://lochiwei.gitbook.io/web/js/val/prim/str/method/str.match/split-into-course-names "mention")
  {% endtab %}

{% tab title="⬇️ 應用" %}

* [a1notationtorowcolumn](https://lochiwei.gitbook.io/web/appendix/gas/classes/range/a1-notation/a1notationtorowcolumn "mention") - <mark style="color:blue;">`"AA3"`</mark> to <mark style="color:blue;">`[ "AA", "3" ]`</mark>.
  {% endtab %}

{% tab title="📘 手冊" %}

* String ⟩&#x20;
  * [.match()](https://developer.mozilla.org/zh-TW/docs/Web/JavaScript/Reference/Global_Objects/String/match)
  * .[replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)() ⟩ [replacer function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_function_as_a_parameter)
    {% endtab %}

{% tab title="👥 相關 " %}

* [regex](https://lochiwei.gitbook.io/web/js/val/builtin/regex "mention")
* [str.replace](https://lochiwei.gitbook.io/web/js/val/prim/str/method/str.replace "mention")
* [str.matchall](https://lochiwei.gitbook.io/web/js/val/prim/str/method/str.matchall "mention")
  {% endtab %}
  {% endtabs %}