public Interface IPosition<T, P extends IPosition<T, P>>

Add/remove operations affect the index and span of this position depending on the anchor type of the position.

Once the span becomes 0, no modifications to the list can change it to span 1 element.

PositionAnchor#CURRENT - tracks a specific element at index when the position is instantiated. Adding elements before the position will shift the range down in the list. Removing elements before the position will shift the range up in the list. Removing elements which include the position's index will set its span to 0. The position is always available for adding/removing next/previous elements. The current element is only available when span is 1.

PositionAnchor#PREVIOUS - tracks the previous element to the position from which it was instantiated. The span will be 0 if no previous element existed when it was instantiated (ie. at position 0) or was removed later.

The index of this position reflects the position in the list previous to the position from which it was instantiated and the index is valid if span is 1 or index is >0. Relative offset <0 will be increased by 1 if span is 0 to reflect removal of previous element.

This anchor position type is used for iterating positions in reverse since it ignores insertions into the list immediately before the current position.

PositionAnchor#NEXT - tracks the next element to the position from which it was instantiated. The span will be 0 if no next element existed when it was instantiated (ie. at end of the list) or was removed later.

The index of this position reflects the position in the list next to the position from which it was instantiated and the index is valid if span is 1 or index is <list.size(). Relative offset >0 will be reduced by 1 if span is 0 to reflect removal of next element.

This anchor position type is used for iterating positions since it ignores insertions into the list immediately after the current position.

All offset based operations on this position are operations on the list at index relative to this position's index and span, so offsets may be -ve or +ve as long as absolute index is >=0 and <list.size()

Offset <0 refer to the elements preceding the element at this position. For PositionAnchor#PREVIOUS If span is 0 then the offset is increased by 1 to reflect that there is no current element at this position.

Offset >0 refer to the elements following the element at this position. If span is 0 then offset is reduced by 1 to reflect that there is no current element.

PositionList iterator will iterate over list elements while elements are added or removed from the list without affecting count of the iteration as long as elements are only added immediately before or after the current position.

This is not limited to adding 1 element. Each added element before or after the current position moves the previous/next element position in the list. The first addition is limited to relative offset of -1, 0 or 1 from current index if the addition is not to affect iteration.

The following operations can insert anywhere in the previously inserted range.

Deletions have no limitations. They can never cause new elements to be inserted after the next element position of the iterator so cannot cause iteration to continue on a newly added element.

All this makes list manipulation while traversing it easier to write, debug and understand because all operations are relative to current position instead of a numeric index. In the code you see -1, 0, +1, for previous, current and next element references taking removal and addition of elements into account.

PositionList adjusts all outstanding positions into its instance. Allowing getting multiple positions in the list before making modification, in order to track index of elements at those positions. If after modifications the position has 0 span, as reflected by its IPosition#isValidElement() being false, then the element at that position was removed. Otherwise, getIndex() will return the current index of that element in the list. If there is no valid element will return the index of the position, which will be the next available element in the list.

Index computations can be a real bug generator, throw inserting, deleting and traversing a list at the same time and you have a beast to debug and maintenance nightmare to look forward to. PositionList and Position instances make all that go away. That's why I wrote these classes so I don't have to write and debug the same error prone code for manipulating lists.