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
位元組緊縮陣列。
說明
An array specifically designed to hold bytes (integers between 0 and 255). Packs data tightly, so it saves memory for large array sizes.
PackedByteArray also provides methods to encode/decode various types to/from bytes. The way values are encoded is an implementation detail and shouldn't be relied upon when interacting with external apps.
Note: Packed arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use duplicate(). This is not the case for built-in properties and methods. In these cases the returned packed array is a copy, and changing it will not affect the original value. To update a built-in property of this type, modify the returned array and then assign it to the property again.
Note: In a boolean context, a packed array will evaluate to false if it's empty. Otherwise, a packed array will always evaluate to true.
備註
使用 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)
Constructs a new PackedByteArray from a generic Array.
Boolean false and true are converted to 0 and 1 respectively.
Integers from the generic Array outside the byte range will overflow and roll over.
Floating-point numbers from the generic Array are converted to integers by truncating the decimal part. If the resulting integer is outside the byte range, it will overflow and roll over.
Strings from the generic Array are converted to integers using String.to_int(), with 0 as a fallback value if no integer can be parsed from the string. If the resulting integer is outside the byte range, it will overflow and roll over.
Other values from the generic Array that cannot be converted into an integer are initialized to 0.
print(PackedByteArray([true, false])) # Prints [1, 0]
print(PackedByteArray([-1, 0, 255, 256, 300])) # Prints [255, 0, 255, 0, 44]
print(PackedByteArray([-1.0, 0.0, 1.0, 1.9, 2.0, 500.0])) # Prints [255, 0, 1, 1, 2, 244]
print(PackedByteArray(["", "10", "123.456", "-1 but valid", "invalid"])) # Prints [0, 10, 123, 255, 0]
print(PackedByteArray([Object.new(), Callable(), Signal()])) # Prints [0, 0, 0]
方法說明
向陣列末尾追加一個元素(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 個位元組的資料,否則返回 null。
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 🔗
Returns a new PackedByteArray with the data decompressed. Set the compression mode using one of CompressionMode's constants. This method only accepts brotli, gzip, and deflate compression modes.
This method is potentially slower than decompress(), as it may have to re-allocate its output buffer multiple times while decompressing, whereas decompress() knows the size of its output buffer from the beginning.
GZIP has a maximal compression ratio of 1032:1, meaning it's very possible for a small compressed payload to decompress to a potentially very large output. To guard against this, you may provide a maximum size this function is allowed to allocate in bytes via max_output_size. Passing -1 will allow for unbounded output. If any positive value is passed, and the decompression exceeds that amount in bytes, then an error will be returned.
Note: Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header.
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) 🔗
Encodes a Variant at the index of byte_offset bytes. A sufficient space must be allocated, depending on the encoded variant's size. If allow_objects is false, Object-derived values are not permitted and will instead be serialized as ID-only. Returns the length of the encoded data in bytes.
在陣列中移除首次出現的某個值並回傳 true。如果陣列中不存在該值,則不會發生任何事情,回傳 false。要按照索引移除元素,請改用 remove_at()。
將陣列中的所有元素都設為給定的值。通常與 resize() 一起使用,建立給定大小的陣列並初始化元素。
int find(value: int, from: int = 0) const 🔗
在陣列中搜尋值並返回其索引,如果未找到則返回 -1 。可選地,可以傳遞起始搜尋索引。
回傳陣列中索引為 index 的位元組。如果 index 越界或為負數,則該方法失敗並回傳 0。
該方法類似於 [] 運算符(但不等價)。最顯著的區別就是從編輯器中執行時,該方法失敗不會暫停專案執行。
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。
在陣列的末尾追加一個元素。
Removes an element from the array by index. If index is out-of-bounds or negative, this method fails.
設定陣列的大小。如果陣列增大,則預留陣列末端的元素。如果陣列縮小,則將陣列截斷到新的大小。呼叫一次 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。