## `$string()`

**用法:** `$string(arg, prettify)`
使用以下轉換規則將 `arg` 參數轉換為字符串

* 字符串不變
* 函數轉換為空字符串
* 數值無窮大和 NaN 拋出錯誤，因為它們不能表示為 JSON 數字
* 所有其他值都使用 JSON.stringify 函數轉換為 JSON 字符串

如果未指定 `arg`（即此函數在沒有參數的情況下被調用），則上下文值將用作 `arg` 的值。

如果 `prettify` 為真，則生成“pretified”JSON。即每個場一行，行將根據場深縮進。

實例：

* `$string(5)` => `"5"`
* `[1..5].$string()` => `["1", "2", "3", "4", "5"]`

## `$length()`

**用法:** `$length(str)`
返回字符串 `str` 中的字符數。如果未指定 `str`（即此函數在沒有參數的情況下調用），則將上下文值用作 `str` 的值。如果 `str` 不是字符串，則會拋出錯誤。

實例：

* `$length("Hello World")` => `11`

## `$substring()`

**用法:** `$substring(str, start[, length])`

返回一個 `str`，其中包含從位置 `start`（零偏移）開始的第一個參數 str 中的字符。如果未指定 `str`（即僅使用數字參數調用此函數），則使用上下文值作為 str 的值。如果 `str` 不是字符串，則會拋出錯誤。

如果指定了長度，則子字符串將包含最大 `length` 的字符。

如果 `start` 為負，則表示從 `str` 末尾開始的字符數。有關完整定義，請參閱 substr。

實例：

* `$substring("Hello World", 3)` => `"lo World"`
* `$substring("Hello World", 3, 5)` => `"lo Wo"`
* `$substring("Hello World", -4)` => `"orld"`
* `$substring("Hello World", -4, 2)` => `"or"`

## `$substringBefore()`

**用法:** `$substringBefore(str, chars)`

返回字符串中字符序列 `chars` 第一次出現之前的子字符串。如果未指定 `str`（即此函數僅用一個參數調用），則上下文值用作 `str` 的值。如果 `str` 不包含 `chars`，則返回 tr。如果 `str` 和 `chars` 不是字符串，則拋出錯誤。

例子：

* `$substringBefore("Hello World", " ")` => `"Hello"`

## `$substringAfter()`

**用法:** `$substringAfter(str, chars)`

返回字符串中字符序列 `chars` 第一次出現后的子字符串。如果未指定 `str`（即此函數僅用一個參數調用），則上下文值用作 `str` 的值。如果 `str` 不包含 `chars`，則返回 `str`。如果 `str` 和 `chars` 不是字符串，則拋出錯誤。

例子：

* `$substringAfter("Hello World", " ")` => `"World"`

## `$uppercase()`

**用法:** `$uppercase(str)`

返回一個字符串，其中 `str` 的所有字符都轉換為大寫。如果未指定 `str`（即此函數在沒有參數的情況下調用），則使用上下文值作為 `str` 的值。如果 `str` 不是字符串，則會拋出錯誤。

例子：

* `$uppercase("Hello World")` => `"HELLO WORLD"`

## `$lowercase()`

**用法:** `$lowercase(str)`
返回一個字符串，其中 `str` 的所有字符都轉換為小寫。如果未指定 `str`（即此函數在沒有參數的情況下調用），則使用上下文值作為 str 的值。如果 str 不是字符串，則會拋出錯誤。

## `$trim()`

**用法:** `$trim(str)`

通過應用以下步驟規范和修剪 str 中的所有空白字符：

* 所有制表符、回車符和換行符都替換為空格。
* 連續的空間序列被簡化為單個空間。
* 尾隨和前導空格被刪除。

如果未指定 `str`（即此函數在沒有參數的情況下調用），則使用上下文值作為 `str` 的值。如果 `str` 不是字符串，則會拋出錯誤。

例子：

* `$trim(" Hello \n World ")` => `"Hello World"`

## `$pad()`

**用法:** `$pad(str, width [, char])`

如有必要，返回字符串 `str` 的副本，并添加額外的填充，使其字符總數至少為 `width` 參數的絕對值。如果 `width` 是正數，則字符串向右填充；如果為負數，則將其填充到左側。可選的 `char` 參數指定要使用的填充字符。如果未指定，則默認為空格字符。

例子：

* `$pad("foo", 5)` => `"foo "`
* `$pad("foo", -5)` => `" foo"`
* `$pad("foo", -5, "#")` => `"##foo"`
* `$formatBase(35, 2) ~> $pad(-8, '0')` => `"00100011"`

## `$contains()`

**用法:** `$contains(str, pattern)`

如果 `str` 與模式匹配，則返回 `true`，否則返回 `false`。如果未指定 `str`（即使用一個參數調用此函數），則使用上下文值作為 `str` 的值。

模式參數可以是字符串或正則表達式（regex）。如果是字符串，如果模式中的字符連續包含在 `str` 中，則函數返回 true。如果是正則表達式，如果正則表達式與 `str` 的內容匹配，則函數將返回 `true`。

例子：

* `$contains("abracadabra", "bra")` => `true`
* `$contains("abracadabra", /a.*a/)` => `true`
* `$contains("abracadabra", /ar.*a/)` => `false`
* `$contains("Hello World", /wo/)` => `false`
* `$contains("Hello World", /wo/i)` => `true`
* `Phone[$contains(number, /^077/)]` => `{ "type": "mobile", "number": "077 7700 1234" }`

## `$split()`

**用法:** `$split(str, separator [, limit])`

將 `str` 參數拆分為一個子字符串數組。如果未指定 `str`，則使用上下文值作為 `str` 的值。如果 `str` 不是字符串，則會出錯。

分隔符參數可以是字符串或正則表達式（regex）。如果它是一個字符串，它指定 `str` 中應該拆分的字符。如果它是空字符串，`str` 將被拆分為單個字符的數組。如果是正則表達式，它會將字符串拆分為與正則表達式匹配的任何字符序列。

可選的 `limit` 參數是一個數字，指定要包含在結果數組中的子字符串的最大數量。任何額外的子字符串都將被丟棄。如果未指定 `limit`，則 `str` 將被完全拆分，對結果數組的大小沒有限制。如果極限不是非負數，則是錯誤的。

例子：

* `$split("so many words", " ")` => `[ "so", "many", "words" ]`
* `$split("so many words", " ", 2)` => `[ "so", "many" ]`
* `$split("too much, punctuation. hard; to read", /[ ,.;]+/)` => `["too", "much", "punctuation", "hard", "to", "read"]`

## `$join()`

**用法:** `$join(array[, separator])`

將一組組件字符串連接成一個連接字符串，每個組件字符串由可選的`separator`參數分隔。

如果輸入數組包含的項不是字符串，則會出錯。

如果未指定`separator`，則假定為空字符串，即組件字符串之間沒有分隔符。如果`separator`不是字符串，則會出錯。

例子：

* `$join(['a','b','c'])` => `"abc"`
* `$split("too much, punctuation. hard; to read", /[ ,.;]+/, 3) ~> $join(', ')` => `"too, much, punctuation"`

## `$match()`

**用法:** `$match(str, pattern [, limit])`

將`str`字符串應用于`pattern`正則表達式，并返回一個對象數組，每個對象都包含str中每次匹配的信息。

該對象包含以下字段：

* `match` - 正則表達式匹配的子字符串
* `index` - 此匹配的`str`內的偏移量（從零開始）。
* `groups` -如果正則表達式包含捕獲組（括號），則它包含一個表示每個捕獲組的字符串數組。

如果未指定`str`，則使用上下文值作為`str`的值。如果`str`不是字符串，則會出錯。

例子：

`$match("ababbabbcc",/a(b+)/)` =>

```
[
  {
    "match": "ab",
    "index": 0,
    "groups": ["b"]
  },
  {
    "match": "abb",
    "index": 2,
    "groups": ["bb"]
  },
  {
    "match": "abb",
    "index": 5,
    "groups": ["bb" ]
  }
]
```

## `$replace()`

**用法:** `$replace(str, pattern, replacement [, limit])`

在`str`中查找`pattern`的出現，并用替換`replacement`它們。

如果未指定`str`，則使用上下文值作為`str`的值。如果`str`不是字符串，則會出錯。
`pattern`參數可以是字符串或正則表達式（regex）。如果它是一個字符串，則指定`str`中應替換的字符串。如果它是正則表達式，則用于查找。

`replacement`參數可以是字符串或函數。如果它是一個字符串，則指定替換模式匹配的子字符串的字符序列。如果`pattern`是正則表達式，那么替換字符串可以引用正則表達式匹配的字符，以及使用`$`后跟數字`N`的任何捕獲組：

* 如果`N = 0`，則將其替換為正則表達式作為一個整體匹配的子字符串。
* 如果`N > 0`，則將其替換為正則表達式中第N個括號組捕獲的子字符串。
* 如果`N`大于捕獲的組數，則將其替換為空字符串。
* `replacement`字符串中的文字`$`字符必須寫成`$$`

如果`replacement`參數是一個函數，那么在模式正則表達式的每次匹配出現時都會調用它。`replacement`函數必須采用一個參數，該參數將是正則表達式匹配的對象結構，如`$match`函數所述；并且必須返回一個字符串。

可選的`limit`參數是一個數字，指定停止前要進行的最大替換次數。超出此限制的其余輸入將原封不動地復制到輸出中。

例子：

```
$replace("John Smith and John Jones", "John", "Mr")
//結果
"Mr Smith and Mr Jones"
```

```
$replace("John Smith and John Jones", "John", "Mr", 1)
//結果
"Mr Smith and Mr Jones"
```

```
$replace("abracadabra", /a.*?a/, "*")
//結果
"*c*bra"
```

```
$replace("John Smith", /(\w+)\s(\w+)/, "$2, $1")
//結果
"Smith, John"
```

```
$replace("265USD", /([0-9]+)USD/, "$$$1")
//結果
"$265"
```

```
(
  $convert := function($m) {
    ($number($m.groups[0]) - 32) * 5/9 & "C"
  };
  $replace("temperature = 68F today", /(\d+)F/, $convert)
)
//結果
"temperature = 20C today"
```

## `$eval()`

**用法:** `$eval(expr [, context])`
使用當前上下文作為求值上下文，解析并求值包含文字JSON或JSONata表達式的字符串`expr`。

舉例：

```
$([0-9]+)USD/, "$$$1")
//結果
"[1, 2, 3]
```

```
$eval('[1,$string(2),3]')
//結果
[1,"2",3]
```
## `$base64encode()`

**用法:** `$base64encode()`

將ASCII字符串轉換為以64為基數的表示形式。字符串中的每個字符都被視為二進制數據的一個字節。這要求字符串中的所有字符都在0x00到0xFF范圍內，這包括URI編碼字符串中的全部字符。不支持該范圍之外的Unicode字符。

舉例：

* `$base64encode("myuser:mypass")` => `"bXl1c2VyOm15cGFzcw=="`

## `$base64decode()`

**用法:** `$base64decode()`

使用UTF-8 Unicode代碼頁將基64編碼字節轉換為字符串。

* `$base64decode("bXl1c2VyOm15cGFzcw==")` => `"myuser:mypass"`

## `$encodeUrlComponent()`

**用法:** `$encodeUrlComponent(str)`

通過將某些字符的每個實例替換為表示字符UTF-8編碼的一個、兩個、三個或四個轉義序列，對統一資源定位符（URL）組件進行編碼。

舉例：

* `$encodeUrlComponent("?x=test")` => `"%3Fx%3Dtest"`

## `$encodeUrl()`

**用法:** `$encodeUrl(str)`

通過將某些字符的每個實例替換為表示字符UTF-8編碼的一個、兩個、三個或四個轉義序列來對統一資源定位符（URL）進行編碼。

舉例：

* `$encodeUrl("https://mozilla.org/?x=шеллы")` => `"https://mozilla.org/?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"`

## `$decodeUrlComponent()`

**用法:** `$decodeUrlComponent(str)`

對之前由encodeUrlComponent創建的統一資源定位符（URL）組件進行解碼。

舉例：

* `$decodeUrlComponent("%3Fx%3Dtest")` => `"?x=test"`

## `$decodeUrl()`

**用法:** `$decodeUrl(str)`

對之前由encodeUrl創建的統一資源定位符（URL）進行解碼。

舉例：

* `$decodeUrl("https://mozilla.org/?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B")` => `"https://mozilla.org/?x=шеллы"`

16、字符串函數

16、字符串函數