com.helger.commons.collection.impl.ICommonsList Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ph-commons Show documentation
Show all versions of ph-commons Show documentation
Java 1.8+ Library with tons of utility classes required in all projects
/*
* Copyright (C) 2014-2024 Philip Helger (www.helger.com)
* philip[at]helger[dot]com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.helger.commons.collection.impl;
import java.util.Collections;
import java.util.Comparator;
import java.util.List;
import java.util.function.Function;
import java.util.function.Predicate;
import javax.annotation.Nonnegative;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import com.helger.commons.annotation.CodingStyleguideUnaware;
import com.helger.commons.annotation.ReturnsMutableCopy;
import com.helger.commons.lang.ICloneable;
import com.helger.commons.state.EChange;
/**
* A special {@link List} interface with extended functionality based on
* {@link ICommonsCollection}.
*
* @author Philip Helger
* @param
* The data type of the elements in the list.
*/
public interface ICommonsList extends
List ,
ICommonsCollection ,
ICloneable >
{
/**
* Create a new empty list. Overwrite this if you don't want to use
* {@link CommonsArrayList}.
*
* @return A new empty list. Never null.
* @param
* List element type
*/
@Nonnull
@ReturnsMutableCopy
default ICommonsList createInstance ()
{
return new CommonsArrayList <> ();
}
/**
* Get all elements matching the provided filter. If no filter is provided,
* the return value is same as {@link #getClone()}.
*
* @param aFilter
* The filter to be applied. May be null.
* @return A non-null copy of this list containing all matching
* entries (or all entries if no filter is provided).
* @see #findAll(Predicate, java.util.function.Consumer)
*/
@Nonnull
@ReturnsMutableCopy
default ICommonsList getAll (@Nullable final Predicate aFilter)
{
if (aFilter == null)
return getClone ();
final ICommonsList ret = createInstance ();
findAll (aFilter, ret::add);
return ret;
}
/**
* Create a new list where all existing elements are mapped with the provided
* function.
*
* @param aMapper
* The mapping function to be executed. May not be null.
* @return A new non-null list with all mapped elements.
* @param
* The destination type to be mapped to
* @see #getAllMapped(Predicate, Function)
* @see #findAllMapped(Function, java.util.function.Consumer)
*/
@Nonnull
@ReturnsMutableCopy
default ICommonsList getAllMapped (@Nonnull final Function aMapper)
{
final ICommonsList ret = createInstance ();
findAllMapped (aMapper, ret::add);
return ret;
}
/**
* Create a new list where all elements matching the filter are mapped with
* the provided function.
*
* @param aFilter
* The filter to be applied. Maybe null.
* @param aMapper
* The mapping function to be executed. May not be null.
* @return A new non-null list with all mapped elements. If no
* filter is provided the result is the same as of
* {@link #getAllMapped(Function)}.
* @param
* The destination type to be mapped to
* @see #getAllMapped(Function)
* @see #findAllMapped(Predicate, Function, java.util.function.Consumer)
*/
@Nonnull
@ReturnsMutableCopy
default ICommonsList getAllMapped (@Nullable final Predicate aFilter,
@Nonnull final Function aMapper)
{
final ICommonsList ret = createInstance ();
findAllMapped (aFilter, aMapper, ret::add);
return ret;
}
/**
* Get all instances of the provided class that are contained in this list.
*
* @param aDstClass
* The class to search all instances of. May not be null.
* @return A list with all instances of the provided class, already casted.
* Never null.
* @param
* The destination type to be casted to
* @see #findAllInstanceOf(Class, java.util.function.Consumer)
*/
@Nonnull
@ReturnsMutableCopy
default ICommonsList getAllInstanceOf (@Nonnull final Class aDstClass)
{
final ICommonsList ret = createInstance ();
findAllInstanceOf (aDstClass, ret::add);
return ret;
}
/**
* Note: this methods conflicts with a method added in Java SE 21 in class
* ArrayList. Therefore {@link #getFirstOrNull()} should be used instead.
*
* @return The first element of the list or null if the list is
* empty.
* @see #getFirst(Object)
* @see #findFirst(Predicate)
* @deprecated Use {@link #getFirstOrNull()} instead
*/
@Nullable
@Deprecated (forRemoval = true, since = "11.1.5")
default ELEMENTTYPE getFirst ()
{
return getFirst (null);
}
/**
* @return The first element of the list or null if the list is
* empty.
* @see #getFirst(Object)
* @see #findFirst(Predicate)
* @since 11.1.5
*/
@Nullable
default ELEMENTTYPE getFirstOrNull ()
{
return getFirst (null);
}
/**
* @param aDefault
* The default value to be returned if this list is empty. May be
* null.
* @return The first element of the list or the provided default value if the
* list is empty.
* @see #getFirstOrNull()
* @see #findFirst(Predicate)
*/
@Nullable
default ELEMENTTYPE getFirst (@Nullable final ELEMENTTYPE aDefault)
{
return isEmpty () ? aDefault : get (0);
}
/**
* Note: this methods conflicts with a method added in Java SE 21 in class
* ArrayList. Therefore {@link #getLastOrNull()} should be used instead.
*
* @return The last element of the list or null if the list is
* empty.
* @see #getLast(Object)
* @deprecated Use {@link #getLastOrNull()} instead
*/
@Nullable
@Deprecated (forRemoval = true, since = "11.1.5")
default ELEMENTTYPE getLast ()
{
return getLast (null);
}
/**
* @return The last element of the list or null if the list is
* empty.
* @see #getLast(Object)
* @since 11.1.5
*/
@Nullable
default ELEMENTTYPE getLastOrNull ()
{
return getLast (null);
}
/**
* @param aDefault
* The default value to be returned if this list is empty. May be
* null.
* @return The last element of the list or null if the list is
* empty.
* @see #getLastOrNull()
*/
@Nullable
default ELEMENTTYPE getLast (@Nullable final ELEMENTTYPE aDefault)
{
final int nSize = size ();
return nSize == 0 ? aDefault : get (nSize - 1);
}
/*
* Special overload with the index-based access.
*/
@Override
@Nullable
default ELEMENTTYPE getAtIndex (@Nonnegative final int nIndex, @Nullable final ELEMENTTYPE aDefault)
{
return nIndex >= 0 && nIndex < size () ? get (nIndex) : aDefault;
}
/**
* Set the first element of this list.
*
* @param aNewElement
* The new element at index 0.
* @return The previous element. May be null.
* @see #set(int, Object)
*/
@Nullable
default ELEMENTTYPE setFirst (@Nullable final ELEMENTTYPE aNewElement)
{
return set (0, aNewElement);
}
/**
* Set the last element of this list.
*
* @param aNewElement
* The new element at index size()-1.
* @return The previous element. May be null.
* @see #set(int, Object)
*/
@Nullable
default ELEMENTTYPE setLast (@Nullable final ELEMENTTYPE aNewElement)
{
return set (size () - 1, aNewElement);
}
/**
* Remove the element at the specified index from the passed list. This works
* if the list is not null and the index is ≥ 0 and <
* list.size()
*
* @param nIndex
* The index to be removed. May be arbitrary.
* @return {@link EChange#CHANGED} if removal was successful
* @see #removeAndReturnElementAtIndex(int)
*/
@Nonnull
default EChange removeAtIndex (final int nIndex)
{
if (nIndex < 0 || nIndex >= size ())
return EChange.UNCHANGED;
remove (nIndex);
return EChange.CHANGED;
}
/**
* Remove the element at the specified index from the passed list. This works
* if the list is not null and the index is ≥ 0 and <
* list.size()
*
* @param nIndex
* The index to be removed. May be arbitrary.
* @return null if removal failed or the removed element. Note:
* the removed element may also be null so it may be
* tricky to determine if removal succeeded or not!
* @see #removeAtIndex(int)
*/
@Nullable
default ELEMENTTYPE removeAndReturnElementAtIndex (final int nIndex)
{
return nIndex < 0 || nIndex >= size () ? null : remove (nIndex);
}
/**
* Remove the first element of the list.
* Note: this methods conflicts with a method added in Java SE 21 in class
* ArrayList. Therefore {@link #removeFirstOrNull()} should be used instead.
*
* @return null if the list is empty or the previously contained
* element at index 0.
* @deprecated Use {@link #removeFirstOrNull()} instead
*/
@Nullable
@Deprecated (forRemoval = true, since = "11.1.5")
default ELEMENTTYPE removeFirst ()
{
return removeFirstOrNull ();
}
/**
* Remove the first element of the list.
*
* @return null if the list is empty or the previously contained
* element at index 0.
* @since 11.1.5
*/
@Nullable
default ELEMENTTYPE removeFirstOrNull ()
{
return isEmpty () ? null : remove (0);
}
/**
* Remove the last element of the list.
* Note: this methods conflicts with a method added in Java SE 21 in class
* ArrayList. Therefore {@link #removeLastOrNull()} should be used instead.
*
* @return null if the list is empty or the previously contained
* element at index size()-1.
*/
@Nullable
@Deprecated (forRemoval = true, since = "11.1.5")
default ELEMENTTYPE removeLast ()
{
return removeLastOrNull ();
}
/**
* Remove the last element of the list.
*
* @return null if the list is empty or the previously contained
* element at index size()-1.
* @since 11.1.5
*/
@Nullable
default ELEMENTTYPE removeLastOrNull ()
{
final int nSize = size ();
return nSize == 0 ? null : remove (nSize - 1);
}
@Override
@Nonnull
@CodingStyleguideUnaware
default List getAsUnmodifiable ()
{
return Collections.unmodifiableList (this);
}
/**
* Sort this line without creating a copy.
*
* @param aComparator
* The comparator used for sorting. May not be null.
* @return this for chaining
*/
@Nonnull
default ICommonsList getSortedInline (@Nonnull final Comparator aComparator)
{
sort (aComparator);
return this;
}
/**
* Reverse the order of this list.
*
* @return this for chaining
*/
@Nonnull
default ICommonsList reverse ()
{
Collections.reverse (this);
return this;
}
/**
* Swap list items.
*
* @param nFirstIndex
* The first index to swap.
* @param nSecondIndex
* The second index to swap.
* @return this for chaining
* @since 8.6.0
*/
@Nonnull
default ICommonsList swapItems (final int nFirstIndex, final int nSecondIndex)
{
if (nFirstIndex != nSecondIndex)
{
final ELEMENTTYPE aTmp = get (nFirstIndex);
set (nFirstIndex, get (nSecondIndex));
set (nSecondIndex, aTmp);
}
return this;
}
}