0
# Scala 3 Standard Library
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.scala-lang:scala3-library_3
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.scala-lang" %% "scala3-library" % "3.7.0"`
10

11
## Core Imports
12

13
```scala
14
import scala.*                      // Core types and functions
15
import scala.compiletime.*          // Compile-time utilities
16
import scala.quoted.*              // Macro/metaprogramming
17
import scala.deriving.*            // Generic derivation
18
```
19

20
## Basic Usage
21

22
```scala
23
import scala.*
24
import scala.compiletime.*
25

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

31
// Tuples with rich operations
32
val tuple = ("Alice", 25, true)
33
val head = tuple.head                    // "Alice"
34
val tail = tuple.tail                    // (25, true)
35
val appended = tuple :* "Engineer"       // ("Alice", 25, true, "Engineer")
36

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

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

46
// Compile-time programming
47
inline def typeInfo[T]: String = 
48
  constValue[T] match
49
    case t: String => s"String: $t"
50
    case n: Int => s"Int: $n"
51
    case _ => "Other type"
52
```
53

54
## Architecture
55

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

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

65
## Capabilities
66

67
### Type-Safe Equality
68

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

71
```scala { .api }
72
trait CanEqual[-L, -R]
73

74
object CanEqual:
75
  def canEqualAny[L, R]: CanEqual[L, R]
76
  given canEqualNumber: CanEqual[Number, Number]
77
  given canEqualString: CanEqual[String, String]
78
```
79

80
[Type-Safe Equality](./type-safe-equality.md)
81

82
### Tuples and Product Types
83

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

86
```scala { .api }
87
sealed trait Tuple extends Product:
88
  def toArray: Array[Object]
89
  def toList: List[Union[this.type]]
90
  def :*[L](x: L): This :* L
91
  def *:[H](x: H): H *: This
92
  def apply(n: Int): Elem[This, n.type]
93
  def head: Head[This]
94
  def tail: Tail[This]
95

96
type NamedTuple[N <: Tuple, +V <: Tuple] >: V <: AnyNamedTuple
97
```
98

99
[Tuples and Product Types](./tuples.md)
100

101
### Immutable Arrays
102

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

105
```scala { .api }
106
opaque type IArray[+T] = Array[? <: T]
107

108
object IArray:
109
  def apply[T: ClassTag](xs: T*): IArray[T]
110
  def empty[T: ClassTag]: IArray[T]
111
  extension [T](arr: IArray[T])
112
    def apply(n: Int): T
113
    def length: Int
114
    def map[U: ClassTag](f: T => U): IArray[U]
115
    def filter(p: T => Boolean): IArray[T]
116
```
117

118
[Immutable Arrays](./immutable-arrays.md)
119

120
### Compile-Time Programming
121

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

124
```scala { .api }
125
def erasedValue[T]: T
126
transparent inline def constValue[T]: T
127
transparent inline def summonFrom[T](f: Nothing => T): T
128
inline def error(inline msg: String): Nothing
129
transparent inline def codeOf(arg: Any): String
130
```
131

132
[Compile-Time Programming](./compile-time.md)
133

134
### Macro and Metaprogramming
135

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

138
```scala { .api }
139
abstract class Expr[+T]:
140
  def show: String
141
  def value: T
142
  def asTerm: Term
143

144
abstract class Type[T]:
145
  def show: String
146

147
trait ToExpr[T]:
148
  def apply(x: T)(using Quotes): Expr[T]
149
```
150

151
[Macro and Metaprogramming](./macros.md)
152

153
### Generic Programming and Derivation
154

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

157
```scala { .api }
158
sealed trait Mirror:
159
  type MirroredType
160
  type MirroredLabel <: String
161

162
trait Mirror.Product extends Mirror:
163
  type MirroredElemTypes <: Tuple
164
  type MirroredElemLabels <: Tuple
165
  def fromProduct(p: Product): MirroredType
166

167
trait Mirror.Sum extends Mirror:
168
  type MirroredElemTypes <: Tuple
169
  type MirroredElemLabels <: Tuple
170
  def ordinal(x: MirroredType): Int
171
```
172

173
[Generic Programming](./generic-programming.md)
174

175
### Structural Types and Selection
176

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

179
```scala { .api }
180
trait Selectable extends Any
181

182
// Implementation classes should define:
183
def selectDynamic(name: String): Any
184
def applyDynamic(name: String)(args: Any*): Any
185
```
186

187
[Structural Types](./structural-types.md)
188

189
### Annotation System
190

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

193
```scala { .api }
194
class experimental extends StaticAnnotation
195
class alpha extends StaticAnnotation
196
class capability extends StaticAnnotation
197
class targetName(name: String) extends StaticAnnotation
198
class threadUnsafe extends StaticAnnotation
199
```
200

201
[Annotation System](./annotations.md)
202

203
### Utility APIs
204

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

207
```scala { .api }
208
// Boundary-based control flow
209
object boundary:
210
  def apply[T](inline body: Label[T] ?=> T): T
211
  def break[T](value: T)(using label: Label[T]): Nothing
212
  def break()(using label: Label[Unit]): Nothing
213
  final class Label[-T]
214

215
// Implicit search negation
216
final class NotGiven[+T] private ()
217
object NotGiven:
218
  def value: NotGiven[Nothing]
219

220
// Numeric literal parsing
221
trait FromDigits[T]:
222
  def fromDigits(digits: String): T
223
trait WithRadix[T] extends FromDigits[T]:
224
  def fromDigits(digits: String, radix: Int): T
225
```
226

227
### Function Conversion
228

229
Type-safe function conversion utilities.
230

231
```scala { .api }
232
abstract class Conversion[-T, +U] extends Function1[T, U]:
233
  def apply(x: T): U
234
  extension (x: T) def convert = this(x)
235
```
236

237
### Experimental Traits
238

239
Experimental features for capability tracking and precise type inference.
240

241
```scala { .api }
242
@experimental trait Pure
243
@experimental erased trait Precise:
244
  type Self
245
@experimental erased class CanThrow[-E <: Exception] extends caps.Capability
246
```
247

248
## Types
249

250
### Core Type Aliases
251

252
```scala { .api }
253
type EmptyTuple = EmptyTuple.type
254
sealed abstract class *:[+H, +T <: Tuple] extends NonEmptyTuple
255
type AnyNamedTuple = Any
256
```
257

258
### Compile-Time Type Operations
259

260
```scala { .api }
261
// Integer operations
262
type +[X <: Int, Y <: Int] <: Int
263
type -[X <: Int, Y <: Int] <: Int
264
type *[X <: Int, Y <: Int] <: Int
265
type S[X <: Int] <: Int
266

267
// Boolean operations  
268
type ![X <: Boolean] <: Boolean
269
type &&[X <: Boolean, Y <: Boolean] <: Boolean
270
type ||[X <: Boolean, Y <: Boolean] <: Boolean
271

272
// String operations
273
type +[X <: String, Y <: String] <: String
274
type Length[X <: String] <: Int
275
```
276

277
### Tuple Type Operations
278

279
```scala { .api }
280
type Head[X <: Tuple]
281
type Tail[X <: Tuple] <: Tuple
282
type Concat[X <: Tuple, +Y <: Tuple] <: Tuple
283
type ++[X <: Tuple, +Y <: Tuple] = Concat[X, Y]
284
type Size[X <: Tuple] <: Int
285
type Union[T <: Tuple]
286
```