0
# Range Module
1

2
Advanced range creation and manipulation for dates, numbers, and strings with comprehensive set operations and iteration capabilities.
3

4
## Core Imports
5

6
```javascript
7
// Import Sugar namespace
8
import Sugar from "sugar";
9
// Range class available as Sugar.Range
10
// Range creation methods available as Sugar.Date.range, Sugar.Number.range, Sugar.String.range
11
```
12

13
CommonJS:
14
```javascript
15
const Sugar = require("sugar");
16
// Range class available as Sugar.Range
17
// Range creation methods available via module namespaces
18
Sugar.Date.range(start, end);
19
Sugar.Number.range(start, end);
20
Sugar.String.range(start, end);
21
```
22

23
## Capabilities
24

25
### Range Creation
26

27
Create ranges from different data types using module-specific range functions.
28

29
#### Date Range Creation
30

31
Creates a range of dates between start and end points.
32

33
```javascript { .api }
34
/**
35
 * Creates a range of dates between start and end points
36
 * @param start - Start date (any format Sugar.Date.create accepts)
37
 * @param end - End date (any format Sugar.Date.create accepts)
38
 * @returns Range instance containing dates
39
 */
40
function range(start?: any, end?: any): Range;
41
```
42

43
**Usage Example:**
44
```javascript
45
import Sugar from "sugar";
46

47
// Create a date range
48
const dateRange = Sugar.Date.range('2023-01-01', '2023-12-31');
49
const thisWeek = Sugar.Date.range('monday', 'sunday');
50
const nextMonth = Sugar.Date.range('next month', 'end of next month');
51
```
52

53
#### Number Range Creation
54

55
Creates a range of numbers between start and end points.
56

57
```javascript { .api }
58
/**
59
 * Creates a range of numbers between start and end points
60
 * @param start - Starting number (default: 0)
61
 * @param end - Ending number (default: start value, start becomes 0)
62
 * @returns Range instance containing numbers
63
 */
64
function range(start?: number, end?: number): Range;
65
```
66

67
**Usage Example:**
68
```javascript
69
import Sugar from "sugar";
70

71
// Create number ranges
72
const oneToTen = Sugar.Number.range(1, 10);
73
const zeroToFive = Sugar.Number.range(5); // start defaults to 0
74
const negativeRange = Sugar.Number.range(-5, 5);
75
```
76

77
#### String Range Creation
78

79
Creates a range of strings between start and end characters.
80

81
```javascript { .api }
82
/**
83
 * Creates a range of strings between start and end characters
84
 * @param start - Starting character or string
85
 * @param end - Ending character or string
86
 * @returns Range instance containing strings
87
 */
88
function range(start?: string, end?: string): Range;
89
```
90

91
**Usage Example:**
92
```javascript
93
import Sugar from "sugar";
94

95
// Create string ranges
96
const alphabet = Sugar.String.range('a', 'z');
97
const numbers = Sugar.String.range('0', '9');
98
const customRange = Sugar.String.range('aa', 'zz');
99
```
100

101
### Range Class
102

103
The Range class provides methods for working with ranges of any comparable data type.
104

105
#### Range Constructor
106

107
```javascript { .api }
108
/**
109
 * Range class for creating and manipulating ranges
110
 * @param start - Starting value of the range
111
 * @param end - Ending value of the range
112
 */
113
class Range {
114
  constructor(start: any, end: any);
115
}
116
```
117

118
### Core Range Operations
119

120
Essential methods for range manipulation and querying.
121

122
#### Clamp
123

124
Constrains an element to fall within the range bounds.
125

126
```javascript { .api }
127
/**
128
 * Constrains an element to fall within the range bounds
129
 * @param el - Element to clamp to the range
130
 * @returns Element clamped to range bounds
131
 */
132
clamp<T>(el: T): T;
133
```
134

135
**Usage Example:**
136
```javascript
137
import Sugar from "sugar";
138

139
const numberRange = Sugar.Number.range(1, 10);
140
numberRange.clamp(15); // Returns 10
141
numberRange.clamp(-5); // Returns 1
142
numberRange.clamp(5);  // Returns 5
143
```
144

145
#### Clone
146

147
Creates a deep copy of the range.
148

149
```javascript { .api }
150
/**
151
 * Creates a deep copy of the range
152
 * @returns New Range instance with same bounds
153
 */
154
clone(): Range;
155
```
156

157
#### Contains
158

159
Tests whether an element falls within the range.
160

161
```javascript { .api }
162
/**
163
 * Tests whether an element falls within the range
164
 * @param el - Element to test for containment
165
 * @returns true if element is within range bounds
166
 */
167
contains<T>(el: T): boolean;
168
```
169

170
**Usage Example:**
171
```javascript
172
import Sugar from "sugar";
173

174
const dateRange = Sugar.Date.range('2023-01-01', '2023-12-31');
175
dateRange.contains('2023-06-15'); // true
176
dateRange.contains('2024-01-01'); // false
177

178
const stringRange = Sugar.String.range('a', 'z');
179
stringRange.contains('m'); // true
180
stringRange.contains('A'); // false
181
```
182

183
#### IsValid
184

185
Tests whether the range is valid (start <= end).
186

187
```javascript { .api }
188
/**
189
 * Tests whether the range is valid (start <= end)
190
 * @returns true if range has valid bounds
191
 */
192
isValid(): boolean;
193
```
194

195
### Range Conversion
196

197
Methods for converting ranges to different formats.
198

199
#### ToArray
200

201
Converts the range to an array of all values within the range.
202

203
```javascript { .api }
204
/**
205
 * Converts the range to an array of all values within the range
206
 * @returns Array containing all values in the range
207
 */
208
toArray<T>(): T[];
209
```
210

211
**Usage Example:**
212
```javascript
213
import Sugar from "sugar";
214

215
Sugar.Number.range(1, 5).toArray(); // [1, 2, 3, 4, 5]
216
Sugar.String.range('a', 'e').toArray(); // ['a', 'b', 'c', 'd', 'e']
217
```
218

219
#### ToString
220

221
Returns a string representation of the range.
222

223
```javascript { .api }
224
/**
225
 * Returns a string representation of the range
226
 * @returns String representation of the range bounds
227
 */
228
toString(): string;
229
```
230

231
### Range Set Operations
232

233
Mathematical set operations for combining and comparing ranges.
234

235
#### Intersect
236

237
Returns the intersection of this range with another range.
238

239
```javascript { .api }
240
/**
241
 * Returns the intersection of this range with another range
242
 * @param range - Range to intersect with
243
 * @returns New Range representing the intersection, or null if no overlap
244
 */
245
intersect(range: Range): Range | null;
246
```
247

248
**Usage Example:**
249
```javascript
250
import Sugar from "sugar";
251

252
const range1 = Sugar.Number.range(1, 10);
253
const range2 = Sugar.Number.range(5, 15);
254
const intersection = range1.intersect(range2); // Range from 5 to 10
255

256
const range3 = Sugar.Number.range(20, 30);
257
const noOverlap = range1.intersect(range3); // null
258
```
259

260
#### Union
261

262
Returns the union of this range with another range.
263

264
```javascript { .api }
265
/**
266
 * Returns the union of this range with another range
267
 * @param range - Range to union with
268
 * @returns New Range representing the union
269
 */
270
union(range: Range): Range;
271
```
272

273
**Usage Example:**
274
```javascript
275
import Sugar from "sugar";
276

277
const range1 = Sugar.Number.range(1, 5);
278
const range2 = Sugar.Number.range(3, 8);
279
const union = range1.union(range2); // Range from 1 to 8
280

281
const range3 = Sugar.Number.range(10, 15);
282
const extended = range1.union(range3); // Range from 1 to 15
283
```
284

285
#### Span
286

287
Returns the total span of the range.
288

289
```javascript { .api }
290
/**
291
 * Returns the total span of the range
292
 * @returns Span value representing range size
293
 */
294
span(): any;
295
```
296

297
### Range Iteration
298

299
Methods for iterating over and processing range values.
300

301
#### Every
302

303
Iterates over the range with specified intervals, calling a function for each step.
304

305
```javascript { .api }
306
/**
307
 * Iterates over the range with specified intervals
308
 * @param amount - Step amount (string for dates, number for others)
309
 * @param everyFn - Function to call for each iteration step
310
 * @returns Array of results from function calls
311
 */
312
every<T>(amount: string | number, everyFn?: (value: any, index: number) => T): T[];
313
```
314

315
**Usage Example:**
316
```javascript
317
import Sugar from "sugar";
318

319
// Iterate over date range by days
320
const dateRange = Sugar.Date.range('2023-01-01', '2023-01-07');
321
dateRange.every('day', (date, index) => {
322
  console.log(`Day ${index + 1}: ${date}`);
323
});
324

325
// Iterate over number range by steps
326
const numbers = Sugar.Number.range(1, 10);
327
numbers.every(2, (num, index) => {
328
  return num * 2; // [2, 6, 10, 14, 18]
329
});
330
```
331

332
### Date Range Specific Methods
333

334
When a range contains dates, additional time-based methods become available.
335

336
#### Time Unit Methods
337

338
Get the span of a date range in specific time units.
339

340
```javascript { .api }
341
/**
342
 * Returns the range span in days
343
 * @returns Number of days in the range
344
 */
345
days(): number;
346

347
/**
348
 * Returns the range span in hours
349
 * @returns Number of hours in the range
350
 */
351
hours(): number;
352

353
/**
354
 * Returns the range span in milliseconds
355
 * @returns Number of milliseconds in the range
356
 */
357
milliseconds(): number;
358

359
/**
360
 * Returns the range span in minutes
361
 * @returns Number of minutes in the range
362
 */
363
minutes(): number;
364

365
/**
366
 * Returns the range span in months
367
 * @returns Number of months in the range
368
 */
369
months(): number;
370

371
/**
372
 * Returns the range span in seconds
373
 * @returns Number of seconds in the range
374
 */
375
seconds(): number;
376

377
/**
378
 * Returns the range span in weeks
379
 * @returns Number of weeks in the range
380
 */
381
weeks(): number;
382

383
/**
384
 * Returns the range span in years
385
 * @returns Number of years in the range
386
 */
387
years(): number;
388
```
389

390
**Usage Example:**
391
```javascript
392
import Sugar from "sugar";
393

394
const dateRange = Sugar.Date.range('2023-01-01', '2023-12-31');
395
dateRange.days();    // 365
396
dateRange.hours();   // 8760
397
dateRange.months();  // 12
398
dateRange.years();   // 1
399

400
const shortRange = Sugar.Date.range('today', 'tomorrow');
401
shortRange.days();   // 1
402
shortRange.hours();  // 24
403
```
404

405
## Types
406

407
```javascript { .api }
408
/**
409
 * Range class for creating ranges of dates, numbers, or strings
410
 */
411
class Range {
412
  constructor(start: any, end: any);
413
  
414
  // Core operations
415
  clamp<T>(el: T): T;
416
  clone(): Range;
417
  contains<T>(el: T): boolean;
418
  isValid(): boolean;
419
  
420
  // Conversion
421
  toArray<T>(): T[];
422
  toString(): string;
423
  
424
  // Set operations
425
  intersect(range: Range): Range | null;
426
  union(range: Range): Range;
427
  span(): any;
428
  
429
  // Iteration
430
  every<T>(amount: string | number, everyFn?: (value: any, index: number) => T): T[];
431
  
432
  // Date-specific methods (available when range contains dates)
433
  days(): number;
434
  hours(): number;
435
  milliseconds(): number;
436
  minutes(): number;
437
  months(): number;
438
  seconds(): number;
439
  weeks(): number;
440
  years(): number;
441
}
442
```