This class serves as a wrapper for Arrays with many of the operations found in indexed sequences. Where needed, instances of arrays are implicitly converted into this class. There is generally no reason to create an instance explicitly or use an ArrayOps type. It is better to work with plain Array types instead and rely on the implicit conversion to ArrayOps when calling a method (which does not actually allocate an instance of ArrayOps because it is a value class).

Neither Array nor ArrayOps are proper collection types (i.e. they do not extend Iterable or even IterableOnce). mutable.ArraySeq and immutable.ArraySeq serve this purpose.

The difference between this class and ArraySeqs is that calling transformer methods such as filter and map will yield an array, whereas an ArraySeq will remain an ArraySeq.

Base type of bitsets.

This trait provides most of the operations of a BitSet independently of its representation. It is inherited by all concrete implementations of bitsets.

This trait provides default implementations for the factory methods fromSpecific and newSpecificBuilder that need to be refined when implementing a collection type that refines the CC and C type parameters. It is used for collections that have an additional constraint, expressed by the evidenceIterableFactory method.

The default implementations in this trait can be used in the common case when CC[A] is the same as C.

A factory that builds a collection of type C with elements of type A.

This is a general form of any factory (IterableFactory, SortedIterableFactory, MapFactory and SortedMapFactory) whose element type is fixed.

This trait provides default implementations for the factory methods fromSpecific and newSpecificBuilder that need to be refined when implementing a collection type that refines the CC and C type parameters.

The default implementations in this trait can be used in the common case when CC[A] is the same as C.

A template trait for collections which can be traversed either once only or one or more times.

Note: IterableOnce does not extend IterableOnceOps. This is different than the general design of the collections library, which uses the following pattern:

trait Seq extends Iterable with SeqOps
trait SeqOps extends IterableOps

trait IndexedSeq extends Seq with IndexedSeqOps
trait IndexedSeqOps extends SeqOps

The goal is to provide a minimal interface without any sequential operations. This allows third-party extension like Scala parallel collections to integrate at the level of IterableOnce without inheriting unwanted implementations.

Base trait for Iterable operations

VarianceNote

We require that for all child classes of Iterable the variance of the child class and the variance of the C parameter passed to IterableOps are the same. We cannot express this since we lack variance polymorphism. That's why we have to resort at some places to write C[A @uncheckedVariance].

Iterators are data structures that allow to iterate over a sequence of elements. They have a hasNext method for checking if there is a next element available, and a next method which returns the next element and advances the iterator.

An iterator is mutable: most operations on it change its state. While it is often used to iterate through the elements of a collection, it can also be used without being backed by any collection (see constructors on the companion object).

It is of particular importance to note that, unless stated otherwise, one should never use an iterator after calling a method on it. The two most important exceptions are also the sole abstract methods: next and hasNext.

Both these methods can be called any number of times without having to discard the iterator. Note that even hasNext may cause mutation -- such as when iterating from an input stream, where it will block until the stream is closed or some input becomes available.

Consider this example for safe and unsafe use:

def f[A](it: Iterator[A]) = {
 if (it.hasNext) {            // Safe to reuse "it" after "hasNext"
   it.next()                  // Safe to reuse "it" after "next"
   val remainder = it.drop(2) // it is *not* safe to use "it" again after this line!
   remainder.take(2)          // it is *not* safe to use "remainder" after this line!
 } else it
}

This trait provides default implementations for the factory methods fromSpecific and newSpecificBuilder that need to be refined when implementing a collection type that refines the CC and C type parameters. It is used for maps.

Note that in maps, the CC type of the map is not the same as the CC type for the underlying iterable (which is fixed to Map in MapOps). This trait has therefore two type parameters CC and WithFilterCC. The withFilter method inherited from IterableOps is overridden with a compatible default implementation.

The default implementations in this trait can be used in the common case when CC[A] is the same as C.

A generic trait for ordered maps. Concrete classes have to provide functionality for the abstract methods in SeqMap.

Note that when checking for equality SeqMap does not take into account ordering.

This trait provides default implementations for the factory methods fromSpecific and newSpecificBuilder that need to be refined when implementing a collection type that refines the CC and C type parameters. It is used for sorted maps.

Note that in sorted maps, the CC type of the map is not the same as the CC type for the underlying map (which is fixed to Map in SortedMapOps). This trait has therefore three type parameters CC, WithFilterCC and UnsortedCC. The withFilter method inherited from IterableOps is overridden with a compatible default implementation.

The default implementations in this trait can be used in the common case when CC[A] is the same as C.

This trait provides default implementations for the factory methods fromSpecific and newSpecificBuilder that need to be refined when implementing a collection type that refines the CC and C type parameters. It is used for sorted sets.

Note that in sorted sets, the CC type of the set is not the same as the CC type for the underlying iterable (which is fixed to Set in SortedSetOps). This trait has therefore two type parameters CC and WithFilterCC. The withFilter method inherited from IterableOps is overridden with a compatible default implementation.

The default implementations in this trait can be used in the common case when CC[A] is the same as C.

Steppers exist to enable creating Java streams over Scala collections, see scala.jdk.StreamConverters. Besides that use case, they allow iterating over collections holding unboxed primitives (e.g., Array[Int]) without boxing the elements.

Steppers have an iterator-like interface with methods hasStep and nextStep(). The difference to iterators - and the reason Stepper is not a subtype of Iterator - is that there are hand-specialized variants of Stepper for Int, Long and Double (IntStepper, etc.). These enable iterating over collections holding unboxed primitives (e.g., Arrays, scala.jdk.Accumulators) without boxing the elements.

The selection of primitive types (Int, Long and Double) matches the hand-specialized variants of Java Streams (java.util.stream.Stream, java.util.stream.IntStream, etc.) and the corresponding Java Spliterators (java.util.Spliterator, java.util.Spliterator.OfInt, etc.).

Steppers can be converted to Scala Iterators, Java Iterators and Java Spliterators. Primitive Steppers are converted to the corresponding primitive Java Iterators and Spliterators.

Provides extension methods for strings.

Some of these methods treat strings as a plain collection of Chars without any regard for Unicode handling. Unless the user takes Unicode handling in to account or makes sure the strings don't require such handling, these methods may result in unpaired or invalidly paired surrogate code units.

A variety of decorators that enable converting between Scala and Java collections using extension methods, asScala and asJava.

The extension methods return adapters for the corresponding API.

The following conversions are supported via asScala and asJava:

scala.collection.Iterable       <=> java.lang.Iterable
scala.collection.Iterator       <=> java.util.Iterator
scala.collection.mutable.Buffer <=> java.util.List
scala.collection.mutable.Set    <=> java.util.Set
scala.collection.mutable.Map    <=> java.util.Map
scala.collection.concurrent.Map <=> java.util.concurrent.ConcurrentMap

The following conversions are supported via asScala and through specially-named extension methods to convert to Java collections, as shown:

scala.collection.Iterable    <=> java.util.Collection   (via asJavaCollection)
scala.collection.Iterator    <=> java.util.Enumeration  (via asJavaEnumeration)
scala.collection.mutable.Map <=> java.util.Dictionary   (via asJavaDictionary)

In addition, the following one-way conversions are provided via asJava:

scala.collection.Seq         => java.util.List
scala.collection.mutable.Seq => java.util.List
scala.collection.Set         => java.util.Set
scala.collection.Map         => java.util.Map

The following one way conversion is provided via asScala:

java.util.Properties => scala.collection.mutable.Map

In all cases, converting from a source type to a target type and back again will return the original source object. For example:

import scala.collection.JavaConverters._

val source = new scala.collection.mutable.ListBuffer[Int]
val target: java.util.List[Int] = source.asJava
val other: scala.collection.mutable.Buffer[Int] = target.asScala
assert(source eq other)

Alternatively, the conversion methods have descriptive names and can be invoked explicitly.

scala> val vs = java.util.Arrays.asList("hi", "bye")
vs: java.util.List[String] = [hi, bye]

scala> val ss = asScalaIterator(vs.iterator)
ss: Iterator[String] = <iterator>

scala> .toList
res0: List[String] = List(hi, bye)

scala> val ss = asScalaBuffer(vs)
ss: scala.collection.mutable.Buffer[String] = Buffer(hi, bye)