0
# Manipulation and Arithmetic
1

2
Date manipulation methods for adding/subtracting time, setting specific values, navigating to specific time boundaries, and timezone operations on Moment instances.
3

4
## Capabilities
5

6
### Arithmetic Operations
7

8
Methods for adding and subtracting time amounts from Moment instances.
9

10
```javascript { .api }
11
/**
12
 * Add time to this moment
13
 * @param amount - Amount to add (number, string, Duration, or object)
14
 * @param unit - Unit of time when amount is number/string
15
 * @returns This moment instance (for chaining)
16
 */
17
add(amount?: DurationInputArg1, unit?: DurationInputArg2): Moment;
18

19
/**
20
 * Subtract time from this moment
21
 * @param amount - Amount to subtract (number, string, Duration, or object)
22
 * @param unit - Unit of time when amount is number/string
23
 * @returns This moment instance (for chaining)
24
 */
25
subtract(amount?: DurationInputArg1, unit?: DurationInputArg2): Moment;
26

27
// Input types
28
type DurationInputArg1 = Duration | number | string | FromTo | DurationInputObject | void;
29
type DurationInputArg2 = unitOfTime.DurationConstructor;
30

31
interface FromTo {
32
  from: MomentInput;
33
  to: MomentInput;
34
}
35

36
interface DurationInputObject extends MomentInputObject {
37
  quarters?: numberlike;
38
  quarter?: numberlike;
39
  Q?: numberlike;
40
  weeks?: numberlike;
41
  week?: numberlike;
42
  w?: numberlike;
43
}
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
import moment from "moment";
50

51
const date = moment("2023-12-25T15:30:00");
52

53
// Add time (various units)
54
console.log(date.clone().add(1, "day").format()); // "2023-12-26T15:30:00"
55
console.log(date.clone().add(2, "hours").format()); // "2023-12-25T17:30:00"
56
console.log(date.clone().add(30, "minutes").format()); // "2023-12-25T16:00:00"
57
console.log(date.clone().add(1, "week").format()); // "2024-01-01T15:30:00"
58
console.log(date.clone().add(1, "month").format()); // "2024-01-25T15:30:00"
59
console.log(date.clone().add(1, "year").format()); // "2024-12-25T15:30:00"
60

61
// Subtract time
62
console.log(date.clone().subtract(1, "day").format()); // "2023-12-24T15:30:00"
63
console.log(date.clone().subtract(2, "hours").format()); // "2023-12-25T13:30:00"
64
console.log(date.clone().subtract(1, "month").format()); // "2023-11-25T15:30:00"
65

66
// Add with object notation
67
console.log(date.clone().add({
68
  years: 1,
69
  months: 2,
70
  days: 3,
71
  hours: 4
72
}).format()); // "2025-02-28T19:30:00"
73

74
// Add with Duration object
75
const duration = moment.duration(2, "hours");
76
console.log(date.clone().add(duration).format()); // "2023-12-25T17:30:00"
77

78
// Chaining operations
79
const result = date.clone()
80
  .add(1, "week")
81
  .subtract(2, "days")
82
  .add(3, "hours");
83
console.log(result.format()); // "2023-12-30T18:30:00"
84
```
85

86
### Start and End of Time Periods
87

88
Navigate to the beginning or end of various time periods.
89

90
```javascript { .api }
91
/**
92
 * Set to the start of a unit of time
93
 * @param unitOfTime - Time unit to start of
94
 * @returns This moment instance (mutates original)
95
 */
96
startOf(unitOfTime: unitOfTime.StartOf): Moment;
97

98
/**
99
 * Set to the end of a unit of time  
100
 * @param unitOfTime - Time unit to end of
101
 * @returns This moment instance (mutates original)
102
 */
103
endOf(unitOfTime: unitOfTime.StartOf): Moment;
104

105
// StartOf units
106
type StartOf = "year" | "years" | "y" |
107
              "quarter" | "quarters" | "Q" |
108
              "month" | "months" | "M" |
109
              "week" | "weeks" | "w" |
110
              "isoWeek" | "isoWeeks" | "W" |
111
              "day" | "days" | "d" |
112
              "date" | "dates" | "D" |
113
              "hour" | "hours" | "h" |
114
              "minute" | "minutes" | "m" |
115
              "second" | "seconds" | "s" |
116
              "millisecond" | "milliseconds" | "ms";
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
import moment from "moment";
123

124
const date = moment("2023-12-25T15:30:45.123");
125

126
// Start of time periods
127
console.log(date.clone().startOf("year").format()); // "2023-01-01T00:00:00"
128
console.log(date.clone().startOf("month").format()); // "2023-12-01T00:00:00"
129
console.log(date.clone().startOf("week").format()); // "2023-12-24T00:00:00" (Sunday)
130
console.log(date.clone().startOf("isoWeek").format()); // "2023-12-25T00:00:00" (Monday)
131
console.log(date.clone().startOf("day").format()); // "2023-12-25T00:00:00"
132
console.log(date.clone().startOf("hour").format()); // "2023-12-25T15:00:00"
133
console.log(date.clone().startOf("minute").format()); // "2023-12-25T15:30:00"
134
console.log(date.clone().startOf("second").format()); // "2023-12-25T15:30:45"
135

136
// End of time periods
137
console.log(date.clone().endOf("year").format()); // "2023-12-31T23:59:59"
138
console.log(date.clone().endOf("month").format()); // "2023-12-31T23:59:59"
139
console.log(date.clone().endOf("week").format()); // "2023-12-30T23:59:59" (Saturday)
140
console.log(date.clone().endOf("day").format()); // "2023-12-25T23:59:59"
141
console.log(date.clone().endOf("hour").format()); // "2023-12-25T15:59:59"
142
console.log(date.clone().endOf("minute").format()); // "2023-12-25T15:30:59"
143

144
// Quarter boundaries
145
console.log(date.clone().startOf("quarter").format()); // "2023-10-01T00:00:00" (Q4)
146
console.log(date.clone().endOf("quarter").format()); // "2023-12-31T23:59:59"
147

148
// Common use cases
149
const startOfToday = moment().startOf("day");
150
const endOfMonth = moment().endOf("month");
151
const startOfWeek = moment().startOf("week");
152
```
153

154
### Timezone Operations
155

156
Methods for converting between timezones and managing UTC offsets.
157

158
```javascript { .api }
159
/**
160
 * Convert to local time
161
 * @param keepLocalTime - Keep the same local time when converting (default: false)
162
 * @returns This moment instance
163
 */
164
local(keepLocalTime?: boolean): Moment;
165

166
/**
167
 * Convert to UTC time
168
 * @param keepLocalTime - Keep the same local time when converting (default: false)  
169
 * @returns This moment instance
170
 */
171
utc(keepLocalTime?: boolean): Moment;
172

173
/**
174
 * Get current UTC offset in minutes, or set new offset
175
 * @param b - Offset in minutes (number) or offset string like "+05:00"
176
 * @param keepLocalTime - Keep the same local time when setting offset
177
 * @returns Current offset (when getting) or this moment (when setting)
178
 */
179
utcOffset(): number;
180
utcOffset(b: number|string, keepLocalTime?: boolean): Moment;
181

182
/**
183
 * Parse input while keeping original timezone offset
184
 * @returns This moment instance with preserved timezone
185
 */
186
parseZone(): Moment;
187

188
/**
189
 * Check if this moment is in local time mode
190
 * @returns true if in local time, false if UTC
191
 */
192
isLocal(): boolean;
193

194
/**
195
 * Check if this moment is in UTC mode
196
 * @returns true if in UTC, false if local
197
 */
198
isUTC(): boolean;
199

200
/**
201
 * @deprecated Use isUTC() instead. This alias is deprecated.
202
 */
203
isUtc(): boolean;
204

205
/**
206
 * Check if UTC offset has been explicitly set
207
 * @returns true if offset is set, false otherwise
208
 */
209
isUtcOffset(): boolean;
210
```
211

212
**Usage Examples:**
213

214
```javascript
215
import moment from "moment";
216

217
// Create moments in different modes
218
const localMoment = moment("2023-12-25T15:30:00");
219
const utcMoment = moment.utc("2023-12-25T15:30:00");
220

221
console.log(localMoment.format()); // Local interpretation
222
console.log(utcMoment.format()); // UTC interpretation
223

224
// Convert between local and UTC
225
const local = moment("2023-12-25T15:30:00");
226
console.log(local.isLocal()); // true
227
console.log(local.isUTC()); // false
228

229
const asUtc = local.clone().utc();
230
console.log(asUtc.isUTC()); // true
231
console.log(asUtc.format()); // Converted to UTC
232

233
const backToLocal = asUtc.clone().local();
234
console.log(backToLocal.isLocal()); // true
235

236
// UTC offset operations
237
const withOffset = moment.utc("2023-12-25T15:30:00");
238
console.log(withOffset.utcOffset()); // 0 (UTC)
239

240
// Set timezone offset
241
withOffset.utcOffset(300); // +5 hours
242
console.log(withOffset.format()); // Time adjusted for +5 offset
243
console.log(withOffset.utcOffset()); // 300 minutes
244

245
// Set offset with string
246
withOffset.utcOffset("+08:00");
247
console.log(withOffset.utcOffset()); // 480 minutes
248

249
// Keep local time when changing offset
250
const keepTime = moment("2023-12-25T15:30:00+05:00");
251
keepTime.utcOffset("-08:00", true); // Keeps 15:30 local time
252
console.log(keepTime.format()); // Same local time, different offset
253

254
// Parse and preserve timezone
255
const parsed = moment.parseZone("2023-12-25T15:30:00-05:00");
256
console.log(parsed.utcOffset()); // -300 (5 hours behind UTC)
257
console.log(parsed.format()); // Maintains original offset
258
```
259

260
### Advanced Manipulation
261

262
More complex manipulation operations and utility methods.
263

264
```javascript { .api }
265
/**
266
 * Check if this moment has aligned hour offset with another moment
267
 * @param other - Other moment to compare with (defaults to current time)
268
 * @returns true if hour offsets are aligned
269
 */
270
hasAlignedHourOffset(other?: MomentInput): boolean;
271

272
/**
273
 * Get timezone abbreviation (like "PST", "GMT")
274
 * @returns Timezone abbreviation string
275
 */
276
zoneAbbr(): string;
277

278
/**
279
 * Get timezone name (like "Pacific Standard Time")
280
 * @returns Timezone name string
281
 */
282
zoneName(): string;
283

284
/**
285
 * Check if current time is during Daylight Saving Time
286
 * @returns true if in DST, false otherwise
287
 */
288
isDST(): boolean;
289

290
/**
291
 * Check if current year is a leap year
292
 * @returns true if leap year, false otherwise
293
 */
294
isLeapYear(): boolean;
295

296
/**
297
 * Get number of days in the current month
298
 * @returns Number of days (28-31)
299
 */
300
daysInMonth(): number;
301

302
/**
303
 * Get number of weeks in the current year
304
 * @returns Number of weeks (52 or 53)
305
 */
306
weeksInYear(): number;
307

308
/**
309
 * Get number of weeks in the current week year
310
 * @returns Number of weeks (52 or 53)
311
 */
312
weeksInWeekYear(): number;
313

314
/**
315
 * Get number of ISO weeks in the current year
316
 * @returns Number of ISO weeks (52 or 53)
317
 */
318
isoWeeksInYear(): number;
319

320
/**
321
 * Get number of ISO weeks in the current ISO week year
322
 * @returns Number of ISO weeks (52 or 53)
323
 */
324
isoWeeksInISOWeekYear(): number;
325
```
326

327
**Usage Examples:**
328

329
```javascript
330
import moment from "moment";
331

332
const date = moment("2023-12-25T15:30:00");
333

334
// Timezone information
335
console.log(date.zoneAbbr()); // Timezone abbreviation
336
console.log(date.zoneName()); // Full timezone name
337
console.log(date.isDST()); // false (December, not DST)
338

339
// Calendar information
340
console.log(date.isLeapYear()); // false (2023 is not a leap year)
341
console.log(date.daysInMonth()); // 31 (December has 31 days)
342

343
// Week information
344
console.log(date.weeksInYear()); // 52 or 53
345
console.log(date.isoWeeksInYear()); // 52 or 53
346

347
// Hour alignment
348
const moment1 = moment("2023-12-25T15:30:00+05:00");
349
const moment2 = moment("2023-12-25T10:30:00+00:00"); // Same UTC time
350
console.log(moment1.hasAlignedHourOffset(moment2)); // true
351

352
// Leap year examples
353
console.log(moment("2024-02-01").isLeapYear()); // true (2024 is leap year)
354
console.log(moment("2024-02-01").daysInMonth()); // 29 (February in leap year)
355
console.log(moment("2023-02-01").daysInMonth()); // 28 (February in normal year)
356
```
357

358
### Immutable Operations
359

360
While Moment.js mutates the original instance by default, you can create immutable operations using `clone()`.
361

362
```javascript { .api }
363
/**
364
 * Create a copy of this Moment instance
365
 * @returns New Moment instance with same date/time and settings
366
 */
367
clone(): Moment;
368
```
369

370
**Immutable Patterns:**
371

372
```javascript
373
import moment from "moment";
374

375
const original = moment("2023-12-25T15:30:00");
376

377
// Mutating operations (change original)
378
const mutated = original.add(1, "day");
379
console.log(original === mutated); // true (same object)
380
console.log(original.format()); // "2023-12-26T15:30:00" (changed)
381

382
// Immutable operations (preserve original)
383
const original2 = moment("2023-12-25T15:30:00");
384
const immutable = original2.clone().add(1, "day");
385
console.log(original2 === immutable); // false (different objects)
386
console.log(original2.format()); // "2023-12-25T15:30:00" (unchanged)
387
console.log(immutable.format()); // "2023-12-26T15:30:00" (changed)
388

389
// Chaining immutable operations
390
const result = moment("2023-12-25T15:30:00")
391
  .clone()
392
  .startOf("month")
393
  .add(15, "days")
394
  .endOf("day");
395

396
// Common immutable patterns
397
const now = moment();
398
const startOfWeek = now.clone().startOf("week");
399
const endOfWeek = now.clone().endOf("week");
400
const nextMonth = now.clone().add(1, "month");
401
const lastYear = now.clone().subtract(1, "year");
402
```
403

404
## Time Unit Types
405

406
```javascript { .api }
407
// Unit of time namespace
408
namespace unitOfTime {
409
  // Base units for most operations
410
  type Base = "year" | "years" | "y" |
411
              "month" | "months" | "M" |
412
              "week" | "weeks" | "w" |
413
              "day" | "days" | "d" |
414
              "hour" | "hours" | "h" |
415
              "minute" | "minutes" | "m" |
416
              "second" | "seconds" | "s" |
417
              "millisecond" | "milliseconds" | "ms";
418

419
  // Units for duration constructor
420
  type DurationConstructor = Base | "quarter" | "quarters" | "Q" | 
421
                            "isoWeek" | "isoWeeks" | "W";
422

423
  // Units for startOf/endOf operations  
424
  type StartOf = Base | "quarter" | "quarters" | "Q" |
425
                 "isoWeek" | "isoWeeks" | "W" |
426
                 "date" | "dates" | "D";
427

428
  // Units for diff operations
429
  type Diff = Base | "quarter" | "quarters" | "Q";
430

431
  // All available units
432
  type All = Base | "quarter" | "quarters" | "Q" |
433
             "isoWeek" | "isoWeeks" | "W" |
434
             "date" | "dates" | "D" |
435
             "weekYear" | "weekYears" | "gg" |
436
             "isoWeekYear" | "isoWeekYears" | "GG" |
437
             "dayOfYear" | "dayOfYears" | "DDD" |
438
             "weekday" | "weekdays" | "e" |
439
             "isoWeekday" | "isoWeekdays" | "E";
440
}
441
```