5.13 array -- Array efficienti di valori numerici

Questo modulo definisce un tipo di oggetto che può rappresentare in modo efficiente un array (NdT: vettore) di valori basilari: caratteri, interi, numeri in virgola mobile. Gli array sono tipi sequenza e si comportano in modo molto simile alle liste, tranne per il fatto che il tipo degli oggetti contenuti è vincolato. Il tipo viene specificato al momento della creazione dell'oggetto usando un singolo carattere chiamato type code. Vengono definiti i seguenti type code:

Type code  Tipo C  Tipo Python  Dimensione minima in byte 
'c' char character 1
'b' signed char int 1
'B' unsigned char int 1
'u' Py_UNICODE Unicode character 2
'h' signed short int 2
'H' unsigned short int 2
'i' signed int int 2
'I' unsigned int long 2
'l' signed long int 4
'L' unsigned long long 4
'f' float float 4
'd' double float 8

La rappresentazione reale dei valori viene determinata dall'architettura della macchina (strettamente parlando, dall'implementazione C). La dimensione reale può essere ottenuta attraverso l'attributo itemsize. I valori memorizzati per gli elementi 'L' e 'I' verranno rappresentati come interi long Python al momento del loro recupero, poiché il tipo dei normali interi Python non può rappresentare l'intera estensione degli interi(long) senza segno del C.

Il modulo definisce il seguente tipo:

array( typecode[, initializer])
Restituisce un nuovo array i cui elementi vengono limitati al tipo indicato da typecode ed inizializzati dal valore facoltativo initializer, che deve essere una lista o una stringa. La lista o la stringa viene passata al metodo fromlist(), fromstring() o fromunicode() del nuovo array (vedi in seguito) per aggiungere elementi iniziali all'array.

ArrayType
Sinonimo obsoleto di array.

Gli oggetti array supportano le ordinarie operazioni di indicizzazione, affettamento, concatenazione e moltiplicazione delle sequenze. Durante l'assegnazione di una fetta, il valore assegnato deve essere un oggetto array con lo stesso type code; in tutti gli altri casi, viene sollevata un'eccezione TypeError. Gli oggetti array implementano anche l'interfaccia buffer e possono essere utilizzati ovunque siano supportati gli oggetti buffer.

Vengono supportati anche i seguenti attributi e metodi:

typecode
Il carattere che indica il typecode utilizzato per creare l'array.

itemsize
La lunghezza in byte di un elemento dell'array nella rappresentazione interna.

append( x)
Aggiunge un nuovo elemento con valore x alla fine dell'array.

buffer_info( )
Restituisce una tupla (indirizzo, lunghezza) che fornisce l'indirizzo di memoria corrente e la lunghezza in elementi del buffer usato per contenere l'array. La dimensione in byte del buffer di memoria può essere calcolato come array.buffer_info()[1] * array.itemsize. Questo torna utile talvolta, quando si lavora con interfacce I/O a basso livello (e quindi insicure) che richiedono indirizzi di memoria, come alcune ioctl(). I numeri restituiti sono validi a patto che l'array esista e non vengano applicate operazioni su di esso che ne modifichino la lunghezza.

Note: Quando si usano oggetti array da codice scritto in C o C++ (il solo modo per fare effettivo utilizzo di questa informazione), ha più senso usare l'interfaccia buffer supportata dagli oggetti array. Questo metodo viene mantenuto per retrocompatibilità e bisognerebbe evitarlo nel nuovo codice. L'interfaccia buffer è documentata nel Python/C API Reference Manual.

byteswap( )
Esegue il ``Byteswap'' (NdT: lo scambio) dei byte di tutti gli elementi dell'array. Viene supportato solo per valori che hanno dimensione di 1, 2, 4 o 8 byte; per gli altri tipi di valori viene sollevata un'eccezione RuntimeError. Questo metodo è utile quando si leggono dati da un file scritto su una macchina che utilizza un ordine di byte differente.

count( x)
Restituisce il numero di occorrenze di x nell'array.

extend( iterable)
Aggiunge alla fine dell'array gli elementi di iterable. Se iterable è un altro array, dovrà avere esattamente lo stesso type code; altrimenti verrà sollevata l'eccezione TypeError. Se iterable non è un array, dovrà comunque essere iterabile ed i suoi elementi verranno aggiunti alla destra dell'array. Modificato nella versione 2.4: In passato, l'argomento poteva essere solamente un altro array.

fromfile( f, n)
Legge n elementi (come valori macchina) dall'oggetto file f e li aggiunge alla fine dell'array. Se sono disponibili meno di n elementi, viene sollevata un'eccezione EOFError, ma gli elementi che erano disponibili vengono comunque inseriti nell'array. f deve essere un vero oggetto file built-in; un altro oggetto, anche se possiede un metodo read(), non è sufficiente.

fromlist( list)
Aggiunge gli elementi della lista list. Equivale a "for x in list: a.append(x)" eccetto per il fatto che se viene rilevato un errore sul tipo, l'array rimane immutato.

fromstring( s)
Aggiunge elementi prendendoli dalla stringa s, interpretando la stringa come un array di valori macchina (come se fossero stati letti da un file usando il metodo fromfile()).

fromunicode( s)
Estende l'array con dati provenienti da una stringa unicode. L'array deve essere un array di tipo 'u'; altrimenti viene sollevata un'eccezione ValueError. Usate "array.fromstring(ustr.decode(enc))" per aggiungere dati Unicode ad un array di qualche altro tipo.

index( x)
Restituisce il più piccolo i tale che i sia l'indice della prima occorrenza di x nell'array.

insert( i, x)
Inserisce nell'array un nuovo elemento con valore x prima della posizione i. I valori negativi vengono trattati come relativi alla fine dell'array.

pop( [i])
Rimuove l'elemento di indice i dall'array e lo restituisce. Il valore predefinito dell'argomento facoltativo è -1, così che, senza argomenti, pop() rimuova e restituisca l'ultimo elemento.

read( f, n)
Deprecato dalla versione 1.5.1 di Python. Usate il metodo fromfile(). Legge n elementi (come valori macchina) dall'oggetto file f e li aggiunge alla fine dell'array. Se sono disponibili meno di n elementi, viene sollevata un'eccezione EOFError, ma gli elementi disponibili vengono comunque inseriti nell'array. f deve essere un vero oggetto file built-in; un altro oggetto, anche se possiede un metodo read(), non è sufficiente.

remove( x)
Rimuove la prima occorrenza di x dall'array.

reverse( )
Inverte l'ordine degli elementi dell'array.

tofile( f)
Scrive tutti gli elementi (come valori macchina) nell'oggetto file f.

tolist( )
Converte l'array in una normale lista con gli stessi elementi.

tostring( )
Converte l'array in un array di valori macchina e restituisce la rappresentazione sotto forma di stringa (la stessa sequenza di byte che verrebbero scritti in un file dal metodo tofile()).

tounicode( )
Converte l'array in una stringa unicode. L'array deve essere di tipo 'u'; altrimenti viene sollevata un'eccezione ValueError. Usate array.tostring().decode(enc) per ottenere una stringa unicode da un array di altro tipo.

write( f)
Deprecato dalla versione 1.5.1 di Python. Usate il metodo tofile(). Scrive tutti gli elementi (come valori macchina) nell'oggetto file f.

Quando un oggetto array viene stampato o convertito in una stringa, viene rappresentato come array(typecode, initializer). Il parametro initializer viene omesso se l'array è vuoto, è una stringa se il type code è 'c', altrimenti è una lista di numeri. Viene garantito che la stringa possa essere riconvertita in un array dello stesso tipo e valore usando gli apici inversi (``), a condizione che la funzione array() sia stata importata usando l'istruzione from array import array. Esempi:

array('l')
array('c', 'hello world')
array('u', u'hello \textbackslash u2641')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])

Vedete anche:

Modulo struct:
Impacchettamento e spacchettamento di dati binari eterogenei.
Modulo xdrlib:
Impacchettamento e spacchettamento di External Data Representation (NdT: rappresentazione di dati esterni) (XDR) come avviene in alcune chiamate di sistema di procedure remote.
Il manuale di Numerical Python
Le estensioni Numeric Python (NumPy) definiscono un altro tipo di array; vedete http://numpy.sourceforge.net/ per ulteriori informazioni circa Numerical Python. Una versione in PDF del manuale di NumPy è disponibile presso http://numpy.sourceforge.net/numdoc/numdoc.pdf.
Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.