0
# nscala-time
1

2
nscala-time is a comprehensive Scala wrapper library around the Joda Time date and time API, offering idiomatic Scala syntax for date/time operations including operators for addition, subtraction, and comparison. It features enhanced functionality over Java's built-in Date and Calendar classes through immutable objects, thread-safe operations, and convenient method chaining.
3

4
## Package Information
5

6
- **Package Name**: nscala-time  
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Organization**: com.github.nscala-time
10
- **Installation**: `libraryDependencies += "com.github.nscala-time" %% "nscala-time" % "2.34.0"`
11

12
## Core Imports
13

14
```scala
15
import com.github.nscala_time.time.Imports._
16
```
17

18
This single import provides access to all functionality including:
19
- Type aliases for all Joda Time types
20
- Enhanced static factory methods
21
- Rich wrapper classes with operator overloading
22
- Implicit conversions for seamless integration
23

24
Alternative selective imports:
25
```scala
26
import com.github.nscala_time.time.TypeImports._      // Type aliases only
27
import com.github.nscala_time.time.StaticForwarderImports._  // Static factories only
28
import com.github.nscala_time.time.Implicits._        // Implicit conversions only
29
```
30

31
## Basic Usage
32

33
```scala
34
import com.github.nscala_time.time.Imports._
35

36
// Create dates with enhanced syntax
37
val now = DateTime.now()
38
val tomorrow = DateTime.tomorrow()
39
val nextWeek = now + 1.week
40

41
// Arithmetic operations
42
val future = now + 2.months + 3.days
43
val past = now - 1.year
44

45
// Fluent interface for time construction
46
val specificTime = now.withHour(14).withMinute(30).withSecond(0)
47

48
// String parsing with safe options
49
val parsed = "2023-12-25".toDateTimeOption
50
val withFormat = "25/12/2023".toDateTime("dd/MM/yyyy")
51

52
// Duration building
53
val duration = 2.hours + 45.minutes + 10.seconds
54
val durationInMillis = duration.millis
55

56
// Comparisons and intervals
57
val isAfter = now > yesterday()
58
val interval = now to tomorrow
59
val intervalDuration = interval.millis
60
```
61

62
## Architecture
63

64
nscala-time is built around several key components:
65

66
- **Type Aliases**: Direct access to Joda Time types with Scala naming conventions
67
- **Static Factories**: Enhanced factory methods for creating date/time objects with relative time support
68
- **Rich Wrappers**: Enhanced functionality for all Joda Time classes through implicit conversions
69
- **Duration Builder**: Fluent builder pattern for creating complex durations and periods
70
- **Operator Overloading**: Mathematical operators (+, -, comparisons) for intuitive date arithmetic
71
- **Implicit Conversions**: Seamless integration with Scala types, Java Date, and Scala Duration
72

73
## Capabilities
74

75
### Core Date/Time Types
76

77
Core date and time type aliases and enhanced factory methods for creating and manipulating temporal objects.
78

79
```scala { .api }
80
type DateTime = org.joda.time.DateTime
81
type LocalDate = org.joda.time.LocalDate
82
type LocalDateTime = org.joda.time.LocalDateTime
83
type LocalTime = org.joda.time.LocalTime
84
type Duration = org.joda.time.Duration
85
type Period = org.joda.time.Period
86
type Interval = org.joda.time.Interval
87

88
// Enhanced factory objects
89
val DateTime: StaticDateTime
90
val LocalDate: StaticLocalDate  
91
val LocalDateTime: StaticLocalDateTime
92
val LocalTime: StaticLocalTime
93
```
94

95
[Core Types and Factories](./core-types.md)
96

97
### Duration and Period Building
98

99
Fluent builder system for creating durations and periods with natural language syntax and arithmetic operations.
100

101
```scala { .api }
102
class DurationBuilder(val underlying: Period) extends AnyVal {
103
  def +(that: DurationBuilder): DurationBuilder
104
  def -(that: DurationBuilder): DurationBuilder
105
  def ago(): DateTime
106
  def later(): DateTime
107
  def millis: Long
108
  def toDuration: Duration
109
  def toPeriod: Period
110
}
111

112
// Integer extensions for duration building
113
implicit class RichInt(val underlying: Int) extends AnyVal {
114
  def millis: DurationBuilder
115
  def seconds: DurationBuilder
116
  def minutes: DurationBuilder
117
  def hours: DurationBuilder
118
  def days: Period
119
  def weeks: Period
120
  def months: Period
121
  def years: Period
122
}
123

124
// Long extensions for duration conversion and arithmetic
125
implicit class RichLong(val underlying: Long) extends AnyVal {
126
  def toDateTime: DateTime
127
  def toDuration: Duration
128
  def -(duration: Duration): Duration
129
  def +(duration: Duration): Duration
130
  def *(duration: Duration): Duration
131
}
132
```
133

134
[Duration and Period Building](./duration-building.md)
135

136
### Enhanced DateTime Operations
137

138
Comprehensive enhancements to DateTime with operator overloading, property accessors, and fluent setters.
139

140
```scala { .api }
141
implicit class RichDateTime(val underlying: DateTime) extends AnyVal {
142
  // Arithmetic operators
143
  def +(duration: ReadableDuration): DateTime
144
  def +(period: ReadablePeriod): DateTime
145
  def +(builder: DurationBuilder): DateTime
146
  def -(duration: ReadableDuration): DateTime
147
  def -(period: ReadablePeriod): DateTime
148
  
149
  // Property accessors
150
  def year: DateTime.Property
151
  def month: DateTime.Property
152
  def day: DateTime.Property
153
  def hour: DateTime.Property
154
  def minute: DateTime.Property
155
  def second: DateTime.Property
156
  
157
  // Fluent setters
158
  def withYear(year: Int): DateTime
159
  def withMonth(month: Int): DateTime
160
  def withDay(day: Int): DateTime
161
  def withHour(hour: Int): DateTime
162
  def withMinute(minute: Int): DateTime
163
  def withSecond(second: Int): DateTime
164
}
165
```
166

167
[DateTime Operations](./datetime-operations.md)
168

169
### String Parsing and Conversion
170

171
Safe string parsing capabilities with Option-based returns and custom format support for all major date/time types.
172

173
```scala { .api }
174
implicit class RichString(val s: String) extends AnyVal {
175
  def toDateTime: DateTime
176
  def toLocalDate: LocalDate
177
  def toInterval: Interval
178
  def toDateTimeOption: Option[DateTime]
179
  def toLocalDateOption: Option[LocalDate]
180
  def toIntervalOption: Option[Interval]
181
  def toDateTime(format: String): DateTime
182
  def toLocalDate(format: String): LocalDate
183
  def toDateTimeOption(format: String): Option[DateTime]
184
  def toLocalDateOption(format: String): Option[LocalDate]
185
}
186
```
187

188
[String Parsing](./string-parsing.md)
189

190
### Local Date and Time Types
191

192
Enhanced functionality for local date and time types including arithmetic operations and property access.
193

194
```scala { .api }
195
implicit class RichLocalDate(ld: LocalDate) extends AnyVal
196
implicit class RichLocalDateTime(dt: LocalDateTime) extends AnyVal  
197
implicit class RichLocalTime(lt: LocalTime) extends AnyVal
198

199
// Enhanced static factories
200
object StaticLocalDate {
201
  def now(): LocalDate
202
  def parse(str: String): LocalDate
203
  // Additional factory methods
204
}
205
```
206

207
[Local Date and Time](./local-datetime.md)
208

209
### Ordering and Comparisons
210

211
Built-in ordering instances and comparison operators for all date/time types enabling seamless integration with Scala collections.
212

213
```scala { .api }
214
implicit val DateTimeOrdering: Ordering[DateTime]
215
implicit val LocalDateOrdering: Ordering[LocalDate]
216
implicit val LocalTimeOrdering: Ordering[LocalTime]
217
implicit val LocalDateTimeOrdering: Ordering[LocalDateTime]
218
implicit val DurationOrdering: Ordering[Duration]
219
```
220

221
[Ordering and Comparisons](./ordering.md)
222

223
## Types
224

225
```scala { .api }
226
// Core date/time type aliases
227
type Chronology = org.joda.time.Chronology
228
type DateTime = org.joda.time.DateTime
229
type DateTimeFormat = org.joda.time.format.DateTimeFormat
230
type DateTimeFormatter = org.joda.time.format.DateTimeFormatter
231
type DateTimeZone = org.joda.time.DateTimeZone
232
type Duration = org.joda.time.Duration
233
type Interval = org.joda.time.Interval
234
type LocalDate = org.joda.time.LocalDate
235
type LocalDateTime = org.joda.time.LocalDateTime
236
type LocalTime = org.joda.time.LocalTime
237
type Period = org.joda.time.Period
238
type Partial = org.joda.time.Partial
239
type YearMonth = org.joda.time.YearMonth
240
type MonthDay = org.joda.time.MonthDay
241

242
// Java interop types
243
type Calendar = java.util.Calendar
244
type Date = java.util.Date
245

246
// Enhanced builder types
247
class DurationBuilder(val underlying: Period) extends AnyVal
248

249
// Property types
250
type DateTimeProperty = DateTime.Property
251
type LocalDateProperty = LocalDate.Property
252
type LocalDateTimeProperty = LocalDateTime.Property
253
type LocalTimeProperty = LocalTime.Property
254
```