# 字符串

一个固定长度的 UTF-16 代码单元序列。

String API 的工作方式与 JavaScript 的 (MDN (在新窗口中打开)) 很相似，区别在于 string 类型是 String 的实际别名。

# 静态成员

```
function fromCharCode(unit: i32, surr?: i32): string
```
从指定的 UTF-16 代码单元创建一个只有一个字符的字符串。

function fromCharCodes(units: u16[]): string

从 UTF-16 代码单元序列创建字符串。

```
function fromCodePoint(code: i32): string
```
从指定的 Unicode 代码点创建一个只有一个字符的字符串。

function fromCodePoints(codes: i32[]): string

从 Unicode 代码点序列创建字符串。

# 实例成员

# 字段

```
readonly length: i32
```
字符串中 UTF-16 代码单元的长度。

# 方法

```
function at(pos: i32): string
```
获取指定位置的 UTF-16 代码单元，作为单个字符字符串。此方法允许使用正负整数。负整数从最后一个字符串字符开始倒数。
```
function charAt(pos: i32): string
```
获取指定位置的 UTF-16 代码单元，作为单个字符字符串。如果超出范围，则返回 ""（空字符串）。
```
function charCodeAt(pos: i32): i32
```
获取指定位置的 UTF-16 代码单元，作为数字。如果超出范围，则返回 -1。
```
function codePointAt(pos: i32): i32
```
获取指定（UTF-16 代码单元）位置的 Unicode 代码点，作为数字，可能组合多个连续的 UTF-16 代码单元。如果超出范围，则返回 -1。
```
function concat(other: string): string
```
将此字符串与另一个字符串连接起来，按此顺序，并返回结果字符串。
```
function endsWith(search: string, end?: i32): bool
```
测试字符串是否以指定字符串结尾。如果指定，则 end 指示停止搜索的位置，就像它是字符串的长度一样。
```
function includes(search: string, start?: i32): bool
```
测试字符串是否包含搜索字符串。如果指定，则 start 指示开始搜索的位置。
```
function indexOf(search: string, start?: i32): i32
```
获取指定搜索字符串在字符串中的第一个索引，如果未找到则返回 -1。如果指定，则 start 指示开始搜索的位置。
```
function lastIndexOf(search: string, start?: i32): i32
```
获取指定搜索字符串在字符串中的最后一个索引，如果未找到则返回 -1。如果指定，则 start 指示从右向左开始搜索的位置。
```
function padStart(length: i32, pad: string): string
```
使用另一个字符串的内容（可能多次）填充字符串，直到结果字符串达到指定的长度，并返回结果字符串。
```
function padEnd(length: i32, pad: string): string
```
使用另一个字符串的内容（可能多次）填充字符串，直到结果字符串达到指定的长度，并返回结果字符串。
```
function repeat(count?: i32): string
```
将字符串重复 count 次，并返回连接的结果。

function replace(search: string, replacement: string): string

将 search 的第一次出现替换为 replacement。

function replaceAll(search: string, replacement: string): string

将 search 的所有出现替换为 replacement。

```
function slice(start: i32, end?: i32): string
```
返回字符串中从 start 包含到 end 不包含的区域，作为新字符串。如果省略，end 默认为字符串的末尾。
```
function split(separator?: string, limit?: i32): string[]
```
在 separator 的每次出现处拆分字符串，并将结果作为具有最多 limit 个值的新字符串数组返回。如果省略 limit，则不假设限制。如果省略 separator 或它不在字符串中，则字符串成为数组的唯一元素。如果 separator 是空字符串，则拆分将在代码单元之间执行（而不是代码点），这可能会破坏代理对。
```
function startsWith(search: string, start?: i32): bool
```
测试字符串是否以指定字符串开头。如果指定，则 start 指示开始搜索的位置，充当字符串的开头。
```
function substring(start: i32, end?: i32): string
```
获取字符串中从 start 包含到 end 不包含的部分，作为新字符串。
```
function toString(): this
```
返回字符串。
```
function trim(): string
```
从字符串的开头和结尾删除空白字符，并返回结果字符串。
```
function trimStart(): string
function trimLeft(): string
```
从字符串的开头删除空白字符，并返回结果字符串。
```
function trimEnd(): string
function trimRight(): string
```
从字符串的结尾删除空白字符，并返回结果字符串。

# 编码 API

# UTF8

当与使用 UTF-8 的环境集成时，可以使用以下帮助程序快速重新编码 String 数据。

```
function String.UTF8.byteLength(str: string, nullTerminated?: bool): i32
```
计算以 UTF-8 编码的指定字符串的字节长度，可以选择空终止符。

function String.UTF8.encode(str: string, nullTerminated?: bool): ArrayBuffer

将指定字符串编码为 UTF-8 字节，可以选择空终止符。

function String.UTF8.encodeUnsafe(str: usize, len: i32, buf: usize, nullTerminated?: bool): usize

将指定的原始字符串编码为 UTF-8 字节，可以选择空终止符。返回写入的字节数。

function String.UTF8.decode(buf: ArrayBuffer, nullTerminated?: bool): string

将指定缓冲区从 UTF-8 字节解码为字符串，可以选择空终止符。

function String.UTF8.decodeUnsafe(
  buf: usize,
  len: usize,
  nullTerminated?: bool
): string

将原始 UTF-8 字节解码为字符串，可以选择空终止符。

提示

请注意，任何 ArrayBuffer 返回值都是指向缓冲区数据的内部指针，因此可以直接传递给例如 C 函数。但是，如果指针的生存期应该比立即外部函数调用更长，则必须跟踪缓冲区的生存期，以防止它过早地被收集，导致数据变得无效。

# UTF16

以下主要存在于 String 和 ArrayBuffer 之间安全复制的方法，但不涉及重新编码步骤。

```
function String.UTF16.byteLength(str: string): i32
```
计算以 UTF-16 编码的指定字符串的字节长度。

function String.UTF16.encode(str: string): ArrayBuffer

将指定字符串编码为 UTF-16 字节。

function String.UTF16.encodeUnsafe(str: usize, len: i32, buf: usize): usize

将指定的原始字符串编码为 UTF-16 字节。返回写入的字节数。

function String.UTF16.decode(buf: ArrayBuffer): string

将指定缓冲区从 UTF-16 字节解码为字符串。

function String.UTF16.decodeUnsafe(buf: usize, len: usize): string

将原始 UTF-16 字节解码为字符串。

# 注意事项

TL;DR: AssemblyScript 像 JavaScript 一样处理字符串，但是...

AssemblyScript 字符串故意与其语义共享 JavaScript 字符串，包括隔离的代理可以出现并且不会被急切地清理。这样做有两个原因。首先，作为 Unicode 标准，版本 13.0 (在新窗口中打开) 在 §2.7 Unicode 字符串 中说明

根据编程环境，Unicode 字符串可能需要或不需要采用相应的 Unicode 编码形式。例如，Java、C# 或 ECMAScript 中的字符串是 Unicode 16 位字符串，但并不一定格式良好的 UTF-16 序列。在正常处理中，允许此类字符串包含不是格式良好的 UTF-16 的代码单元序列（即孤立的代理）可能效率更高。由于字符串是每个程序的基本组成部分，因此在修改字符串的每个操作中检查孤立的代理可能会产生巨大的开销，尤其是因为辅助字符在全球程序中所有文本的百分比中极其罕见。

其次，在 AssemblyScript 和 JavaScript 之间，或在两个 AssemblyScript 模块之间，消毒也不理想，因为在函数调用跨越 JS<->AS 或 AS<->AS 边界时，保持惯用字符串的相等性、不相等性和哈希完整性至关重要。例如，一个应用程序通常由 AssemblyScript 和 JavaScript 代码组成，或者一个 AssemblyScript 模块替换了一个 JavaScript 模块，并且期望两个 AssemblyScript 模块可以交换字符串，而急于消毒（修改）字符串既不必要也不安全。此外，ESM 集成旨在更广泛地使 JavaScript 和 WebAssembly 模块可以互换，这只有在保持兼容性的情况下才能安全实现。

请注意，这种立场不同于 WebAssembly CG 内大多数人所决定的 (opens new window) 对于接口类型和组件模型，包括其 Web 集成，无论我们有什么顾虑 (1 (opens new window), 2 (opens new window)），但我们认为，消毒只应在不可避免的情况下进行，理想情况下应该尽可能地延迟，与 Web API 当今的做法一致（例如，在调用 HTTP API 时，但不能更早），以避免给许多已经与 JavaScript 和 Web 相匹配的流行语言带来无法解决的问题。因此，我们希望接口类型和类似或相关的提案修改其方法以遵循 WebIDL 的先例，其中 DOMString (opens new window) 代表了概念，而 USVString (opens new window) 是特殊情况。正如 WebIDL 所述

如有疑问，请使用 DOMString。

当然，我们同意 USVString 应该以某种方式得到支持以匹配 Rust 和 C++ 的做法，但将其作为唯一支持的概念，不仅会在根本层面上破坏生态系统的另一半，还会破坏整个 Web 平台，而鉴于消毒可以轻松地由接口适配器仅在需要时执行，这是不必要的且可以避免的。

← 静态数组符号 →