Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
PackedByteArray
字节紧缩数组。
描述
专门设计用于保存字节的数组。紧缩数组紧密打包数据，因此可为大型数组节省内存。
PackedByteArray 还提供了将各种类型编码为字节/从字节解码的方法。值的编码方式是实现细节，在与外部应用程序交互时不应依赖它。
注意：打包数组始终通过引用传递。要获取可以独立于原始数组进行修改的数组副本，请使用 duplicate()。内置属性和方法并非如此。这些返回的打包数组是副本，更改它不会影响原始值。要更新内置属性，需要修改返回的数组，然后再次将其分配给该属性。
Note
通过 C# 使用该 API 时会有显著不同，详见 C# API differences to GDScript。
构造函数
PackedByteArray(from: PackedByteArray) |
|
PackedByteArray(from: Array) |
方法
void |
append_array(array: PackedByteArray) |
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 |
|
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_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_float32_array() const |
|
to_float64_array() const |
|
to_int32_array() const |
|
to_int64_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) 🔗
使用二进法查找已有值的索引（如果该值尚未存在于数组中，则为保持排序顺序的插入索引）。传递 before 说明符是可选的。如果该参数为 false，则返回的索引位于数组中该值的所有已有的条目之后。
注意：在未排序的数组上调用 bsearch() 会产生预料之外的行为。
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() 🔗
创建该数组的副本，并将该副本返回。
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 进行序列化。
将数组中的所有元素都设为给定的值。通常与 resize() 一起使用，创建给定大小的数组并初始化元素。
int find(value: int, from: int = 0) const 🔗
在数组中搜索值并返回其索引，如果未找到则返回 -1 。可选地，可以传递起始搜索索引。
返回数组中位于给定索引 index 处的字节。与使用 [] 运算符相同（array[index]）。
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() 的逆运算。
如果该数组包含 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() 并分配新值比逐个添加新元素要快。
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() 🔗
将该数组中的元素按升序排列。
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。
返回索引 index 处的字节。负数索引可以从末尾开始访问元素。使用越界的索引会报错。
请注意，返回的字节是 64 位 int。