字符串函数

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

采用 STRING 作为输入的所有函数都对Unicode 字符进行操作，而不是对标准 char[] 进行操作。例如，应用于任何Unicode 字符的 size() 函数将返回 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>`，该列表是根据给定分隔符(s)的匹配项对给定 `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 为基的索引 start 开始。
参数	名称	类型	描述
	`original`	`STRING`	要缩短的字符串。
	`start`	`INTEGER`	新字符串的起始位置。
	`length`	`INTEGER`	新字符串的长度。
返回值	`STRING`

注意事项
`start` 使用 0 为基的索引。
如果省略 `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)`
描述	返回给定的 `STRING`，其中已删除前导和/或尾随 `trimCharacterString`。
参数	名称	类型	描述
	`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