izumi.fundamentals.collections.nonempty

Companion object for class NEList.

Companion object for class NEMap.

A non-empty map: an ordered, immutable, non-empty collection of key-value tuples with LinearSeq performance characteristics.

The purpose of NEMap is to allow you to express in a type that a Map is non-empty, thereby eliminating the need for (and potential exception from) a run-time check for non-emptiness. For a non-empty sequence with IndexedSeq performance, see Vector.

== Constructing NEMaps ==

You can construct a NEMap by passing one or more elements to the NEMap.apply factory method:

scala> NEMap(1 -> "one", 2 -> "two", 3 -> "three")
res0: org.scalactic.anyvals.NEMap[Int, String] = NEMap(1 -> "one", 2 -> "two", 3 -> "three")

== Working with NEMaps ==

NEMap does not extend Scala's Map or Traversable traits because these require that implementations may be empty. For example, if you invoke tail on a Seq that contains just one element, you'll get an empty Seq:

scala> Map(1 -> "one").tail
res6: Map[Int] = Map()

On the other hand, many useful methods exist on Map that when invoked on a non-empty Seq are guaranteed to not result in an empty Map. For convenience, NEMap defines a method corresponding to every such Map method. Here are an example:

NEMap(1 -> "one", 2 -> "two", 3 -> "three").map(t => (t._1 + 1, t._2))                        // Result: NEMap(2 -> "one", 3 -> "two", 4 -> "three")

NEMap does not currently define any methods corresponding to Map methods that could result in an empty Map. However, an implicit converison from NEMap to Map is defined in the NEMap companion object that will be applied if you attempt to call one of the missing methods. As a result, you can invoke filter on an NEMap, even though filter could result in an empty map—but the result type will be Map instead of NEMap:

NEMap(1 -> "one", 2 -> "two", 3 -> "three").filter(_._1 < 10) // Result: Map(1 -> "one", 2 -> "two", 3 -> "three")
NEMap(1 -> "one", 2 -> "two", 3 -> "three").filter(_._ 1> 10) // Result: Map()

You can use NEMaps in for expressions. The result will be an NEMap unless you use a filter (an if clause). Because filters are desugared to invocations of filter, the result type will switch to a Map at that point. Here are some examples:

scala> import org.scalactic.anyvals._
import org.scalactic.anyvals._

scala> for ((i, j) <- NEMap(1 -> "one", 2 -> "two", 3 -> "three")) yield (i + 1, j)
res0: org.scalactic.anyvals.NEMap[Int, String] = NEMap(2 -> "one", 3 -> "two", 4 -> "three")

scala> for ((i, j) <- NEMap(1, 2, 3) if i < 10) yield (i + 1, j)
res1: Map[Int, String] = Map(2 -> "one", 3 -> "two", 4 -> "three")

A non-empty Set: an ordered, immutable, non-empty collection of elements with LinearSeq performance characteristics.

The purpose of NESet is to allow you to express in a type that a Set is non-empty, thereby eliminating the need for (and potential exception from) a run-time check for non-emptiness. For a non-empty sequence with IndexedSeq performance, see Vector.

== Constructing NESets ==

You can construct a NESet by passing one or more elements to the NESet.apply factory method:

scala> NESet(1, 2, 3)
res0: org.scalactic.anyvals.NESet[Int] = NESet(1, 2, 3)

Alternatively you can cons elements onto the End singleton object, similar to making a Set starting with Nil:

scala> 1 :: 2 :: 3 :: Nil
res0: Set[Int] = Set(1, 2, 3)

scala> 1 :: 2 :: 3 :: End
res1: org.scalactic.NESet[Int] = NESet(1, 2, 3)

Note that although Nil is a Set[Nothing], End is not a NESet[Nothing], because no empty NESet exists. (A non-empty Set is a series of connected links; if you have no links, you have no non-empty Set.)

scala> val nil: Set[Nothing] = Nil
nil: Set[Nothing] = Set()

scala> val nada: NESet[Nothing] = End
<console>:16: error: type mismatch;
found   : org.scalactic.anyvals.End.type
required: org.scalactic.anyvals.NESet[Nothing]
      val nada: NESet[Nothing] = End
                                        ^

== Working with NESets ==

NESet does not extend Scala's Seq or Traversable traits because these require that implementations may be empty. For example, if you invoke tail on a Seq that contains just one element, you'll get an empty Seq:

scala> Set(1).tail
res6: Set[Int] = Set()

On the other hand, many useful methods exist on Seq that when invoked on a non-empty Seq are guaranteed to not result in an empty Seq. For convenience, NESet defines a method corresponding to every such Seq method. Here are some examples:

NESet(1, 2, 3).map(_ + 1)                        // Result: NESet(2, 3, 4)
NESet(1).map(_ + 1)                              // Result: NESet(2)
NESet(1, 2, 3).containsSlice(NESet(2, 3)) // Result: true
NESet(1, 2, 3).containsSlice(NESet(3, 4)) // Result: false
NESet(-1, -2, 3, 4, 5).minBy(_.abs)              // Result: -1

NESet does not currently define any methods corresponding to Seq methods that could result in an empty Seq. However, an implicit converison from NESet to Set is defined in the NESet companion object that will be applied if you attempt to call one of the missing methods. As a result, you can invoke filter on an NESet, even though filter could result in an empty sequence—but the result type will be Set instead of NESet:

NESet(1, 2, 3).filter(_ < 10) // Result: Set(1, 2, 3)
NESet(1, 2, 3).filter(_ > 10) // Result: Set()

You can use NESets in for expressions. The result will be an NESet unless you use a filter (an if clause). Because filters are desugared to invocations of filter, the result type will switch to a Set at that point. Here are some examples:

scala> import org.scalactic.anyvals._
import org.scalactic.anyvals._

scala> for (i <- NESet(1, 2, 3)) yield i + 1
res0: org.scalactic.anyvals.NESet[Int] = NESet(2, 3, 4)

scala> for (i <- NESet(1, 2, 3) if i < 10) yield i + 1
res1: Set[Int] = Set(2, 3, 4)

scala> for {
    |   i <- NESet(1, 2, 3)
    |   j <- NESet('a', 'b', 'c')
    | } yield (i, j)
res3: org.scalactic.anyvals.NESet[(Int, Char)] =
       NESet((1,a), (1,b), (1,c), (2,a), (2,b), (2,c), (3,a), (3,b), (3,c))

scala> for {
    |   i <- NESet(1, 2, 3) if i < 10
    |   j <- NESet('a', 'b', 'c')
    | } yield (i, j)
res6: Set[(Int, Char)] =
       Set((1,a), (1,b), (1,c), (2,a), (2,b), (2,c), (3,a), (3,b), (3,c))

Companion object for class NESet.

Companion object for class NEString.

A non-empty list: an ordered, immutable, non-empty collection of elements with LinearSeq performance characteristics.

The purpose of NEString is to allow you to express in a type that a String is non-empty, thereby eliminating the need for (and potential exception from) a run-time check for non-emptiness. For a non-empty sequence with IndexedSeq performance, see Vector.

== Constructing NEStrings ==

You can construct a NEString by passing one or more elements to the NEString.apply factory method:

scala> NEString(1, 2, 3)
res0: org.scalactic.anyvals.NEString[Int] = NEString(1, 2, 3)

Alternatively you can cons elements onto the End singleton object, similar to making a String starting with Nil:

scala> 1 :: 2 :: 3 :: Nil
res0: String[Int] = String(1, 2, 3)

scala> 1 :: 2 :: 3 :: End
res1: org.scalactic.NEString[Int] = NEString(1, 2, 3)

Note that although Nil is a String[Nothing], End is not a NEString[Nothing], because no empty NEString exists. (A non-empty list is a series of connected links; if you have no links, you have no non-empty list.)

scala> val nil: String[Nothing] = Nil
nil: String[Nothing] = String()

scala> val nada: NEString[Nothing] = End
<console>:16: error: type mismatch;
found   : org.scalactic.anyvals.End.type
required: org.scalactic.anyvals.NEString[Nothing]
      val nada: NEString[Nothing] = End
                                        ^

== Working with NEStrings ==

NEString does not extend Scala's Seq or Traversable traits because these require that implementations may be empty. For example, if you invoke tail on a Seq that contains just one element, you'll get an empty Seq:

scala> String(1).tail
res6: String[Int] = String()

On the other hand, many useful methods exist on Seq that when invoked on a non-empty Seq are guaranteed to not result in an empty Seq. For convenience, NEString defines a method corresponding to every such Seq method. Here are some examples:

NEString(1, 2, 3).map(_ + 1)                        // Result: NEString(2, 3, 4)
NEString(1).map(_ + 1)                              // Result: NEString(2)
NEString(1, 2, 3).containsSlice(NEString(2, 3)) // Result: true
NEString(1, 2, 3).containsSlice(NEString(3, 4)) // Result: false
NEString(-1, -2, 3, 4, 5).minBy(_.abs)              // Result: -1

NEString does not currently define any methods corresponding to Seq methods that could result in an empty Seq. However, an implicit converison from NEString to String is defined in the NEString companion object that will be applied if you attempt to call one of the missing methods. As a result, you can invoke filter on an NEString, even though filter could result in an empty sequence—but the result type will be String instead of NEString:

NEString(1, 2, 3).filter(_ < 10) // Result: String(1, 2, 3)
NEString(1, 2, 3).filter(_ > 10) // Result: String()

You can use NEStrings in for expressions. The result will be an NEString unless you use a filter (an if clause). Because filters are desugared to invocations of filter, the result type will switch to a String at that point. Here are some examples:

scala> import org.scalactic.anyvals._
import org.scalactic.anyvals._

scala> for (i <- NEString(1, 2, 3)) yield i + 1
res0: org.scalactic.anyvals.NEString[Int] = NEString(2, 3, 4)

scala> for (i <- NEString(1, 2, 3) if i < 10) yield i + 1
res1: String[Int] = String(2, 3, 4)

scala> for {
    |   i <- NEString(1, 2, 3)
    |   j <- NEString('a', 'b', 'c')
    | } yield (i, j)
res3: org.scalactic.anyvals.NEString[(Int, Char)] =
       NEString((1,a), (1,b), (1,c), (2,a), (2,b), (2,c), (3,a), (3,b), (3,c))

scala> for {
    |   i <- NEString(1, 2, 3) if i < 10
    |   j <- NEString('a', 'b', 'c')
    | } yield (i, j)
res6: String[(Int, Char)] =
       String((1,a), (1,b), (1,c), (2,a), (2,b), (2,c), (3,a), (3,b), (3,c))