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
```