Ion Java 1.11.10 · com.amazon.ion.IonSequence · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: `true` (as per the general contract of the `Collection#add` method). add(IonValue is the value to be appended to this sequence. child) Redeclares java.util.List.add. Appends a child value to the end of this sequence.
public ValueFactory	add() Provides a factory that when invoked constructs a new value and `add`s it to this sequence.
public void	add(int index at which the specified element is to be inserted index, IonValue is the element to be appended to this sequence. child) Redeclares java.util.List.add. Inserts a child value at the specified position in this sequence.
public ValueFactory	add(int element to be appended to this list index) Redeclares java.util.List.add. Provides a factory that when invoked constructs a new value and `add`s it to this sequence at the specified position.
public boolean	Returns: `true` if this sequence changed as a result of the call. addAll(Collection<? extends IonValue> elements to be appended to this sequence. c) Redeclares java.util.List.addAll. 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.
public boolean	Returns: `true` if this sequence changed as a result of the call. addAll(int index at which to insert first element from the specified collection. index, Collection<? extends IonValue> elements to be inserted into this sequence. c) Redeclares java.util.List.addAll. Inserts all of the elements in the specified collection into this sequence at the specified position.
public IonSequence	clone() Redeclares com.amazon.ion.IonContainer.clone. Creates a copy of this value and all of its children.
public boolean	Returns: `true` if `o` is an element of this sequence. contains(Object element whose presence in this list is to be tested o) Redeclares java.util.List.contains. Determines whether this sequence contains the given instance.
public boolean	Returns: `true` if this sequence contains all of the elements of the given collection. containsAll(Collection<?> collection to be checked for containment in this list c) Redeclares java.util.List.containsAll. Determines whether this sequence contains all of the given instances.
public <T extends IonValue> T[]	Returns: a new array with all of the children of `s` in order, or `null` if `isNullValue()`. extract(Class<T> type) Removes all children of this sequence, returning them in an array.
public IonValue	Returns: the element at the given index; not `null`. get(int identifies the element to return. index) Redeclares java.util.List.get. Returns the element at the specified position in this sequence.
public int	Returns: the index in this sequence of the element, or -1 if this sequence doesn't contain the element. indexOf(Object the element to search for. o) Redeclares java.util.List.indexOf. Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.
public int	Returns: the index in this sequence of the element, or -1 if this sequence doesn't contain the element. lastIndexOf(Object the element to search for. o) Redeclares java.util.List.lastIndexOf. Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.
public ListIterator<IonValue>	listIterator() Redeclares java.util.List.listIterator. Returns a list iterator of the elements in this sequence (in proper order).
public ListIterator<IonValue>	listIterator(int index of first element to be returned from the list iterator (by a call to the `next` method). index) Redeclares java.util.List.listIterator. Returns a list iterator of the elements in this sequence (in proper order), starting at the specified position in this sequence.
public IonValue	Returns: the element previously at the specified position. remove(int the index of the element to be removed. index) Redeclares java.util.List.remove. Removes the element at the specified position.
public boolean	Returns: `true` if this sequence changed as a result of the call. remove(Object element to be removed from this list, if present o) Redeclares java.util.List.remove. Removes a given `IonValue` from this sequence, if it is present.
public boolean	Returns: `true` if this sequence changed as a result of the call. removeAll(Collection<?> collection containing elements to be removed from this list c) Redeclares java.util.List.removeAll. Removes all elements from this sequence that are also contained in the specified collection.
public boolean	Returns: `true` if this sequence changed as a result of the call. retainAll(Collection<?> collection containing elements to be retained in this list c) Redeclares java.util.List.retainAll. Retains only the elements in this sequence that are also contained in the specified collection.
public IonValue	Returns: the element previously at the specified index. set(int index of the element to replace. index, IonValue element to be stored at the specified position. element) Redeclares java.util.List.set. Replaces the element at the specified position in this list with the specified element.
public List<IonValue>	subList(int low endpoint (inclusive) of the subList fromIndex, int high endpoint (exclusive) of the subList toIndex) Redeclares java.util.List.subList. Returns a view of the portion of this list according to `List#subList(int, int)` contract.
public IonValue[]	Returns: an array containing all of the elements in this sequence in proper order. toArray() Redeclares java.util.List.toArray. Returns an array containing all of the elements in this sequence in proper order.
public <T> T[]	Returns: an array containing all of the elements in this sequence in proper order. toArray(T[] 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. a) Redeclares java.util.List.toArray. 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.

Inherited from com.amazon.ion.IonContainer:: clear isEmpty iterator makeNull remove size
Inherited from java.util.List:: addFirst addLast clear copyOf equals getFirst getLast hashCode isEmpty iterator of of of of of of of of of of of of removeFirst removeLast replaceAll reversed size sort spliterator

Method Detail

add back to summary

add	back to summary
public boolean add(IonValue child) throws ContainedValueException, NullPointerException Redeclares java.util.List.add. Appends a child value to the end of this sequence. If `isNullValue()`, then it becomes a single-element sequence. Parameters child:IonValue is the value to be appended to this sequence. Returns:boolean `true` (as per the general contract of the `Collection#add` method). Exceptions ContainedValueException: if `child` is already part of a container. NullPointerException: if `child` is `null`. IllegalArgumentException: if `child` is an `IonDatagram`.

public boolean add(IonValue child) throws ContainedValueException, NullPointerException

Redeclares java.util.List.add.

Appends a child value to the end of this sequence. If isNullValue(), then it becomes a single-element sequence.

Parameters

child:IonValue: is the value to be appended to this sequence.

Returns:boolean

true (as per the general contract of the Collection#add method).

Exceptions

ContainedValueException:: if child is already part of a container.
NullPointerException:: if child is null.
IllegalArgumentException:: if child is an IonDatagram.

add back to summary

add	back to summary
public ValueFactory add() Provides a factory that when invoked constructs a new value and `add`s it to this sequence. These two lines are equivalent: seq.add().newInt(3); seq.add(seq.getSystem().newInt(3));

public ValueFactory add()

Provides a factory that when invoked constructs a new value and adds it to this sequence.

These two lines are equivalent:

    seq.add().newInt(3);
    seq.add(seq.getSystem().newInt(3));

add back to summary

add	back to summary
public void add(int index, IonValue child) throws ContainedValueException, NullPointerException Redeclares java.util.List.add. Inserts a child value at the specified position in this sequence. If `isNullValue()`, then it becomes a single-element sequence. Parameters index:int Doc from java.util.List.add. index at which the specified element is to be inserted child:IonValue is the element to be appended to this sequence. Exceptions ContainedValueException: if `child` is already part of a container. NullPointerException: if `child` is `null`. IllegalArgumentException: if `child` is an `IonDatagram`. IndexOutOfBoundsException: if the index is out of range (index < 0 \|\| index > size()).

public void add(int index, IonValue child) throws ContainedValueException, NullPointerException

Redeclares java.util.List.add.

Inserts a child value at the specified position in this sequence. If isNullValue(), then it becomes a single-element sequence.

Parameters

index:int

Doc from java.util.List.add.

index at which the specified element is to be inserted

child:IonValue

is the element to be appended to this sequence.

Exceptions

ContainedValueException:: if child is already part of a container.
NullPointerException:: if child is null.
IllegalArgumentException:: if child is an IonDatagram.
IndexOutOfBoundsException:: if the index is out of range (index < 0 || index > size()).

add back to summary

add	back to summary
public ValueFactory add(int index) Redeclares java.util.List.add. Provides a factory that when invoked constructs a new value and `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. Parameters index:int Doc from java.util.List.add. element to be appended to this list Returns:ValueFactory Doc from java.util.List.add. `true` (as specified by `Collection#add`)

public ValueFactory add(int index)

Redeclares java.util.List.add.

Provides a factory that when invoked constructs a new value and adds 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.

Parameters

index:int

Doc from java.util.List.add.

element to be appended to this list

Returns:ValueFactory

Doc from java.util.List.add.

true (as specified by Collection#add)

addAll back to summary

addAll	back to summary
public boolean addAll(Collection<? extends IonValue> c) Redeclares java.util.List.addAll. 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. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this sequence, and it's nonempty.) Since Ion values can only have a single parent, this method will fail if the given collection is a non-empty `IonContainer`. Parameters c:Collection<? extends IonValue> elements to be appended to this sequence. Returns:boolean `true` if this sequence changed as a result of the call. Exceptions 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`.

public boolean addAll(Collection<? extends IonValue> c)

Redeclares java.util.List.addAll.

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. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this sequence, and it's nonempty.)

Since Ion values can only have a single parent, this method will fail if the given collection is a non-empty IonContainer.

Parameters

c:Collection<? extends IonValue>: elements to be appended to this sequence.

Returns:boolean

true if this sequence changed as a result of the call.

Exceptions

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.

addAll back to summary

addAll	back to summary
public boolean addAll(int index, Collection<? extends IonValue> c) Redeclares java.util.List.addAll. Inserts all of the elements in the specified collection into this sequence at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this sequence in the order that they are returned by the specified collection's iterator. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this sequence, and it's nonempty.) Since Ion values can only have a single parent, this method will fail if the given collection is a non-empty `IonContainer`. Parameters index:int index at which to insert first element from the specified collection. c:Collection<? extends IonValue> elements to be inserted into this sequence. Returns:boolean `true` if this sequence changed as a result of the call. Exceptions 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()).

public boolean addAll(int index, Collection<? extends IonValue> c)

Redeclares java.util.List.addAll.

Inserts all of the elements in the specified collection into this sequence at the specified position. Shifts the element currently at that position (if any) and any subsequent elements to the right (increases their indices). The new elements will appear in this sequence in the order that they are returned by the specified collection's iterator. The behavior of this operation is unspecified if the specified collection is modified while the operation is in progress. (Note that this will occur if the specified collection is this sequence, and it's nonempty.)

Since Ion values can only have a single parent, this method will fail if the given collection is a non-empty IonContainer.

Parameters

index:int: index at which to insert first element from the specified collection.
c:Collection<? extends IonValue>: elements to be inserted into this sequence.

Returns:boolean

true if this sequence changed as a result of the call.

Exceptions

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()).

clone back to summary

clone	back to summary
public IonSequence clone() throws UnknownSymbolException Redeclares com.amazon.ion.IonContainer.clone. Doc from com.amazon.ion.IonValue.clone. Creates a copy of this value and all of its children. The cloned value may use the same shared symbol tables, but it will have an independent local symbol table if necessary. The cloned value will be modifiable regardless of whether this instance `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. Exceptions UnknownSymbolException: if any part of this value has unknown text but known Sid for its field name, annotation or symbol.

public IonSequence clone() throws UnknownSymbolException

Redeclares com.amazon.ion.IonContainer.clone.

Doc from com.amazon.ion.IonValue.clone.

Creates a copy of this value and all of its children. The cloned value may use the same shared symbol tables, but it will have an independent local symbol table if necessary. The cloned value will be modifiable regardless of whether this instance 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.

Exceptions

UnknownSymbolException:: if any part of this value has unknown text but known Sid for its field name, annotation or symbol.

contains back to summary

contains	back to summary
public boolean contains(Object o) Redeclares java.util.List.contains. Determines whether this sequence contains the given instance. Due to the reference-equality-based semantics of Ion sequences, this method does not use `Object#equals` as specified by the contract of `java.util.Collection`. Instead it uses reference equality (`==` operator) to find the given instance. Parameters o:Object Doc from java.util.List.contains. element whose presence in this list is to be tested Returns:boolean `true` if `o` is an element of this sequence. Exceptions NullPointerException: if `o` is `null`. ClassCastException: if `o` is not an `IonValue`.

public boolean contains(Object o)

Redeclares java.util.List.contains.

Determines whether this sequence contains the given instance.

Due to the reference-equality-based semantics of Ion sequences, this method does not use Object#equals as specified by the contract of java.util.Collection. Instead it uses reference equality (== operator) to find the given instance.

Parameters

o:Object

Doc from java.util.List.contains.

element whose presence in this list is to be tested

Returns:boolean

true if o is an element of this sequence.

Exceptions

NullPointerException:: if o is null.
ClassCastException:: if o is not an IonValue.

containsAll back to summary

containsAll	back to summary
public boolean containsAll(Collection<?> c) Redeclares java.util.List.containsAll. Determines whether this sequence contains all of the given instances. Due to the reference-equality-based semantics of Ion sequences, this method does not use `Object#equals` as specified by the contract of `java.util.Collection`. Instead it uses reference equality (`==` operator) to find the given instances. Parameters c:Collection<?> Doc from java.util.List.containsAll. collection to be checked for containment in this list Returns:boolean `true` if this sequence contains all of the elements of the given collection. Exceptions NullPointerException: if `c` is `null`. if `c` contains one or more `null` elements. ClassCastException: if `c` contains one or more elements that do not implement `IonValue`.

public boolean containsAll(Collection<?> c)

Redeclares java.util.List.containsAll.

Determines whether this sequence contains all of the given instances.

Parameters

c:Collection<?>

Doc from java.util.List.containsAll.

collection to be checked for containment in this list

Returns:boolean

true if this sequence contains all of the elements of the given collection.

Exceptions

NullPointerException:

if c is null.
if c contains one or more null elements.

ClassCastException:

if c contains one or more elements that do not implement IonValue.

extract back to summary

extract	back to summary
public <T extends IonValue> T[] extract(Class<T> type) Removes all children of this sequence, returning them in an array. This is much more efficient than iterating the sequence and removing children one by one. Returns:T[] a new array with all of the children of `s` in order, or `null` if `isNullValue()`. Exceptions NullPointerException: if `type` is `null`. ClassCastException: if any value in this sequence does not implement the given type.

public <T extends IonValue> T[] extract(Class<T> type)

Removes all children of this sequence, returning them in an array. This is much more efficient than iterating the sequence and removing children one by one.

Returns:T[]

a new array with all of the children of s in order, or null if isNullValue().

Exceptions

NullPointerException:: if type is null.
ClassCastException:: if any value in this sequence does not implement the given type.

get back to summary

get	back to summary
public IonValue get(int index) throws NullValueException, IndexOutOfBoundsException Redeclares java.util.List.get. Returns the element at the specified position in this sequence. Parameters index:int identifies the element to return. Returns:IonValue the element at the given index; not `null`. Exceptions NullValueException: if `isNullValue()`. IndexOutOfBoundsException: if the index is out of range (`index < 0 \|\| index >= size()`).

public IonValue get(int index) throws NullValueException, IndexOutOfBoundsException

Redeclares java.util.List.get.

Returns the element at the specified position in this sequence.

Parameters

index:int: identifies the element to return.

Returns:IonValue

the element at the given index; not null.

Exceptions

NullValueException:: if isNullValue().
IndexOutOfBoundsException:: if the index is out of range (index < 0 || index >= size()).

indexOf back to summary

indexOf	back to summary
public int indexOf(Object o) Redeclares java.util.List.indexOf. Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element. Due to the reference-equality-based semantics of Ion sequences, this method does not use `Object#equals` as specified by the contract of `java.util.List`. Instead it uses reference equality (`==` operator) to find the instance. Parameters o:Object the element to search for. Returns:int the index in this sequence of the element, or -1 if this sequence doesn't contain the element.

public int indexOf(Object o)

Redeclares java.util.List.indexOf.

Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.

Parameters

o:Object: the element to search for.

Returns:int

the index in this sequence of the element, or -1 if this sequence doesn't contain the element.

lastIndexOf back to summary

lastIndexOf	back to summary
public int lastIndexOf(Object o) Redeclares java.util.List.lastIndexOf. Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element. Due to the reference-equality-based semantics of Ion sequences, this method does not use `Object#equals` as specified by the contract of `java.util.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 `IonSequence#indexOf(Object)` Parameters o:Object the element to search for. Returns:int the index in this sequence of the element, or -1 if this sequence doesn't contain the element.

public int lastIndexOf(Object o)

Redeclares java.util.List.lastIndexOf.

Returns the index in the sequence of the specified element, or -1 if this sequence doesn't contain the element.

Due to the reference-equality-based semantics of Ion sequences, this method does not use Object#equals as specified by the contract of java.util.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 IonSequence#indexOf(Object)

Parameters

o:Object: the element to search for.

Returns:int

the index in this sequence of the element, or -1 if this sequence doesn't contain the element.

listIterator back to summary

listIterator	back to summary
public ListIterator<IonValue> listIterator() Redeclares java.util.List.listIterator. Returns a list iterator of the elements in this sequence (in proper order). The result does not support `ListIterator#add(Object)` or `ListIterator#set(Object)`. If this sequence `isReadOnly()` then it also does not support `Iterator#remove()`. Returns:ListIterator<IonValue> Doc from java.util.List.listIterator. a list iterator over the elements in this list (in proper sequence)

public ListIterator<IonValue> listIterator()

Redeclares java.util.List.listIterator.

Returns a list iterator of the elements in this sequence (in proper order).

The result does not support ListIterator#add(Object) or ListIterator#set(Object). If this sequence isReadOnly() then it also does not support Iterator#remove().

Returns:ListIterator<IonValue>

Doc from java.util.List.listIterator.

a list iterator over the elements in this list (in proper sequence)

listIterator back to summary

listIterator	back to summary
public ListIterator<IonValue> listIterator(int index) Redeclares java.util.List.listIterator. Returns a list iterator of the elements in this sequence (in proper order), starting at the specified position in this sequence. The result does not support `ListIterator#add(Object)` or `ListIterator#set(Object)`. If this sequence `isReadOnly()` then it also does not support `Iterator#remove()`. Parameters index:int index of first element to be returned from the list iterator (by a call to the `next` method). Returns:ListIterator<IonValue> Doc from java.util.List.listIterator. a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list Exceptions IndexOutOfBoundsException: if the index is out of range (`index < 0 \|\| index > size()`).

public ListIterator<IonValue> listIterator(int index)

Redeclares java.util.List.listIterator.

Returns a list iterator of the elements in this sequence (in proper order), starting at the specified position in this sequence.

The result does not support ListIterator#add(Object) or ListIterator#set(Object). If this sequence isReadOnly() then it also does not support Iterator#remove().

Parameters

index:int: index of first element to be returned from the list iterator (by a call to the next method).

Returns:ListIterator<IonValue>

Doc from java.util.List.listIterator.

a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list

Exceptions

IndexOutOfBoundsException:: if the index is out of range (index < 0 || index > size()).

remove	back to summary
public IonValue remove(int index) Redeclares java.util.List.remove. Removes the element at the specified position. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list. Parameters index:int the index of the element to be removed. Returns:IonValue the element previously at the specified position. Exceptions IndexOutOfBoundsException: if the index is out of range (index < 0 \|\| index >= size()).

remove

back to summary

public IonValue remove(int index)

Redeclares java.util.List.remove.

Removes the element at the specified position. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that was removed from the list.

Parameters

index:int: the index of the element to be removed.

Returns:IonValue

the element previously at the specified position.

Exceptions

IndexOutOfBoundsException:: if the index is out of range (index < 0 || index >= size()).

remove back to summary

remove	back to summary
public boolean remove(Object o) Redeclares java.util.List.remove. Removes a given `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` as specified by the contract of `java.util.Collection`. Instead it uses reference equality (`==` operator) to find the given instance. Parameters o:Object Doc from java.util.List.remove. element to be removed from this list, if present Returns:boolean `true` if this sequence changed as a result of the call. Exceptions NullPointerException: if `o` is `null`. ClassCastException: if `o` is not an `IonValue`.

public boolean remove(Object o)

Redeclares java.util.List.remove.

Removes a given IonValue from this sequence, if it is present.

Parameters

o:Object

Doc from java.util.List.remove.

element to be removed from this list, if present

Returns:boolean

true if this sequence changed as a result of the call.

Exceptions

NullPointerException:: if o is null.
ClassCastException:: if o is not an IonValue.

removeAll back to summary

removeAll	back to summary
public boolean removeAll(Collection<?> c) Redeclares java.util.List.removeAll. Removes all elements from this sequence that are also contained in the specified collection. After this call returns, this sequence will contain no elements in common with the specified collection. Due to the reference-equality-based semantics of Ion sequences, this method does not use `Object#equals` as specified by the contract of `java.util.Collection`. Instead it uses reference equality (`==` operator) to find the given instance. Parameters c:Collection<?> Doc from java.util.List.removeAll. collection containing elements to be removed from this list Returns:boolean `true` if this sequence changed as a result of the call. Exceptions NullPointerException: if `c` is `null`. if `c` contains one or more `null` elements. ClassCastException: if `c` contains one or more elements that do not implement `IonValue`.

public boolean removeAll(Collection<?> c)

Redeclares java.util.List.removeAll.

Removes all elements from this sequence that are also contained in the specified collection. After this call returns, this sequence will contain no elements in common with the specified collection.

Parameters

c:Collection<?>

Doc from java.util.List.removeAll.

collection containing elements to be removed from this list

Returns:boolean

true if this sequence changed as a result of the call.

Exceptions

NullPointerException:

if c is null.
if c contains one or more null elements.

ClassCastException:

if c contains one or more elements that do not implement IonValue.

retainAll back to summary

retainAll	back to summary
public boolean retainAll(Collection<?> c) Redeclares java.util.List.retainAll. Retains only the elements in this sequence that are also contained in the specified collection. In other words, removes from this sequence all of its elements that are not contained in the specified collection. Due to the reference-equality-based semantics of Ion sequences, this method does not use `Object#equals` as specified by the contract of `java.util.Collection`. Instead it uses reference equality (`==` operator) to find the given instance. Parameters c:Collection<?> Doc from java.util.List.retainAll. collection containing elements to be retained in this list Returns:boolean `true` if this sequence changed as a result of the call. Exceptions NullPointerException: if `c` is `null`. if `c` contains one or more `null` elements. ClassCastException: if `c` contains one or more elements that do not implement `IonValue`.

public boolean retainAll(Collection<?> c)

Redeclares java.util.List.retainAll.

Retains only the elements in this sequence that are also contained in the specified collection. In other words, removes from this sequence all of its elements that are not contained in the specified collection.

Parameters

c:Collection<?>

Doc from java.util.List.retainAll.

collection containing elements to be retained in this list

Returns:boolean

true if this sequence changed as a result of the call.

Exceptions

NullPointerException:

if c is null.
if c contains one or more null elements.

ClassCastException:

if c contains one or more elements that do not implement IonValue.

set back to summary

set	back to summary
public IonValue set(int index, IonValue element) Redeclares java.util.List.set. Replaces the element at the specified position in this list with the specified element. Parameters index:int index of the element to replace. element:IonValue element to be stored at the specified position. Returns:IonValue the element previously at the specified index. Exceptions 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 `isReadOnly()`. IndexOutOfBoundsException: if the index is out of range (`index < 0 \|\| index >= size()`).

public IonValue set(int index, IonValue element)

Redeclares java.util.List.set.

Replaces the element at the specified position in this list with the specified element.

Parameters

index:int: index of the element to replace.
element:IonValue: element to be stored at the specified position.

Returns:IonValue

the element previously at the specified index.

Exceptions

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 isReadOnly().
IndexOutOfBoundsException:: if the index is out of range (index < 0 || index >= size()).

subList back to summary

subList	back to summary
public List<IonValue> subList(int fromIndex, int toIndex) Redeclares java.util.List.subList. Returns a view of the portion of this list according to `List#subList(int, int)` contract. Sublist methods will throw a `java.util.ConcurrentModificationException` if its parent list, i.e. this list, had any changes that affect its size the after sublist was created. The implementation of `List<IonValue>` returned by this method implements `List#equals(Object)` and `List#equals(Object)` ()} per the specification of these methods. However, the existing implementation of `IonSequence` does not provide a specification compliant `List#equals` and `List#hashCode()`} which results to the following caveats: Given: `int[] ints = new int[] {1, 2, 3, 4}; IonList list = SYSTEM.newList(ints); IonSexp sexp = SYSTEM.newSexp(ints) IonSexp dgrm = SYSTEM.newDatagram(ints) List listSubList = list.subList(0, ints.size()) List sexpSubList = sexp.subList(0, ints.size()) List dgrmSubList = sexp.subList(0, ints.size()) List arrayList = new ArrayList(); for(int i : ints) { arrayList.add(SYSTEM.newInt(i)); }` `IonSequence#equals(Object)` always returns false when presented with a non `IonSequence` instance of `List<IonValue>`. Hence, the following invocations of `Object#equals(Object)` return false even if the contained elements are equivalent. This means that `Object#equals(Object)` is not symmetric in these cases. The reason for the asymmetry is historical: `IonSequence` has long violated the contract outlined by the `List` documentation. For the current major version of this library we maintain backwards compatibility and support this behaviour as-is. `list.equals(listSubList) // false list.equals(sexpSubList) // false list.equals(dgrm) // false list.equals(arrayList) // false sexp.equals(listSubList) // false sexp.equals(sexpSubList) // false sexp.equals(dgrm) // false sexp.equals(arrayList) // false dgrm.equals(listSubList) // false dgrm.equals(sexpSubList) // false dgrm.equals(dgrmSubList) // false dgrm.equals(arrayList) // false` However, `IonSequence#subList(int, int)` was implemented much later and faithfully implements `List#equals(Object)` meaning the cases below all work as expected. While `IonSequence` does not comply with the specification for `List#equals(Object)` because it has to comply with Ion's rules for equality, the same is not true for sub-lists. Unlike `IonSequence`, sub-lists have no notion of an `IonType`, annotations or nullability which allows for compliance with the `List` specification. listSubList.equals(listSubList); // true listSubList.equals(sexpSubList); // true listSubList.equals(dgrmSubList); // true listSubList.equals(list); // true listSubList.equals(sexp); // true listSubList.equals(arrayList); // true sexpSubList.equals(listSubList); // true sexpSubList.equals(sexpSubList); // true sexpSubList.equals(dgrmSubList); // true sexpSubList.equals(list); // true sexpSubList.equals(sexp); // true sexpSubList.equals(arrayList); // true dgrmSubList.equals(listSubList); // true dgrmSubList.equals(sexpSubList); // true dgrmSubList.equals(dgrmSubList); // true dgrmSubList.equals(list); // true dgrmSubList.equals(sexp); // true dgrmSubList.equals(arrayList); // true Parameters fromIndex:int Doc from java.util.List.subList. low endpoint (inclusive) of the subList toIndex:int Doc from java.util.List.subList. high endpoint (exclusive) of the subList Returns:List<IonValue> Doc from java.util.List.subList. a view of the specified range within this list See Also `List#subList(int, int)`

public List<IonValue> subList(int fromIndex, int toIndex)

Redeclares java.util.List.subList.

Returns a view of the portion of this list according to List#subList(int, int) contract.

Sublist methods will throw a java.util.ConcurrentModificationException if its parent list, i.e. this list, had any changes that affect its size the after sublist was created.

The implementation of List<IonValue> returned by this method implements List#equals(Object) and List#equals(Object) ()} per the specification of these methods. However, the existing implementation of IonSequence does not provide a specification compliant List#equals and List#hashCode()} which results to the following caveats: Given:


 int[] ints = new int[] {1, 2, 3, 4};
 IonList list = SYSTEM.newList(ints);
 IonSexp sexp = SYSTEM.newSexp(ints)
 IonSexp dgrm = SYSTEM.newDatagram(ints)
 List listSubList = list.subList(0, ints.size())
 List sexpSubList = sexp.subList(0, ints.size())
 List dgrmSubList = sexp.subList(0, ints.size())
 List arrayList = new ArrayList();
 for(int i : ints) { arrayList.add(SYSTEM.newInt(i)); }

IonSequence#equals(Object) always returns false when presented with a non IonSequence instance of List<IonValue>. Hence, the following invocations of Object#equals(Object) return false even if the contained elements are equivalent. This means that Object#equals(Object) is not symmetric in these cases. The reason for the asymmetry is historical: IonSequence has long violated the contract outlined by the List documentation. For the current major version of this library we maintain backwards compatibility and support this behaviour as-is.


 list.equals(listSubList)     // false
 list.equals(sexpSubList)     // false
 list.equals(dgrm)            // false
 list.equals(arrayList)       // false

 sexp.equals(listSubList)     // false
 sexp.equals(sexpSubList)     // false
 sexp.equals(dgrm)            // false
 sexp.equals(arrayList)       // false

 dgrm.equals(listSubList)     // false
 dgrm.equals(sexpSubList)     // false
 dgrm.equals(dgrmSubList)     // false
 dgrm.equals(arrayList)       // false

However, IonSequence#subList(int, int) was implemented much later and faithfully implements List#equals(Object) meaning the cases below all work as expected. While IonSequence does not comply with the specification for List#equals(Object) because it has to comply with Ion's rules for equality, the same is not true for sub-lists. Unlike IonSequence, sub-lists have no notion of an IonType, annotations or nullability which allows for compliance with the List specification.


 listSubList.equals(listSubList); // true
 listSubList.equals(sexpSubList); // true
 listSubList.equals(dgrmSubList); // true
 listSubList.equals(list);        // true
 listSubList.equals(sexp);        // true
 listSubList.equals(arrayList);   // true

 sexpSubList.equals(listSubList); // true
 sexpSubList.equals(sexpSubList); // true
 sexpSubList.equals(dgrmSubList); // true
 sexpSubList.equals(list);        // true
 sexpSubList.equals(sexp);        // true
 sexpSubList.equals(arrayList);   // true

 dgrmSubList.equals(listSubList); // true
 dgrmSubList.equals(sexpSubList); // true
 dgrmSubList.equals(dgrmSubList); // true
 dgrmSubList.equals(list);        // true
 dgrmSubList.equals(sexp);        // true
 dgrmSubList.equals(arrayList);   // true

Parameters

fromIndex:int

Doc from java.util.List.subList.

low endpoint (inclusive) of the subList

toIndex:int

Doc from java.util.List.subList.

high endpoint (exclusive) of the subList

Returns:List<IonValue>

Doc from java.util.List.subList.

a view of the specified range within this list

See Also

List#subList(int, int)

toArray back to summary

toArray	back to summary
public IonValue[] toArray() Redeclares java.util.List.toArray. Returns an array containing all of the elements in this sequence in proper order. Obeys the general contract of the `Collection#toArray()` method. If this sequence is an Ion null value, it will behave like an empty sequence. Returns:IonValue[] an array containing all of the elements in this sequence in proper order.

public IonValue[] toArray()

Redeclares java.util.List.toArray.

Returns an array containing all of the elements in this sequence in proper order. Obeys the general contract of the Collection#toArray() method.

If this sequence is an Ion null value, it will behave like an empty sequence.

Returns:IonValue[]: an array containing all of the elements in this sequence in proper order.

toArray back to summary

toArray	back to summary
public <T> T[] toArray(T[] a) Redeclares java.util.List.toArray. 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. Obeys the general contract of the `Collection#toArray()` method. If this sequence is an Ion null value, it will behave like an empty sequence. Parameters <T> Doc from java.util.Collection.toArray. the component type of the array to contain the collection a:T[] 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. Returns:T[] an array containing all of the elements in this sequence in proper order. Exceptions 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`.

public <T> T[] toArray(T[] a)

Redeclares java.util.List.toArray.

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. Obeys the general contract of the Collection#toArray() method.

If this sequence is an Ion null value, it will behave like an empty sequence.

Parameters

<T>: Doc from java.util.Collection.toArray. the component type of the array to contain the collection
a:T[]: 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.

Returns:T[]

an array containing all of the elements in this sequence in proper order.

Exceptions

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.

public Interface IonSequence

Method Summary

Method Detail