com.jongsoft.lang.collection.Sequence Maven / Gradle / Ivy
The newest version!
/*
* The MIT License
*
* Copyright 2016-2019 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 com.jongsoft.lang.API;
import com.jongsoft.lang.Collections;
import com.jongsoft.lang.collection.tuple.Pair;
import java.util.Comparator;
import java.util.NoSuchElementException;
import java.util.Objects;
import java.util.function.Function;
import java.util.function.Predicate;
import java.util.function.Supplier;
/**
*
* 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.
*
*
* Creating a new sequence can be achieved by using the on of the following operations:
*
*
* - {@link com.jongsoft.lang.Collections#List(Iterator)}
* - {@link com.jongsoft.lang.Collections#List(Iterable)}
* - {@link com.jongsoft.lang.Collections#List(Object[])}
* - {@link com.jongsoft.lang.Collections#List(Object)}
*
*
* Single change operations
*
* Operation Description {@linkplain #append(Object)} Add element 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
*
* Collection 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 set 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);
@Override
Sequence replace(int index, T replacement);
@Override
Sequence replaceIf(Predicate predicate, T replacement);
/**
* 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
Map> groupBy(Function keyGenerator);
@Override
default Sequence reject(Predicate predicate) {
Objects.requireNonNull(predicate, "predicate is null");
return filter(predicate.negate());
}
@Override
default Pair, ? extends Sequence> split(Predicate predicate) {
Objects.requireNonNull(predicate, "predicate is null");
final Map> pairs = groupBy(predicate::test);
return API.Tuple(pairs.get(true), pairs.get(false));
}
/**
* Generate a new set containing only unique elements from this collection. As identified by their
* {@link Object#hashCode()}.
*
* @return a set with unique elements
*/
Set distinct();
@Override
Set distinctBy(Comparator comparator);
@Override
Sequence map(Function mapper);
@Override
default Sequence orElse(Iterable other) {
return isEmpty() ? Collections.List(other) : this;
}
@Override
default Sequence orElse(Supplier> supplier) {
return isEmpty() ? Collections.List(supplier.get()) : this;
}
/**
* Transform this collection into one supported natively in Java.
*
* @return the native java collection
*/
java.util.List toJava();
@Override
Sequence sorted();
@Override
Sequence union(Iterable iterable);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy