0
# Date/Time Functions
1

2
Functions for working with timestamps, date formatting, and time calculations.
3

4
## Capabilities
5

6
### Current Time Functions
7

8
#### Now Function
9

10
Returns the current timestamp, optionally formatted according to a picture string.
11

12
```javascript { .api }
13
/**
14
 * Get current timestamp
15
 * @param picture - Optional picture string for formatting
16
 * @param timezone - Optional timezone specification
17
 * @returns Current timestamp as string (formatted) or milliseconds
18
 */
19
function $now(picture, timezone);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
// Get current timestamp in ISO format
26
const current = await jsonata('$now()').evaluate({}); // "2023-10-15T14:30:25.123Z"
27

28
// Format current time
29
const formatted = await jsonata('$now("[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]")').evaluate({});
30
// "2023-10-15 14:30:25"
31

32
// With timezone
33
const utc = await jsonata('$now("[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "+0000")').evaluate({});
34
const est = await jsonata('$now("[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "-0500")').evaluate({});
35

36
// Custom formats
37
const readable = await jsonata('$now("[MNn] [D1o], [Y]")').evaluate({}); // "October 15th, 2023"
38
const time = await jsonata('$now("[h]:[m01] [PN]")').evaluate({}); // "2:30 PM"
39
```
40

41
#### Millis Function
42

43
Returns the current time in milliseconds since the Unix epoch.
44

45
```javascript { .api }
46
/**
47
 * Get current time in milliseconds
48
 * @returns Current time as milliseconds since epoch
49
 */
50
function $millis();
51
```
52

53
**Usage Examples:**
54

55
```javascript
56
const timestamp = await jsonata('$millis()').evaluate({}); // 1697374225123
57

58
// Calculate elapsed time
59
const data = { startTime: 1697374200000 };
60
const elapsed = await jsonata('$millis() - startTime').evaluate(data); // Time difference in ms
61

62
// Generate unique IDs with timestamp
63
const uniqueId = await jsonata('"user_" & $string($millis())').evaluate({}); // "user_1697374225123"
64
```
65

66
### Time Conversion Functions
67

68
#### To Millis Function
69

70
Converts a timestamp string to milliseconds since the Unix epoch.
71

72
```javascript { .api }
73
/**
74
 * Convert timestamp to milliseconds
75
 * @param timestamp - ISO 8601 timestamp string or custom format
76
 * @param picture - Optional picture string for parsing custom formats
77
 * @returns Milliseconds since Unix epoch
78
 */
79
function $toMillis(timestamp, picture);
80
```
81

82
**Usage Examples:**
83

84
```javascript
85
// Parse ISO 8601 timestamps
86
const iso = await jsonata('$toMillis("2023-10-15T14:30:25.123Z")').evaluate({}); // 1697374225123
87
const date = await jsonata('$toMillis("2023-10-15")').evaluate({}); // 1697328000000
88

89
// Parse custom formats
90
const custom = await jsonata('$toMillis("15/10/2023 14:30:25", "[D01]/[M01]/[Y0001] [H01]:[m01]:[s01]")').evaluate({});
91

92
// Process array of timestamps
93
const data = {
94
  events: [
95
    { name: "Event 1", time: "2023-10-15T10:00:00Z" },
96
    { name: "Event 2", time: "2023-10-15T14:30:00Z" }
97
  ]
98
};
99
const withMillis = await jsonata('events.{"name": name, "timestamp": $toMillis(time)}').evaluate(data);
100

101
// Calculate time differences
102
const start = "2023-10-15T10:00:00Z";
103
const end = "2023-10-15T14:30:00Z";
104
const duration = await jsonata('$toMillis(end) - $toMillis(start)').evaluate({ start, end }); // Duration in ms
105
```
106

107
#### From Millis Function
108

109
Converts milliseconds since the Unix epoch to a formatted timestamp string.
110

111
```javascript { .api }
112
/**
113
 * Convert milliseconds to formatted timestamp
114
 * @param millis - Milliseconds since Unix epoch
115
 * @param picture - Optional picture string for formatting
116
 * @param timezone - Optional timezone specification
117
 * @returns Formatted timestamp string
118
 */
119
function $fromMillis(millis, picture, timezone);
120
```
121

122
**Usage Examples:**
123

124
```javascript
125
// Convert to ISO format (default)
126
const iso = await jsonata('$fromMillis(1697374225123)').evaluate({}); // "2023-10-15T14:30:25.123Z"
127

128
// Custom formatting
129
const readable = await jsonata('$fromMillis(1697374225123, "[MNn] [D1o], [Y] at [h]:[m01] [PN]")').evaluate({});
130
// "October 15th, 2023 at 2:30 PM"
131

132
// Date only
133
const dateOnly = await jsonata('$fromMillis(1697374225123, "[Y0001]-[M01]-[D01]")').evaluate({}); // "2023-10-15"
134

135
// Time only
136
const timeOnly = await jsonata('$fromMillis(1697374225123, "[H01]:[m01]:[s01]")').evaluate({}); // "14:30:25"
137

138
// With timezone conversion
139
const utc = await jsonata('$fromMillis(1697374225123, "[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "+0000")').evaluate({});
140
const est = await jsonata('$fromMillis(1697374225123, "[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]", "-0500")').evaluate({});
141

142
// Format array of timestamps
143
const data = { 
144
  events: [
145
    { name: "Start", timestamp: 1697374200000 },
146
    { name: "End", timestamp: 1697374800000 }
147
  ]
148
};
149
const formatted = await jsonata('events.{"name": name, "time": $fromMillis(timestamp, "[h]:[m01] [PN]")}').evaluate(data);
150
```
151

152
## Picture String Format
153

154
JSONata uses picture strings to specify date/time formatting patterns:
155

156
### Date Components
157
- `[Y]` - Year (variable width)
158
- `[Y0001]` - Year (4 digits, zero-padded)
159
- `[M]` - Month number (variable width)
160
- `[M01]` - Month number (2 digits, zero-padded)
161
- `[MNn]` - Month name (January, February, etc.)
162
- `[MN]` - Month abbreviation (Jan, Feb, etc.)
163
- `[D]` - Day of month (variable width)
164
- `[D01]` - Day of month (2 digits, zero-padded)
165
- `[D1o]` - Day with ordinal suffix (1st, 2nd, 3rd, etc.)
166
- `[FNn]` - Day of week name (Monday, Tuesday, etc.)
167
- `[FN]` - Day of week abbreviation (Mon, Tue, etc.)
168

169
### Time Components
170
- `[H]` - Hour (24-hour format, variable width)
171
- `[H01]` - Hour (24-hour format, 2 digits, zero-padded)
172
- `[h]` - Hour (12-hour format, variable width)
173
- `[h01]` - Hour (12-hour format, 2 digits, zero-padded)  
174
- `[m]` - Minutes (variable width)
175
- `[m01]` - Minutes (2 digits, zero-padded)
176
- `[s]` - Seconds (variable width)
177
- `[s01]` - Seconds (2 digits, zero-padded)
178
- `[f]` - Fractional seconds (variable width)
179
- `[f001]` - Fractional seconds (3 digits, zero-padded)
180
- `[PN]` - AM/PM indicator
181
- `[pn]` - am/pm indicator (lowercase)
182

183
### Timezone Components
184
- `[Z]` - Timezone offset from UTC (+0100, -0500, etc.)
185
- `[z]` - Timezone abbreviation (EST, PST, etc.)
186

187
**Example Usage:**
188

189
```javascript
190
const data = { timestamp: 1697374225123 }; // 2023-10-15T14:30:25.123Z
191

192
// Various formatting examples
193
const formats = {
194
  iso: await jsonata('$fromMillis(timestamp)').evaluate(data),
195
  // "2023-10-15T14:30:25.123Z"
196
  
197
  readable: await jsonata('$fromMillis(timestamp, "[MNn] [D1o], [Y]")').evaluate(data),
198
  // "October 15th, 2023"
199
  
200
  withTime: await jsonata('$fromMillis(timestamp, "[MNn] [D1o], [Y] at [h]:[m01] [PN]")').evaluate(data),
201
  // "October 15th, 2023 at 2:30 PM"
202
  
203
  technical: await jsonata('$fromMillis(timestamp, "[Y0001]-[M01]-[D01] [H01]:[m01]:[s01].[f001]")').evaluate(data),
204
  // "2023-10-15 14:30:25.123"
205
  
206
  logFormat: await jsonata('$fromMillis(timestamp, "[Y0001]/[M01]/[D01] [H01]:[m01]:[s01]")').evaluate(data),
207
  // "2023/10/15 14:30:25"
208
  
209
  dayOfWeek: await jsonata('$fromMillis(timestamp, "[FNn], [MNn] [D1o]")').evaluate(data)
210
  // "Sunday, October 15th"
211
};
212
```
213

214
## Time Calculations
215

216
JSONata's date/time functions work well with arithmetic operations for time calculations:
217

218
```javascript
219
// Add/subtract time
220
const data = { baseTime: "2023-10-15T10:00:00Z" };
221

222
// Add 2 hours (2 * 60 * 60 * 1000 ms)
223
const later = await jsonata('$fromMillis($toMillis(baseTime) + 7200000)').evaluate(data);
224

225
// Subtract 30 minutes
226
const earlier = await jsonata('$fromMillis($toMillis(baseTime) - 1800000)').evaluate(data);
227

228
// Calculate duration between timestamps
229
const start = "2023-10-15T10:00:00Z";
230
const end = "2023-10-15T14:30:00Z";
231
const durationMs = await jsonata('$toMillis(end) - $toMillis(start)').evaluate({ start, end });
232
const durationHours = durationMs / (1000 * 60 * 60); // Convert to hours
233

234
// Find events within time window
235
const events = {
236
  events: [
237
    { name: "Meeting", time: "2023-10-15T09:00:00Z" },
238
    { name: "Lunch", time: "2023-10-15T12:00:00Z" },
239
    { name: "Call", time: "2023-10-15T15:00:00Z" }
240
  ],
241
  windowStart: "2023-10-15T10:00:00Z",
242
  windowEnd: "2023-10-15T14:00:00Z"
243
};
244

245
const inWindow = await jsonata(`
246
  events[$toMillis(time) >= $toMillis(windowStart) and $toMillis(time) <= $toMillis(windowEnd)]
247
`).evaluate(events);
248
```
249

250
### Integer Formatting Functions
251

252
#### Format Integer Function
253

254
Formats a number as a string using a picture string for integer representation.
255

256
```javascript { .api }
257
/**
258
 * Format integer using picture string
259
 * @param number - Number to format
260
 * @param picture - Picture string for formatting
261
 * @returns Formatted number string
262
 */
263
function $formatInteger(number, picture);
264
```
265

266
**Usage Examples:**
267

268
```javascript
269
// Basic number formatting
270
const num = await jsonata('$formatInteger(123, "000")').evaluate({}); // "123"
271
const padded = await jsonata('$formatInteger(42, "0000")').evaluate({}); // "0042"
272

273
// Roman numerals
274
const roman = await jsonata('$formatInteger(1984, "I")').evaluate({}); // "MCMLXXXIV"
275
const romanLower = await jsonata('$formatInteger(42, "i")').evaluate({}); // "xlii"
276

277
// Ordinal numbers
278
const ordinal = await jsonata('$formatInteger(21, "1o")').evaluate({}); // "21st"
279
const ordinalWord = await jsonata('$formatInteger(3, "Ww")').evaluate({}); // "Third"
280
```
281

282
#### Parse Integer Function
283

284
Parses a formatted integer string back to a number using a picture string.
285

286
```javascript { .api }
287
/**
288
 * Parse formatted integer string
289
 * @param string - Formatted integer string
290
 * @param picture - Picture string used for formatting
291
 * @returns Parsed number
292
 */
293
function $parseInteger(string, picture);
294
```
295

296
**Usage Examples:**
297

298
```javascript
299
// Parse padded numbers
300
const parsed = await jsonata('$parseInteger("0042", "0000")').evaluate({}); // 42
301

302
// Parse Roman numerals
303
const fromRoman = await jsonata('$parseInteger("MCMLXXXIV", "I")').evaluate({}); // 1984
304
const fromRomanLower = await jsonata('$parseInteger("xlii", "i")').evaluate({}); // 42
305

306
// Parse ordinal numbers
307
const fromOrdinal = await jsonata('$parseInteger("21st", "1o")').evaluate({}); // 21
308
```