Package io.atlassian.fugue

Class Iterables

java.lang.Object
io.atlassian.fugue.Iterables
public class Iterables extends Object
Contains static utility methods that operate on or return objects of type {code}Iterable{code}. The iterables produced from the functions in this class are safe to reuse multiple times. Iterables#iterator returns a new iterator each time.
Since:
1.0

  • Field Details

    • EMPTY

      static final Iterable<?> EMPTY

  • Constructor Details

    • Iterables

      private Iterables()

  • Method Details

    • emptyIterable

      public static <T> Iterable<T> emptyIterable()
      Returns an empty iterable, that is, an Iterable with an Iterator for which hasNext() always returns false, and the other methods throw appropriate exceptions if called. Intended to be used as a more idiomatic replacement for Collections.emptyList() in code that otherwise deals only with iterables.
      Type Parameters:
      T - the type
      Returns:
      an empty iterable
      Since:
      1.2

    • iterable

      @SafeVarargs public static <A> Iterable<A> iterable(A... as)
      Creates an Iterable from the underlying array of elements.
      Type Parameters:
      A - The type of the elements
      Parameters:
      as - the elements to iterate over
      Returns:
      an Iterable across the underlying elements
      Since:
      2.3

    • findFirst

      public static <T> Option<T> findFirst(Iterable<? extends T> elements, Predicate<? super T> p)
      Finds the first item that matches the predicate. Traditionally, this should be named find; in this case it is named findFirst to avoid clashing with static imports from Guava's com.google.common.collect.Iterables.
      Type Parameters:
      T - the type
      Parameters:
      elements - the iterable to search for a matching element
      p - the predicate to use to determine if an element is eligible to be returned
      Returns:
      the first item in elements that matches predicate
      Since:
      1.0

    • findFirst

      public static <A> Function<Iterable<A>,Option<A>> findFirst(Predicate<? super A> predicate)
      Partial application of the predicate argument to findFirst(Iterable, Predicate) returning a function that takes an Iterable as its argument
      Type Parameters:
      A - the type
      Parameters:
      predicate - the predicate to use to determine if an element is eligible to be returned
      Returns:
      a Function that takes an Iterable as its argument, and returns the first element that satisfies the predicate
      Since:
      2.2

    • first

      public static <A> Option<A> first(Iterable<A> as)
      If as is empty, returns none(). Otherwise, returns some(get(as, 0)).
      Type Parameters:
      A - type of elements in as
      Parameters:
      as - elements to get the first value of, must not be null
      Returns:
      none() if as is empty. some(get(as, 0)) otherwise
      Since:
      1.1

    • ap

      public static <A, B> Iterable<B> ap(Iterable<A> as, Iterable<Function<A,B>> fs)
      Performs function application within an iterable (applicative functor pattern).
      Parameters:
      as - an iterable
      fs - The iterable of functions to apply.
      Returns:
      A new iterable after applying the given stream of functions through as.

    • flatMap

      public static <A, B> Iterable<B> flatMap(Iterable<A> collection, Function<? super A,? extends Iterable<? extends B>> f)
      Applies f to each element of collection, then concatenates the result.
      Type Parameters:
      A - type of elements in collection
      B - type elements in the new Iterable f will transform elements to
      Parameters:
      collection - elements to apply f to
      f - Function to apply to elements of collection
      Returns:
      concatenated result of applying f to each element of collection
      Since:
      1.1

    • revMap

      public static <A, B> Iterable<B> revMap(Iterable<? extends Function<A,B>> fs, A arg)
      Applies each function in fs to arg.
      Type Parameters:
      A - the argument type
      B - the function output and type of the elements of the final iterable.
      Parameters:
      fs - an iterable of functions that the arg will be applied to
      arg - the argument to apply to the functions
      Returns:
      the results of the functions when applied to the arg
      Since:
      1.1

    • isEmpty

      public static Predicate<Iterable<?>> isEmpty()
      Predicate that checks if an iterable is empty.
      Returns:
      Predicate which checks if an Iterable is empty
      Since:
      1.1

    • collect

      public static <A, B> Iterable<B> collect(Iterable<? extends A> from, Function<? super A,Option<B>> partial)
      Filters and maps (aka transforms) the unfiltered iterable. Applies the given partial function to each element of the unfiltered iterable. If the application returns none, the element will be left out; otherwise, the transformed object contained in the Option will be added to the result.
      Type Parameters:
      A - the input type
      B - the output type
      Parameters:
      from - the input iterable, must not be null and must not contain null
      partial - the collecting function
      Returns:
      the collected iterable
      Since:
      2.2

    • collect

      public static <T, A, R> R collect(Iterable<T> elements, Collector<T,A,R> collector)
      Uses a Collector to collect/reduce an Iterable.
      Type Parameters:
      T - the type of elements in the original Iterable
      A - accumulator type
      R - return type
      Parameters:
      elements - the iterable to run the Collector on. Can not be null.
      collector - the Collector. Can not be null.
      Returns:
      the result of the reduction, using the given Collector
      Since:
      3.1
      See Also:

    • foldLeft

      public static <T, R> R foldLeft(Iterable<T> elements, BiFunction<? super R,? super T,? extends R> foldFunction, R initial)
      Folds the Iterable elements into the value of potentially another type. Starting the computation with the specified initial value.
      Type Parameters:
      T - the type of elements in the original Iterable
      R - return type
      Parameters:
      elements - the iterable to run the foldLeft operation on. Can not be null.
      foldFunction - the BiFunction used for reducing. Can not be null.
      initial - the initial value the folding is started with
      Returns:
      the result of the reduction, using the given BiFunction
      Since:
      6.1

    • partition

      public static <A> Pair<Iterable<A>,Iterable<A>> partition(Iterable<A> iterable, Predicate<? super A> p)
      Filter an Iterable into a Pair of Iterable's.
      Type Parameters:
      A - the type
      Parameters:
      iterable - to be filtered
      p - to filter each element
      Returns:
      a pair where the left matches the predicate, and the right does not.
      Since:
      1.2

    • take

      public static <A> Iterable<A> take(int n, Iterable<A> as)
      Aakes the first n as and returns them.
      Type Parameters:
      A - type of as
      Parameters:
      n - number of as to take, must greater than or equal to zero
      as - list of values, must not be null and must not contain null
      Returns:
      first n as
      Since:
      1.1

    • drop

      public static <A> Iterable<A> drop(int n, Iterable<A> as)
      Drop the first n as and return the rest.
      Type Parameters:
      A - type of as
      Parameters:
      n - number of as to drop, must greater than or equal to zero
      as - list of values, must not be null and must not contain null
      Returns:
      remaining as after dropping the first n
      Since:
      1.1

    • dropWhile

      public static <A> Iterable<A> dropWhile(Iterable<A> as, Predicate<A> p)
      Drop elements of as until an element returns false for p#test
      Type Parameters:
      A - type of as
      Parameters:
      as - iterable to remove the first elements of as, must not be null
      p - predicate used to test which elements to drop from the iterable, must not be null
      Returns:
      remaining elements of as after removing the starting elements that for which p#test returns true
      Since:
      3.0
      See Also:

    • takeWhile

      public static <A> Iterable<A> takeWhile(Iterable<A> as, Predicate<A> p)
      Return a new iterable containing only the first elements of as for which p#test returns true.
      Type Parameters:
      A - type of as
      Parameters:
      as - iterable to source the first elements of as, must not be null
      p - predicate used to test which elements to include in the new iterable, must not be null
      Returns:
      a new iterable containing elements of as starting from the first element of as until p#test returns false
      Since:
      3.0
      See Also:

    • zip

      public static <A, B> Iterable<Pair<A,B>> zip(Iterable<A> as, Iterable<B> bs)
      Zips two iterables into a single iterable that produces pairs. See unzip(Iterable) for the opposite operation
      Type Parameters:
      A - LHS type
      B - RHS type
      Parameters:
      as - left values
      bs - right values
      Returns:
      an iterable of pairs, only as long as the shortest input iterable.
      Since:
      1.2

    • zipWith

      public static <A, B, C> BiFunction<Iterable<A>,Iterable<B>,Iterable<C>> zipWith(BiFunction<A,B,C> f)
      Takes a two-arg function that returns a third type and reurn a new function that takes iterables of the two input types and combines them into a new iterable.
      Type Parameters:
      A - LHS type
      B - RHS type
      C - result type
      Parameters:
      f - combiner function, must not be null
      Returns:
      an Function that takes two iterables and zips them using the supplied function. The input iterables must not be null and must not contain null
      Since:
      1.2

    • zipWithIndex

      public static <A> Iterable<Pair<A,Integer>> zipWithIndex(Iterable<A> as)
      Takes an Iterable, and returns an Iterable of a Pair of the original element and its index starting at zero.
      Type Parameters:
      A - the type
      Parameters:
      as - the original iterable
      Returns:
      the decorated iterable that generates pairs.
      Since:
      1.2

    • unzip

      public static <A, B> Pair<Iterable<A>,Iterable<B>> unzip(Iterable<Pair<A,B>> pairs)
      Unzips an iterable of pairs into a pair of iterables.
      Type Parameters:
      A - LHS type
      B - RHS type
      Parameters:
      pairs - the values
      Returns:
      a pair of iterable of the same length as the input iterable.
      Since:
      1.2

    • rangeUntil

      public static Iterable<Integer> rangeUntil(int start, int end)
      Creates a sequence of integers from start up to but not including end.
      Parameters:
      start - from (inclusive)
      end - to (exclusive)
      Returns:
      a sequence of integers
      Since:
      1.2

    • rangeUntil

      public static Iterable<Integer> rangeUntil(int start, int end, int step)
      Creates a sequence of integers from start up to but not including end with the the supplied step between them.
      Parameters:
      start - from (inclusive)
      end - to (exclusive)
      step - size to step – must not be zero, must be positive if end is greater than start, neagtive otherwise
      Returns:
      a sequence of integers
      Since:
      1.2

    • rangeTo

      public static Iterable<Integer> rangeTo(int start, int end)
      Creates a sequence of integers from start up to and including end.
      Parameters:
      start - from (inclusive)
      end - to (inclusive)
      Returns:
      a sequence of integers
      Since:
      1.2

    • rangeTo

      public static Iterable<Integer> rangeTo(int start, int end, int step)
      Creates a sequence of integers from start up to and including end with the the supplied step between them.
      Parameters:
      start - from (inclusive), must be greater than zero and less than end
      end - to (inclusive)
      step - size to step – must not be zero, must be positive if end is greater than start, negative otherwise
      Returns:
      a sequence of integers
      Since:
      1.2

    • intersperse

      public static <A> Iterable<A> intersperse(Iterable<? extends A> as, A a)
      Intersperse an element between all the elements in an iterable.
      Type Parameters:
      A - the type of the elements.
      Parameters:
      as - the source iterable.
      a - the element to intersperse between the source elements.
      Returns:
      a new Iterable that intersperses the element between the source.
      Since:
      2.3

    • intersperse

      public static <A> Iterable<A> intersperse(Iterable<? extends A> as, Supplier<A> a)
      Intersperse an element between all the elements in an iterable.
      Type Parameters:
      A - the type of the elements.
      Parameters:
      as - the source iterable.
      a - the supplier of elements to intersperse between the source elements.
      Returns:
      a new Iterable that intersperses the element between the source.
      Since:
      2.3

    • size

      public static <A> int size(Iterable<A> as)
      Return the size of an iterable. In most cases this function is required to walk the entire iterable to determine the result. Consider this an O(n) complexity function.
      Type Parameters:
      A - element type
      Parameters:
      as - iterable to compute the size of
      Returns:
      number of elements in the iterable
      Since:
      3.0

    • count

      public static <A> int count(Iterable<A> as, Predicate<? super A> p)
      Return the size of the elements inside an iterable that meets a specified predicate.
      Type Parameters:
      A - element type
      Parameters:
      as - the source iterable
      p - predicate to filter by
      Returns:
      number of elements in the iterable that meets a prediction
      Since:
      6.1

    • transform

      @Deprecated public static <A, B> Iterable<B> transform(Iterable<A> as, Function<? super A,? extends B> f)
      Deprecated.
      function provided to make migration easier prefer to use #map where possible
      Transform an interable by mapping a function across each of its elements
      Type Parameters:
      A - original iterable type
      B - output iterable type
      Parameters:
      as - the source iterable
      f - function to apply to all the elements of as
      Returns:
      new iterable containing the transformed values produced by f#apply
      Since:
      3.0

    • map

      public static <A, B> Iterable<B> map(Iterable<A> as, Function<? super A,? extends B> f)
      Apply the input function to each of the elements of the input iterable returning a new iterable
      Type Parameters:
      A - original iterable type
      B - output iterable type
      Parameters:
      as - the source iterable
      f - function to apply to all the elements of as
      Returns:
      new iterable containing values produced by f#apply called on each element
      Since:
      3.0

    • filter

      public static <A> Iterable<A> filter(Iterable<A> as, Predicate<? super A> p)
      Remove elements from the input iterable for which the predicate returns false
      Type Parameters:
      A - element type
      Parameters:
      as - original iterable
      p - predicate to filter by
      Returns:
      new iterable containing only those elements for which p#test returns true
      Since:
      3.0

    • join

      public static <A> Iterable<A> join(Iterable<? extends Iterable<? extends A>> ias)
      Join Iterable<Iterable<A>> down to Iterable<A>. The resulting iterable will exhaust the first input iterable in order before returning values from the second. Input iterables must not be null and must not contain null.
      Type Parameters:
      A - element type
      Parameters:
      ias - one or more iterable to merge into the final iterable result, must not be null and must not return null
      Returns:
      single level iterable with all the elements of the original iterables
      Since:
      3.0

    • concat

      @SafeVarargs public static <A> Iterable<A> concat(Iterable<? extends A>... as)
      Concatenate a series of iterables into a single iterable. Returns an empty iterable if no iterables are supplied. Input iterables must not be null and must not contain null.
      Type Parameters:
      A - super type of contained by all input iterables
      Parameters:
      as - any number of iterables containing A
      Returns:
      new iterable containing all the elements of the input iterables
      Since:
      3.0

    • any

      public static <A> boolean any(Iterable<? extends A> as, Predicate<? super A> p)
      Check if the iterable contains any elements that match the predicate.
      Type Parameters:
      A - type of elements inside the input iterable
      Parameters:
      as - iterable to compare for matching elements
      p - predicate to test for matching elements
      Returns:
      true if any element in the iterable returns true for the input predicate otherwise false. False for an empty iterable.
      Since:
      3.0

    • all

      public static <A> boolean all(Iterable<? extends A> as, Predicate<? super A> p)
      Check if all elements in the input iterable match the input predicate
      Type Parameters:
      A - type of elements inside the input iterable
      Parameters:
      as - iterable to compare for matching elements
      p - predicate to test for matching elements
      Returns:
      true if all elements in the iterable return true for the input predicate otherwise false. True for an empty iterable.
      Since:
      3.0

    • iterate

      public static <A> Iterable<A> iterate(Function<? super A,? extends A> f, A start)
      Returns an infinite Iterable constructed by applying the given iteration function starting at the given value.
      Type Parameters:
      A - type of the elements
      Parameters:
      f - The iteration function, must not return null
      start - The value to begin iterating from.
      Returns:
      An infinite Iterable of repeated applications of f to start.
      Since:
      2.4

    • unfold

      public static <A, B> Iterable<A> unfold(Function<? super B,Option<Pair<A,B>>> f, B seed)
      Builds an Iterable from a seed value until f returns none() .
      Type Parameters:
      A - type of the returned elements.
      B - type of the elements for which f is applied.
      Parameters:
      f - The function that returns some(pair(a, b)), in which case a is the next element of the resulting Iterable and b is used as the input value for the next call of f, or none() if it is done producing the elements. f must not be null and must not return a pair containing null.
      seed - The start value to begin the unfold.
      Returns:
      An Iterable that is a result of unfolding.
      Since:
      2.4

    • mergeSorted

      public static <A extends Comparable<A>> Iterable<A> mergeSorted(Iterable<? extends Iterable<A>> xss)
      Merge a number of already sorted collections of elements into a single collection of elements, using the elements natural ordering.
      Type Parameters:
      A - collection type
      Parameters:
      xss - collection of already sorted collections, must not be null and must not return null
      Returns:
      xss merged in a sorted order
      Since:
      1.1

    • mergeSorted

      public static <A> Iterable<A> mergeSorted(Iterable<? extends Iterable<A>> xss, Comparator<A> ordering)
      Merge a number of already sorted collections of elements into a single collection of elements.
      Type Parameters:
      A - type of the elements
      Parameters:
      xss - already sorted collection of collections, must not be null and must not return null
      ordering - ordering to use when comparing elements, must not be null
      Returns:
      xss merged in a sorted order
      Since:
      1.1

    • addAll

      public static <A> boolean addAll(Collection<A> collectionToModify, Iterable<? extends A> elementsToAdd)
      Add all the elements of the iterable to the collection
      Type Parameters:
      A - element type
      Parameters:
      collectionToModify - collection to add elements to
      elementsToAdd - source of addtional elements
      Returns:
      true if the collectionToModify was changed
      Since:
      3.0

    • cycle

      @SafeVarargs public static <A> Iterable<A> cycle(A... as)
      Return an infinite iterable that cycles through the input values in order in a loop. If no elements are provided returns an empty iterable. Does not support element removal via Iterator#remove.
      Type Parameters:
      A - returned elements
      Parameters:
      as - input values to cycle through
      Returns:
      an infinite iterable containing the original elements
      Since:
      3.0

    • cycle

      public static <A> Iterable<A> cycle(Iterable<? extends A> as)
      Return an infinite iterable that cycles through the input values in order in a loop. If no elements are provided returns an empty iterable. Does not support element removal via Iterator#remove.
      Type Parameters:
      A - returned elements
      Parameters:
      as - input values to cycle through must not be null
      Returns:
      an infinite iterable containing the original elements
      Since:
      3.0

    • makeString

      public static <A> String makeString(Iterable<? extends A> as, String start, String sep, String end, int maxLength)
      Pretty print an Iterable. Printing following this pattern: <start><element><sep><element><end> If the iterable would result in a String with length more than maxLength printing follows this pattern: <start><element><sep><element>...<end>
      Type Parameters:
      A - type of the elements in the iterable
      Parameters:
      as - the iterable to print must not be null
      start - prefix to start the printing with
      sep - separator to use between each element
      end - suffic to end the printing with
      maxLength - limit the length of the resulting string
      Returns:
      a pretty printed copy of the input iterable
      Since:
      3.0

    • makeString

      public static <A> String makeString(Iterable<? extends A> as, String start, String sep, String end)
      Pretty print an Iterable. Printing following this pattern: <start><element><sep><element><end> If the iterable would result in a String with length more than 100 characters printing follows this pattern: <start><element><sep><element>...<end>
      Type Parameters:
      A - type of the elements in the iterable
      Parameters:
      as - the iterable to print must not be null
      start - prefix to start the printing with
      sep - separator to use between each element
      end - suffic to end the printing with
      Returns:
      a pretty printed copy of the input iterable
      Since:
      3.0
      See Also:

    • memoize

      public static <A> Iterable<A> memoize(Iterable<A> xs)
      Makes a lazy copy of xs.
      Type Parameters:
      A - type of elements in xs
      Parameters:
      xs - Iterable to be memoized
      Returns:
      lazy copy of as
      Since:
      1.1