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

PackedByteArray ( PackedByteArray from )

PackedByteArray

PackedByteArray ( Array from )

方法

bool

append ( int value )

void

append_array ( PackedByteArray array )

int

bsearch ( int value, bool before=true )

void

clear ( )

PackedByteArray

compress ( int compression_mode=0 ) const

int

count ( int value ) const

float

decode_double ( int byte_offset ) const

float

decode_float ( int byte_offset ) const

float

decode_half ( int byte_offset ) const

int

decode_s8 ( int byte_offset ) const

int

decode_s16 ( int byte_offset ) const

int

decode_s32 ( int byte_offset ) const

int

decode_s64 ( int byte_offset ) const

int

decode_u8 ( int byte_offset ) const

int

decode_u16 ( int byte_offset ) const

int

decode_u32 ( int byte_offset ) const

int

decode_u64 ( int byte_offset ) const

Variant

decode_var ( int byte_offset, bool allow_objects=false ) const

int

decode_var_size ( int byte_offset, bool allow_objects=false ) const

PackedByteArray

decompress ( int buffer_size, int compression_mode=0 ) const

PackedByteArray

decompress_dynamic ( int max_output_size, int compression_mode=0 ) const

PackedByteArray

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

encode_s8 ( int byte_offset, int value )

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

encode_u8 ( int byte_offset, int value )

void

encode_u16 ( int byte_offset, int value )

void

encode_u32 ( int byte_offset, int value )

void

encode_u64 ( int byte_offset, int value )

int

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

void

fill ( int value )

int

find ( int value, int from=0 ) const

String

get_string_from_ascii ( ) const

String

get_string_from_utf8 ( ) const

String

get_string_from_utf16 ( ) const

String

get_string_from_utf32 ( ) const

String

get_string_from_wchar ( ) const

bool

has ( int value ) const

bool

has_encoded_var ( int byte_offset, bool allow_objects=false ) const

String

hex_encode ( ) const

int

insert ( int at_index, int value )

bool

is_empty ( ) const

bool

push_back ( int value )

void

remove_at ( int index )

int

resize ( int new_size )

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

void

sort ( )

PackedFloat32Array

to_float32_array ( ) const

PackedFloat64Array

to_float64_array ( ) const

PackedInt32Array

to_int32_array ( ) const

PackedInt64Array

to_int64_array ( ) const

操作符

bool

operator != ( PackedByteArray right )

PackedByteArray

operator + ( PackedByteArray right )

bool

operator == ( PackedByteArray right )

int

operator [] ( int index )


构造函数说明

PackedByteArray PackedByteArray ( )

构造空的 PackedByteArray


PackedByteArray PackedByteArray ( PackedByteArray from )

构造给定 PackedByteArray 的副本。


PackedByteArray PackedByteArray ( Array from )

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


方法说明

bool append ( int value )

向数组末尾追加一个元素(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 常量。


int count ( int value ) const

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


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。如果无法解码有效的变体,或者其值派生自 Objectallow_objectsfalse,则返回 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_objectsfalse,则不允许派生自 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 的逆运算。


bool has ( int value ) const

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


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

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


String hex_encode ( ) const

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

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

int insert ( int at_index, int value )

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


bool is_empty ( ) const

该数组为空时,返回 true


bool push_back ( int value )

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


void remove_at ( int index )

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


int resize ( int new_size )

设置数组的大小。如果数组被增大,则保留数组末端的元素。如果数组被缩小,则将数组截断到新的大小。


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

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

如果 beginend 为负,则表示相对于数组的末尾(即 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


int operator [] ( int index )

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

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