0
# DateTime Operations
1

2
Comprehensive enhancements to DateTime with operator overloading, property accessors, and fluent setters. These extensions make DateTime manipulation intuitive and type-safe while maintaining full compatibility with Joda Time.
3

4
## Capabilities
5

6
### Enhanced DateTime Class
7

8
Rich wrapper providing operator overloading and fluent API for DateTime manipulation.
9

10
```scala { .api }
11
/**
12
 * Enhanced DateTime with operator overloading and fluent API
13
 * @param underlying The underlying Joda Time DateTime
14
 */
15
implicit class RichDateTime(val underlying: DateTime) extends AnyVal {
16
  // Arithmetic operators - subtraction
17
  def -(duration: Long): DateTime
18
  def -(duration: ReadableDuration): DateTime
19
  def -(period: ReadablePeriod): DateTime
20
  def -(builder: DurationBuilder): DateTime
21
  
22
  // Arithmetic operators - addition
23
  def +(duration: Long): DateTime
24
  def +(duration: ReadableDuration): DateTime
25
  def +(period: ReadablePeriod): DateTime
26
  def +(builder: DurationBuilder): DateTime
27
  
28
  // Property accessors for time components
29
  def millis: DateTime.Property
30
  def second: DateTime.Property
31
  def minute: DateTime.Property
32
  def hour: DateTime.Property
33
  def day: DateTime.Property
34
  def week: DateTime.Property
35
  def month: DateTime.Property
36
  def year: DateTime.Property
37
  def century: DateTime.Property
38
  def era: DateTime.Property
39
  
40
  // Fluent setter methods
41
  def withSecond(second: Int): DateTime
42
  def withMinute(minute: Int): DateTime
43
  def withHour(hour: Int): DateTime
44
  def withDay(day: Int): DateTime
45
  def withWeek(week: Int): DateTime
46
  def withMonth(month: Int): DateTime
47
  def withYear(year: Int): DateTime
48
  def withCentury(century: Int): DateTime
49
  def withEra(era: Int): DateTime
50
}
51
```
52

53
**Usage Examples:**
54

55
```scala
56
import com.github.nscala_time.time.Imports._
57

58
val now = DateTime.now()
59

60
// Arithmetic operations
61
val future = now + 2.hours + 30.minutes
62
val past = now - 1.day
63
val withMillis = now + 5000L  // Add 5000 milliseconds
64
val withDuration = now + Duration.standardHours(3)
65

66
// Property access
67
val currentYear = now.year.get()
68
val currentMonth = now.month.get()
69
val currentDay = now.day.get()
70
val currentHour = now.hour.get()
71

72
// Fluent setters - method chaining
73
val specificTime = now
74
  .withYear(2024)
75
  .withMonth(12)
76
  .withDay(25)
77
  .withHour(14)
78
  .withMinute(30)
79
  .withSecond(0)
80

81
// Property-based operations
82
val endOfMonth = now.day.withMaximumValue()
83
val startOfYear = now.month.withMinimumValue().day.withMinimumValue()
84
```
85

86
### DateTime Property Operations
87

88
Enhanced property classes for fine-grained DateTime manipulation.
89

90
```scala { .api }
91
/**
92
 * Enhanced DateTime property operations
93
 */
94
implicit class RichDateTimeProperty(pty: DateTime.Property) extends AnyVal {
95
  // Property-specific operations available through implicit enhancement
96
  // Inherits all Joda Time Property methods plus Scala enhancements
97
}
98
```
99

100
### Enhanced Abstract DateTime Operations
101

102
Base functionality for all DateTime-like objects.
103

104
```scala { .api }
105
/**
106
 * Enhanced functionality for AbstractDateTime types
107
 * @param dt The underlying AbstractDateTime
108
 */
109
implicit class RichAbstractDateTime(dt: AbstractDateTime) extends AnyVal {
110
  // Base DateTime functionality that applies to all DateTime-like objects
111
  // Provides common operations for DateTime hierarchy
112
}
113
```
114

115
### Enhanced Abstract Instant Operations
116

117
Base functionality for all instant-like objects.
118

119
```scala { .api }
120
/**
121
 * Enhanced functionality for AbstractInstant types
122
 * @param in The underlying AbstractInstant
123
 */
124
implicit class RichAbstractInstant(in: AbstractInstant) extends AnyVal {
125
  // Base instant functionality for all instant-like objects
126
  // Provides common time-point operations
127
}
128
```
129

130
### Enhanced Readable DateTime Operations
131

132
Operations for all readable DateTime objects.
133

134
```scala { .api }
135
/**
136
 * Enhanced functionality for ReadableDateTime types
137
 * @param dt The underlying ReadableDateTime
138
 */
139
implicit class RichReadableDateTime(dt: ReadableDateTime) extends AnyVal {
140
  // Enhanced operations for all readable DateTime objects
141
  // Provides consistent interface across DateTime types
142
}
143
```
144

145
### Enhanced Readable Instant Operations
146

147
Operations for all readable instant objects.
148

149
```scala { .api }
150
/**
151
 * Enhanced functionality for ReadableInstant types
152
 * @param in The underlying ReadableInstant
153
 */
154
implicit class RichReadableInstant(in: ReadableInstant) extends AnyVal {
155
  // Enhanced operations for all readable instant objects
156
  // Enables operator overloading and comparisons
157
}
158
```
159

160
### Enhanced Instant Operations
161

162
Operations for Instant objects.
163

164
```scala { .api }
165
/**
166
 * Enhanced functionality for Instant types
167
 * @param in The underlying Instant
168
 */
169
implicit class RichInstant(in: Instant) extends AnyVal {
170
  // Enhanced Instant operations
171
  // Provides arithmetic and comparison operations
172
}
173
```
174

175
**Complex Usage Examples:**
176

177
```scala
178
import com.github.nscala_time.time.Imports._
179

180
// Complex date arithmetic
181
val startDate = DateTime.parse("2023-01-01T00:00:00")
182
val endDate = startDate + 1.year + 2.months + 15.days + 8.hours
183

184
// Working with different time zones
185
val utcTime = DateTime.now(DateTimeZone.UTC)
186
val localTime = utcTime.withZone(DateTimeZone.getDefault)
187

188
// Property manipulations
189
val businessHours = DateTime.now()
190
  .withHour(9)  // 9 AM
191
  .withMinute(0)
192
  .withSecond(0)
193
  .withMillisOfSecond(0)
194

195
val endOfBusinessDay = businessHours.withHour(17)  // 5 PM
196

197
// Calendar operations
198
val firstDayOfMonth = DateTime.now().day.withMinimumValue()
199
val lastDayOfMonth = DateTime.now().day.withMaximumValue()
200
val firstDayOfYear = DateTime.now().dayOfYear.withMinimumValue()
201

202
// Complex time calculations
203
val meetingTime = DateTime.now()
204
  .plusDays(7)  // Next week
205
  .withDayOfWeek(DateTimeConstants.MONDAY)  // Monday
206
  .withHour(10)  // 10 AM
207
  .withMinute(30)  // 10:30 AM
208

209
// Combining with intervals
210
val workingHours = businessHours to endOfBusinessDay
211
val lunchBreak = businessHours.withHour(12) to businessHours.withHour(13)
212
```
213

214
### Comparison and Interval Creation
215

216
DateTime objects enhanced with comparison operators and interval creation.
217

218
```scala
219
import com.github.nscala_time.time.Imports._
220

221
val now = DateTime.now()
222
val later = now + 1.hour
223

224
// Comparisons (enabled by implicit Ordering)
225
val isBefore = now < later  // true
226
val isAfter = now > later   // false
227
val isEqual = now == now    // true
228

229
// Interval creation using 'to' method
230
val interval = now to later
231
val intervalDuration = interval.toDurationMillis
232
val intervalPeriod = interval.toPeriod
233

234
// Checking if time falls within interval
235
val someTime = now + 30.minutes
236
val isWithin = interval.contains(someTime)  // true
237
```