0
# Range Manipulation
1

2
Manipulate ranges through addition, subtraction, cloning, and boundary snapping operations.
3

4
## Capabilities
5

6
### Add
7

8
Merge two ranges if they overlap or are adjacent.
9

10
```javascript { .api }
11
/**
12
 * Add (merge) this range with another range if they overlap
13
 * @param other - Range to merge with
14
 * @param options - Options for considering adjacent ranges
15
 * @returns New DateRange spanning both ranges, or null if no overlap
16
 */
17
add(other: DateRange, options?: AddOptions): DateRange | null;
18

19
interface AddOptions {
20
  adjacent?: boolean; // Consider adjacent ranges as mergeable
21
}
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
const range1 = moment.range('2024-01-01', '2024-01-15');
28
const range2 = moment.range('2024-01-10', '2024-01-25');
29

30
// Merge overlapping ranges
31
const merged = range1.add(range2);
32
console.log(merged.toString()); // "2024-01-01T00:00:00Z/2024-01-25T23:59:59Z"
33

34
// Try to merge non-overlapping ranges
35
const range3 = moment.range('2024-01-20', '2024-01-31');
36
const notMerged = range1.add(range3);
37
console.log(notMerged); // null
38

39
// Merge adjacent ranges
40
const range4 = moment.range('2024-01-16', '2024-01-31');
41
const adjacentMerged = range1.add(range4, { adjacent: true });
42
console.log(adjacentMerged.toString()); // "2024-01-01T00:00:00Z/2024-01-31T23:59:59Z"
43
```
44

45
### Subtract
46

47
Remove another range from this range, potentially splitting it.
48

49
```javascript { .api }
50
/**
51
 * Subtract another range from this range
52
 * @param other - Range to subtract
53
 * @returns Array of remaining DateRange objects (0-2 ranges)
54
 */
55
subtract(other: DateRange): DateRange[];
56
```
57

58
**Usage Examples:**
59

60
```javascript
61
const range = moment.range('2024-01-01', '2024-01-31');
62

63
// Subtract from middle (splits range)
64
const middle = moment.range('2024-01-10', '2024-01-20');
65
const split = range.subtract(middle);
66
console.log(split.length); // 2
67
console.log(split[0].toString()); // "2024-01-01T00:00:00Z/2024-01-10T00:00:00Z"
68
console.log(split[1].toString()); // "2024-01-20T00:00:00Z/2024-01-31T23:59:59Z"
69

70
// Subtract from beginning
71
const beginning = moment.range('2024-01-01', '2024-01-10');
72
const fromStart = range.subtract(beginning);
73
console.log(fromStart.length); // 1
74
console.log(fromStart[0].toString()); // "2024-01-10T00:00:00Z/2024-01-31T23:59:59Z"
75

76
// Subtract entire range
77
const entire = range.subtract(range);
78
console.log(entire.length); // 0 (empty array)
79

80
// Subtract non-overlapping range
81
const noOverlap = moment.range('2024-02-01', '2024-02-28');
82
const unchanged = range.subtract(noOverlap);
83
console.log(unchanged.length); // 1 (original range unchanged)
84
```
85

86
### Clone
87

88
Create a deep copy of the range.
89

90
```javascript { .api }
91
/**
92
 * Create a deep copy of this range
93
 * @returns New DateRange instance with cloned start and end moments
94
 */
95
clone(): DateRange;
96
```
97

98
**Usage Examples:**
99

100
```javascript
101
const original = moment.range('2024-01-01', '2024-01-31');
102
const copy = original.clone();
103

104
// Modify copy without affecting original
105
copy.start.add(1, 'day');
106
console.log(original.start.format('YYYY-MM-DD')); // "2024-01-01" (unchanged)
107
console.log(copy.start.format('YYYY-MM-DD'));     // "2024-01-02" (modified)
108
```
109

110
### SnapTo
111

112
Snap range boundaries to interval boundaries.
113

114
```javascript { .api }
115
/**
116
 * Snap range boundaries to the boundaries of a time interval
117
 * @param interval - Time unit to snap to (year, month, day, etc.)
118
 * @returns New DateRange with snapped boundaries
119
 */
120
snapTo(interval: IntervalUnit): DateRange;
121

122
type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
// Snap to day boundaries
129
const range = moment.range('2024-01-15T14:30:00', '2024-01-20T09:45:00');
130
const daySnapped = range.snapTo('day');
131
console.log(daySnapped.start.format()); // "2024-01-15T00:00:00Z"
132
console.log(daySnapped.end.format());   // "2024-01-20T23:59:59Z"
133

134
// Snap to month boundaries
135
const monthSnapped = range.snapTo('month');
136
console.log(monthSnapped.start.format()); // "2024-01-01T00:00:00Z"
137
console.log(monthSnapped.end.format());   // "2024-01-31T23:59:59Z"
138

139
// Open-ended ranges are not snapped
140
const openRange = moment.range(null, '2024-01-15T14:30:00');
141
const openSnapped = openRange.snapTo('day');
142
console.log(openSnapped.start.valueOf()); // -8640000000000000 (unchanged)
143
console.log(openSnapped.end.format());    // "2024-01-15T23:59:59Z" (snapped)
144
```
145

146
### Center
147

148
Get the center moment of the range.
149

150
```javascript { .api }
151
/**
152
 * Get the center moment of this range
153
 * @returns Moment representing the midpoint of the range
154
 */
155
center(): Moment;
156
```
157

158
**Usage Examples:**
159

160
```javascript
161
const range = moment.range('2024-01-01', '2024-01-31');
162
const centerPoint = range.center();
163
console.log(centerPoint.format('YYYY-MM-DD')); // "2024-01-16"
164

165
// Works with time ranges too
166
const timeRange = moment.range('2024-01-01T00:00:00', '2024-01-01T12:00:00');
167
const timeCenter = timeRange.center();
168
console.log(timeCenter.format('HH:mm')); // "06:00"
169
```
170

171
### Duration and Difference
172

173
Get the duration or difference of the range.
174

175
```javascript { .api }
176
/**
177
 * Get the difference between end and start in specified units
178
 * @param unit - Unit to measure difference in (optional)
179
 * @param precise - Whether to use precise calculation (optional)
180
 * @returns Numeric difference
181
 */
182
diff(unit?: string, precise?: boolean): number;
183

184
/**
185
 * Alias for diff method
186
 * @param unit - Unit to measure duration in (optional)
187
 * @param precise - Whether to use precise calculation (optional)
188
 * @returns Numeric duration
189
 */
190
duration(unit?: string, precise?: boolean): number;
191

192
/**
193
 * Get the duration in milliseconds
194
 * @returns Duration in milliseconds
195
 */
196
valueOf(): number;
197
```
198

199
**Usage Examples:**
200

201
```javascript
202
const range = moment.range('2024-01-01', '2024-01-31');
203

204
// Get difference in various units
205
console.log(range.diff('days'));    // 30
206
console.log(range.diff('weeks'));   // 4
207
console.log(range.diff('months'));  // 1
208

209
// Duration is an alias for diff
210
console.log(range.duration('days')); // 30
211

212
// Get milliseconds
213
console.log(range.valueOf()); // 2678400000 (30 days in ms)
214

215
// Precise calculations
216
const preciseRange = moment.range('2024-01-01', '2024-01-01T12:00:00');
217
console.log(preciseRange.diff('days', true)); // 0.5
218
```
219

220
### String and Date Conversion
221

222
Convert ranges to various output formats.
223

224
```javascript { .api }
225
/**
226
 * Convert range to ISO 8601 interval string
227
 * @returns String in format "start/end"
228
 */
229
toString(): string;
230

231
/**
232
 * Convert range to array of native Date objects
233
 * @returns Array containing [startDate, endDate]
234
 */
235
toDate(): [Date, Date];
236
```
237

238
**Usage Examples:**
239

240
```javascript
241
const range = moment.range('2024-01-01', '2024-01-31');
242

243
// Convert to ISO string
244
console.log(range.toString()); // "2024-01-01T00:00:00Z/2024-01-31T23:59:59Z"
245

246
// Convert to native Date objects
247
const [startDate, endDate] = range.toDate();
248
console.log(startDate instanceof Date); // true
249
console.log(endDate instanceof Date);   // true
250
```
251

252
## Types
253

254
```javascript { .api }
255
interface AddOptions {
256
  adjacent?: boolean;
257
}
258

259
type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
260
```