Up to date
This page is up to date for Godot 4.2.
If you still find outdated information, please open an issue.
PackedByteArray¶
字节紧缩数组。
描述¶
专门设计用于存放字节的数组。数据是紧密存放的，因此能够在数组较大时节省内存。
PackedByteArray 还提供了在许多类型和字节之间进行编码/解码的方法。这些值的编码方式属于实现细节，与外部应用程序交互时不应依赖这种编码。
备注
通过 C# 使用这个 API 时有显著的不同。详见 C# API 与 GDScript 的差异。
构造函数¶
PackedByteArray ( ) |
|
PackedByteArray ( PackedByteArray from ) |
|
PackedByteArray ( Array from ) |
方法¶
void |
append_array ( PackedByteArray array ) |
void |
clear ( ) |
decode_double ( int byte_offset ) const |
|
decode_float ( int byte_offset ) const |
|
decode_half ( int byte_offset ) const |
|
decode_s16 ( int byte_offset ) const |
|
decode_s32 ( int byte_offset ) const |
|
decode_s64 ( int byte_offset ) const |
|
decode_u16 ( int byte_offset ) const |
|
decode_u32 ( int byte_offset ) const |
|
decode_u64 ( int byte_offset ) const |
|
decode_var ( int byte_offset, bool allow_objects=false ) const |
|
decode_var_size ( int byte_offset, bool allow_objects=false ) const |
|
decompress ( int buffer_size, int compression_mode=0 ) const |
|
decompress_dynamic ( int max_output_size, int compression_mode=0 ) const |
|
duplicate ( ) |
|
void |
encode_double ( int byte_offset, float value ) |
void |
encode_float ( int byte_offset, float value ) |
void |
encode_half ( int byte_offset, float value ) |
void |
|
void |
encode_s16 ( int byte_offset, int value ) |
void |
encode_s32 ( int byte_offset, int value ) |
void |
encode_s64 ( int byte_offset, int value ) |
void |
|
void |
encode_u16 ( int byte_offset, int value ) |
void |
encode_u32 ( int byte_offset, int value ) |
void |
encode_u64 ( int byte_offset, int value ) |
encode_var ( int byte_offset, Variant value, bool allow_objects=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 ( int byte_offset, bool allow_objects=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 != ( PackedByteArray right ) |
|
operator + ( PackedByteArray right ) |
|
operator == ( PackedByteArray right ) |
|
operator [] ( int index ) |
构造函数说明¶
PackedByteArray PackedByteArray ( )
构造空的 PackedByteArray。
PackedByteArray PackedByteArray ( PackedByteArray from )
构造给定 PackedByteArray 的副本。
PackedByteArray PackedByteArray ( Array from )
构造新 PackedByteArray。你还可以传入通用 Array 进行转换。
方法说明¶
向数组末尾追加一个元素（push_back 的别名）。
void append_array ( PackedByteArray array )
在该数组的末尾追加一个 PackedByteArray。
int bsearch ( int value, bool before=true )
使用二进法查找已有值的索引（如果该值尚未存在于数组中，则为保持排序顺序的插入索引）。传递 before 说明符是可选的。如果该参数为 false，则返回的索引位于数组中该值的所有已有的条目之后。
注意：在未排序的数组上调用 bsearch 会产生预料之外的行为。
void clear ( )
清空数组。相当于调用 resize 时指定大小为 0。
PackedByteArray compress ( int compression_mode=0 ) const
返回新的 PackedByteArray，其中的数据已压缩。请将压缩模式设置为 CompressionMode 常量。
返回元素在数组中出现的次数。
float decode_double ( int byte_offset ) const
将字节序列解码为 64 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
float decode_float ( int byte_offset ) const
将字节序列解码为 32 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
float decode_half ( int byte_offset ) const
将字节序列解码为 16 位浮点数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s8 ( int byte_offset ) const
将字节序列解码为 8 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s16 ( int byte_offset ) const
将字节序列解码为 16 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s32 ( int byte_offset ) const
将字节序列解码为 32 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_s64 ( int byte_offset ) const
将字节序列解码为 64 位有符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u8 ( int byte_offset ) const
将字节序列解码为 8 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u16 ( int byte_offset ) const
将字节序列解码为 16 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u32 ( int byte_offset ) const
将字节序列解码为 32 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
int decode_u64 ( int byte_offset ) const
将字节序列解码为 64 位无符号整数，起始位置字节偏移量为 byte_offset。字节数不足时会失败。如果无法解码有效的数字，则返回 0.0。
Variant decode_var ( int byte_offset, bool allow_objects=false ) const
将字节序列解码为 Variant，起始位置字节偏移量为 byte_offset。如果无法解码有效的变体，或者其值派生自 Object 而 allow_objects 为 false，则返回 null。
int decode_var_size ( int byte_offset, bool allow_objects=false ) const
将字节序列解码为 Variant 的大小，起始位置字节偏移量为 byte_offset。要求起始位置后至少有 4 个字节的数据，否则返回 null。
PackedByteArray decompress ( int buffer_size, int compression_mode=0 ) const
返回新的 PackedByteArray，其中的数据已解压。请将 buffer_size 设置为数据解压后的大小。请将压缩模式设置为 CompressionMode 常量。
注意：不保证解压缩可以处理未经 Godot 压缩的数据，例如，如果使用 deflate 压缩模式压缩的数据缺少校验和或标头。
PackedByteArray decompress_dynamic ( int max_output_size, int compression_mode=0 ) const
返回新的 PackedByteArray，其中的数据已解压。请将压缩模式设置为 CompressionMode 常量。这个方法只接受 brotli、gzip 和 deflate 压缩模式。
这个方法可能比 decompress 慢，因为在解压时可能需要多次重新分配输出缓冲区，而 decompress 则在一开始就知道输出缓冲区的大小。
GZIP 的最大压缩率为 1032:1，这意味着较小的压缩后负载很有可能解压出非常巨大的输出。为了防止这种情况，你可以通过 max_output_size 提供允许这个函数分配的最大字节数。传入 -1 则不限制输出。传入正数且解压超过该字节数时，会返回错误。
注意：不保证解压缩可以处理未经 Godot 压缩的数据，例如，如果使用 deflate 压缩模式压缩的数据缺少校验和或标头。
PackedByteArray duplicate ( )
创建该数组的副本，并将该副本返回。
void encode_double ( int byte_offset, float value )
将 64 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。
void encode_float ( int byte_offset, float value )
将 32 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。
void encode_half ( int byte_offset, float value )
将 16 位浮点数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。
void encode_s8 ( int byte_offset, int value )
将 8 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 1 个字节的空间。
void encode_s16 ( int byte_offset, int value )
将 16 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。
void encode_s32 ( int byte_offset, int value )
将 32 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。
void encode_s64 ( int byte_offset, int value )
将 64 位有符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。
void encode_u8 ( int byte_offset, int value )
将 8 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 1 个字节的空间。
void encode_u16 ( int byte_offset, int value )
将 16 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 2 个字节的空间。
void encode_u32 ( int byte_offset, int value )
将 32 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 4 个字节的空间。
void encode_u64 ( int byte_offset, int value )
将 64 位无符号整数编码为字节序列，起始位置字节偏移量为 byte_offset。从偏移量位置开始，该数组必须还分配有至少 8 个字节的空间。
int encode_var ( int byte_offset, Variant value, bool allow_objects=false )
将 Variant 编码为字节序列，起始位置字节偏移量为 byte_offset。必须分配有足够的空间，空间大小取决于编码后变体的大小。如果 allow_objects 为 false，则不允许派生自 Object 的值，只会将其 ID 进行序列化。
void fill ( int value )
将数组中的所有元素都设为给定的值。通常与 resize 一起使用，创建给定大小的数组并初始化元素。
int find ( int value, int from=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 的逆运算。
如果该数组包含 value，则返回 true。
bool has_encoded_var ( int byte_offset, bool allow_objects=false ) const
如果可以从字节偏移量 byte_offset 处解码出有效的 Variant，则返回 true。其他情况，或者当该值派生自 Object 而 allow_objects 为 false 时，则返回 false。
String hex_encode ( ) const
返回该数组的十六进制表示，类型为 String。
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 ( int at_index, int value )
在数组中给定的位置插入一个新元素。这个位置必须是有效的，或者是在数组的末端（idx == size()）。
bool is_empty ( ) const
该数组为空时，返回 true。
在数组的末尾追加一个元素。
void remove_at ( int index )
从数组中删除位于索引的元素。
设置数组的大小。如果数组被增大，则保留数组末端的元素。如果数组被缩小，则将数组截断到新的大小。调用一次 resize 并分配新值比逐个添加新元素要快。
void reverse ( )
将数组中的元素逆序排列。
int rfind ( int value, int from=-1 ) const
逆序搜索数组。还可以传递起始搜索位置索引。如果为负，则起始索引被视为相对于数组的结尾。
void set ( int index, int value )
改变给定索引处的字节。
int size ( ) const
返回数组中元素的个数。
PackedByteArray slice ( int begin, int end=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 != ( PackedByteArray right )
如果数组内容不同，则返回 true。
PackedByteArray operator + ( PackedByteArray right )
返回新的 PackedByteArray，新数组的内容为此数组在末尾加上 right。为了提高性能，请考虑改用 append_array。
bool operator == ( PackedByteArray right )
如果两个数组的内容相同，即对应索引号的字节相等，则返回 true。
返回索引 index 处的字节。负数索引可以从末尾开始访问元素。使用越界的索引会报错。
请注意，返回的字节是 64 位 int。