izumi.fundamentals.collections.nonempty

Companion object for class NonEmptyList.

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

The purpose of NonEmptyMap 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 NonEmptyMaps ==

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

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

== Working with NonEmptyMaps ==

NonEmptyMap 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, NonEmptyMap defines a method corresponding to every such Map method. Here are an example:

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

NonEmptyMap does not currently define any methods corresponding to Map methods that could result in an empty Map. However, an implicit converison from NonEmptyMap to Map is defined in the NonEmptyMap 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 NonEmptyMap, even though filter could result in an empty map—but the result type will be Map instead of NonEmptyMap:

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

You can use NonEmptyMaps in for expressions. The result will be an NonEmptyMap 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) <- NonEmptyMap(1 -> "one", 2 -> "two", 3 -> "three")) yield (i + 1, j)
res0: org.scalactic.anyvals.NonEmptyMap[Int, String] = NonEmptyMap(2 -> "one", 3 -> "two", 4 -> "three")

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

Companion object for class NonEmptyMap.

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

The purpose of NonEmptySet 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 NonEmptySets ==

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

scala> NonEmptySet(1, 2, 3)
res0: org.scalactic.anyvals.NonEmptySet[Int] = NonEmptySet(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.NonEmptySet[Int] = NonEmptySet(1, 2, 3)

Note that although Nil is a Set[Nothing], End is not a NonEmptySet[Nothing], because no empty NonEmptySet 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: NonEmptySet[Nothing] = End
<console>:16: error: type mismatch;
found   : org.scalactic.anyvals.End.type
required: org.scalactic.anyvals.NonEmptySet[Nothing]
      val nada: NonEmptySet[Nothing] = End
                                        ^

== Working with NonEmptySets ==

NonEmptySet 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, NonEmptySet defines a method corresponding to every such Seq method. Here are some examples:

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

NonEmptySet does not currently define any methods corresponding to Seq methods that could result in an empty Seq. However, an implicit converison from NonEmptySet to Set is defined in the NonEmptySet 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 NonEmptySet, even though filter could result in an empty sequence—but the result type will be Set instead of NonEmptySet:

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

You can use NonEmptySets in for expressions. The result will be an NonEmptySet 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 <- NonEmptySet(1, 2, 3)) yield i + 1
res0: org.scalactic.anyvals.NonEmptySet[Int] = NonEmptySet(2, 3, 4)

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

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

scala> for {
    |   i <- NonEmptySet(1, 2, 3) if i < 10
    |   j <- NonEmptySet('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 NonEmptySet.

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

The purpose of NonEmptyString 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 NonEmptyStrings ==

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

scala> NonEmptyString(1, 2, 3)
res0: org.scalactic.anyvals.NonEmptyString[Int] = NonEmptyString(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.NonEmptyString[Int] = NonEmptyString(1, 2, 3)

Note that although Nil is a String[Nothing], End is not a NonEmptyString[Nothing], because no empty NonEmptyString 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: NonEmptyString[Nothing] = End
<console>:16: error: type mismatch;
found   : org.scalactic.anyvals.End.type
required: org.scalactic.anyvals.NonEmptyString[Nothing]
      val nada: NonEmptyString[Nothing] = End
                                        ^

== Working with NonEmptyStrings ==

NonEmptyString 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, NonEmptyString defines a method corresponding to every such Seq method. Here are some examples:

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

NonEmptyString does not currently define any methods corresponding to Seq methods that could result in an empty Seq. However, an implicit converison from NonEmptyString to String is defined in the NonEmptyString 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 NonEmptyString, even though filter could result in an empty sequence—but the result type will be String instead of NonEmptyString:

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

You can use NonEmptyStrings in for expressions. The result will be an NonEmptyString 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 <- NonEmptyString(1, 2, 3)) yield i + 1
res0: org.scalactic.anyvals.NonEmptyString[Int] = NonEmptyString(2, 3, 4)

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

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

scala> for {
    |   i <- NonEmptyString(1, 2, 3) if i < 10
    |   j <- NonEmptyString('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))

Companion object for class NonEmptyString.