17.4.11.2 Funzioni per lavorare coi vettori

Le funzioni seguenti permettono di gestire singoli elementi di un vettore:

awk_bool_t get_element_count(awk_array_t a_cookie, size_t *count);

Per il vettore rappresentato da a_cookie, restituisce in *count il numero di elementi in esso contenuti. Ogni sottovettore è conteggiato come se fosse un solo elemento. Restituisce false se si verifica un errore.

awk_bool_t get_array_element(awk_array_t a_cookie,

                             const awk_value_t *const index,

                             awk_valtype_t wanted,

                             awk_value_t *risultato);

Per il vettore rappresentato da a_cookie, restituisce in *risultato il valore dell’elemento il cui indice è index. wanted specifica il tipo di valore che si vuole ritrovare. Restituisce false se wanted non coincide con il tipo di dato o se index non è nel vettore (vedi Tabella 17.2).

Il valore per index può essere numerico, nel qual caso gawk lo converte in una stringa. Usare valori non interi è possibile, ma richiede di comprendere il modo con cui tali valori sono convertiti in stringhe (vedi la sezione Conversione di stringhe e numeri); per questo motivo, è meglio usare numeri interi.

Come per tutte le stringhe passate a gawk da un’estensione, la memoria che contiene il valore della stringa con chiave index deve essere stata acquisita utilizzando le funzioni gawk_malloc(), gawk_calloc() o gawk_realloc(), e gawk rilascerà (al momento opportuno) la relativa memoria.

awk_bool_t set_array_element(awk_array_t a_cookie,

                             const awk_value_t *const index,

                             const awk_value_t *const value);

Nel vettore rappresentato da a_cookie, crea o modifica l’elemento il cui indice è contenuto in index. I vettori ARGV ed ENVIRON non possono essere modificati, mentre il vettore PROCINFO è modificabile.

awk_bool_t set_array_element_by_elem(awk_array_t a_cookie,

                                     awk_element_t element);

Come set_array_element(), ma prende l’indice index e il valore value da element. Questa è una macro di utilità.

awk_bool_t del_array_element(awk_array_t a_cookie,

                             const awk_value_t* const index);

Elimina dal vettore, rappresentato da a_cookie, l’elemento con l’indice specificato. Restituisce true se l’elemento è stato rimosso o false se l’elemento non era presente nel vettore.

Le seguenti funzioni operano sull’intero vettore:

awk_array_t create_array(void);

Crea un nuovo vettore a cui si possono aggiungere elementi. Vedi la sezione Come creare e popolare vettori per una trattazione su come creare un nuovo vettore e aggiungervi elementi.

awk_bool_t clear_array(awk_array_t a_cookie);

Svuota il vettore rappresentato da a_cookie. Restituisce false in presenza di qualche tipo di problema, true in caso contrario. Il vettore non viene eliminato ma, dopo aver chiamato questa funzione, resta privo di elementi. Questo equivale a usare l’istruzione delete (vedi la sezione L’istruzione delete).

awk_bool_t flatten_array_typed(awk_array_t a_cookie,

                               awk_flat_array_t **data,

                               awk_valtype_t index_type,

                               awk_valtype_t value_type);

Per il vettore rappresentato da a_cookie, crea una struttura awk_flat_array_t e la riempie con indici e valori del tipo richiesto. Imposta il puntatore il cui indirizzo è passato in data per puntare a questa struttura. Restituisce true se tutto va bene o false in caso contrario. Vedi la sezione Lavorare con tutti gli elementi di un vettore, per una trattazione su come appiattire un vettore per poterci lavorare.

awk_bool_t flatten_array(awk_array_t a_cookie, awk_flat_array_t **data);

Per il vettore rappresentato da a_cookie, crea una struttura awk_flat_array_t e la riempie con indici di tipo AWK_STRING e valori AWK_UNDEFINED. Questa funzione è resa obsoleta da flatten_array_typed(). È fornita come macro, e mantenuta per convenienza e per compatibilità a livello di codice sorgente con la precedente versione dell’API.

awk_bool_t release_flattened_array(awk_array_t a_cookie,

                                   awk_flat_array_t *data);

Quando si è finito di lavorare con un vettore appiattito, si liberi la memoria usando questa funzione. Occorre fornire sia il cookie del vettore originale, sia l’indirizzo della struttura da liberare, awk_flat_array_t. La funzione restituisce true se tutto va bene, false in caso contrario.