Package org.daiitech.naftah.builtin.utils.tuple

Class Tuple

java.lang.Object
org.daiitech.naftah.builtin.utils.tuple.Tuple
All Implemented Interfaces:
Serializable, Iterable<Object>, Collection<Object>, List<Object>, NTuple
public final class Tuple extends Object implements NTuple, List<Object>, Serializable
An immutable tuple implementation that implements List<Object>.

This class wraps an unmodifiable list of objects and provides factory methods to create tuples from arrays or lists. All mutating operations throw UnsupportedOperationException.

The string representation includes the Arabic word "تركيبة" meaning "Tuple".

Author:
Chakib Daii
See Also:

  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      See Also:

    • values

      private final List<Object> values
      The underlying unmodifiable list of tuple elements.

  • Constructor Details

    • Tuple

      private Tuple(Object... values)
      Private constructor to create a tuple from the given elements.

      The elements are stored in an immutable list using List.of(Object...). Once created, the tuple cannot be modified: no elements can be added, removed, or replaced. This ensures that the tuple is fully immutable.

      Parameters:
      values - the elements to be included in the tuple
      Throws:
      NullPointerException - if values is null or contains null elements

  • Method Details

    • of

      public static Tuple of(Object... elements)
      Creates a tuple from a variable number of elements.
      Parameters:
      elements - the elements to be included in the tuple
      Returns:
      a new Tuple containing the given elements
      Throws:
      NaftahBugError - if the input array is null

    • of

      public static Tuple of(List<?> elements)
      Creates a tuple from a list of elements.
      Parameters:
      elements - the list of elements to be included in the tuple
      Returns:
      a new Tuple containing the given list elements
      Throws:
      NaftahBugError - if the input list is null

    • arity

      public int arity()
      Returns the number of elements contained in this tuple.
      Specified by:
      arity in interface NTuple
      Returns:
      the arity (size) of this tuple, always >= 0

    • size

      public int size()
      Returns the number of elements in this tuple.
      Specified by:
      size in interface Collection<Object>
      Specified by:
      size in interface List<Object>
      Returns:
      the size of the tuple

    • isEmpty

      public boolean isEmpty()
      Checks if the tuple contains no elements.
      Specified by:
      isEmpty in interface Collection<Object>
      Specified by:
      isEmpty in interface List<Object>
      Returns:
      true if empty, false otherwise

    • contains

      public boolean contains(Object o)
      Checks if the tuple contains the specified element.
      Specified by:
      contains in interface Collection<Object>
      Specified by:
      contains in interface List<Object>
      Specified by:
      contains in interface NTuple
      Parameters:
      o - the element to check for presence
      Returns:
      true if the element is present, false otherwise

    • toArray

      public Object[] toArray()
      Returns an array containing all elements of the tuple.
      Specified by:
      toArray in interface Collection<Object>
      Specified by:
      toArray in interface List<Object>
      Specified by:
      toArray in interface NTuple
      Returns:
      an array of tuple elements

    • toArray

      public <T> T[] toArray(T[] a)
      Returns an array containing all elements of the tuple, using the provided array if it is large enough.
      Specified by:
      toArray in interface Collection<Object>
      Specified by:
      toArray in interface List<Object>
      Type Parameters:
      T - the type of the array elements
      Parameters:
      a - the array into which the elements are to be stored
      Returns:
      an array containing the elements of the tuple

    • toArray

      public <T> T[] toArray(IntFunction<T[]> f)
      Returns an array containing all elements of the tuple, using the provided array generator function.
      Specified by:
      toArray in interface Collection<Object>
      Type Parameters:
      T - the type of the array elements
      Parameters:
      f - the array generator function
      Returns:
      an array containing the elements of the tuple

    • toString

      public String toString()
      Returns a string representation of the tuple. The list's string as a tuple
      Overrides:
      toString in class Object
      Returns:
      the string representation of this tuple

    • iterator

      public Iterator<Object> iterator()
      Returns an iterator over the elements in this tuple.
      Specified by:
      iterator in interface Collection<Object>
      Specified by:
      iterator in interface Iterable<Object>
      Specified by:
      iterator in interface List<Object>
      Returns:
      an iterator over tuple elements

    • forEach

      public void forEach(Consumer<? super Object> action)
      Performs the given action for each element of the tuple.
      Specified by:
      forEach in interface Iterable<Object>
      Parameters:
      action - the action to be performed for each element

    • spliterator

      public Spliterator<Object> spliterator()
      Creates a Spliterator over the elements in this tuple.
      Specified by:
      spliterator in interface Collection<Object>
      Specified by:
      spliterator in interface Iterable<Object>
      Specified by:
      spliterator in interface List<Object>
      Returns:
      a spliterator over the tuple elements

    • stream

      public Stream<Object> stream()
      Returns a sequential Stream with the tuple elements.
      Specified by:
      stream in interface Collection<Object>
      Returns:
      a sequential stream over the tuple elements

    • parallelStream

      public Stream<Object> parallelStream()
      Returns a possibly parallel Stream with the tuple elements.
      Specified by:
      parallelStream in interface Collection<Object>
      Returns:
      a parallel stream over the tuple elements

    • equals

      public boolean equals(Object o)
      Checks equality with another object. Returns true if the other object is the same instance or if the underlying list equals the other object.
      Specified by:
      equals in interface Collection<Object>
      Specified by:
      equals in interface List<Object>
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare to
      Returns:
      true if equal, false otherwise

    • hashCode

      public int hashCode()
      Returns the hash code value for this tuple, delegated to the underlying list's hash code.
      Specified by:
      hashCode in interface Collection<Object>
      Specified by:
      hashCode in interface List<Object>
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of the tuple

    • get

      public Object get(int index)
      Returns the element at the specified position in this tuple.
      Specified by:
      get in interface List<Object>
      Specified by:
      get in interface NTuple
      Parameters:
      index - index of the element to return
      Returns:
      the element at the specified position

    • indexOf

      public int indexOf(Object o)
      Returns the index of the first occurrence of the specified element, or -1 if not found.
      Specified by:
      indexOf in interface List<Object>
      Parameters:
      o - the element to search for
      Returns:
      the index of the first occurrence, or -1 if not found

    • lastIndexOf

      public int lastIndexOf(Object o)
      Returns the index of the last occurrence of the specified element, or -1 if not found.
      Specified by:
      lastIndexOf in interface List<Object>
      Parameters:
      o - the element to search for
      Returns:
      the index of the last occurrence, or -1 if not found

    • listIterator

      public ListIterator<Object> listIterator()
      Returns a list iterator over the elements in this tuple.
      Specified by:
      listIterator in interface List<Object>
      Returns:
      a list iterator over the tuple elements

    • listIterator

      public ListIterator<Object> listIterator(int index)
      Returns a list iterator of the elements in this tuple, starting at the specified position.
      Specified by:
      listIterator in interface List<Object>
      Parameters:
      index - the index to start the iterator at
      Returns:
      a list iterator over the tuple elements starting at index

    • subList

      public Tuple subList(int fromIndex, int toIndex)
      Returns a view of the portion of this tuple between the specified indices. The returned view is wrapped in a new Tuple.
      Specified by:
      subList in interface List<Object>
      Parameters:
      fromIndex - the start index (inclusive)
      toIndex - the end index (exclusive)
      Returns:
      a new Tuple representing the specified range

    • add

      public boolean add(Object e)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      add in interface Collection<Object>
      Specified by:
      add in interface List<Object>
      Parameters:
      e - element to be added
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • remove

      public boolean remove(Object o)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      remove in interface Collection<Object>
      Specified by:
      remove in interface List<Object>
      Parameters:
      o - element to be removed
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • containsAll

      public boolean containsAll(Collection<?> c)
      Always returns false. (Note: This deviates from usual List behavior.)
      Specified by:
      containsAll in interface Collection<Object>
      Specified by:
      containsAll in interface List<Object>
      Parameters:
      c - the collection to check for containment
      Returns:
      false always

    • addAll

      public boolean addAll(Collection<?> coll)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      addAll in interface Collection<Object>
      Specified by:
      addAll in interface List<Object>
      Parameters:
      coll - collection containing elements to be added
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • removeAll

      public boolean removeAll(Collection<?> coll)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      removeAll in interface Collection<Object>
      Specified by:
      removeAll in interface List<Object>
      Parameters:
      coll - collection containing elements to be removed
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • retainAll

      public boolean retainAll(Collection<?> coll)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      retainAll in interface Collection<Object>
      Specified by:
      retainAll in interface List<Object>
      Parameters:
      coll - collection containing elements to be retained
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • clear

      public void clear()
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      clear in interface Collection<Object>
      Specified by:
      clear in interface List<Object>
      Throws:
      UnsupportedOperationException - always thrown

    • set

      public Object set(int index, Object element)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      set in interface List<Object>
      Parameters:
      index - index of element to replace
      element - element to be stored
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • add

      public void add(int index, Object element)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      add in interface List<Object>
      Parameters:
      index - index at which the specified element is to be inserted
      element - element to be inserted
      Throws:
      UnsupportedOperationException - always thrown

    • remove

      public Object remove(int index)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      remove in interface List<Object>
      Parameters:
      index - index of the element to be removed
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • addAll

      public boolean addAll(int index, Collection<?> c)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      addAll in interface List<Object>
      Parameters:
      index - index at which to insert elements
      c - collection containing elements to be added
      Returns:
      never returns normally
      Throws:
      UnsupportedOperationException - always thrown

    • replaceAll

      public void replaceAll(UnaryOperator<Object> operator)
      Not supported. Always throws UnsupportedOperationException.
      Specified by:
      replaceAll in interface List<Object>
      Parameters:
      operator - the operator to apply to each element
      Throws:
      UnsupportedOperationException - always thrown