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 还提供了在许多类型和字节之间进行编码/解码的方法。这些值的编码方式属于实现细节，与外部应用程序交互时不应依赖这种编码。
备注
通过 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 常量。
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 则不限制输出。传入正数且解压超过该字节数时，会返回错误。
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 )
从数组中删除位于索引的元素。
设置数组的大小。如果数组被增大，则保留数组末端的元素。如果数组被缩小，则将数组截断到新的大小。
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。