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
Un array compatto di byte.
Descrizione
An array specifically designed to hold bytes. 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.
Nota
Ci sono differenze sostanziali quando si usa questa API con C#. Vedi Differenze dell'API C# rispetto a GDScript per maggiori informazioni.
Costruttori
PackedByteArray(from: PackedByteArray) |
|
PackedByteArray(from: Array) |
Metodi
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 |
Operatori
operator !=(right: PackedByteArray) |
|
operator +(right: PackedByteArray) |
|
operator ==(right: PackedByteArray) |
|
operator [](index: int) |
Descrizioni dei costruttori
PackedByteArray PackedByteArray() 🔗
Costruisce un PackedByteArray vuoto.
PackedByteArray PackedByteArray(from: PackedByteArray)
Costruisce un PackedByteArray come copia del PackedByteArray specificato.
PackedByteArray PackedByteArray(from: Array)
Costruisce un nuovo PackedByteArray. È possibile passare un Array generico che sarà convertito.
Descrizioni dei metodi
Aggiunge un elemento alla fine dell'array (pseudonimo di push_back()).
void append_array(array: PackedByteArray) 🔗
Accoda un PackedByteArray alla fine di questo array.
int bsearch(value: int, before: bool = true) const 🔗
Trova l'indice di un valore esistente (o l'indice di inserimento che mantiene l'ordine di ordinamento, se il valore non è ancora presente nell'array) utilizzando la ricerca binaria. Facoltativamente, è possibile passare uno specificatore before. Se false, l'indice restituito viene dopo tutte le voci esistenti del valore nell'array.
Nota: Chiamare bsearch() su un array non ordinato provoca un comportamento imprevisto.
void bswap16(offset: int = 0, count: int = -1) 🔗
Scambia l'ordine dei byte di count segmenti a 16 bit nell'array a partire da offset. Lo scambio viene eseguito sul posto. Se count è minore di zero, vengono elaborati tutti i segmenti fino alla fine dell'array; se la dimensione dei dati elaborati non è un multiplo di 2, il byte successivo all'ultimo segmento a 16 bit elaborato non viene modificato.
void bswap32(offset: int = 0, count: int = -1) 🔗
Scambia l'ordine dei byte di count segmenti a 32 bit nell'array a partire da offset. Lo scambio viene eseguito sul posto. Se count è minore di zero, vengono elaborati tutti i segmenti fino alla fine dell'array; se la dimensione dei dati elaborati non è un multiplo di 4, il byte successivo all'ultimo segmento a 32 bit elaborato non viene modificato.
void bswap64(offset: int = 0, count: int = -1) 🔗
Scambia l'ordine dei byte di count segmenti a 64 bit nell'array a partire da offset. Lo scambio viene eseguito sul posto. Se count è minore di zero, vengono elaborati tutti i segmenti fino alla fine dell'array; se la dimensione dei dati elaborati non è un multiplo di 8, il byte successivo all'ultimo segmento a 64 bit elaborato non viene modificato.
void clear() 🔗
Cancella l'array. Ciò equivale a usare resize() con una dimensione di 0.
PackedByteArray compress(compression_mode: int = 0) const 🔗
Restituisce un nuovo PackedByteArray con i dati compressi. Imposta la modalità di compressione utilizzando una delle costanti di CompressionMode.
Restituisce il numero di volte che un elemento è presente nell'array.
float decode_double(byte_offset: int) const 🔗
Decodifica un numero in virgola mobile a 64 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
float decode_float(byte_offset: int) const 🔗
Decodifica un numero in virgola mobile a 32 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
float decode_half(byte_offset: int) const 🔗
Decodifica un numero in virgola mobile a 16 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_s8(byte_offset: int) const 🔗
Decodifica un numero intero con segno a 8 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_s16(byte_offset: int) const 🔗
Decodifica un numero intero con segno a 16 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_s32(byte_offset: int) const 🔗
Decodifica un numero intero con segno a 32 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_s64(byte_offset: int) const 🔗
Decodifica un numero intero con segno a 64 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_u8(byte_offset: int) const 🔗
Decodifica un numero intero senza segno a 8 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_u16(byte_offset: int) const 🔗
Decodifica un numero intero senza segno a 16 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_u32(byte_offset: int) const 🔗
Decodifica un numero intero senza segno a 32 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
int decode_u64(byte_offset: int) const 🔗
Decodifica un numero intero senza segno a 64 bit dai byte che iniziano da byte_offset. Fallisce se il numero dei byte è insufficiente. Restituisce 0.0 se non è possibile decodificare un numero valido.
Variant decode_var(byte_offset: int, allow_objects: bool = false) const 🔗
Decodifica una Variant dai byte che iniziano da byte_offset. Restituisce null se una variante valida non può essere decodificata o se il valore deriva da Object e allow_objects è false.
int decode_var_size(byte_offset: int, allow_objects: bool = false) const 🔗
Decodifica la dimensione di una Variant dai byte che iniziano da byte_offset. Richiede almeno 4 byte di dati che iniziano dall'offset, altrimenti fallisce.
PackedByteArray decompress(buffer_size: int, compression_mode: int = 0) const 🔗
Restituisce un nuovo PackedByteArray con i dati decompressi. Imposta buffer_size sulla dimensione dei dati non compressi. Imposta la modalità di compressione usando una delle costanti di CompressionMode.
Nota: Non è garantito che la decompressione funzioni con dati non compressi da Godot, ad esempio se i dati compressi con la modalità di compressione deflate non hanno un checksum o un'intestazione.
PackedByteArray decompress_dynamic(max_output_size: int, compression_mode: int = 0) const 🔗
Restituisce un nuovo PackedByteArray con i dati decompressi. Imposta la modalità di compressione usando una delle costanti di CompressionMode. Questo metodo accetta solo le modalità di compressione brotli, gzip e deflate.
Questo metodo è potenzialmente più lento di decompress(), poiché potrebbe dover riallocare il suo buffer di output più volte durante la decompressione, mentre decompress() conosce la dimensione del suo buffer di output dall'inizio.
GZIP ha un rapporto di compressione massimo di 1032:1, il che significa che è molto probabile che un piccolo payload compresso si decomprima in un output potenzialmente molto grande. Per proteggersi da questo, puoi fornire una dimensione massima che questa funzione può allocare in byte tramite max_output_size. Passando -1 sarà consentito un output illimitato. Se viene passato un valore positivo e la decompressione supera tale quantità in byte, verrà restituito un errore.
Nota: Non è garantito che la decompressione funzioni con dati non compressi da Godot, ad esempio se i dati compressi con la modalità di compressione deflate non hanno un checksum o un'intestazione.
PackedByteArray duplicate() const 🔗
Crea una copia dell'array, e la restituisce.
void encode_double(byte_offset: int, value: float) 🔗
Codifica un numero in virgola mobile a 64 bit come byte all'indice di byte_offset byte. L'array deve avere almeno 8 byte di spazio allocato, a partire dall'offset.
void encode_float(byte_offset: int, value: float) 🔗
Codifica un numero in virgola mobile a 32 bit come byte all'indice di byte_offset byte. L'array deve avere almeno 4 byte di spazio, a partire dall'offset.
void encode_half(byte_offset: int, value: float) 🔗
Codifica un numero in virgola mobile a 16 bit come byte all'indice di byte_offset byte. L'array deve avere almeno 2 byte di spazio allocato, a partire dall'offset.
void encode_s8(byte_offset: int, value: int) 🔗
Codifica un numero intero con segno a 8 bit (byte con segno) all'indice di byte_offset byte. L'array deve avere almeno 1 byte di spazio, a partire dall'offset.
void encode_s16(byte_offset: int, value: int) 🔗
Codifica un numero intero con segno a 16 bit all'indice di byte_offset byte. L'array deve avere almeno 2 byte di spazio, a partire dall'offset.
void encode_s32(byte_offset: int, value: int) 🔗
Codifica un numero intero con segno a 32 bit all'indice di byte_offset byte. L'array deve avere almeno 4 byte di spazio, a partire dall'offset.
void encode_s64(byte_offset: int, value: int) 🔗
Codifica un numero intero con segno a 64 bit all'indice di byte_offset byte. L'array deve avere almeno 8 byte di spazio, a partire dall'offset.
void encode_u8(byte_offset: int, value: int) 🔗
Codifica un numero intero senza segno a 8 bit (byte) all'indice di byte_offset byte. L'array deve avere almeno 1 byte di spazio, a partire dall'offset.
void encode_u16(byte_offset: int, value: int) 🔗
Codifica un numero intero senza segno a 16 bit all'indice di byte_offset byte. L'array deve avere almeno 2 byte di spazio, a partire dall'offset.
void encode_u32(byte_offset: int, value: int) 🔗
Codifica un numero intero senza segno a 32 bit all'indice di byte_offset byte. L'array deve avere almeno 4 byte di spazio, a partire dall'offset.
void encode_u64(byte_offset: int, value: int) 🔗
Codifica un numero intero senza segno a 64 bit all'indice di byte_offset byte. L'array deve avere almeno 8 byte di spazio, a partire dall'offset.
int encode_var(byte_offset: int, value: Variant, allow_objects: bool = false) 🔗
Codifica una Variant all'indice di byte_offset byte. Deve essere allocato uno spazio sufficiente, a seconda della dimensione della variante codificata. Se allow_objects è false, i valori derivati da Object non sono consentiti e soltanto i loro ID saranno serializzati.
Rimuove la prima occorrenza di un valore dall'array e restituisce true. Se il valore non esiste nell'array, nulla accade e viene restituito false. Per rimuovere un elemento in base all'indice, utilizzare invece remove_at().
Assegna il valore specificato a tutti gli elementi nell'array. Questo può solitamente essere usato insieme a resize() per creare un array con una determinata dimensione ed elementi inizializzati.
int find(value: int, from: int = 0) const 🔗
Cerca un valore nell'array e restituisce il suo indice o -1 se non trovato. Facoltativamente, può essere passato l'indice di ricerca iniziale.
Returns the byte at the given index in the array. If index is out-of-bounds or negative, this method fails and returns 0.
This method is similar (but not identical) to the [] operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor.
String get_string_from_ascii() const 🔗
Converte un array codificato con ASCII/Latin-1 in String. Alternativa veloce a get_string_from_utf8() se il contenuto è solo ASCII/Latin-1. A differenza della funzione UTF-8, questa funzione mappa ogni byte a un carattere nell'array. Le sequenze multibyte non saranno interpretate correttamente. Per elaborare l'input dell'utente, utilizza sempre get_string_from_utf8(). Questo è l'inverso di String.to_ascii_buffer().
String get_string_from_multibyte_char(encoding: String = "") const 🔗
Converte un array codificato con code page multibyte di sistema in String. Se la conversione fallisce, viene restituita una stringa vuota. Questo è l'inverso di String.to_multibyte_char_buffer().
I valori consentiti per encoding dipendono dal sistema. Se encoding è una stringa vuota, viene utilizzata la codifica predefinita del sistema.
Per Windows, consultare i nomi .NET per i Code Page Identifiers.
Per macOS e Linux/BSD, consultare la documentazione della libreria
libiconveiconv --listper un elenco delle codifiche supportate.
String get_string_from_utf8() const 🔗
Converte un array codificato con UTF-8 in String. Più lento di get_string_from_ascii() ma supporta dati codificati con UTF-8. Usa questa funzione se non si è sicuri dell'origine dei dati. Per l'input dell'utente questa funzione dovrebbe sempre essere preferita. Restituisce una stringa vuota se l'array sorgente non è una stringa UTF-8 valida. Questo è l'inverso di String.to_utf8_buffer().
String get_string_from_utf16() const 🔗
Converte un array codificato in UTF-16 in String. Se il BOM manca, si presume l'ordine dei byte "little" . Restituisce una stringa vuota se l'array sorgente non è una stringa UTF-16 valida. Questo è l'inverso di String.to_utf16_buffer().
String get_string_from_utf32() const 🔗
Converte un array codificato con UTF-32 in String. Restituisce una stringa vuota se l'array sorgente non è una stringa UTF-32 valida. Questo è l'inverso di String.to_utf32_buffer().
String get_string_from_wchar() const 🔗
Converte un array codificato con caratteri estesi (wchar_t, UTF-16 su Windows, UTF-32 su altre piattaforme) in String. Restituisce una stringa vuota se l'array sorgente non è una stringa estesa valida. Questo è l'inverso di String.to_wchar_buffer().
Restituisce true se l'array contiene value.
bool has_encoded_var(byte_offset: int, allow_objects: bool = false) const 🔗
Restituisce true se un valore Variant valido può essere decodificato nell'offset byte_offset. Restituisce false in caso contrario o quando il valore è derivato da Object e allow_objects è false.
Restituisce una rappresentazione esadecimale di questo array come String.
var array = PackedByteArray([11, 46, 255])
print(array.hex_encode()) # Stampa "0b2eff"
var array = new byte[] {11, 46, 255};
GD.Print(array.HexEncode()); // Stampa "0b2eff"
int insert(at_index: int, value: int) 🔗
Inserisce un nuovo elemento in una determinata posizione nell'array. La posizione deve essere valida o alla fine dell'array (idx == size()).
Restituisce true se l'array è vuoto.
Appende un elemento alla fine dell'array.
Rimuove un elemento dall'array in base all'indice.
Imposta la dimensione dell'array. Se l'array viene ingrandito, riserva gli elementi alla fine dell'array. Se l'array viene rimpicciolito, tronca l'array alla nuova dimensione. Chiamare resize() una sola volta e assegnare i nuovi valori è più veloce che aggiungere nuovi elementi uno alla volta.
Restituisce @GlobalScope.OK in caso di successo, oppure una delle seguenti costanti di Error se questo metodo fallisce: @GlobalScope.ERR_INVALID_PARAMETER se la dimensione è negativa, oppure @GlobalScope.ERR_OUT_OF_MEMORY se le allocazioni falliscono. Usare size() per trovare la dimensione effettiva dell'array dopo il ridimensionamento.
void reverse() 🔗
Inverte l'ordine degli elementi nell'array.
int rfind(value: int, from: int = -1) const 🔗
Cerca nell'array in ordine inverso. Facoltativamente, può essere passato un indice di ricerca iniziale. Se negativo, l'indice di inizio è considerato relativo alla fine dell'array.
void set(index: int, value: int) 🔗
Modifica il byte all'indice specificato.
Restituisce il numero di elementi nell'array.
PackedByteArray slice(begin: int, end: int = 2147483647) const 🔗
Restituisce la sezione del PackedByteArray, da begin (incluso) a end (escluso), sotto forma di un nuovo PackedByteArray.
Il valore assoluto di begin e end sarà limitato alla dimensione dell'array, quindi il valore predefinito per end lo suddivide alla dimensione dell'array per impostazione predefinita (ad esempio, arr.slice(1) è un'abbreviazione per arr.slice(1, arr.size())).
Se begin o end sono negativi, saranno relativi alla fine dell'array (ad esempio, arr.slice(0, -2) è un'abbreviazione per arr.slice(0, arr.size() - 2)).
void sort() 🔗
Ordina gli elementi dell'array in ordine crescente.
PackedColorArray to_color_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedColorArray, dove ogni blocco di 16 byte è stato convertito in un variante di tipo Color
Nota: La dimensione dell'array in input deve essere un multiplo di 16 (dimensione di quattro float a 32 bit). La dimensione del nuovo array sarà byte_array.size() / 16. Se non è possibile convertire i dati originali in varianti Color, i dati risultanti sono indefiniti.
PackedFloat32Array to_float32_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedFloat32Array, dove ogni blocco di 4 byte è stato convertito in un float a 32 bit (float in C++).
La dimensione dell'array in input deve essere un multiplo di 4 (dimensione di float a 32 bit). La dimensione del nuovo array sarà byte_array.size() / 4.
Se non è possibile convertire i dati originali convertiti in float a 32 bit, i dati risultanti sono indefiniti.
PackedFloat64Array to_float64_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedFloat32Array, dove ogni blocco di 8 byte è stato convertito in un float a 64 bit (double in C++).
La dimensione dell'array in input deve essere un multiplo di 8 (dimensione di double a 64 bit). La dimensione del nuovo array sarà byte_array.size() / 8.
Se non è possibile convertire i dati originali in float a 64 bit, i dati risultanti sono indefiniti.
PackedInt32Array to_int32_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedInt32Array, dove ogni blocco di 4 byte è stato convertito in un intero con segno a 32 bit (int32_t in C++).
La dimensione dell'array in input deve essere un multiplo di 4 (dimensione di intero a 32 bit). La dimensione del nuovo array sarà byte_array.size() / 4.
Se non è possibile convertire i dati originali in interi con segno a 32 bit, i dati risultanti sono indefiniti.
PackedInt64Array to_int64_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedInt32Array, dove ogni blocco di 8 byte è stato convertito in un intero con segno a 64 bit (int64_t in C++).
La dimensione dell'array in input deve essere un multiplo di 8 (dimensione di intero a 64 bit). La dimensione del nuovo array sarà byte_array.size() / 8.
Se non è possibile convertire i dati originali in interi con segno a 64 bit, i dati risultanti sono indefiniti.
PackedVector2Array to_vector2_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedVector2Array, dove ogni blocco di 8 o 16 byte (32 bit o 64 bit) è stato convertito in un variante di tipo Vector2
Nota: La dimensione dell'array in input deve essere un multiplo di 8 o 16 (a seconda della configurazione della build, vedi Vector2 per più dettagli). La dimensione del nuovo array sarà byte_array.size() / (8 o 16). Se non è possibile convertire i dati originali in varianti Vector2, i dati risultanti sono indefiniti.
PackedVector3Array to_vector3_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedVector3Array, dove ogni blocco di 12 o 24 byte (32 bit o 64 bit) è stato convertito in un variante di tipo Vector3
Nota: La dimensione dell'array in input deve essere un multiplo di 12 o 24 (a seconda della configurazione della build, vedi Vector3 per più dettagli). La dimensione del nuovo array sarà byte_array.size() / (12 o 24). Se non è possibile convertire i dati originali in varianti Vector3, i dati risultanti sono indefiniti.
PackedVector4Array to_vector4_array() const 🔗
Restituisce una copia dei dati convertiti in un PackedVector4Array, dove ogni blocco di 16 o 32 byte (32 bit o 64 bit) è stato convertito in un variante di tipo Vector4
Nota: La dimensione dell'array in input deve essere un multiplo di 16 o 32 (a seconda della configurazione della build, vedi Vector4 per più dettagli). La dimensione del nuovo array sarà byte_array.size() / (16 o 32). Se non è possibile convertire i dati originali in varianti Vector4, i dati risultanti sono indefiniti.
Descrizioni degli operatori
bool operator !=(right: PackedByteArray) 🔗
Restituisce true se i contenuti degli array differiscono.
PackedByteArray operator +(right: PackedByteArray) 🔗
Restituisce un nuovo PackedByteArray con il contenuto di right accodato alla fine di questo array. Per prestazioni migliori, considera invece di usare append_array().
bool operator ==(right: PackedByteArray) 🔗
Restituisce true se il contenuto di entrambi gli array è lo stesso, ovvero hanno tutti i byte uguali agli indici corrispondenti.
Restituisce il byte all'indice index. Gli indici negativi possono essere utilizzati per accedere agli elementi partendo dalla fine. Utilizzare un indice fuori dai limiti dell'array genererà un errore.
Nota che il byte è restituito come un int a 64 bit.