All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.shapesecurity.functional.data.ImmutableList Maven / Gradle / Ivy

Go to download

Shift format ECMAScript 6 AST tooling

There is a newer version: 2.2.0
Show newest version
/*
 * Copyright 2014 Shape Security, Inc.
 *
 * 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.shapesecurity.functional.data;

import java.lang.reflect.Array;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.NoSuchElementException;

import com.shapesecurity.functional.Effect;
import com.shapesecurity.functional.F;
import com.shapesecurity.functional.F2;
import com.shapesecurity.functional.Pair;
import com.shapesecurity.functional.Thunk;

import org.jetbrains.annotations.NotNull;

/**
 * An immutable singly linked list implementation. None of the operations in {@link ImmutableList} changes the list itself. Therefore you can freely share the list in
 * your system.
 * 

 * This is a "classical" list implementation that the list is only allowed to prepend and to remove the first element efficiently.
 * Therefore it is essentially equivalent to a stack.
 * 

 * It is either an empty list, or a record that contains the first element (called "head") and a list that follows(called "tail").
 * With the assumption that all the elements in the list are also immutable, the sharing of the tails is possible.
 * 

 * For a data structure that allows O(1) concatenation, try {@link ConcatList}. A BinaryTree can be converted into a List in O(n) time.
 *
 * @param  The super type of all the elements.
 */
public abstract class ImmutableList implements Iterable {
  private static final ImmutableList NIL = new Nil<>();
  @NotNull
  private final Thunk hashCodeThunk = Thunk.from(this::calcHashCode);

  /**
   * The length of the list.
   */
  public final int length;

  // package local
  ImmutableList(int length) {
    super();
    this.length = length;
  }

  /**
   * Creating List from.
   *
   * @param arrayList The {@link java.util.ArrayList} to construct the {@link ImmutableList} from.
   * @param        The type of the elements of the list.
   * @return a new {@link ImmutableList} that is comprised of all the elements in the {@link java.util.ArrayList}.
   */
  @NotNull
  public static  ImmutableList from(@NotNull ArrayList arrayList) {
    // Manual expansion of tail recursion.
    ImmutableList l = nil();
    int size = arrayList.size();
    for (int i = size - 1; i >= 0; i--) {
      l = cons(arrayList.get(i), l);
    }
    return l;
  }

  /**
   * Prepends "cons" an head element to a {@link ImmutableList}.
   *
   * @param head The head element to be prepended to the {@link ImmutableList}.
   * @param tail The {@link ImmutableList} to be prepended to.
   * @param   The super type of both the element and the {@link ImmutableList}
   * @return A {@link ImmutableList} that is comprised of the head then the tail.
   */
  public static  NonEmptyImmutableList cons(@NotNull T head, @NotNull ImmutableList tail) {
    return new NonEmptyImmutableList<>(head, tail);
  }

  // Construction

  @SuppressWarnings("unchecked")
  public static  ImmutableList nil() {
    return (ImmutableList) NIL;
  }

  @SuppressWarnings("unchecked")
  public static  ImmutableList list() {
    return (ImmutableList) NIL;
  }

  /**
   * A helper constructor to create a {@link NonEmptyImmutableList}.
   * @param head The first element
   * @param el rest of the elements
   * @param  The type of the element
   * @return a NonEmptyImmutableList of type T.
   */
  @NotNull
  @SafeVarargs
  public static  NonEmptyImmutableList list(@NotNull T head, @NotNull T... el) {
    if (el.length == 0) {
      return cons(head, ImmutableList.nil());
    }
    NonEmptyImmutableList l = cons(el[el.length - 1], ImmutableList.nil());
    for (int i = el.length - 2; i >= 0; i--) {
      l = cons(el[i], l);
    }
    return cons(head, l);
  }

  /**
   * A helper constructor to create a potentially empty {@link ImmutableList}.
   * @param el Elements of the list
   * @param  The type of elements
   * @return a ImmutableList of type A.
   */
  @NotNull
  @SafeVarargs
  public static  ImmutableList from(@NotNull A... el) {
    if (el.length == 0) {
      return nil();
    }
    NonEmptyImmutableList l = cons(el[el.length - 1], ImmutableList.nil());
    for (int i = el.length - 2; i >= 0; i--) {
      l = cons(el[i], l);
    }
    return l;
  }

  protected abstract int calcHashCode();

  @Override
  public final int hashCode() {
    return this.hashCodeThunk.get();
  }

  @Override
  public Iterator iterator() {

    return new Iterator() {
      private ImmutableList curr = ImmutableList.this;

      @Override
      public boolean hasNext() {
        return !this.curr.isEmpty();
      }

      @Override
      public A next() {
        if (this.curr.isEmpty()) {
          throw new NoSuchElementException();
        }
        A head = this.curr.maybeHead().just();
        this.curr = this.curr.maybeTail().just();
        return head;
      }

      @Override
      public void remove() {
        throw new UnsupportedOperationException();
      }
    };
  }

  // Methods

  /**
   * Prepend an element to the list.
   *
   * @param left The element to prepend.
   * @return A list with left as the first element followed by this.
   */
  @NotNull
  public final NonEmptyImmutableList cons(@NotNull A left) {
    return cons(left, this);
  }

  /**
   * Classic "foldl" operation on the {@link ImmutableList}.
   *
   * @param f    The function.
   * @param init The initial value.
   * @param   The type of the result of the folding.
   * @return The result of the folder.
   * @see http://en.wikipedia.org/wiki/Fold_
   * (higher-order_function)
   */
  @NotNull
  public abstract  B foldLeft(@NotNull F2 f, @NotNull B init);

  /**
   * Classic "foldr" operation on the {@link ImmutableList}.
   *
   * @param f    The function.
   * @param init The initial value.
   * @param   The type of the result of the folding.
   * @return The result of the folder.
   * @see http://en.wikipedia.org/wiki/Fold_
   * (higher-order_function)
   */
  @NotNull
  public abstract  B foldRight(@NotNull F2 f, @NotNull B init);

  /**
   * Returns the head of the {@link ImmutableList}.
   *
   * @return Maybe.just(head of the list), or Maybe.nothing() if the list is empty.
   */
  @NotNull
  public abstract Maybe maybeHead();

  /**
   * Returns the last of the {@link ImmutableList}.
   *
   * @return Maybe.just(last of the list), or Maybe.nothing() if the list is empty.
   */
  @NotNull
  public abstract Maybe maybeLast();

  /**
   * Returns the tail of the {@link ImmutableList}.
   *
   * @return Maybe.just(tail of the list), or Maybe.nothing() if the list is empty.
   */
  @NotNull
  public abstract Maybe> maybeTail();

  /**
   * Returns the init of the {@link ImmutableList}. The init of a List is defined as the rest of List removing the last element.
   *
   * @return Maybe.just(init of the list), or Maybe.nothing() if the list is empty.
   */
  @NotNull
  public abstract Maybe> maybeInit();

  /**
   * Returns a new list of elements when applying f to an element returns true.
   *
   * @param f The "predicate" function.
   * @return A new list of elements that satisfies the predicate.
   */
  @NotNull
  public abstract ImmutableList filter(@NotNull F f);

  /**
   * Applies the f function to each of the elements of the list and collect the result.
   * It will be a new list with the same length of the original one.
   *
   * @param f   The function to apply.
   * @param  The type of the new {@link ImmutableList}.
   * @return The new {@link ImmutableList} containing the result.
   */
  @NotNull
  public abstract  ImmutableList map(@NotNull F f);

  /**
   * Applies the f function to each of the elements of the list and collect the result.
   * This method also provides an extra index parameter to f function as the first parameter.
   *
   * @param f   The function to apply.
   * @param  The type of the new {@link ImmutableList}.
   * @return The new {@link ImmutableList} containing the result.
   */
  @NotNull
  public abstract  ImmutableList mapWithIndex(@NotNull F2 f);

  /**
   * The the first n elements of the list and create a new List of them. If the original
   * list contains less than n elements, returns a copy of the original List.
   *
   * @param n The number of elements to take.
   * @return A new list containing at most n elements that are the first elements of the original list.
   */
  @NotNull
  public abstract ImmutableList take(int n);

  /**
   * Removes the first n elements of the list and return the rest of the List by reference. If the original list
   * contains less than n elements, returns an empty list as if it is returned by {@link #nil}.
   *
   * @param n The number of elements to skip.
   * @return A shared list containing at most n elements removed from the original list.
   */
  @NotNull
  public abstract ImmutableList drop(int n);

  /**
   * Specialize this type to be a {@link NonEmptyImmutableList} if possible.
   *
   * @return Returns is Maybe.just(this) if this is indeed non-empty. Otherwise returns Maybe.nothing().
   */
  @NotNull
  public abstract Maybe> toNonEmptyList();

  /**
   * Deconstruct the list in to its head and tail, and feed them into another function f.
   *
   * @param f   The function to receive the head and tail if they exist.
   * @param  The return type of f
   * @return If the list is an non-empty list, returns Maybe.just(f(head, tail)); otherwise returns Maybe.nothing().
   */
  @NotNull
  public abstract  Maybe decons(@NotNull F2, B> f);

  /**
   * Takes another list and feeds the elements of both lists to a function at the same pace, then collects the result and forms another list.
   * Stops once either of the two lists came to an end.
   * 

   * Another way to visualize this operation is to imagine this operation as if it's zipping a zipper. taking two lists of things, merge them one by one,
   * and collect the results.
   *
   * @param f    The function to apply
   * @param list the other list to zip with this.
   * @param   The type of the element of the other list.
   * @param   The type of the result of the merging function.
   * @return The return type of the merging function.
   */
  @NotNull
  public abstract  ImmutableList zipWith(@NotNull F2 f, @NotNull ImmutableList list);

  /**
   * Converts this list into an array.
   * 

   * Due to type erasure, the type of the resulting array has to be determined at runtime. Fortunately, you can create a zero length array and this method
   * can create an large enough array to contain all the elements. If the given array is large enough, this method will put elements in it.
   *
   * @param target The target array.
   * @return The array that contains the elements. It may or may not be the same reference of target.
   */
  @SuppressWarnings("unchecked")
  @NotNull
  public final A[] toArray(@NotNull A[] target) {
    int length = this.length;
    if (target.length < length) {
      // noinspection unchecked
      target = (A[]) Array.newInstance(target.getClass().getComponentType(), length);
    }
    ImmutableList l = this;
    for (int i = 0; i < length; i++) {
      target[i] = l.maybeHead().just();
      l = l.maybeTail().just();
    }
    return target;
  }

  /**
   * Runs an effect function across all the elements.
   *
   * @param f The Effect function.
   */
  public final void foreach(@NotNull Effect f) {
    // Hand expanded recursion.
    ImmutableList list = this;
    Maybe head;
    while ((head = list.maybeHead()).isJust()) {
      f.e(head.just());
      list = list.maybeTail().just();
    }
  }

  public abstract boolean isEmpty();

  /**
   * Creates a list with the content of the current list followed by another list. If the current list is empty, simply return the second one.
   *
   * @param defaultClause The list to concatenate with. It will be reused as part of the returned list.
   * @param            The type of the resulting list.
   * @return The concatenation of the two lists.
   */
  @NotNull
  public abstract  ImmutableList append(@NotNull ImmutableList defaultClause);

  /**
   * Tests all the elements in the {@link ImmutableList} with predicate f until it finds the element of reaches the end, then returns whether an element
   * has been found or not.
   *
   * @param f The predicate.
   * @return Whether an elements satisfies the predicate f.
   */
  public abstract boolean exists(@NotNull F f);

  /**
   * Separates the list into a pair of lists such that 1. the concatenation of the lists is equal to this; 2. The first list is the longest list
   * that every element of the list fails the predicate f.
   *
   * @param f The predicate.
   * @return The pair.
   */
  @NotNull
  public abstract Pair, ImmutableList> span(@NotNull F f);

  /**
   * A synonym of {@link #flatMap}.
   *
   * @param f   The function.
   * @param  The type of result function.
   * @return The result of bind.
   */
  @NotNull
  public final  ImmutableList bind(@NotNull F> f) {
    return this.flatMap(f);
  }

  /**
   * Apply f to each element of this list to get a list of lists (of not necessarily the same type), then concatenate all these lists to get a
   * single list.
   * 

   * This operation can be thought of as a generalization of {@link #map} and {@link #filter}, which, instead of keeping the number of elements in the list,
   * changes the number and type of the elements in an customizable way but keeps the original order.
   * 

   * This operation can also be thought of as an assembly line that takes one stream of input and returns another stream of output, but not necessarily of
   * the
   * same size, type or number.
   * 

   * This operation is often called "bind" or ">>=" of a monad in pure functional programming context.
   *
   * @param f   The function to expand the list element.
   * @param  The type of the result list.
   * @return The result list.
   */
  @NotNull
  public abstract  ImmutableList flatMap(@NotNull F> f);

  public final boolean isNotEmpty() {
    return !isEmpty();
  }

  /**
   * Tests the elements of the list with a predicate f and returns the first one that satisfies the predicate without testing the rest of the
   * list.
   *
   * @param f The predicate.
   * @return Maybe.just(the found element) if an element is found or Maybe.nothing() if none is found.
   */
  @NotNull
  public final Maybe find(@NotNull F f) {
    ImmutableList self = this;
    while (self instanceof NonEmptyImmutableList) {
      NonEmptyImmutableList selfNel = (NonEmptyImmutableList) self;
      boolean result = f.apply(selfNel.head);
      if (result) {
        return Maybe.just(selfNel.head);
      }
      self = selfNel.tail();
    }
    return Maybe.nothing();
  }

  /**
   * Run f on each element of the list and return the result immediately if it is a
   * Maybe.just. Other wise return Maybe.nothing()
   *
   * @param f The predicate.
   * @param  The type of the result of the mapping function.
   *
   * @return Maybe.just(the found element) if an element is found or Maybe.nothing() if none is found.
   */
  @NotNull
  public final  Maybe findMap(@NotNull F> f) {
    ImmutableList self = this;
    while (self instanceof NonEmptyImmutableList) {
      NonEmptyImmutableList selfNel = (NonEmptyImmutableList) self;
      Maybe result = f.apply(selfNel.head);
      if (result.isJust()) {
        return result;
      }
      self = selfNel.tail();
    }
    return Maybe.nothing();
  }

  /**
   * Creats a new list with all the elements but those satisfying the predicate.
   *
   * @param f The predicate.
   * @return A new list of filtered elements.
   */
  @NotNull
  public abstract ImmutableList removeAll(@NotNull F f);

  /**
   * Reverses the list in linear time.
   *
   * @return Reversed list.
   */
  @NotNull
  public abstract ImmutableList reverse();

  /**
   * Patches the current list.
   * Patching a list first takes the first index elements then concatenates it with replacements and then concatenates it with
   * the original list dropping index + patchLength elements.
   * 

   * A visualization of this operation is to replace the patchLength elements in the list starting from index with a list of new
   * elements given by replacements.
   *
   * @param index        The index to start patching.
   * @param patchLength  The length to patch.
   * @param replacements The replacements of the patch.
   * @param           The type of the replacements. It must be A or a subtype of A.
   * @return The patched list.
   */
  @NotNull
  public  ImmutableList patch(int index, int patchLength, @NotNull ImmutableList replacements) {
    return this.take(index).append(replacements).append(this.drop(index + patchLength));
  }

  /**
   * mapAccumL performs {@link #map} and {@link #foldLeft} method at the same time. It is similar to {@link #foldLeft}, but instead of returning
   * the
   * new accumulation value, it also allows the user to return an extra value which will be collected and returned.
   *
   * @param f   The accumulation function.
   * @param acc The initial value of the fold part.
   * @param  The type of the initial value.
   * @param  The type of the result of map.
   * @return A pair of the accumulation value and a mapped list.
   */
  @NotNull
  public abstract  Pair> mapAccumL(@NotNull F2> f, @NotNull B acc);

  /**
   * Get the indexth element of the list. It is comparable to the [] operator for array but instead of returning the element, it
   * returns an Maybe to indicate whether the element can be found or not.
   *
   * @param index The index.
   * @return Maybe.just(found element)if the element can be retrieved; or Maybe.nothing() if index out of range().
   */
  @NotNull
  public final Maybe index(int index) {
    ImmutableList l = this;
    if (index < 0) {
      return Maybe.nothing();
    }
    while (index > 0) {
      if (l.isEmpty()) {
        return Maybe.nothing();
      }
      index--;
      l = l.maybeTail().just();
    }
    return l.maybeHead();
  }

  @Override
  public abstract boolean equals(Object o);
}

    

    

    

    

            



    
    






    
© 2015 - 2024 Weber Informatics LLC | Privacy Policy