or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

annotations.mdcompile-time.mdgeneric-programming.mdimmutable-arrays.mdindex.mdmacros.mdstructural-types.mdtuples.mdtype-safe-equality.md
tile.json

tessl/maven-org-scala-lang--scala3-library_3

The Scala 3 standard library providing essential data types, collections, and functional programming constructs for the Scala 3 programming language

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.scala-lang/scala3-library_3@3.7.x

To install, run

npx @tessl/cli install tessl/maven-org-scala-lang--scala3-library_3@3.7.0

index.mddocs/

Scala 3 Standard Library

The Scala 3 standard library provides essential data types, collections, functional programming constructs, and advanced type system features for the Scala 3 programming language. It includes foundational types like tuples and immutable arrays, advanced functional programming features such as type-safe equality, compile-time metaprogramming utilities, and comprehensive support for Scala 3's enhanced type system including union types, intersection types, and improved type inference.

Package Information

  • Package Name: org.scala-lang:scala3-library_3
  • Package Type: maven
  • Language: Scala
  • Installation: libraryDependencies += "org.scala-lang" %% "scala3-library" % "3.7.0"

Core Imports

import scala.*                      // Core types and functions
import scala.compiletime.*          // Compile-time utilities
import scala.quoted.*              // Macro/metaprogramming
import scala.deriving.*            // Generic derivation

Basic Usage

import scala.*
import scala.compiletime.*

// Type-safe equality
val x: String = "hello"
val y: Int = 42
// x == y  // Compile error with CanEqual system

// Tuples with rich operations
val tuple = ("Alice", 25, true)
val head = tuple.head                    // "Alice"
val tail = tuple.tail                    // (25, true)
val appended = tuple :* "Engineer"       // ("Alice", 25, true, "Engineer")

// Named tuples for better type safety
val person = (name = "Bob", age = 30, active = true)
val name = person.name                   // Type-safe field access

// Immutable arrays
val nums = IArray(1, 2, 3, 4, 5)
val doubled = nums.map(_ * 2)            // IArray(2, 4, 6, 8, 10)
val filtered = nums.filter(_ > 3)        // IArray(4, 5)

// Compile-time programming
inline def typeInfo[T]: String = 
  constValue[T] match
    case t: String => s"String: $t"
    case n: Int => s"Int: $n"
    case _ => "Other type"

Architecture

The Scala 3 standard library is organized into several key modules:

  • Core Types: Essential types like Tuple, IArray, CanEqual for type-safe programming
  • Compile-Time Utilities: The compiletime package for type-level programming and metaprogramming
  • Macro System: The quoted package for compile-time code generation and analysis
  • Generic Programming: The deriving package for automatic type class derivation
  • Annotation System: Rich annotations for controlling compiler behavior and optimization
  • Capability System: Experimental capture checking and capability classes for effect safety

Capabilities

Type-Safe Equality

The CanEqual system provides compile-time guarantees that equality comparisons are meaningful and safe, preventing comparisons between unrelated types.

trait CanEqual[-L, -R]

object CanEqual:
  def canEqualAny[L, R]: CanEqual[L, R]
  given canEqualNumber: CanEqual[Number, Number]
  given canEqualString: CanEqual[String, String]

Type-Safe Equality

Tuples and Product Types

Rich tuple system with arbitrary arity, type-level operations, and comprehensive manipulation methods. Supports both traditional tuples and named tuples for enhanced type safety.

sealed trait Tuple extends Product:
  def toArray: Array[Object]
  def toList: List[Union[this.type]]
  def :*[L](x: L): This :* L
  def *:[H](x: H): H *: This
  def apply(n: Int): Elem[This, n.type]
  def head: Head[This]
  def tail: Tail[This]

type NamedTuple[N <: Tuple, +V <: Tuple] >: V <: AnyNamedTuple

Tuples and Product Types

Immutable Arrays

Covariant immutable arrays with rich collection operations, providing Array performance with immutability guarantees.

opaque type IArray[+T] = Array[? <: T]

object IArray:
  def apply[T: ClassTag](xs: T*): IArray[T]
  def empty[T: ClassTag]: IArray[T]
  extension [T](arr: IArray[T])
    def apply(n: Int): T
    def length: Int
    def map[U: ClassTag](f: T => U): IArray[U]
    def filter(p: T => Boolean): IArray[T]

Immutable Arrays

Compile-Time Programming

Comprehensive utilities for compile-time metaprogramming, type-level computation, and constexpr-style programming.

def erasedValue[T]: T
transparent inline def constValue[T]: T
transparent inline def summonFrom[T](f: Nothing => T): T
inline def error(inline msg: String): Nothing
transparent inline def codeOf(arg: Any): String

Compile-Time Programming

Macro and Metaprogramming

Powerful macro system using quotes and splices for compile-time code generation and analysis.

abstract class Expr[+T]:
  def show: String
  def value: T
  def asTerm: Term

abstract class Type[T]:
  def show: String

trait ToExpr[T]:
  def apply(x: T)(using Quotes): Expr[T]

Macro and Metaprogramming

Generic Programming and Derivation

Mirror-based system for automatic derivation of type classes and generic programming constructs.

sealed trait Mirror:
  type MirroredType
  type MirroredLabel <: String

trait Mirror.Product extends Mirror:
  type MirroredElemTypes <: Tuple
  type MirroredElemLabels <: Tuple
  def fromProduct(p: Product): MirroredType

trait Mirror.Sum extends Mirror:
  type MirroredElemTypes <: Tuple
  type MirroredElemLabels <: Tuple
  def ordinal(x: MirroredType): Int

Generic Programming

Structural Types and Selection

Enhanced structural typing with Selectable trait for dynamic member access and structural subtyping.

trait Selectable extends Any

// Implementation classes should define:
def selectDynamic(name: String): Any
def applyDynamic(name: String)(args: Any*): Any

Structural Types

Annotation System

Rich annotation system for controlling compiler behavior, optimization hints, and API design.

class experimental extends StaticAnnotation
class alpha extends StaticAnnotation
class capability extends StaticAnnotation
class targetName(name: String) extends StaticAnnotation
class threadUnsafe extends StaticAnnotation

Annotation System

Utility APIs

Advanced utility functions for control flow, implicit search negation, and numeric literal parsing.

// Boundary-based control flow
object boundary:
  def apply[T](inline body: Label[T] ?=> T): T
  def break[T](value: T)(using label: Label[T]): Nothing
  def break()(using label: Label[Unit]): Nothing
  final class Label[-T]

// Implicit search negation
final class NotGiven[+T] private ()
object NotGiven:
  def value: NotGiven[Nothing]

// Numeric literal parsing
trait FromDigits[T]:
  def fromDigits(digits: String): T
trait WithRadix[T] extends FromDigits[T]:
  def fromDigits(digits: String, radix: Int): T

Function Conversion

Type-safe function conversion utilities.

abstract class Conversion[-T, +U] extends Function1[T, U]:
  def apply(x: T): U
  extension (x: T) def convert = this(x)

Experimental Traits

Experimental features for capability tracking and precise type inference.

@experimental trait Pure
@experimental erased trait Precise:
  type Self
@experimental erased class CanThrow[-E <: Exception] extends caps.Capability

Types

Core Type Aliases

type EmptyTuple = EmptyTuple.type
sealed abstract class *:[+H, +T <: Tuple] extends NonEmptyTuple
type AnyNamedTuple = Any

Compile-Time Type Operations

// Integer operations
type +[X <: Int, Y <: Int] <: Int
type -[X <: Int, Y <: Int] <: Int
type *[X <: Int, Y <: Int] <: Int
type S[X <: Int] <: Int

// Boolean operations  
type ![X <: Boolean] <: Boolean
type &&[X <: Boolean, Y <: Boolean] <: Boolean
type ||[X <: Boolean, Y <: Boolean] <: Boolean

// String operations
type +[X <: String, Y <: String] <: String
type Length[X <: String] <: Int

Tuple Type Operations

type Head[X <: Tuple]
type Tail[X <: Tuple] <: Tuple
type Concat[X <: Tuple, +Y <: Tuple] <: Tuple
type ++[X <: Tuple, +Y <: Tuple] = Concat[X, Y]
type Size[X <: Tuple] <: Int
type Union[T <: Tuple]