PackedByteArray
字节紧缩数组。
描述
专门设计用于保存字节的数组。紧缩数组紧密打包数据，因此可为大型数组节省内存。
PackedByteArray 还提供了将各种类型编码为字节/从字节解码的方法。值的编码方式是实现细节，在与外部应用程序交互时不应依赖它。
注意：紧缩数组始终通过引用传递。要获取可以独立于原始数组进行修改的数组副本，请使用 duplicate()。内置属性和方法并非如此，它们返回的是紧缩数组的副本，对其进行修改不会影响原值。更新此类内置属性请修改返回的数组，然后将其重新赋值给该属性。
备注
通过 C# 使用该 API 时会有显著不同，详见 C# API 与 GDScript 的差异。
构造函数
PackedByteArray(from: PackedByteArray) |
|
PackedByteArray(from: Array) |
方法
void |
append_array(array: PackedByteArray) |
void |
|
void |
|
void |
|
void |
clear() |
decode_double(byte_offset: int) const |
|
decode_float(byte_offset: int) const |
|
decode_half(byte_offset: int) const |
|
decode_s16(byte_offset: int) const |
|
decode_s32(byte_offset: int) const |
|
decode_s64(byte_offset: int) const |
|
decode_u16(byte_offset: int) const |
|
decode_u32(byte_offset: int) const |
|
decode_u64(byte_offset: int) const |
|
decode_var(byte_offset: int, allow_objects: bool = false) const |
|
decode_var_size(byte_offset: int, allow_objects: bool = false) const |
|
decompress(buffer_size: int, compression_mode: int = 0) const |
|
decompress_dynamic(max_output_size: int, compression_mode: int = 0) const |
|
duplicate() const |
|
void |
encode_double(byte_offset: int, value: float) |
void |
encode_float(byte_offset: int, value: float) |
void |
encode_half(byte_offset: int, value: float) |
void |
|
void |
encode_s16(byte_offset: int, value: int) |
void |
encode_s32(byte_offset: int, value: int) |
void |
encode_s64(byte_offset: int, value: int) |
void |
|
void |
encode_u16(byte_offset: int, value: int) |
void |
encode_u32(byte_offset: int, value: int) |
void |
encode_u64(byte_offset: int, value: int) |
encode_var(byte_offset: int, value: Variant, allow_objects: bool = false) |
|
void |
|
get_string_from_ascii() const |
|
get_string_from_multibyte_char(encoding: String = "") const |
|
get_string_from_utf8() const |
|
get_string_from_utf16() const |
|
get_string_from_utf32() const |
|
get_string_from_wchar() const |
|
has_encoded_var(byte_offset: int, allow_objects: bool = false) const |
|
hex_encode() const |
|
is_empty() const |
|
void |
|
void |
reverse() |
void |
|
size() const |
|
void |
sort() |
to_color_array() const |
|
to_float32_array() const |
|
to_float64_array() const |
|
to_int32_array() const |
|
to_int64_array() const |
|
to_vector2_array() const |
|
to_vector3_array() const |
|
to_vector4_array() const |
运算符
operator !=(right: PackedByteArray) |
|
operator +(right: PackedByteArray) |
|
operator ==(right: PackedByteArray) |
|
operator [](index: int) |
构造函数说明
PackedByteArray PackedByteArray() 🔗
构造空的 PackedByteArray。
PackedByteArray PackedByteArray(from: PackedByteArray)
构造给定 PackedByteArray 的副本。
PackedByteArray PackedByteArray(from: Array)
构造新 PackedByteArray。你还可以传入通用 Array 进行转换。
方法说明
向数组末尾追加一个元素（push_back() 的别名）。
void append_array(array: PackedByteArray) 🔗
在该数组的末尾追加一个 PackedByteArray。
int bsearch(value: int, before: bool = true) const 🔗
使用二进法查找已有值的索引（如果该值尚未存在于数组中，则为保持排序顺序的插入索引）。传递 before 说明符是可选的。如果该参数为 false，则返回的索引位于数组中该值的所有已有的条目之后。
注意：在未排序的数组上调用 bsearch() 会产生预料之外的行为。
void bswap16(offset: int = 0, count: int = -1) 🔗
对数组中从偏移量为 offset 处开始的 count 个 16 位段落进行字节顺序交换的操作。交换是原地进行的。如果 count 小于零，则会处理到数组结尾为止，如果处理的数据大小不是 2 的倍数，则处理的最后一个 16 位段落之后的字节不会发生修改。
void bswap32(offset: int = 0, count: int = -1) 🔗
对数组中从偏移量为 offset 处开始的 count 个 32 位段落进行字节顺序交换的操作。交换是原地进行的。如果 count 小于零，则会处理到数组结尾为止，如果处理的数据大小不是 4 的倍数，则处理的最后一个 32 位段落之后的字节不会发生修改。
void bswap64(offset: int = 0, count: int = -1) 🔗
对数组中从偏移量为 offset 处开始的 count 个 64 位段落进行字节顺序交换的操作。交换是原地进行的。如果 count 小于零，则会处理到数组结尾为止，如果处理的数据大小不是 8 的倍数，则处理的最后一个 64 位段落之后的字节不会发生修改。
void clear() 🔗
清空数组。相当于调用 resize() 时指定大小为 0。
PackedByteArray compress(compression_mode: int = 0) const 🔗
返回新的 PackedByteArray，其中的数据已压缩。请将压缩模式设置为 CompressionMode 常量。
返回元素在数组中出现的次数。
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 个字节的数据，否则会失败。
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() const 🔗
创建该数组的副本，并将该副本返回。
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 进行序列化。
在数组中移除首次出现的某个值并返回 true。如果数组中不存在该值，则不会发生任何事情，返回 false。要按照索引移除元素，请改用 remove_at()。
将数组中的所有元素都设为给定的值。通常与 resize() 一起使用，创建给定大小的数组并初始化元素。
int find(value: int, from: int = 0) const 🔗
在数组中搜索值并返回其索引，如果未找到则返回 -1 。可选地，可以传递起始搜索索引。
Returns the byte at the given index in the array. If index is out-of-bounds or negative, this method fails and returns 0.
This method is similar (but not identical) to the [] operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor.
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_multibyte_char(encoding: String = "") const 🔗
将使用系统多字节代码页编码的数组转换为 String。如果转换失败，则会返回空字符串。这是 String.to_multibyte_char_buffer() 的逆运算。
encoding 的有效值由系统决定。如果 encoding 为空字符串，则会使用系统默认的编码。
对于 Windows，见代码页标识符 .NET 名称。
对于 macOS 和 Linux/BSD，支持的编码列表见
libiconv库文档及iconv --list。
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() 的逆运算。
如果该数组包含 value，则返回 true。
bool has_encoded_var(byte_offset: int, allow_objects: bool = false) const 🔗
如果可以从字节偏移量 byte_offset 处解码出有效的 Variant，则返回 true。其他情况，或者当该值派生自 Object 而 allow_objects 为 false 时，则返回 false。
返回该数组的十六进制表示，类型为 String。
var array = PackedByteArray([11, 46, 255])
print(array.hex_encode()) # 输出“0b2eff”
byte[] array = [11, 46, 255];
GD.Print(array.HexEncode()); // 输出“0b2eff”
int insert(at_index: int, value: int) 🔗
在数组中给定的位置插入一个新元素。这个位置必须是有效的，或者是在数组的末端（idx == size()）。
该数组为空时，返回 true。
在数组的末尾追加一个元素。
从数组中删除位于索引的元素。
设置数组的大小。如果数组增大，则预留数组末端的元素。如果数组缩小，则将数组截断到新的大小。调用一次 resize() 然后赋值比逐个添加新元素要快。
成功时返回 @GlobalScope.OK，失败时返回下列 Error 常量：大小为负数则返回 @GlobalScope.ERR_INVALID_PARAMETER，分配失败则返回 @GlobalScope.ERR_OUT_OF_MEMORY。请使用 size() 获取调整后的实际大小。
void reverse() 🔗
将数组中的元素逆序排列。
int rfind(value: int, from: int = -1) const 🔗
逆序搜索数组。还可以传递起始搜索位置索引。如果为负，则起始索引被视为相对于数组的结尾。
void set(index: int, value: int) 🔗
改变给定索引处的字节。
返回数组中元素的个数。
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() 🔗
将该数组中的元素按升序排列。
PackedColorArray to_color_array() const 🔗
返回数据副本转换得到的 PackedColorArray，会将每 16 个字节的数据块会转换为一个 Color 变体。
注意：输入数组的大小必须为 16（四个 32 位 float 变量的大小）的倍数。新数组的大小是 byte_array.size() / 16。如果原数据无法转换为 Color 变体，则最终的数据未定义。
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 位有符号整数，则最终的数据未定义。
PackedVector2Array to_vector2_array() const 🔗
返回数据副本转换得到的 PackedVector2Array，会将每 8 个字节（32 位）或每 16 个字节（64 位）的数据块会转换为一个 Vector2 变体。
注意：输入数组的大小必须为 8 或 16（取决于构建设置，详见 Vector2）的倍数。新数组的大小是 byte_array.size() / (8 或 16)。如果原数据无法转换为 Vector2 变体，则最终的数据未定义。
PackedVector3Array to_vector3_array() const 🔗
返回数据副本转换得到的 PackedVector3Array，会将每 12 个字节（32 位）或每 24 个字节（64 位）的数据块会转换为一个 Vector3 变体。
注意：输入数组的大小必须为 12 或 24（取决于构建设置，详见 Vector3）的倍数。新数组的大小是 byte_array.size() / (12 或 24)。如果原数据无法转换为 Vector3 变体，则最终的数据未定义。
PackedVector4Array to_vector4_array() const 🔗
返回数据副本转换得到的 PackedVector4Array，会将每 16 个字节（32 位）或每 32 个字节（64 位）的数据块会转换为一个 Vector4 变体。
注意：输入数组的大小必须为 16 或 32（取决于构建设置，详见 Vector4）的倍数。新数组的大小是 byte_array.size() / (16 或 32)。如果原数据无法转换为 Vector4 变体，则最终的数据未定义。
运算符说明
bool operator !=(right: PackedByteArray) 🔗
如果数组内容不同，则返回 true。
PackedByteArray operator +(right: PackedByteArray) 🔗
返回新的 PackedByteArray，新数组的内容为此数组在末尾加上 right。为了提高性能，请考虑改用 append_array()。
bool operator ==(right: PackedByteArray) 🔗
如果两个数组的内容相同，即对应索引号的字节相等，则返回 true。
返回索引 index 处的字节。负数索引可以从末尾开始访问元素。使用越界的索引会报错。
请注意，返回的字节是 64 位 int。