字符串函数

字符串函数仅对字符串表达式进行操作，如果用于其他任何值，将返回错误。此规则的例外是 toString()，它也接受数字、布尔值和时间值（即 DATE、ZONED TIME`、LOCAL TIME、ZONED DATETIME、LOCAL DATETIME 或 DURATION 值）。

以 STRING 作为输入的所有函数都作用于 Unicode 字符，而不是标准 char[]。例如，size() 函数应用于任何 Unicode 字符时将返回 1，即使该字符不适合单个 char 的 16 位。

当 toString() 应用于时间值时，它会返回一个 STRING 表示，适合由相应的时间函数解析。因此，这个 STRING 将按照 ISO 8601 格式进行格式化。

另请参阅字符串连接运算符。

btrim()

详情
语法	`btrim(input[, trimCharacterString])`
描述	返回移除了开头和结尾空白字符的给定 `STRING`，可选择指定要移除的 `trimCharacterString`。
参数	名称	类型	描述
	`input`	`STRING`	将从中移除开头和结尾修剪字符的值。
	`trimCharacterString`	`STRING`	将从给定字符串的开头和结尾移除的字符。
返回	`STRING`

注意事项
`btrim(null)` 返回 `null`。
`btrim(null, null)` 返回 `null`。
`btrim("hello", null)` 返回 `null`。
`btrim(null, ' ')` 返回 `null`。
如果未指定 `trimCharacterString`，则将移除所有开头和结尾的空白字符。

示例 1. btrim()

查询

RETURN btrim('   hello    '), btrim('xxyyhelloxyxy', 'xy')

结果
btrim(' hello')	btrim('xxyyhelloxyxy', 'xy')
`"hello"`	`"hello"`
行数: 1

left()

详情
语法	`left(original, length)`
描述	返回一个 `STRING`，其中包含给定 `STRING` 中指定数量（`INTEGER`）的最左侧字符。
参数	名称	类型	描述
	`original`	`STRING`	其最右侧字符将被修剪的字符串值。
	`length`	`INTEGER`	要返回的最左侧字符的长度。
返回	`STRING`

注意事项
`left(null, length)` 返回 `null`。
`left(null, null)` 返回 `null`。
`left(original, null)` 将引发错误。
如果 `length` 不是正 `INTEGER`，则会引发错误。
如果 `length` 超过 `original` 的大小，则返回 `original`。

示例 2. left()

查询

RETURN left('hello', 3)

结果
left('hello', 3)
`"hel"`
行数: 1

lower()

详情
语法	`lower(input)`
描述	将给定 `STRING` 转换为小写。
参数	名称	类型	描述
	`input`	`STRING`	要转换为小写的字符串。
返回	`STRING`

此函数是 toLower() 函数的别名，它是作为 Cypher^® GQL 一致性的一部分引入的。

注意事项
`lower(null)` 返回 `null`。

示例 3. lower()

查询

RETURN lower('HELLO')

结果
lower('HELLO')
`"hello"`
行数: 1

ltrim()

详情
语法	`ltrim(input[, trimCharacterString])`
描述	返回移除了开头空白字符的给定 `STRING`，可选择指定要移除的 `trimCharacterString`。
参数	名称	类型	描述
	`input`	`STRING`	将从中移除开头修剪字符的值。
	`trimCharacterString`	`STRING`	将从给定字符串开头移除的字符。
返回	`STRING`

注意事项
`ltrim(null)` 返回 `null`。
`ltrim(null, null)` 返回 `null`。
`ltrim("hello", null)` 返回 `null`。
`ltrim(null, ' ')` 返回 `null`。
从 Neo4j 5.20 开始，可以指定 `trimCharacterString`。如果未指定此参数，则将移除所有开头的空白字符。

示例 4. ltrim()

查询

RETURN ltrim('   hello'), ltrim('xxyyhelloxyxy', 'xy')

结果
ltrim(' hello')	ltrim('xxyyhelloxyxy', 'xy')
`"hello"`	`"helloxyxy"`
行数: 1

normalize()

详情
语法	`normalize(input[, normalForm])`
描述	规范化一个 `STRING`，可选择指定一种规范化形式。
参数	名称	类型	描述
	`input`	`STRING`	要规范化的值。
	`normalForm`	`[NFC, NFD, NFKC, NFKD]`	指定任何一种规范化形式的关键字；NFC、NFD、NFKC 或 NFKD。
返回	`STRING`

Unicode 规范化是一个将同一字符串的不同表示形式转换为标准化形式的过程。欲了解更多信息，请参阅Unicode 规范化形式的文档。

normalize() 函数对于将 STRING 值转换为可比较的形式非常有用。比较两个 STRING 值时，比较的是它们的 Unicode 码点。在 Unicode 中，外观相同的字符的码点可能由两个或多个不同的码点表示。例如，字符 < 可以表示为 \uFE64 (﹤) 或 \u003C (<)。在人眼看来，这些字符可能相同。然而，如果进行比较，Cypher 将返回 false，因为 \uFE64 不等于 \u003C。使用 normalize() 函数，可以将码点 \uFE64 规范化为 \u003C，从而创建一个单一码点表示，使它们能够成功比较。

注意事项
`normalize(null)` 返回 `null`。

示例 5. normalize()

查询

RETURN normalize('\u212B') = '\u00C5' AS result

结果
结果
`true`
行数: 1

要检查 STRING 是否已规范化，请使用 IS NORMALIZED 运算符。

指定规范化形式的 normalize()

规范化形式主要有两种类型

规范等价：NFC（默认）和 NFD 是规范等价的形式。这意味着表示相同抽象字符的码点将被规范化为相同的码点（并且具有相同的外观和行为）。NFC 形式将始终给出组合规范形式（如果可能，其中组合代码被单个表示替换）。NFD 形式给出分解形式（与组合形式相反，如果可能，它将组合的码点转换为拆分形式）。
兼容性规范化：NFKC 和 NFKD 是兼容性规范化的形式。所有规范等价的序列都是兼容的，但并非所有兼容的序列都是规范的。这意味着在 NFC 或 NFD 中规范化的字符也应在 NFKC 和 NFKD 中规范化。外观只有轻微差异的其他字符应是兼容等价的。

例如，带尖音符和钩号的希腊字母Upsilon ϓ 可以用 Unicode 码点：\u03D3 表示。

在 NFC 中规范化：\u03D3 带尖音符和钩号的希腊字母 Upsilon (ϓ)
在 NFD 中规范化：\u03D2\u0301 带钩号的希腊字母 Upsilon + 组合尖音符 (ϓ)
在 NFKC 中规范化：\u038E 带重音的希腊大写字母 Upsilon (Ύ)
在 NFKD 中规范化：\u03A5\u0301 希腊大写字母 Upsilon + 组合尖音符 (Ύ)

在兼容性规范化形式（NFKC 和 NFKD）中，该字符明显不同，因为它不再包含钩号。

示例 6. 指定规范化形式的 normalize()

查询

RETURN normalize('\uFE64', NFKC) = '\u003C' AS result

结果
结果
`true`
行数: 1

replace()

详情
语法	`replace(original, search, replace)`
描述	返回一个 `STRING`，其中给定 `STRING` 中所有指定搜索 `STRING` 的出现都已被另一个（指定的）替换 `STRING` 替换。
参数	名称	类型	描述
	`original`	`STRING`	要修改的字符串。
	`search`	`STRING`	要在原始字符串中替换的值。
	`replace`	`STRING`	要插入到原始字符串中的值。
返回	`STRING`

注意事项
如果任何参数为 `null`，则返回 `null`。
如果在 `original` 中未找到 `search`，则返回 `original`。

示例 7. replace()

查询

RETURN replace("hello", "l", "w")

结果
replace("hello", "l", "w")
`"hewwo"`
行数: 1

reverse()

详情
语法	`reverse(input)`
描述	返回一个 `STRING` 或 `LIST<ANY>`，其中给定 `STRING` 或 `LIST<ANY>` 中所有字符或元素的顺序已反转。
参数	名称	类型	描述
	`input`	`STRING \| LIST<ANY>`	要反转的字符串或列表。
返回	`STRING \| LIST<ANY>`

注意事项
`reverse(null)` 返回 `null`。
另请参阅列表函数 → `reverse()`。

示例 8. reverse

查询

RETURN reverse('palindrome')

结果
reverse('palindrome')
`"emordnilap"`
行数: 1

right()

详情
语法	`right(original, length)`
描述	返回一个 `STRING`，其中包含给定 `STRING` 中指定数量的最右侧字符。
参数	名称	类型	描述
	`original`	`STRING`	其最左侧字符将被修剪的字符串值。
	`length`	`INTEGER`	要返回的最右侧字符的长度。
返回	`STRING`

注意事项
`right(null, length)` 返回 `null`。
`right(null, null)` 返回 `null`。
`right(original, null)` 将引发错误。
如果 `length` 不是正 `INTEGER`，则会引发错误。
如果 `length` 超过 `original` 的大小，则返回 `original`。

示例 9. right()

查询

RETURN right('hello', 3)

结果
right('hello', 3)
`"llo"`
行数: 1

rtrim()

详情
语法	`rtrim(input[, trimCharacterString])`
描述	返回移除了尾随空白字符的给定 `STRING`，可选择指定要移除的 `trimCharacterString`。
参数	名称	类型	描述
	`input`	`STRING`	将从中移除开头和结尾修剪字符的值。
	`trimCharacterString`	`STRING`	将从给定字符串的开头和结尾移除的字符。
返回	`STRING`

注意事项
`rtrim(null)` 返回 `null`。
`rtrim(null, null)` 返回 `null`。
`rtrim("hello", null)` 返回 `null`。
`rtrim(null, ' ')` 返回 `null`。
从 Neo4j 5.20 开始，可以指定 `trimCharacterString`。如果未指定此参数，则将移除所有尾随空白字符。

示例 10. rtrim()

查询

RETURN rtrim('hello   '), rtrim('xxyyhelloxyxy', 'xy')

结果
rtrim('hello ')	rtrim('xxyyhelloxyxy', 'xy')
`"hello"`	`"xxyyhello"`
行数: 1

split()

详情
语法	`split(original, splitDelimiters)`
描述	返回一个 `LIST<STRING>`，它是将给定 `STRING` 按指定分隔符进行分割后的结果。
参数	名称	类型	描述
	`original`	`STRING`	要分割的字符串。
	`splitDelimiters`	`STRING \| LIST<STRING>`	用于分割原始字符串的字符串。
返回	`LIST<STRING>`

注意事项
`split(null, splitDelimiter)` 返回 `null`。
`split(original, null)` 返回 `null`

示例 11. split()

查询

RETURN split('one,two', ',')

结果
split('one,two', ',')
`["one","two"]`
行数: 1

substring()

详情
语法	`substring(original, start, length)`
描述	从给定 `STRING` 中返回一个给定 `length` 的子字符串，从 0 开始的索引位置开始。
参数	名称	类型	描述
	`original`	`STRING`	要截短的字符串。
	`start`	`INTEGER`	新字符串的起始位置。
	`length`	`INTEGER`	新字符串的长度。
返回	`STRING`

注意事项
`start` 使用零基索引。
如果省略 `length`，函数将返回从 `start` 指定位置开始并延伸到 `original` 结尾的子字符串。
如果 `original` 为 `null`，则返回 `null`。
如果 `start` 或 `length` 为 `null` 或负整数，则会引发错误。
如果 `start` 为 `0`，子字符串将从 `original` 的开头开始。
如果 `length` 为 `0`，则返回空 `STRING`。

示例 12. substring()

查询

RETURN substring('hello', 1, 3), substring('hello', 2)

结果
substring('hello', 1, 3)	substring('hello', 2)
`"ell"`	`"llo"`
行数: 1

toLower()

详情
语法	`toLower(input)`
描述	将给定 `STRING` 转换为小写。
参数	名称	类型	描述
	`input`	`STRING`	要转换为小写的字符串。
返回	`STRING`

注意事项
`toLower(null)` 返回 `null`。

示例 13. toLower()

查询

RETURN toLower('HELLO')

结果
toLower('HELLO')
`"hello"`
行数: 1

toString()

详情
语法	`toString(input)`
描述	将 `INTEGER`、`FLOAT`、`BOOLEAN`、`POINT` 或时间类型（即 `DATE`、`ZONED TIME`、`LOCAL TIME`、`ZONED DATETIME`、`LOCAL DATETIME` 或 `DURATION`）值转换为 `STRING`。
参数	名称	类型	描述
	`input`	`ANY`	要转换为字符串的值。
返回	`STRING`

注意事项
`toString(null)` 返回 `null`。
如果 `input` 是 `STRING`，则原样返回。
如果提供的表达式不是 `INTEGER`、`FLOAT`、`BOOLEAN`、`STRING`、`POINT`、`DURATION`、`DATE`、`ZONED TIME`、`LOCAL TIME`、`LOCAL DATETIME` 或 `ZONED DATETIME` 值，则此函数将返回错误。

示例 14. toString()

查询

RETURN
  toString(11.5),
  toString('already a string'),
  toString(true),
  toString(date({year: 1984, month: 10, day: 11})) AS dateString,
  toString(datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 341, timezone: 'Europe/Stockholm'})) AS datetimeString,
  toString(duration({minutes: 12, seconds: -60})) AS durationString

结果
toString(11.5)	toString('already a string')	toString(true)	dateString	datetimeString	durationString
`"11.5"`	`"already a string"`	`"true"`	`"1984-10-11"`	`"1984-10-11T12:31:14.341+01:00[Europe/Stockholm]"`	`"PT11M"`
行数: 1

toStringOrNull()

详情
语法	`toStringOrNull(input)`
描述	将 `INTEGER`、`FLOAT`、`BOOLEAN`、`POINT` 或时间类型（即 `DATE`、`ZONED TIME`、`LOCAL TIME`、`ZONED DATETIME`、`LOCAL DATETIME` 或 `DURATION`）值转换为 `STRING`，如果无法转换则为 null。
参数	名称	类型	描述
	`input`	`ANY`	要转换为字符串或 null 的值。
返回	`STRING`

注意事项
`toStringOrNull(null)` 返回 `null`。
如果 `input` 不是 `INTEGER`、`FLOAT`、`BOOLEAN`、`STRING`、`POINT`、`DURATION`、`DATE`、`ZONED TIME`、`LOCAL TIME`、`LOCAL DATETIME` 或 `ZONED DATETIME` 值，则返回 `null`。

示例 15. toStringOrNull()

查询

RETURN toStringOrNull(11.5),
toStringOrNull('already a string'),
toStringOrNull(true),
toStringOrNull(date({year: 1984, month: 10, day: 11})) AS dateString,
toStringOrNull(datetime({year: 1984, month: 10, day: 11, hour: 12, minute: 31, second: 14, millisecond: 341, timezone: 'Europe/Stockholm'})) AS datetimeString,
toStringOrNull(duration({minutes: 12, seconds: -60})) AS durationString,
toStringOrNull(['A', 'B', 'C']) AS list

结果
toStringOrNull(11.5)	toStringOrNull('already a string')	toStringOrNull(true)	dateString	datetimeString	durationString	list
`"11.5"`	`"already a string"`	`"true"`	`"1984-10-11"`	`"1984-10-11T12:31:14.341+01:00[Europe/Stockholm]"`	`"PT11M"`	`<null>`
行数: 1

toUpper()

详情
语法	`toUpper(input)`
描述	将给定 `STRING` 转换为大写。
参数	名称	类型	描述
	`input`	`STRING`	要转换为大写的字符串。
返回	`STRING`

注意事项
`toUpper(null)` 返回 `null`。

示例 16. toUpper()

查询

RETURN toUpper('hello')

结果
toUpper('hello')
`"HELLO"`
行数: 1

trim()

详情
语法	`trim(trimSpecification, trimCharacterString, input)`
描述	返回移除了开头和/或结尾 `trimCharacterString` 的给定 `STRING`。
参数	名称	类型	描述
	`trimSpecification`	`[LEADING, TRAILING, BOTH]`	要修剪的字符串部分；LEADING（开头）、TRAILING（结尾）、BOTH（两端）
	`trimCharacterString`	`STRING`	将从给定字符串的开头和/或结尾移除的字符。
	`input`	`STRING`	将从中移除所有开头和/或结尾修剪字符的值。
返回	`STRING`

注意事项
`trim(null)` 返回 `null`。
`trim(null FROM "hello")` 返回 `null`。
`trim(" " FROM null)` 返回 `null`。
`trim(BOTH null FROM null)` 返回 `null`。
从 Neo4j 5.20 开始，可以指定 `trimSpecification` 和 `trimCharacterString`。如果未指定这些参数，则将移除所有开头和/或结尾的空白字符。

示例 17. trim()

查询

RETURN trim('   hello   '), trim(BOTH 'x' FROM 'xxxhelloxxx')

结果
trim(' hello ')	trim(BOTH 'x' FROM 'xxxhelloxxx')
`"hello"`	`"hello"`
行数: 1

upper()

详情
语法	`upper(input)`
描述	将给定 `STRING` 转换为大写。
参数	名称	类型	描述
	`input`	`STRING`	要转换为大写的字符串。
返回	`STRING`

此函数是 toUpper() 函数的别名，它是作为 Cypher 的 GQL 一致性的一部分引入的。

注意事项
`upper(null)` 返回 `null`。

示例 18. upper()

查询

RETURN upper('hello')

结果
upper('hello')
`"HELLO"`
行数: 1