PackedByteArray

字节紧缩数组。

描述

专门设计用于保存字节的数组。紧缩数组紧密打包数据，因此可为大型数组节省内存。

PackedByteArray 还提供了将各种类型编码为字节/从字节解码的方法。值的编码方式是实现细节，在与外部应用程序交互时不应依赖它。

注意：打包数组始终通过引用传递。要获取可以独立于原始数组进行修改的数组副本，请使用 duplicate。内置属性和方法并非如此。这些返回的打包数组是副本，更改它不会影响原始值。要更新内置属性，需要修改返回的数组，然后再次将其分配给该属性。

备注

通过 C# 使用该 API 时会有显著不同，详见 C# API 与 GDScript 的差异。

构造函数

方法

运算符

构造函数说明

PackedByteArray PackedByteArray() 🔗

构造空的 PackedByteArray。

PackedByteArray PackedByteArray(from: PackedByteArray)

构造给定 PackedByteArray 的副本。

PackedByteArray PackedByteArray(from: Array)

构造新 PackedByteArray。你还可以传入通用 Array 进行转换。

方法说明

bool append(value: int) 🔗

向数组末尾追加一个元素（push_back 的别名）。

void append_array(array: PackedByteArray) 🔗

在该数组的末尾追加一个 PackedByteArray。

int bsearch(value: int, before: bool = true) 🔗

使用二进法查找已有值的索引（如果该值尚未存在于数组中，则为保持排序顺序的插入索引）。传递 before 说明符是可选的。如果该参数为 false，则返回的索引位于数组中该值的所有已有的条目之后。

注意：在未排序的数组上调用 bsearch 会产生预料之外的行为。

void clear() 🔗

清空数组。相当于调用 resize 时指定大小为 0。

PackedByteArray compress(compression_mode: int = 0) const 🔗

返回新的 PackedByteArray，其中的数据已压缩。请将压缩模式设置为 CompressionMode 常量。

int count(value: int) const 🔗

返回元素在数组中出现的次数。

float decode_double(byte_offset: int) const 🔗

将字节序列解码为 64 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

float decode_float(byte_offset: int) const 🔗

将字节序列解码为 32 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

float decode_half(byte_offset: int) const 🔗

将字节序列解码为 16 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_s8(byte_offset: int) const 🔗

将字节序列解码为 8 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_s16(byte_offset: int) const 🔗

将字节序列解码为 16 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_s32(byte_offset: int) const 🔗

将字节序列解码为 32 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_s64(byte_offset: int) const 🔗

将字节序列解码为 64 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_u8(byte_offset: int) const 🔗

将字节序列解码为 8 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_u16(byte_offset: int) const 🔗

将字节序列解码为 16 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_u32(byte_offset: int) const 🔗

将字节序列解码为 32 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

int decode_u64(byte_offset: int) const 🔗

将字节序列解码为 64 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。

Variant decode_var(byte_offset: int, allow_objects: bool = false) const 🔗

将字节序列解码为 Variant，起始位置字节偏移量为 byte_offset。如果无法解码有效的变体，或者其值派生自 Object 而 allow_objects 为 false，则返回 null。

int decode_var_size(byte_offset: int, allow_objects: bool = false) const 🔗

将字节序列解码为 Variant 的大小，起始位置字节偏移量为 byte_offset。要求起始位置后至少有 4 个字节的数据，否则返回 null。

PackedByteArray decompress(buffer_size: int, compression_mode: int = 0) const 🔗

返回新的 PackedByteArray，其中的数据已解压。请将 buffer_size 设置为数据解压后的大小。请将压缩模式设置为 CompressionMode 常量。

注意：不保证解压缩可以处理未经 Godot 压缩的数据，例如，如果使用 deflate 压缩模式压缩的数据缺少校验和或标头。

PackedByteArray decompress_dynamic(max_output_size: int, compression_mode: int = 0) const 🔗

返回新的 PackedByteArray，其中的数据已解压。请将压缩模式设置为 CompressionMode 常量。这个方法只接受 brotli、gzip 和 deflate 压缩模式。

这个方法可能比 decompress 慢，因为在解压时可能需要多次重新分配输出缓冲区，而 decompress 则在一开始就知道输出缓冲区的大小。

GZIP 的最大压缩率为 1032:1，这意味着较小的压缩后负载很有可能解压出非常巨大的输出。为了防止这种情况，你可以通过 max_output_size 提供允许这个函数分配的最大字节数。传入 -1 则不限制输出。传入正数且解压超过该字节数时，会返回错误。

注意：不保证解压缩可以处理未经 Godot 压缩的数据，例如，如果使用 deflate 压缩模式压缩的数据缺少校验和或标头。

PackedByteArray duplicate() 🔗

创建该数组的副本，并将该副本返回。

void encode_double(byte_offset: int, value: float) 🔗

将 64 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。

void encode_float(byte_offset: int, value: float) 🔗

将 32 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。

void encode_half(byte_offset: int, value: float) 🔗

将 16 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。

void encode_s8(byte_offset: int, value: int) 🔗

将 8 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 1 个字节的空间。

void encode_s16(byte_offset: int, value: int) 🔗

将 16 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。

void encode_s32(byte_offset: int, value: int) 🔗

将 32 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。

void encode_s64(byte_offset: int, value: int) 🔗

将 64 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。

void encode_u8(byte_offset: int, value: int) 🔗

将 8 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 1 个字节的空间。

void encode_u16(byte_offset: int, value: int) 🔗

将 16 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。

void encode_u32(byte_offset: int, value: int) 🔗

将 32 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。

void encode_u64(byte_offset: int, value: int) 🔗

将 64 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。

int encode_var(byte_offset: int, value: Variant, allow_objects: bool = false) 🔗

将 Variant 编码为字节序列，起始位置字节偏移量为 byte_offset。必须分配有足够的空间，空间大小取决于编码后变体的大小。如果 allow_objects 为 false，则不允许派生自 Object 的值，只会将其 ID 进行序列化。

void fill(value: int) 🔗

将数组中的所有元素都设为给定的值。通常与 resize 一起使用，创建给定大小的数组并初始化元素。

int find(value: int, from: int = 0) const 🔗

在数组中搜索值并返回其索引，如果未找到则返回 -1 。可选地，可以传递起始搜索索引。

String get_string_from_ascii() const 🔗

将 ASCII/Latin-1 编码的数组转换为 String。如果内容仅为 ASCII/Latin-1，则是比 get_string_from_utf8 更快的选择。与 UTF-8 函数不同，这个函数会将数组中的每个字节都映射到一个字符。多字节序列无法正确解析。要解析用户的输入内容，请始终使用 get_string_from_utf8。这是 String.to_ascii_buffer 的逆运算。

String get_string_from_utf8() const 🔗

将 UTF-8 编码的数组转换为 String。比 get_string_from_ascii 慢，但支持 UTF-8 编码的数据。不确定数据来源时请使用此函数。对于用户的输入内容，应始终首选此函数。如果源数组不是有效的 UTF-8 字符串，则返回空字符串。这是 String.to_utf8_buffer 的逆运算。

String get_string_from_utf16() const 🔗

将 UTF-16 编码的数组转换为 String。如果缺少 BOM，则假定为系统字节序。如果源数组不是有效的 UTF-16 字符串，则返回空字符串。这是 String.to_utf16_buffer 的逆运算。

String get_string_from_utf32() const 🔗

将 UTF-32 编码的数组转换为 String。假定为系统字节序。如果源数组不是有效的 UTF-32 字符串，则返回空字符串。这是 String.to_utf32_buffer 的逆运算。

String get_string_from_wchar() const 🔗

将宽字符（wchar_t，在 Windows 上为 UTF-16，在其他平台上为 UTF-32）编码的数组转换为 String。如果源数组不是有效的宽字符串，则返回空字符串。这是 String.to_wchar_buffer 的逆运算。

bool has(value: int) const 🔗

如果该数组包含 value，则返回 true。

bool has_encoded_var(byte_offset: int, allow_objects: bool = false) const 🔗

如果可以从字节偏移量 byte_offset 处解码出有效的 Variant，则返回 true。其他情况，或者当该值派生自 Object 而 allow_objects 为 false 时，则返回 false。

String hex_encode() const 🔗

返回该数组的十六进制表示，类型为 String。

GDScriptC#

var array = PackedByteArray([11, 46, 255])
print(array.hex_encode()) # 输出：0b2eff

var array = new byte[] {11, 46, 255};
GD.Print(array.HexEncode()); // 输出：0b2eff

int insert(at_index: int, value: int) 🔗

在数组中给定的位置插入一个新元素。这个位置必须是有效的，或者是在数组的末端（idx == size()）。

bool is_empty() const 🔗

该数组为空时，返回 true。

bool push_back(value: int) 🔗

在数组的末尾追加一个元素。

void remove_at(index: int) 🔗

从数组中删除位于索引的元素。

int resize(new_size: int) 🔗

设置数组的大小。如果数组被增大，则保留数组末端的元素。如果数组被缩小，则将数组截断到新的大小。调用一次 resize 并分配新值比逐个添加新元素要快。

void reverse() 🔗

将数组中的元素逆序排列。

int rfind(value: int, from: int = -1) const 🔗

逆序搜索数组。还可以传递起始搜索位置索引。如果为负，则起始索引被视为相对于数组的结尾。

void set(index: int, value: int) 🔗

改变给定索引处的字节。

int size() const 🔗

返回数组中元素的个数。

PackedByteArray slice(begin: int, end: int = 2147483647) const 🔗

返回该 PackedByteArray 的切片，是从 begin（含）到 end（不含）的全新 PackedByteArray。

begin 和 end 的绝对值会按数组大小进行限制，所以 end 的默认值会切到数组大小为止（即 arr.slice(1) 是 arr.slice(1, arr.size()) 的简写）。

如果 begin 或 end 为负，则表示相对于数组的末尾（即 arr.slice(0, -2) 是 arr.slice(0, arr.size() - 2) 的简写）。

void sort() 🔗

将该数组中的元素按升序排列。

PackedFloat32Array to_float32_array() const 🔗

返回将数据转换为 PackedFloat32Array 的副本，每 4 个字节块转换为一个 32 位浮点数（C++ 的 float）。

输入数组的大小必须为 4 的倍数（32 位浮点数的大小）。新数组的大小为 byte_array.size() / 4。

如果原始数据无法转换为 32 位浮点数，则最终的数据未定义。

PackedFloat64Array to_float64_array() const 🔗

返回将数据转换为 PackedFloat64Array 的副本，每 8 个字节块转换为一个 64 位浮点数（C++ 的 double）。

输入数组的大小必须为 8 的倍数（64 位浮点数的大小）。新数组的大小为 byte_array.size() / 8。

如果原始数据无法转换为 64 位浮点数，则最终的数据未定义。

PackedInt32Array to_int32_array() const 🔗

返回将数据转换为 PackedInt32Array 的副本，每 4 个字节块转换为一个 32 位有符号整数（C++ 的 int32_t）。

输入数组的大小必须为 4 的倍数（32 位整数的大小）。新数组的大小为 byte_array.size() / 4。

如果原始数据无法转换为 32 位有符号整数，则最终的数据未定义。

PackedInt64Array to_int64_array() const 🔗

返回将数据转换为 PackedInt64Array 的副本，每 8 个字节块转换为一个 64 位有符号整数（C++ 的 int64_t）。

输入数组的大小必须为 8 的倍数（64 位整数的大小）。新数组的大小为 byte_array.size() / 8。

如果原始数据无法转换为 64 位有符号整数，则最终的数据未定义。

运算符说明

bool operator !=(right: PackedByteArray) 🔗

如果数组内容不同，则返回 true。

PackedByteArray operator +(right: PackedByteArray) 🔗

返回新的 PackedByteArray，新数组的内容为此数组在末尾加上 right。为了提高性能，请考虑改用 append_array。

bool operator ==(right: PackedByteArray) 🔗

如果两个数组的内容相同，即对应索引号的字节相等，则返回 true。

int operator [](index: int) 🔗

返回索引 index 处的字节。负数索引可以从末尾开始访问元素。使用越界的索引会报错。

请注意，返回的字节是 64 位 int。