public interface IonSequence extends IonContainer, List<IonValue>
list
and sexp
types.
WARNING: This interface should not be implemented or extended by code outside of this library.
Ion sequences implement the standard Java List
interface, behaving
generally as expected, with the following exceptions:
remove(Object)
do not use Object.equals(java.lang.Object)
as
specified by the contract of Collection
.
Instead they use reference equality (==
operator) to find the
given instance.
IonValue
instance may be a child of at most one
IonContainer
. Instances may be children of any number of
non-Ion Collection
s.
subList(int, int)
is not implemented at all.
We think it will be quite challenging to get correct, and decided that
it was still valuable to extend List
even with this contractual
violation.
EMPTY_ARRAY
Modifier and Type | Method and Description |
---|---|
ValueFactory |
add()
Provides a factory that when invoked constructs a new value and
add s it to this sequence. |
ValueFactory |
add(int index)
Provides a factory that when invoked constructs a new value and
add s it to this sequence at the specified position. |
void |
add(int index,
IonValue child)
Inserts a child value at the specified position in this sequence.
|
boolean |
add(IonValue child)
Appends a child value to the end of this sequence.
|
boolean |
addAll(Collection<? extends IonValue> c)
Appends all of the elements in the specified collection to the end of
this sequence, in the order that they are returned by the collection's
iterator.
|
boolean |
addAll(int index,
Collection<? extends IonValue> c)
Inserts all of the elements in the specified collection into this
sequence at the specified position.
|
IonSequence |
clone()
Creates a copy of this value and all of its children.
|
boolean |
contains(Object o)
Determines whether this sequence contains the given instance.
|
boolean |
containsAll(Collection<?> c)
Determines whether this sequence contains all of the given instances.
|
<T extends IonValue> |
extract(Class<T> type)
Removes all children of this sequence, returning them in an array.
|
IonValue |
get(int index)
Returns the element at the specified position in this sequence.
|
int |
indexOf(Object o)
Returns the index in the sequence of the specified element,
or -1 if this sequence doesn't contain the element.
|
int |
lastIndexOf(Object o)
Returns the index in the sequence of the specified element,
or -1 if this sequence doesn't contain the element.
|
ListIterator<IonValue> |
listIterator()
Returns a list iterator of the elements in this sequence (in proper
order).
|
ListIterator<IonValue> |
listIterator(int index)
Returns a list iterator of the elements in this sequence (in proper
order), starting at the specified position in this sequence.
|
IonValue |
remove(int index)
Removes the element at the specified position.
|
boolean |
remove(Object o)
Removes a given
IonValue from this sequence, if it is present. |
boolean |
removeAll(Collection<?> c)
Removes all elements from this sequence that are also contained in the
specified collection.
|
boolean |
retainAll(Collection<?> c)
Retains only the elements in this sequence that are also contained in
the specified collection.
|
IonValue |
set(int index,
IonValue element)
Replaces the element at the specified position in this list with the
specified element.
|
List<IonValue> |
subList(int fromIndex,
int toIndex)
Returns a view of the portion of this list according to
List.subList(int, int)
contract. |
IonValue[] |
toArray()
Returns an array containing all of the elements in this sequence in
proper order.
|
<T> T[] |
toArray(T[] a)
Returns an array containing all of the elements in this sequence in
proper order; the runtime type of the returned array is that of the
specified array.
|
clear, isEmpty, iterator, makeNull, remove, size
accept, addTypeAnnotation, clearTypeAnnotations, equals, getContainer, getFieldId, getFieldName, getFieldNameSymbol, getSymbolTable, getSystem, getType, getTypeAnnotations, getTypeAnnotationSymbols, hashCode, hasTypeAnnotation, isNullValue, isReadOnly, makeReadOnly, removeFromContainer, removeTypeAnnotation, setTypeAnnotations, setTypeAnnotationSymbols, topLevelValue, toPrettyString, toString, toString, writeTo
clear, equals, hashCode, isEmpty, iterator, replaceAll, size, sort, spliterator
parallelStream, removeIf, stream
IonValue get(int index) throws NullValueException, IndexOutOfBoundsException
get
in interface List<IonValue>
index
- identifies the element to return.null
.NullValueException
- if IonValue.isNullValue()
.IndexOutOfBoundsException
- if the index is out of range
(index < 0 || index >= size()
).boolean add(IonValue child) throws ContainedValueException, NullPointerException
IonValue.isNullValue()
, then it becomes a single-element
sequence.add
in interface Collection<IonValue>
add
in interface List<IonValue>
child
- is the value to be appended to this sequence.true
(as per the general contract of the
Collection.add(E)
method).NullPointerException
- if child
is null
.ContainedValueException
- if child
is already part of a container.IllegalArgumentException
- if child
is an IonDatagram
.ValueFactory add()
add
s it to this sequence.
These two lines are equivalent:
seq.add().newInt(3); seq.add(seq.getSystem().newInt(3));
void add(int index, IonValue child) throws ContainedValueException, NullPointerException
IonValue.isNullValue()
, then it becomes a single-element
sequence.add
in interface List<IonValue>
child
- is the element to be appended to this sequence.NullPointerException
- if child
is null
.ContainedValueException
- if child
is already part of a container.IllegalArgumentException
- if child
is an IonDatagram
.IndexOutOfBoundsException
- if the index is out of range
(index < 0 || index > size()).ValueFactory add(int index)
add
s it to this sequence at the specified position.
These two lines are equivalent:
seq.add(12).newInt(3); seq.add(12, seq.getSystem().newInt(3));
The given index
is validated when the factory's creation method
is invoked, not when this method is invoked.
IonValue set(int index, IonValue element)
set
in interface List<IonValue>
index
- index of the element to replace.element
- element to be stored at the specified position.UnsupportedOperationException
- if this is an IonDatagram
.NullPointerException
- if the specified element is null
.ContainedValueException
- if the specified element is already part of a container.IllegalArgumentException
- if the specified element is an IonDatagram
.ReadOnlyValueException
- if this value or the specified element IonValue.isReadOnly()
.IndexOutOfBoundsException
- if the index is out of range (index < 0 || index >= size()
).IonValue remove(int index)
remove
in interface List<IonValue>
index
- the index of the element to be removed.IndexOutOfBoundsException
- if the index is out of range
(index < 0 || index >= size()).boolean remove(Object o)
IonValue
from this sequence, if it is present.
Due to the reference-equality-based semantics of Ion sequences,
this method does not use Object.equals(java.lang.Object)
as specified by the
contract of Collection
. Instead it uses reference
equality (==
operator) to find the given instance.
remove
in interface Collection<IonValue>
remove
in interface List<IonValue>
true
if this sequence changed as a result of the call.NullPointerException
- if o
is null
.ClassCastException
- if o
is not an IonValue
.boolean removeAll(Collection<?> c)
Due to the reference-equality-based semantics of Ion sequences,
this method does not use Object.equals(java.lang.Object)
as specified by the
contract of Collection
. Instead it uses reference
equality (==
operator) to find the given instance.
removeAll
in interface Collection<IonValue>
removeAll
in interface List<IonValue>
true
if this sequence changed as a result of the call.NullPointerException
- if c
is null
.NullPointerException
- if c
contains one or more
null
elements.ClassCastException
- if c
contains one or more elements
that do not implement IonValue
.boolean retainAll(Collection<?> c)
Due to the reference-equality-based semantics of Ion sequences,
this method does not use Object.equals(java.lang.Object)
as specified by the
contract of Collection
. Instead it uses reference
equality (==
operator) to find the given instance.
retainAll
in interface Collection<IonValue>
retainAll
in interface List<IonValue>
true
if this sequence changed as a result of the call.NullPointerException
- if c
is null
.NullPointerException
- if c
contains one or more
null
elements.ClassCastException
- if c
contains one or more elements
that do not implement IonValue
.boolean contains(Object o)
Due to the reference-equality-based semantics of Ion sequences,
this method does not use Object.equals(java.lang.Object)
as specified by the
contract of Collection
. Instead it uses reference
equality (==
operator) to find the given instance.
contains
in interface Collection<IonValue>
contains
in interface List<IonValue>
true
if o
is an element of this sequence.NullPointerException
- if o
is null
.ClassCastException
- if o
is not an IonValue
.boolean containsAll(Collection<?> c)
Due to the reference-equality-based semantics of Ion sequences,
this method does not use Object.equals(java.lang.Object)
as specified by the
contract of Collection
. Instead it uses reference
equality (==
operator) to find the given instances.
containsAll
in interface Collection<IonValue>
containsAll
in interface List<IonValue>
true
if this sequence contains all of the elements of
the given collection.NullPointerException
- if c
is null
.NullPointerException
- if c
contains one or more
null
elements.ClassCastException
- if c
contains one or more elements
that do not implement IonValue
.int indexOf(Object o)
Due to the reference-equality-based semantics of Ion sequences,
this method does not use Object.equals(java.lang.Object)
as specified by the
contract of List
. Instead it uses reference
equality (==
operator) to find the instance.
int lastIndexOf(Object o)
Due to the reference-equality-based semantics of Ion sequences,
this method does not use Object.equals(java.lang.Object)
as specified by the
contract of List
. Instead it uses reference
equality (==
operator) to find the instance.
And since IonSequences do not allow for duplicates this method behaves
in the same way as indexOf(Object)
lastIndexOf
in interface List<IonValue>
o
- the element to search for.boolean addAll(Collection<? extends IonValue> c)
Since Ion values can only have a single parent, this method will fail if
the given collection is a non-empty IonContainer
.
addAll
in interface Collection<IonValue>
addAll
in interface List<IonValue>
c
- elements to be appended to this sequence.true
if this sequence changed as a result of the call.UnsupportedOperationException
- if this is an IonDatagram
.ClassCastException
- if one of the elements of the collection is not an IonValue
NullPointerException
- if one of the elements of the collection is null
.ContainedValueException
- if one of the elements is already contained by an IonContainer
.boolean addAll(int index, Collection<? extends IonValue> c)
Since Ion values can only have a single parent, this method will fail if
the given collection is a non-empty IonContainer
.
addAll
in interface List<IonValue>
index
- index at which to insert first element from the specified collection.c
- elements to be inserted into this sequence.true
if this sequence changed as a result of the call.UnsupportedOperationException
- if this is an IonDatagram
.ClassCastException
- if one of the elements of the collection is not an IonValue
NullPointerException
- if one of the elements of the collection is null
.ContainedValueException
- if one of the elements is already contained by an IonContainer
.IndexOutOfBoundsException
- if the index is out of range (index < 0 || index > size()).ListIterator<IonValue> listIterator()
The result does not support ListIterator.add(Object)
or
ListIterator.set(Object)
.
If this sequence IonValue.isReadOnly()
then it also does not support
Iterator.remove()
.
listIterator
in interface List<IonValue>
ListIterator<IonValue> listIterator(int index)
The result does not support ListIterator.add(Object)
or
ListIterator.set(Object)
.
If this sequence IonValue.isReadOnly()
then it also does not support
Iterator.remove()
.
listIterator
in interface List<IonValue>
index
- index of first element to be returned from the list iterator (by a call
to the next
method).IndexOutOfBoundsException
- if the index is out of range (index < 0 || index > size()
).List<IonValue> subList(int fromIndex, int toIndex)
Returns a view of the portion of this list according to List.subList(int, int)
contract.
Sublist methods will throw a ConcurrentModificationException
if
its parent list, i.e. this list, had any changes that affect its size the after sublist
was created.
subList
in interface List<IonValue>
List.subList(int, int)
IonValue[] toArray()
Collection.toArray()
method.
If this sequence is an Ion null value, it will behave like an empty sequence.
<T> T[] toArray(T[] a)
Collection.toArray()
method.
If this sequence is an Ion null value, it will behave like an empty sequence.
toArray
in interface Collection<IonValue>
toArray
in interface List<IonValue>
a
- the array into which the elements of this sequence are to be
stored, if it is big enough; otherwise, a new array of the same
runtime type is allocated for this purpose.ArrayStoreException
- if the runtime type of the specified array
is not a supertype of the runtime type of every element in this
sequence.NullPointerException
- if the specified array is null
.<T extends IonValue> T[] extract(Class<T> type)
s
in order, or
null
if IonValue.isNullValue()
.NullPointerException
- if type
is null
.ClassCastException
- if any value in this sequence does not
implement the given type.IonSequence clone() throws UnknownSymbolException
IonValue
IonValue.isReadOnly()
.
The cloned value will be created in the context of the same
ValueFactory
as this instance; if you want a copy using a
different factory, then use ValueFactory.clone(IonValue)
instead.
clone
in interface IonContainer
clone
in interface IonValue
UnknownSymbolException
- if any part of this value has unknown text but known Sid for
its field name, annotation or symbol.