com.jongsoft.lang.collection.Sequence Maven / Gradle / Ivy
/*
* The MIT License
*
* Copyright 2016-2018 Jong Soft.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
package com.jongsoft.lang.collection;
import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.function.Function;
import java.util.function.Predicate;
/**
*
* Sequences are ordered collections of elements.
* These collections allow for appending duplicate entries, but all entries will always be returned in the order that they were added or
* inserted.
*
*
*
* Single change operations
*
* Operation Description {@linkplain #append(Object)} Add element to end of the sequence {@linkplain #union(Iterable)} Add elements to end of the sequence {@linkplain #prepend(Object)} Add elements to start of the sequence {@linkplain #insert(int, Object)} Add an element to the indicated place {@linkplain #remove(Object)} Remove the element {@linkplain #remove(int)} Remove the element at the indicated place
*
*
* Set operations
*
* Operation Description {@linkplain #union(Iterable)} Combine this sequence of elements with the provided iterable {@linkplain #reject(Predicate)} Create a new sequence without the rejected values matching the
* predicate {@linkplain #filter(Predicate)} Create a new sequence with values matching the predicate {@linkplain #map(Function)} Create a new sequence with the mapped values {@linkplain #distinct()} Create a sequence with only unique elements
*
*
* Note: all operation that alter the contents of the sequence will return a new instance.
*
*
* @param the entity type of the sequence
*/
public interface Sequence extends List {
@Override
default Sequence append(T value) {
return insert(size(), value);
}
/**
* Create a new sequence with the provided {@code value} at position 0 and the remainder of this sequence from position 1 to
* {@linkplain #size()} + 1.
*
* Example:
* {@code // will result in a sequence with 1, 2, 3, 4
* Sequence(2, 3, 4).prepend(1)
* }
*
* @param value the value to be added
* @return the new list with the value appended
*/
default Sequence prepend(T value) {
return insert(0, value);
}
/**
* Add an element to the list at the provided index, shifting all elements after the index one.
*
* @param index the index at which to insert the element
* @param value the element to insert
* @return the updated list with the inserted element
*/
Sequence insert(int index, T value);
@Override
Sequence remove(int index);
/**
* Removes the first element found matching the provided value. The match is done based upon the
* {@link java.util.Objects#equals(Object, Object)} call.
*
* @param value the element to be removed
* @return the current list if the element is not present, otherwise a new list instance without the element in it.
*/
default Sequence remove(T value) {
int idx = indexOf(value);
if (idx > -1) {
return remove(idx);
}
return this;
}
@Override
default T head() {
if (size() > 0) {
return get(0);
}
throw new NoSuchElementException("Cannot get head on empty collection");
}
@Override
Sequence tail();
/**
* Reverse the order of the elements in the sequence.
*
* @return the reversed sequence
*/
Sequence reverse();
@Override
Sequence filter(Predicate predicate);
@Override
default Sequence reject(Predicate predicate) {
Objects.requireNonNull(predicate, "predicate is null");
return filter(predicate.negate());
}
/**
* Generate a new sequence containing only unique elements from this collection.
*
* @return a new unique sequence
*/
Sequence distinct();
@Override
Sequence map(Function mapper);
/**
* Generate a new sequence using the {@code keyGenerator}.
* Calling this operation will create a new map grouping the elements by the generator provided.
* Example:
* {@code // This will result in Map(1 -> List(1, 11, 21), 2 -> List(2, 12, 22))
* List(1, 2, 11, 12, 21, 22)
* .groupBy(x -> x % 10);
* }
*
* @param keyGenerator the generator to use for creating keys
* @param the type of the key
* @return the new map created using the generator
* @throws NullPointerException if {@code keyGenerator} is null
*/
Map> groupBy(Function keyGenerator);
/**
* Create a new sequence with all elements of this sequence combined with the elements of the provided iterable.
* The elements in this sequence will be added before the provided {@code iterable} in the returned sequence.
*
* Example:
* {@code // the example would be a List(1, 2, 3, 4)
* Sequence result = List(1, 2).union(Sequence(3, 4));
* }
*
* @param iterable the elements to be added
* @return the new list containing a union between this and the iterable
*/
Sequence union(Iterable iterable);
/**
* Transform this collection into one supported natively in Java.
*
* @return the native java collection
*/
java.util.List toJava();
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy