org.python.core

Class PyArray

java.lang.Object

org.python.core.PyObject

org.python.core.PySequence

org.python.core.PyArray

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, BufferProtocol, Traverseproc

Direct Known Subclasses:

PyArrayDerived

public class PyArray
extends PySequence
implements java.lang.Cloneable, BufferProtocol, Traverseproc

The type array.array. This is a wrapper around native Java arrays. Instances of PyArray are created either by Java functions or directly by the jarray module (q.v.).

The range of possible element (item) types exceeds that in Python, since it allows for arbitrary Java classes. This extended behaviour is accessible from Python by supplying a Java type (class) to the constructor, where one might have used a single character type code. For example:

 >>> ax = array.array(BigDecimal, (BigDecimal(str(n)) for n in range(5)))
 >>> ax
 array(java.math.BigDecimal, [0, 1, 2, 3, 4])
 >>> type(ax[2])
 <type 'java.math.BigDecimal'>
 

Supported item types

typecode	Python type	Java type	serialised size	signed
b	int	byte	1
B	int	byte	1	unsigned
h	int	short	2
H	int	short	2	unsigned
i	int	int	4
I	long	int	4	unsigned
l	long	long	8
L	long	long	8	unsigned
f	float	float	4
d	float	double	8
c	str	byte	1	unsigned
u	unicode	int	1	unsigned
z	bool	boolean	1

Types shown as "unsigned" represent positive values encoded in the same number of bits as the equivalent signed type. The Java value serialised makes no distinction. The consumer of the stream has to know whether to make a signed or unsigned interpretation of the bits. When reading a stream, the type code declared for the destination array decides the interpretation of the bytes.

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class org.python.core.PyObject

PyObject.ConversionException

Field Summary

Fields

Modifier and Type	Field and Description
static PyType	TYPE

Fields inherited from class org.python.core.PyObject

gcMonitorGlobal

Constructor Summary

Constructors

Constructor and Description
PyArray(java.lang.Class<?> itemClass, int n) Create a PyArray with the given array item class and number of zero or null elements.
PyArray(java.lang.Class<?> itemClass, java.lang.Object data) Create a PyArray with the given array item class and content.
PyArray(java.lang.Class<?> itemClass, PyObject initial) Create a PyArray with the given array item class and content initialised from a Python object (iterable).
PyArray(PyArray toCopy) Create a PyArray as a copy of another.
PyArray(PyType subtype) Create a default PyArray of specific Python type (for sub-class use).

Method Summary

Modifier and Type	Method and Description
PyObject	__add__(PyObject other) Equivalent to the standard Python __add__ method.
PyObject	__iadd__(PyObject other) Equivalent to the standard Python __iadd__ method.
PyObject	__imul__(PyObject o) Equivalent to the standard Python __imul__ method.
int	__len__() Length of the array (as the number of elements, not a storage size).
PyObject	__mul__(PyObject o) Equivalent to the standard Python __mul__ method.
PyObject	__reduce__() Used for pickling.
PyObject	__rmul__(PyObject o) Equivalent to the standard Python __rmul__ method.
java.lang.Object	__tojava__(java.lang.Class<?> c) Equivalent to the Jython __tojava__ method.
void	append(PyObject value) Append new value x to the end of the array.
PyObject	array___iter__()
void	array_append(PyObject value)
void	array_byteswap()
static java.lang.Class<?>	array_class(java.lang.Class<?> type)
int	array_count(PyObject value)
void	array_extend(PyObject iterable)
void	array_fromfile(PyObject f, int count)
void	array_fromlist(PyObject obj)
int	array_index(PyObject value)
void	array_insert(int index, PyObject value)
PyObject	array_pop(int i) Removes the item at the index i from the array and returns it.
void	array_remove(PyObject value)
void	array_reverse()
void	array_tofile(PyObject f)
PyObject	array_tolist()
PyObject	array_tostring()
PyUnicode	array_tounicode()
void	array_write(PyObject f)
static PyArray	array(PyObject seq, char typecode) Create a PyArray with the given array item type and content initialised from a Python object (iterable).
static PyArray	array(PyObject init, java.lang.Class<?> itemClass) Create a PyArray storing ctype types and being initialised with init.
void	byteswap() "Byteswap" all items of the array.
static java.lang.Class<?>	char2class(char typecode) Converts a character code for the array type to the Java Class of the elements of the implementation array.
java.lang.Object	clone() Implementation of Cloneable interface.
PyInteger	count(PyObject value) Return the number of occurrences of x in the array.
void	extend(PyObject iterable) Append items from iterable to the end of the array.
int	fillFromStream(java.io.InputStream is) Fill the current array with primitive values (of the type the array holds) from a stream, starting at array index zero, up to the capacity of the array, without resizing.
void	fromfile(PyObject f, int count) Read count items (as machine values) from the file object f and append them to the end of the array.
void	fromlist(PyObject obj) Append items from the list.
int	fromstring(int start, java.lang.String input) Read primitive values from a stream into a slice of the array, defined by a start and the number of items encoded in the bytes.
void	fromstring(PyObject input) Append items from the object, which is a byte string of some kind (PyString or object with the buffer interface providing bytes).
void	fromstring(java.lang.String input) Append items from the string, interpreting the string as an array of bytes (as if it had been read from a file using the fromfile() method).
void	fromunicode(PyUnicode input)
java.lang.Object	getArray() Return the internal Java array storage of the PyArray instance
PyBuffer	getBuffer(int flags) Method by which the consumer requests the buffer from the exporter.
int	getItemsize() Getter for the item size of the array element type.
int	getStorageSize() Deprecated. Use getItemsize() instead which (since 2.7.3) gives the same result.
java.lang.String	getTypecode() Return either a Python-style array.array type code for the element (item) type or the Java class name.
int	hashCode()
PyObject	index(PyObject value) Return the smallest i such that i is the index of the first occurrence of value in the array.
void	insert(int index, PyObject value) Insert a new item with value value in the array before position index.
PyObject	pop() Removes the last item from the array and return it.
PyObject	pop(int index) Removes the item with the index index from the array and returns it.
boolean	refersDirectlyTo(PyObject ob) Optional operation.
void	remove(PyObject value) Remove the first occurrence of value from the array.
void	reverse() Reverse the elements in the array
void	set(int i, byte value) Set element in an array of element type 'b','B', or 'c' to a Java byte.
void	set(int i, char value) Set element to integer value given as a Java char, tolerating primitive integer values in arrays of Unicode character, int or long.
void	set(int i, int value) Set element to integer value, tolerating primitive integer values in arrays of Unicode character, int or long.
void	set(int i, PyObject value) Set an element in the array - the index needs to exist, this method does not automatically extend the array.
void	tofile(PyObject f) Write all items (as machine values) to the file object f.
PyObject	tolist() Convert the array to an ordinary list with the same items.
int	toStream(java.io.OutputStream os) Generic stream writer to write the entire contents of the array to the stream as primitive types.
java.lang.String	tostring() Convert the array to an array of machine values and return the string representation (the same sequence of bytes that would be written to a file by the tofile() method.)
java.lang.String	toString()
java.lang.String	tounicode()
int	traverse(Visitproc visit, java.lang.Object arg) Traverses all directly contained PyObjects.
static PyArray	zeros(int n, char typecode) Create a PyArray with the given array type code and number of zero elements.
static PyArray	zeros(int n, java.lang.Class<?> itemClass) Create a PyArray with the given array item class and number of zero or null elements.

Methods inherited from class org.python.core.PySequence

__delitem__, __delslice__, __eq__, __finditem__, __finditem__, __ge__, __getitem__, __getslice__, __gt__, __iter__, __le__, __lt__, __ne__, __nonzero__, __setitem__, __setitem__, __setslice__, isMappingType, isNumberType, isSequenceType

Methods inherited from class org.python.core.PyObject

__abs__, __and__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __call__, __cmp__, __coerce__, __coerce_ex__, __complex__, __contains__, __delattr__, __delattr__, __delete__, __delitem__, __delslice__, __dir__, __div__, __divmod__, __ensure_finalizer__, __findattr__, __findattr__, __findattr_ex__, __finditem__, __float__, __floordiv__, __format__, __get__, __getattr__, __getattr__, __getitem__, __getnewargs__, __getslice__, __hash__, __hex__, __iand__, __idiv__, __idivmod__, __ifloordiv__, __ilshift__, __imod__, __index__, __int__, __invert__, __ior__, __ipow__, __irshift__, __isub__, __iternext__, __itruediv__, __ixor__, __long__, __lshift__, __mod__, __neg__, __not__, __oct__, __or__, __pos__, __pow__, __pow__, __radd__, __rand__, __rdiv__, __rdivmod__, __reduce_ex__, __reduce_ex__, __repr__, __rfloordiv__, __rlshift__, __rmod__, __ror__, __rpow__, __rrshift__, __rshift__, __rsub__, __rtruediv__, __rxor__, __set__, __setattr__, __setattr__, __setitem__, __setslice__, __str__, __sub__, __truediv__, __trunc__, __unicode__, __xor__, _add, _and, _callextra, _cmp, _div, _divmod, _doget, _doget, _doset, _eq, _floordiv, _ge, _gt, _iadd, _iand, _idiv, _idivmod, _ifloordiv, _ilshift, _imod, _imul, _in, _ior, _ipow, _irshift, _is, _isnot, _isub, _itruediv, _ixor, _jcall, _jcallexc, _jthrow, _le, _lshift, _lt, _mod, _mul, _ne, _notin, _or, _pow, _rshift, _sub, _truediv, _xor, asDouble, asIndex, asIndex, asInt, asInt, asIterable, asLong, asLong, asName, asName, asString, asString, asStringOrNull, asStringOrNull, bit_length, conjugate, delDict, delType, dispatch__init__, equals, fastGetClass, fastGetDict, getDict, getType, implementsDescrDelete, implementsDescrGet, implementsDescrSet, invoke, invoke, invoke, invoke, invoke, invoke, isCallable, isDataDescr, isIndex, isInteger, noAttributeError, object___subclasshook__, readonlyAttributeError, setDict, setType

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

TYPE

public static final PyType TYPE

Constructor Detail

PyArray

public PyArray(PyType subtype)

Create a default PyArray of specific Python type (for sub-class use).

Parameters:

subtype - actual Python type

PyArray

public PyArray(java.lang.Class<?> itemClass,
               java.lang.Object data)

Create a PyArray with the given array item class and content. If itemClass is one of the primitive types used to implement the "single letter" type codes, the type code of the array will be a signed zero of that item class.

Parameters:

itemClass - of elements in the array

data - content array

PyArray

public PyArray(java.lang.Class<?> itemClass,
               PyObject initial)

Create a PyArray with the given array item class and content initialised from a Python object (iterable).

Parameters:

itemClass - of elements in the array

initial - provider of initial contents

PyArray

public PyArray(java.lang.Class<?> itemClass,
               int n)

Create a PyArray with the given array item class and number of zero or null elements. If itemClass is one of the primitive types used to implement the "single letter" type codes, the type code of the array will be a signed zero of that item class.

Parameters:

itemClass - of elements in the array

n - number of (zero or null) elements

PyArray

public PyArray(PyArray toCopy)

Create a PyArray as a copy of another.

Parameters:

toCopy - the other array

Method Detail

zeros

public static PyArray zeros(int n,
                            char typecode)

Create a PyArray with the given array type code and number of zero elements.

Parameters:

typecode - of elements in the array

n - number of (zero or null) elements

Returns:

created array

zeros

public static PyArray zeros(int n,
                            java.lang.Class<?> itemClass)

Create a PyArray with the given array item class and number of zero or null elements. If itemClass is one of the primitive types used to implement the "single letter" type codes, the type code of the array will be a signed zero of that item class.

Parameters:

itemClass -

n - number of (zero or null) elements

Returns:

created array

array

public static PyArray array(PyObject seq,
                            char typecode)

Create a PyArray with the given array item type and content initialised from a Python object (iterable).

Parameters:

seq - to suply content

typecode -

Returns:

created array

array_class

public static java.lang.Class<?> array_class(java.lang.Class<?> type)

array

public static PyArray array(PyObject init,
                            java.lang.Class<?> itemClass)

Create a PyArray storing ctype types and being initialised with init.

Parameters:

init - an initialiser for the array - can be PyString or PySequence (including PyArray) or iterable type.

itemClass - Class of the elements stored in the array.

Returns:

a new PyArray

hashCode

public int hashCode()

Overrides:

hashCode in class PyObject

array___iter__

public PyObject array___iter__()

__imul__

public PyObject __imul__(PyObject o)

Description copied from class: PyObject

Equivalent to the standard Python __imul__ method.

Overrides:

__imul__ in class PyObject

Parameters:

o - the object to perform this binary operation with (the right-hand operand).

Returns:

the result of the imul, or null if this operation is not defined.

__mul__

public PyObject __mul__(PyObject o)

Description copied from class: PyObject

Equivalent to the standard Python __mul__ method.

Overrides:

__mul__ in class PyObject

Parameters:

o - the object to perform this binary operation with (the right-hand operand).

Returns:

the result of the mul, or null if this operation is not defined

__rmul__

public PyObject __rmul__(PyObject o)

Description copied from class: PyObject

Equivalent to the standard Python __rmul__ method.

Overrides:

__rmul__ in class PyObject

Parameters:

o - the object to perform this binary operation with (the left-hand operand).

Returns:

the result of the mul, or null if this operation is not defined.

__iadd__

public PyObject __iadd__(PyObject other)

Description copied from class: PyObject

Equivalent to the standard Python __iadd__ method.

Overrides:

__iadd__ in class PyObject

Parameters:

other - the object to perform this binary operation with (the right-hand operand).

Returns:

the result of the iadd, or null if this operation is not defined

__add__

public PyObject __add__(PyObject other)

Description copied from class: PyObject

Equivalent to the standard Python __add__ method.

Overrides:

__add__ in class PyObject

Parameters:

other - the object to perform this binary operation with (the right-hand operand).

Returns:

the result of the add, or null if this operation is not defined.

__len__

public int __len__()

Length of the array (as the number of elements, not a storage size).

Overrides:

__len__ in class PyObject

Returns:

number of elements in the array

__reduce__

public PyObject __reduce__()

Description copied from class: PyObject

Used for pickling. Default implementation calls object___reduce__.

Overrides:

__reduce__ in class PyObject

Returns:

a tuple of (class, tuple)

toString

public java.lang.String toString()

Overrides:

toString in class PyObject

__tojava__

public java.lang.Object __tojava__(java.lang.Class<?> c)

Description copied from class: PyObject

Equivalent to the Jython __tojava__ method. Tries to coerce this object to an instance of the requested Java class. Returns the special object Py.NoConversion if this PyObject can not be converted to the desired Java class.

Overrides:

__tojava__ in class PySequence

Parameters:

c - target Class for the conversion

Returns:

Java object converted to required class type if possible.

array_append

public final void array_append(PyObject value)

append

public void append(PyObject value)

Append new value x to the end of the array.

Parameters:

value - item to be appended to the array

array_byteswap

public void array_byteswap()

byteswap

public void byteswap()

"Byteswap" all items of the array. This is only supported for values which are 1, 2, 4, or 8 bytes in size; for other types of values, RuntimeError is raised. It is useful when reading data from a file written on a machine with a different byte order.

clone

public java.lang.Object clone()

Implementation of Cloneable interface.

Overrides:

clone in class java.lang.Object

Returns:

copy of current PyArray

char2class

public static java.lang.Class<?> char2class(char typecode)
                                     throws PyIgnoreMethodTag

Converts a character code for the array type to the Java Class of the elements of the implementation array.

Parameters:

typecode - character code for the array type

Returns:

Class of the native itemClass

Throws:

PyIgnoreMethodTag

array_count

public final int array_count(PyObject value)

count

public PyInteger count(PyObject value)

Return the number of occurrences of x in the array.

Parameters:

value - instances of the value to be counted

Returns:

number of time value was found in the array.

array_extend

public final void array_extend(PyObject iterable)

extend

public void extend(PyObject iterable)

Append items from iterable to the end of the array. If iterable is another array, it must have exactly the same type code; if not, TypeError will be raised. If iterable is not an array, it must be iterable and its elements must be the right type to be appended to the array.

Parameters:

iterable - iterable object used to extend the array

array_fromfile

public final void array_fromfile(PyObject f,
                                 int count)

fromfile

public void fromfile(PyObject f,
                     int count)

Read count items (as machine values) from the file object f and append them to the end of the array. If less than count items are available, EOFError is raised, but the items that were available are still inserted into the array. f must be a real built-in file object; something else with a read() method won't do.

Parameters:

f - Python builtin file object to retrieve data

count - number of array elements to read

array_fromlist

public final void array_fromlist(PyObject obj)

fromlist

public void fromlist(PyObject obj)

Append items from the list. This is equivalent to for x in list: a.append(x) except that if there is a type error, the array is unchanged.

Parameters:

obj - input list object that will be appended to the array

fillFromStream

public int fillFromStream(java.io.InputStream is)
                   throws java.io.IOException

Fill the current array with primitive values (of the type the array holds) from a stream, starting at array index zero, up to the capacity of the array, without resizing. Data are read until the array is filled or the stream runs out. If the stream does not contain a whole number of items (possible if the item size is not one byte), the behaviour in respect of the final partial item and stream position is not defined.

Parameters:

is - InputStream to source the data from

Returns:

number of primitives successfully read

Throws:

java.io.IOException - reflecting I/O errors during reading

fromstring

public void fromstring(PyObject input)

Append items from the object, which is a byte string of some kind (PyString or object with the buffer interface providing bytes). The string of bytes is interpreted as an array of machine values (as if it had been read from a file using the fromfile() method).

Parameters:

input - string of bytes containing array data

fromstring

public void fromstring(java.lang.String input)

Append items from the string, interpreting the string as an array of bytes (as if it had been read from a file using the fromfile() method). The bytes encode primitive values of the type appropriate to the array,

Parameters:

input - string of bytes containing array data

fromstring

public int fromstring(int start,
                      java.lang.String input)

Read primitive values from a stream into a slice of the array, defined by a start and the number of items encoded in the bytes. Data are read until the array slice is filled or the stream runs out. Data in the array beyond the slice are not altered. Write a slice of the array with primitive values items from the string, interpreting the string as an array of bytes (as if it had been read from a file using the fromfile() method). The bytes encode primitive values of the type appropriate to the array,

Parameters:

start - first element index to read into

input - string of bytes containing array data

Returns:

number of primitives successfully read (=count, if not ended by EOF)

fromunicode

public void fromunicode(PyUnicode input)

getArray

public java.lang.Object getArray()
                          throws PyIgnoreMethodTag

Return the internal Java array storage of the PyArray instance

Returns:

the Array store.

Throws:

PyIgnoreMethodTag

getItemsize

public int getItemsize()

Getter for the item size of the array element type.

The sizes returned by this method represent the number of bytes used to store the type. In the case of streams of primitive values, this is the number of bytes written to, or read from a stream. The amount of memory occupied by each item is an internal matter for Java.

This method is used by other methods to define read/write quanta from strings and streams.

Returns:

number of bytes used to store array type, relevant when serialising to an array of bytes, or the reverse.

getStorageSize

@Deprecated
public int getStorageSize()

Deprecated. Use getItemsize() instead which (since 2.7.3) gives the same result.

Getter for the storage size of the array's type, relevant when serialising to an array of bytes, or the reverse.

Returns:

actual storage size

getTypecode

public java.lang.String getTypecode()

Return either a Python-style array.array type code for the element (item) type or the Java class name.

Returns:

single character type code or simple class name

array_index

public final int array_index(PyObject value)

index

public PyObject index(PyObject value)

Return the smallest i such that i is the index of the first occurrence of value in the array.

Parameters:

value - value to find the index of

Returns:

index of the first occurrence of value

array_insert

public final void array_insert(int index,
                               PyObject value)

insert

public void insert(int index,
                   PyObject value)

Insert a new item with value value in the array before position index. Negative values are treated as being relative to the end of the array.

Parameters:

index - insert position

value - value to be inserted into array

array_pop

public final PyObject array_pop(int i)

Removes the item at the index i from the array and returns it. The optional argument defaults to -1, so that by default the last item is removed and returned.

pop

public PyObject pop()

Removes the last item from the array and return it.

pop

public PyObject pop(int index)

Removes the item with the index index from the array and returns it.

Parameters:

index - array location to be popped from the array

Returns:

array element popped from index

array_remove

public final void array_remove(PyObject value)

remove

public void remove(PyObject value)

Remove the first occurrence of value from the array.

Parameters:

value - array value to be removed

array_reverse

public final void array_reverse()

reverse

public void reverse()

Reverse the elements in the array

set

public void set(int i,
                PyObject value)

Set an element in the array - the index needs to exist, this method does not automatically extend the array. See AbstractArray.setSize() or AbstractArray.ensureCapacity() for ways to extend capacity.

This code specifically checks for overflows of the integral types: byte, short, int and long.

Parameters:

i - index of the element to be set

value - value to set the element to

set

public void set(int i,
                int value)

Set element to integer value, tolerating primitive integer values in arrays of Unicode character, int or long. Negative values assigned to unsigned elements adopt their wrapped unsigned values.

Parameters:

i - index to set

value - to set

set

public void set(int i,
                char value)

Set element to integer value given as a Java char, tolerating primitive integer values in arrays of Unicode character, int or long.

Parameters:

i - index to set

value - to set

set

public void set(int i,
                byte value)

Set element in an array of element type 'b','B', or 'c' to a Java byte.

Parameters:

i - index to set

value - to set

array_tofile

public final void array_tofile(PyObject f)

array_write

public void array_write(PyObject f)

tofile

public void tofile(PyObject f)

Write all items (as machine values) to the file object f.

Parameters:

f - Python builtin file object to write data

array_tolist

public final PyObject array_tolist()

tolist

public PyObject tolist()

Convert the array to an ordinary list with the same items.

Returns:

array contents as a list

toStream

public int toStream(java.io.OutputStream os)
             throws java.io.IOException

Generic stream writer to write the entire contents of the array to the stream as primitive types.

Parameters:

os - OutputStream to sink the array data to

Returns:

number of bytes successfully written

Throws:

java.io.IOException

array_tostring

public final PyObject array_tostring()

tostring

public java.lang.String tostring()

Convert the array to an array of machine values and return the string representation (the same sequence of bytes that would be written to a file by the tofile() method.)

array_tounicode

public final PyUnicode array_tounicode()

tounicode

public java.lang.String tounicode()

getBuffer

public PyBuffer getBuffer(int flags)

Method by which the consumer requests the buffer from the exporter. The consumer provides information on its ability to understand buffer navigation. Each consumer requesting a buffer in this way, when it has finished using it, should make a corresponding call to PyBuffer.release() on the buffer it obtained, or PyBuffer.close() using try-with-resources, since some objects alter their behaviour while buffers are exported.

The PyBuffer returned from this method is a one-dimensional array of single byte items that allows modification of the object state. The existence of this export prohibits resizing the array. This prohibition is not only on the consumer of the view but extends to operations on the underlying array, such as insert(int, PyObject) or pop().

Specified by:

getBuffer in interface BufferProtocol

Parameters:

flags - specifying features demanded and the navigational capabilities of the consumer

Returns:

exported buffer

traverse

public int traverse(Visitproc visit,
                    java.lang.Object arg)

Description copied from interface: Traverseproc

Traverses all directly contained PyObjects. Like in CPython, arg must be passed unmodified to visit as its second parameter. If Visitproc.visit(PyObject, Object) returns nonzero, this return value must be returned immediately by traverse. Visitproc.visit(PyObject, Object) must not be called with a null PyObject-argument.

Specified by:

traverse in interface Traverseproc

refersDirectlyTo

public boolean refersDirectlyTo(PyObject ob)
                         throws java.lang.UnsupportedOperationException

Description copied from interface: Traverseproc

Optional operation. Should only be implemented if it is more efficient than calling Traverseproc.traverse(Visitproc, Object) with a visitproc that just watches out for ob. Must return false if ob is null.

Specified by:

refersDirectlyTo in interface Traverseproc

Throws:

java.lang.UnsupportedOperationException