Top Description Inners Fields Constructors Methods
org.python.core

public Class PyList

extends Object
implements List<Object>, CraftedPyObject
Class Inheritance
All Implemented Interfaces
org.python.core.CraftedPyObject, java.util.List, java.util.SequencedCollection, java.util.Collection, java.lang.Iterable
Imports
java.lang.invoke.MethodHandles, java.lang.reflect.Array, java.util.ArrayList, .Collection, .Collections, .Comparator, .Iterator, .List, .ListIterator, .StringJoiner, java.util.function.Function, .Supplier, org.python.base.InterpreterError, org.python.core.PyObjectUtil.NoConversion, .PySlice.Indices, .PyType.Spec

The Python list object that is also a Java List<Object>. Operations in both APIs are synchronised for safety against concurrent threads.

It is synchronized so that competing threads should be able to access it with roughly the same protection against concurrent modification that CPython offers. There are also necessary safeguards during sort() to detect modification from within the current thread as a side effect of comparison. Java brings its own safeguard within iterators against structural concurrent modification.

Implementation Note

The design follows that in Jython 2 with a private Java list member to which operations are delegated directly or indirectly. In the present design, the indirect delegation is through a private delegate member where in the former design behaviour was inherited.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
PyList.KV

During PyList#sortOnKey(Function, boolean), we actually sort a list of these key-value objects.

private class
PyList.ListDelegate

Wrap the list of this PyList as a PySequence.

private abstract class
PyList.ListElementComparator<
type of element to sort (on practice Object or KV.
T
>

This comparator is used in PyList#sort(Function, boolean), sub-classed for the type of sort.

Field Summary

Modifier and TypeField and Description
private boolean
changed

Synchronisation prevents modification by competing threads during an operation, but does not defend against actions within that operation by the same thread.

private final PyList.ListDelegate
delegate

Implementation help for sequence methods.

private final List<Object>
list

Storage for the actual list elements (as a list).

public static final PyType
protected final PyType
type

The Python type of this instance.

Constructor Summary

AccessConstructor and Description
private
PyList(PyType
actual type
type
,
List<Object>
storage object
list
)

Fundamental constructor, specifying actual type and the list that will become the storage object.

public
PyList(PyType
actual type
type
,
int
capacity
initialCapacity
)

Construct a Python list object, specifying actual type and initial capacity.

public
PyList(int
capacity
initialCapacity
)

Construct a Python list object, specifying initial capacity.

public
PyList(PyType
actual type
type
)

Construct an empty Python list object, specifying actual type.

public
PyList()

Construct an empty Python list object.

public
PyList(PyType
actual type
type
,
Collection<?>
initial contents
c
)

Construct a Python list object, specifying actual type and initial contents.

public
PyList(Collection<?>
initial contents
c
)

Construct a Python list object, specifying initial contents.

pack-priv
PyList(Object[]
the array
a
,
int
of slice
start
,
int
of elements to take
count
)

Construct a list with initial contents from an array slice.

Method Summary

Modifier and TypeMethod and Description
pack-priv synchronized Object
pack-priv synchronized boolean
pack-priv synchronized void
pack-priv synchronized Object
pack-priv synchronized Object
pack-priv synchronized Object
public PyTuple
pack-priv synchronized Object
pack-priv synchronized Object
pack-priv synchronized Object
pack-priv synchronized int
pack-priv synchronized Object
pack-priv synchronized Object
pack-priv synchronized Object
pack-priv synchronized Object
pack-priv synchronized Object
pack-priv synchronized void
__setitem__(Object index, Object value)

public synchronized void
add(int
index at which the specified element is to be inserted
index
,
Object
element to be inserted
element
)

Implements java.util.List.add.

Inserts the specified element at the specified position in this list (optional operation).
public synchronized boolean
add(Object
element to be appended to this list
o
)

Implements java.util.List.add.

Appends the specified element to the end of this list (optional operation).
public synchronized boolean
addAll(int
index at which to insert the first element from the specified collection
index
,
Collection<?>
collection containing elements to be added to this list
c
)

Implements java.util.List.addAll.

Inserts all of the elements in the specified collection into this list at the specified position (optional operation).
public boolean
addAll(Collection<?>
collection containing elements to be added to this list
c
)

Implements java.util.List.addAll.

Appends all of the elements in the specified collection to the end of this list, in the order that they are returned by the specified collection's iterator (optional operation).
private int

Returns:

bounded 0 <= index <= list.size()
boundedIndex
(int
as presented
index
)

Accept an index, treating negative values as end-relative, and bound it to the sequence range.

public synchronized void
clear()

Implements java.util.List.clear.

Removes all of the elements from this list (optional operation).
private static PyList
concat(List<?> v, List<?> w)

Concatenate two lists (for ListDelegate).

public synchronized boolean
contains(Object
element whose presence in this list is to be tested
o
)

Implements java.util.List.contains.

Returns true if this list contains the specified element.
public synchronized boolean
containsAll(Collection<?>
collection to be checked for containment in this list
c
)

Implements java.util.List.containsAll.

Returns true if this list contains all of the elements of the specified collection.
public boolean
equals(Object
the object to be compared for equality with this list
other
)

Overrides java.lang.Object.equals.

Implements java.util.List.equals.

Compares the specified object with this list for equality.
private boolean

Returns:

true if erasures is not empty
erase
(List<Integer>
to remove
erasures
)

Given an ordered ascending list of indices into list, remove the elements at those indices.

private int

Returns:

the index of v or -1 if not found.
find
(Object
the element to search for and remove.
v
)

Return the index of v in list or -1 if not found.

public synchronized Object
get(int
index of the element to return
index
)

Implements java.util.List.get.

Returns the element at the specified position in this list.
public PyType
getType()

Implements org.python.core.CraftedPyObject.getType.

The Python type of this object.
public int
hashCode()

Overrides java.lang.Object.hashCode.

Implements java.util.List.hashCode.

Returns the hash code value for this list.
public synchronized int
indexOf(Object
element to search for
o
)

Implements java.util.List.indexOf.

Returns the index of the first occurrence of the specified element in this list, or -1 if this list does not contain the element.
public synchronized boolean
isEmpty()

Implements java.util.List.isEmpty.

Returns true if this list contains no elements.
public Iterator<Object>
iterator()

Implements java.util.List.iterator.

Returns an iterator over the elements in this list in proper sequence.
public synchronized int
lastIndexOf(Object
element to search for
o
)

Implements java.util.List.lastIndexOf.

Returns the index of the last occurrence of the specified element in this list, or -1 if this list does not contain the element.
pack-priv final synchronized void
list_append(Object
the element to add.
o
)

Add a single element to the end of list.

pack-priv final synchronized void
list_clear()

Remove all items from the list (same as del s[:])

pack-priv final synchronized int

Returns:

the number of occurrences.
list_count
(Object
the value to test for.
v
)

Return the number elements in the list that are Python-equal to the argument.

pack-priv final synchronized void
list_extend(Object
the sequence of items to append to the list.
o
)

Append the elements in the argument sequence to the end of the list, s[len(s):len(s)] = o.

pack-priv final <
the type of exception to throw
E extends PyException
>
void
list_extend(Object
the sequence of items to append to the list.
o
,
Supplier<E>
a supplier (e.g. lambda expression) for the exception to throw if an iterator cannot be formed (or null for a default TypeError)
exc
)

Append the elements in the argument sequence to the end of the list, s[len(s):len(s)] = o.

pack-priv final synchronized int

Returns:

index of the occurrence
list_index
(Object
the value to look for.
v
,
Object
first index to test
start
,
Object
first index not to test
stop
)

Return smallest index where an element in the list Python-equals the argument.

pack-priv final synchronized void
list_insert(Object
the position where the element will be inserted.
index
,
Object
the element to insert.
o
)

Insert the argument element into the list at the specified index.

pack-priv final synchronized Object

Returns:

the popped item
list_pop
(int
the index of the element to remove and return.
n
)

Remove and return a specified element from the list.

pack-priv final synchronized void
list_remove(Object
the element to search for and remove.
v
)

Remove from the list the first element that is Python-equal to the argument.

public ListIterator<Object>
listIterator()

Implements java.util.List.listIterator.

Returns a list iterator over the elements in this list (in proper sequence).
public ListIterator<Object>
listIterator(final int
index of the first element to be returned from the list iterator (by a call to next)
index
)

Implements java.util.List.listIterator.

Returns a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list.
public static PyList

Returns:

list of elements
of
(Object...
initial element values
elements
)

Hides java.util.List.of, java.util.List.of.

Return a Python list object, specifying initial contents.
public synchronized Object
remove(int
the index of the element to be removed
index
)

Implements java.util.List.remove.

Removes the element at the specified position in this list (optional operation).
public synchronized boolean
remove(Object
element to be removed from this list, if present
o
)

Implements java.util.List.remove.

Removes the first occurrence of the specified element from this list, if it is present (optional operation).
public synchronized boolean
removeAll(Collection<?>
collection containing elements to be removed from this list
c
)

Implements java.util.List.removeAll.

Removes from this list all of its elements that are contained in the specified collection (optional operation).
public synchronized boolean
retainAll(Collection<?>
collection containing elements to be retained in this list
c
)

Implements java.util.List.retainAll.

Retains only the elements in this list that are contained in the specified collection (optional operation).
pack-priv final synchronized void
reverse()

Reverses the items of s in place.

public synchronized Object
set(int
index of the element to replace
index
,
Object
element to be stored at the specified position
element
)

Implements java.util.List.set.

Replaces the element at the specified position in this list with the specified element (optional operation).
public synchronized int
size()

Implements java.util.List.size.

Returns the number of elements in this list.
pack-priv final synchronized void
sort(Function<Object, Object>
specifies a function of one argument that is used to extract a comparison key from each list element, e.g. key=str.lower. The default value is None.
key
,
boolean
the list elements are sorted as if each comparison were reversed.
reverse
)

Sort the items of the list in place, using only < comparisons between items.

private synchronized void
sortOnKey(Function<Object, Object> keyfunc, boolean reverse)

private synchronized void
sortOnValue(boolean reverse)

public synchronized List<Object>
subList(int
low endpoint (inclusive) of the subList
fromIndex
,
int
high endpoint (exclusive) of the subList
toIndex
)

Implements java.util.List.subList.

Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive.
public synchronized Object[]
toArray()

Implements java.util.List.toArray.

Returns an array containing all of the elements in this list in proper sequence (from first to last element).
public synchronized <T> T[]
toArray(T[]
the array into which the elements of this list are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
a
)

Implements java.util.List.toArray.

Returns an array containing all of the elements in this list in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array.
public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait