0
# String Functions
1

2
Comprehensive string manipulation, formatting, and transformation functions.
3

4
## Capabilities
5

6
### String Conversion and Formatting
7

8
#### String Conversion
9

10
Converts a value to its string representation.
11

12
```javascript { .api }
13
/**
14
 * Convert value to string representation
15
 * @param arg - Value to convert to string
16
 * @param prettify - Optional boolean to pretty-print JSON objects
17
 * @returns String representation of the value
18
 */
19
function $string(arg, prettify);
20
```
21

22
**Usage Examples:**
23

24
```javascript
25
const result1 = await jsonata("$string(123)").evaluate({}); // "123"
26
const result2 = await jsonata("$string(true)").evaluate({}); // "true"
27

28
// Pretty-print JSON objects
29
const data = { user: { name: "Alice", age: 30 } };
30
const pretty = await jsonata("$string(user, true)").evaluate(data);
31
// "{\n  \"name\": \"Alice\",\n  \"age\": 30\n}"
32

33
// Convert array elements to strings
34
const numbers = { values: [1, 2, 3] };
35
const strings = await jsonata("values.$string($)").evaluate(numbers); // ["1", "2", "3"]
36
```
37

38
#### Length Function
39

40
Returns the length of a string or array.
41

42
```javascript { .api }
43
/**
44
 * Get length of string or array
45
 * @param str - String or array input
46
 * @returns Length of the input
47
 */
48
function $length(str);
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
const result1 = await jsonata('$length("hello")').evaluate({}); // 5
55
const result2 = await jsonata("$length([1, 2, 3])").evaluate({}); // 3
56

57
// Check field lengths
58
const user = { name: "Alice", email: "alice@example.com" };
59
const lengths = await jsonata("{ 'name': $length(name), 'email': $length(email) }").evaluate(user);
60
// { "name": 5, "email": 17 }
61
```
62

63
### String Extraction
64

65
#### Substring Function
66

67
Extracts a substring from a string.
68

69
```javascript { .api }
70
/**
71
 * Extract substring from string
72
 * @param str - Source string
73
 * @param start - Starting position (0-based)
74
 * @param length - Optional length of substring
75
 * @returns Extracted substring
76
 */
77
function $substring(str, start, length);
78
```
79

80
**Usage Examples:**
81

82
```javascript
83
const result1 = await jsonata('$substring("hello world", 0, 5)').evaluate({}); // "hello"
84
const result2 = await jsonata('$substring("hello world", 6)').evaluate({}); // "world"
85

86
// Extract file extension
87
const file = { filename: "document.pdf" };
88
const ext = await jsonata('$substring(filename, $length(filename) - 3)').evaluate(file); // "pdf"
89
```
90

91
#### Substring Before
92

93
Returns the substring before the first occurrence of specified characters.
94

95
```javascript { .api }
96
/**
97
 * Get substring before first occurrence of characters
98
 * @param str - Source string
99
 * @param chars - Characters to search for
100
 * @returns Substring before the characters, or original string if not found
101
 */
102
function $substringBefore(str, chars);
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
const result = await jsonata('$substringBefore("hello@world.com", "@")').evaluate({}); // "hello"
109

110
// Extract username from email
111
const user = { email: "john.doe@company.com" };
112
const username = await jsonata('$substringBefore(email, "@")').evaluate(user); // "john.doe"
113
```
114

115
#### Substring After
116

117
Returns the substring after the first occurrence of specified characters.
118

119
```javascript { .api }
120
/**
121
 * Get substring after first occurrence of characters
122
 * @param str - Source string
123
 * @param chars - Characters to search for
124
 * @returns Substring after the characters, or empty string if not found
125
 */
126
function $substringAfter(str, chars);
127
```
128

129
**Usage Examples:**
130

131
```javascript
132
const result = await jsonata('$substringAfter("hello@world.com", "@")').evaluate({}); // "world.com"
133

134
// Extract domain from email
135
const user = { email: "john.doe@company.com" };
136
const domain = await jsonata('$substringAfter(email, "@")').evaluate(user); // "company.com"
137
```
138

139
### Case Conversion
140

141
#### Lowercase Function
142

143
Converts a string to lowercase.
144

145
```javascript { .api }
146
/**
147
 * Convert string to lowercase
148
 * @param str - String to convert
149
 * @returns Lowercase version of the string
150
 */
151
function $lowercase(str);
152
```
153

154
#### Uppercase Function
155

156
Converts a string to uppercase.
157

158
```javascript { .api }
159
/**
160
 * Convert string to uppercase
161
 * @param str - String to convert
162
 * @returns Uppercase version of the string
163
 */
164
function $uppercase(str);
165
```
166

167
**Usage Examples:**
168

169
```javascript
170
const name = { firstName: "Alice", lastName: "Smith" };
171
const upper = await jsonata("$uppercase(firstName & ' ' & lastName)").evaluate(name); // "ALICE SMITH"
172
const lower = await jsonata("$lowercase(firstName & ' ' & lastName)").evaluate(name); // "alice smith"
173

174
// Normalize email addresses
175
const user = { email: "John.Doe@COMPANY.COM" };
176
const normalized = await jsonata("$lowercase(email)").evaluate(user); // "john.doe@company.com"
177
```
178

179
### String Manipulation
180

181
#### Trim Function
182

183
Removes leading and trailing whitespace from a string.
184

185
```javascript { .api }
186
/**
187
 * Remove leading and trailing whitespace
188
 * @param str - String to trim
189
 * @returns Trimmed string
190
 */
191
function $trim(str);
192
```
193

194
**Usage Examples:**
195

196
```javascript
197
const result = await jsonata('$trim("  hello world  ")').evaluate({}); // "hello world"
198

199
// Clean user input
200
const form = { name: "  John Doe  ", email: "  john@example.com  " };
201
const cleaned = await jsonata("{ 'name': $trim(name), 'email': $trim(email) }").evaluate(form);
202
// { "name": "John Doe", "email": "john@example.com" }
203
```
204

205
#### Pad Function
206

207
Pads a string to a specified width with a character.
208

209
```javascript { .api }
210
/**
211
 * Pad string to specified width
212
 * @param str - String to pad
213
 * @param width - Target width (negative for left padding, positive for right)
214
 * @param char - Optional padding character (defaults to space)
215
 * @returns Padded string
216
 */
217
function $pad(str, width, char);
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
const result1 = await jsonata('$pad("hello", 10)').evaluate({}); // "hello     "
224
const result2 = await jsonata('$pad("hello", -10)').evaluate({}); // "     hello"
225
const result3 = await jsonata('$pad("42", -5, "0")').evaluate({}); // "00042"
226

227
// Format table columns
228
const data = { items: [{ id: 1, name: "Apple" }, { id: 123, name: "Banana" }] };
229
const formatted = await jsonata('items.($pad($string(id), -4, "0") & " | " & name)').evaluate(data);
230
// ["0001 | Apple", "0123 | Banana"]
231
```
232

233
### Pattern Matching and Processing
234

235
#### Split Function
236

237
Splits a string into an array using a separator.
238

239
```javascript { .api }
240
/**
241
 * Split string into array using separator
242
 * @param str - String to split
243
 * @param separator - Separator string or regex pattern
244
 * @param limit - Optional maximum number of splits
245
 * @returns Array of string parts
246
 */
247
function $split(str, separator, limit);
248
```
249

250
**Usage Examples:**
251

252
```javascript
253
const result1 = await jsonata('$split("apple,banana,cherry", ",")').evaluate({}); // ["apple", "banana", "cherry"]
254
const result2 = await jsonata('$split("one two three", " ", 2)').evaluate({}); // ["one", "two"]
255

256
// Parse CSV-like data
257
const csv = { line: "John,30,Manager,New York" };
258
const fields = await jsonata('$split(line, ",")').evaluate(csv); // ["John", "30", "Manager", "New York"]
259

260
// Split on multiple delimiters using regex
261
const text = { content: "apple;banana,cherry:grape" };
262
const fruits = await jsonata('$split(content, /[;,:]+/)').evaluate(text); // ["apple", "banana", "cherry", "grape"]
263
```
264

265
#### Join Function
266

267
Joins an array of strings into a single string using a separator.
268

269
```javascript { .api }
270
/**
271
 * Join array elements into string with separator
272
 * @param strs - Array of strings to join
273
 * @param separator - Optional separator string (defaults to empty string)
274
 * @returns Joined string
275
 */
276
function $join(strs, separator);
277
```
278

279
**Usage Examples:**
280

281
```javascript
282
const data = { words: ["hello", "world"] };
283
const result1 = await jsonata('$join(words, " ")').evaluate(data); // "hello world"
284
const result2 = await jsonata('$join(words, "-")').evaluate(data); // "hello-world"
285

286
// Create CSV line
287
const record = { fields: ["John Doe", "30", "Engineer"] };
288
const csv = await jsonata('$join(fields, ",")').evaluate(record); // "John Doe,30,Engineer"
289

290
// Build file path
291
const path = { parts: ["users", "documents", "file.txt"] };
292
const fullPath = await jsonata('$join(parts, "/")').evaluate(path); // "users/documents/file.txt"
293
```
294

295
#### Match Function
296

297
Matches a string against a regex pattern.
298

299
```javascript { .api }
300
/**
301
 * Match string against regex pattern
302
 * @param str - String to match against
303
 * @param pattern - Regex pattern
304
 * @param limit - Optional maximum number of matches
305
 * @returns Array of match objects or null if no matches
306
 */
307
function $match(str, pattern, limit);
308
```
309

310
**Usage Examples:**
311

312
```javascript
313
// Extract phone numbers
314
const text = { content: "Call me at 555-1234 or 555-5678" };
315
const phones = await jsonata('$match(content, /\\d{3}-\\d{4}/g)').evaluate(text);
316
// [{"match": "555-1234", "index": 11, "groups": []}, {"match": "555-5678", "index": 23, "groups": []}]
317

318
// Extract email addresses
319
const content = { text: "Contact john@example.com or mary@test.org" };
320
const emails = await jsonata('$match(text, /[\\w._%+-]+@[\\w.-]+\\.[A-Za-z]{2,}/g).match').evaluate(content);
321
// ["john@example.com", "mary@test.org"]
322
```
323

324
#### Contains Function
325

326
Tests if a string contains a pattern.
327

328
```javascript { .api }
329
/**
330
 * Test if string contains pattern
331
 * @param str - String to test
332
 * @param pattern - Pattern to search for (string or regex)
333
 * @returns Boolean indicating if pattern was found
334
 */
335
function $contains(str, pattern);
336
```
337

338
**Usage Examples:**
339

340
```javascript
341
const result1 = await jsonata('$contains("hello world", "world")').evaluate({}); // true
342
const result2 = await jsonata('$contains("hello world", "xyz")').evaluate({}); // false
343

344
// Filter array by content
345
const data = { emails: ["john@gmail.com", "mary@yahoo.com", "bob@company.com"] };
346
const gmailUsers = await jsonata('emails[$contains($, "gmail")]').evaluate(data); // ["john@gmail.com"]
347

348
// Case-insensitive search using regex
349
const text = { content: "Hello World" };
350
const hasHello = await jsonata('$contains(content, /hello/i)').evaluate(text); // true
351
```
352

353
#### Replace Function
354

355
Replaces occurrences of a pattern in a string with a replacement.
356

357
```javascript { .api }
358
/**
359
 * Replace pattern in string with replacement
360
 * @param str - Source string
361
 * @param pattern - Pattern to replace (string or regex)
362
 * @param replacement - Replacement string
363
 * @param limit - Optional maximum number of replacements
364
 * @returns String with replacements made
365
 */
366
function $replace(str, pattern, replacement, limit);
367
```
368

369
**Usage Examples:**
370

371
```javascript
372
const result1 = await jsonata('$replace("hello world", "world", "universe")').evaluate({}); // "hello universe"
373
const result2 = await jsonata('$replace("one two one", "one", "THREE", 1)').evaluate({}); // "THREE two one"
374

375
// Clean up whitespace
376
const text = { content: "hello    world   test" };
377
const cleaned = await jsonata('$replace(content, /\\s+/g, " ")').evaluate(text); // "hello world test"
378

379
// Mask sensitive data
380
const user = { ssn: "123-45-6789" };
381
const masked = await jsonata('$replace(ssn, /\\d(?=\\d{4})/g, "X")').evaluate(user); // "XXX-XX-6789"
382
```