转义函数

quoteStr

quoteStr 函数用于为字符串添加引号。即使是空字符串，也会为了方便起见加上引号。

导入

import { quoteStr } from "@tai-kun/surrealdb/utils";

用法

function quoteStr(str: string): string;

该函数使用引号（" 或 ') 括起字符串。

参数

`str`

需要添加引号的字符串。

返回值

返回添加了引号的字符串。所使用的引号取决于输入字符串是否包含单引号(')：

若输入字符串为空：
- 返回 ''。
若输入字符串不包含单引号：
- 使用单引号括起字符串。
若输入字符串包含单引号：
- 使用双引号括起字符串。
若输入字符串同时包含单引号和双引号：
- 使用双引号括起字符串。
- 双引号使用反斜杠 (\) 进行转义。

示例

以下示例展示了如何使用单引号括起不包含单引号的字符串：

import { quoteStr } from "@tai-kun/surrealdb/utils";

console.log(quoteStr(``));
console.log(quoteStr(`a`));
console.log(quoteStr(`𩸽`));
console.log(quoteStr(`👍🏽`));
console.log(quoteStr(`パ`));

输出：

''
'a'
'𩸽'
'👍🏽'
'パ'

以下示例展示了如何使用双引号括起包含单引号的字符串：

import { quoteStr } from "@tai-kun/surrealdb/utils";

console.log(quoteStr(`cat's`));
console.log(quoteStr(`𩸽's`));
console.log(quoteStr(`'👍🏽`));
console.log(quoteStr(`'パ`));

输出：

"cat's"
"𩸽's"
"'👍🏽"
"'パ"

以下示例展示了如何使用双引号括起同时包含单引号和双引号的字符串，并在需要时进行转义：

import { quoteStr } from "@tai-kun/surrealdb/utils";

console.log(quoteStr(`cat's "toy"`));
console.log(quoteStr(`'\\"\\`));
console.log(quoteStr(`𩸽's "feed"`));
console.log(quoteStr(`'👍🏽"`));
console.log(quoteStr(`'パ"`));

输出：

"cat's \"toy\""
"'\\\"\\"
"𩸽's \"feed\""
"'👍🏽\""
"'パ\""

escapeKey

escapeKey 函数与 quoteStr 类似，但用于处理对象的键。即使是空字符串，也会为了方便起见加上引号。

导入

import { escapeKey } from "@tai-kun/surrealdb/utils";

用法

function escapeKey(key: string): string;

参数

`key`

对象的键。

返回值

返回转义后的字符串。根据需要，会使用双引号括起字符串：

若输入字符串为空：
- 返回 ""。
若输入字符串不以数字开头，并且只包含字母、数字和下划线：
- 直接返回该字符串。
若输入字符串包含双引号：
- 对其进行转义。
若输入字符串包含反斜杠 (\)：
- 对其进行转义。
若输入字符串以数字开头，或包含字母、数字和下划线以外的字符：
- 使用双引号括起字符串。

示例

以下示例展示了当字符串只包含字母、数字和下划线时，直接返回该字符串的情况：

import { escapeKey } from "@tai-kun/surrealdb/utils";

console.log(escapeKey(`foo_bar`));

输出：

foo_bar

以下示例展示了如何使用双引号括起字符串，并在需要时进行转义：

import { escapeKey } from "@tai-kun/surrealdb/utils";

console.log(escapeKey(``));
console.log(escapeKey(`123`));
console.log(escapeKey(`foo-bar`));
console.log(escapeKey(`'\\"\\`));
console.log(escapeKey(`𩸽's "feed"`));
console.log(escapeKey(`'👍🏽"`));
console.log(escapeKey(`'パ"`));

输出：

""
"123"
"foo-bar"
"'\\"\"
"𩸽's \"feed\""
"'👍🏽\""
"'パ\""

escapeRid

escapeRid 函数与 quoteStr 类似，但用于处理记录 ID。即使是空字符串，也会为了方便起见加上引号。

导入

import { escapeRid } from "@tai-kun/surrealdb/utils";

用法

function escapeRid(rid: string): string;

参数

`rid`

记录 ID 的 ID 部分。

返回值

返回转义后的字符串。根据需要，会使用尖括号 (⟨⟩) 括起字符串：

若输入字符串为空：
- 返回 ⟨⟩。
若输入字符串不以数字开头，并且只包含字母、数字和下划线：
- 直接返回该字符串。
若输入字符串包含尖括号 (⟩)：
- 对其进行转义。
若输入字符串全部由数字组成，或包含字母、数字和下划线以外的字符：
- 使用尖括号 (⟨⟩) 括起字符串。

示例

以下示例展示了当字符串不以数字开头，并且只包含字母、数字和下划线时，直接返回该字符串的情况：

import { escapeRid } from "@tai-kun/surrealdb/utils";

console.log(escapeRid(`foo_123`));

输出：

foo_123

以下示例展示了如何使用尖括号 (⟨⟩) 括起字符串，并在需要时进行转义：

import { escapeRid } from "@tai-kun/surrealdb/utils";

console.log(escapeRid(``));
console.log(escapeRid(`123`));
console.log(escapeRid(`foo-bar`));
console.log(escapeRid(`𩸽's ⟨feed⟩`));
console.log(escapeRid(`'👍🏽⟩`));
console.log(escapeRid(`'パ⟩`));

输出：

⟨⟩
⟨123⟩
⟨foo-bar⟩
⟨𩸽's ⟨feed\⟩⟩
⟨'👍🏽\⟩⟩
⟨'パ\⟩⟩

escapeIdent

escapeIdent 函数与 quoteStr 类似，但用于处理命名空间、数据库、表和字段的名称。即使是空字符串，也会为了方便起见加上引号。

导入

import { escapeIdent } from "@tai-kun/surrealdb/utils";

用法

function escapeIdent(ident: string): string;

参数

`ident`

标识符。

返回值

返回转义后的字符串。根据需要，会使用反引号 (`) 括起字符串：

若输入字符串为空：
- 返回。
若输入字符串不以数字开头，并且只包含字母、数字和下划线：
- 直接返回该字符串。
若输入字符串包含反引号 (`)：
- 对其进行转义。
若输入字符串以数字开头，或包含字母、数字和下划线以外的字符：
- 使用反引号 (`) 括起字符串。

示例

以下示例展示了当字符串不以数字开头，并且只包含字母、数字和下划线时，直接返回该字符串的情况：

import { escapeIdent } from "@tai-kun/surrealdb/utils";

console.log(escapeIdent(`foo_123`));

输出：

foo_123

以下示例展示了如何使用反引号 (`) 括起字符串，并在需要时进行转义：

import { escapeIdent } from "@tai-kun/surrealdb/utils";

console.log(escapeIdent(""));
console.log(escapeIdent("123"));
console.log(escapeIdent("foo-bar"));
console.log(escapeIdent("𩸽's `feed`"));
console.log(escapeIdent("'👍🏽`"));
console.log(escapeIdent("'パ`"));

输出：

``
`123`
`foo-bar`
`𩸽's \`feed\``
`'👍🏽\``
`'パ\``

专栏

字符串长度

前面示例中使用的字符串包含一些在 JavaScript 中的字符串长度与人类感知的长度不同的字符：

类型	显示	`.length`	`Uint8Array`
ASCII	a	1	`[ 0x61 ]`
代理对	𩸽	2	`[ 0xF0, 0xA9, 0xB8, 0xBD ]`
变体选择器	👍🏽	4	`[ 0xF0, 0x9F, 0x91, 0x8D, 0xF0, 0x9F, 0x8F, 0xBD ]`
组合字符	パ	2	`[ 0xE3, 0x83, 0x8F, 0xE3, 0x82, 0x9A ]`

当 .length 的值与直觉不符时，需要谨慎处理字符串操作。