Strings and Regular Expressions

This page covers string literals, string methods, regular expressions, and the encoding and hash helpers of DG Script.

Topics on this page:

String literals and escapes
Joining strings and converting values to strings
String methods
Regular expressions
Encoding and hash helpers
parseUrl

You can quote a string with single or double quotes. A string must end on the same line it starts on.

str1 = 'Single quotes';
str2 = "Double quotes";
str3 = 'Double quotes in "single" quotes';
str4 = "Single quotes in 'double' quotes";
str5 = "escape quote \"";

A backslash (\) starts an escape sequence:

Sequence	Result
`\n`	New line
`\r`	Carriage return
`\t`	Tab
`\b`	Backspace
`\f`	Form feed
`\uXXXX`	The Unicode character with hex code `XXXX` (exactly four hex digits)
`\` `\"` `\\`	A single quote, double quote, or backslash
backslash at the end of a line	The line continues; the line break is removed
`\` followed by any other character	That character. For example `\x41` gives `x41` and `\0` gives `0`

For example, the following code sets the string block's value to C:\:

@parent.string.value = "C:\\";

Template literals (backticks) are not supported. Build strings with + instead.

When the left side of + is a string, the right side is converted to a string and appended. null is appended as an empty string, and lists and maps are appended as JSON.

When the left side is a number, the right side is converted to a number. So 1 + "2" is 3 and 1 + "a" is NaN. To build a string that starts with a number, start with an empty string: "" + 1 + "2".

print("a" + 1, "\n");
print("a" + null, "\n");
print("list: " + [1, 2], "\n");
print(1 + "2", "\n");
return "" + 1 + "2";

Print output:

a1
a
list: [1,2]
3

Output: 12

String(value) converts a value to a string. String(null) is an empty string. Lists and maps become JSON, and a DateTime becomes an ISO 8601 string.

String(number, radix) converts a number to a string in the given base (radix must be an integer from 2 to 36).

print(String(123), "\n");
print(String({"a": 1}), "\n");
return String(27, 16);

Print output:

123
{"a":1}

Output: 1b

Call a method on any string value, for example "abc".toUpperCase(). Positions start at 0.

Strings cannot be indexed with brackets. "abc"[1] does not return b; use charAt(1).
A position outside the string causes an error (for example "abc".charAt(5) or "abc".substring(2, 9)).
These JavaScript methods do not exist: startsWith, endsWith, includes, padStart, padEnd, repeat, search, concat, localeCompare. Use indexOf or a regular expression instead.

Method	Returns
`str.length`	The number of characters (a property, not a method)
`str.charAt(pos)`	The character at `pos`
`str.charCodeAt(pos)`	The UTF-16 code of the character at `pos`
`str.indexOf(search)`	Position of the first occurrence of `search`, or -1. There is no start-position argument
`str.lastIndexOf(search)`	Position of the last occurrence of `search`, or -1
`str.substring(start, end)`	Characters from `start` up to (not including) `end`. Negative values count from the end. `end` is optional. Same as `subString` and `slice`
`str.substr(start, length)`	`length` characters from `start`. `length` is optional. Same as `subStr`. Negative values are not supported
`str.split(separator, removeEmpty)`	A list of parts. `separator` is a string or regular expression. When `removeEmpty` is `true`, empty parts are removed
`str.replace(find, replacement)`	Replaces the first match of `find` (string or regular expression). A regular expression with the `g` flag replaces all matches
`str.replaceAll(find, replacement)`	Replaces all matches of `find` (string or regular expression)
`str.replaceAllMapped(regex, function)`	Replaces all matches with the return value of `function`. See Regular expressions
`str.match(regex)`	See Regular expressions
`str.matchAll(regex)`	See Regular expressions
`str.toLowerCase()`, `str.toUpperCase()`	The string in lower or upper case
`str.trim()`, `str.trimLeft()`, `str.trimRight()`	The string without whitespace at both ends, the start, or the end
`str.encodeUriComponent()`, `str.decodeUriComponent()`	See Encoding
`str.encodeBase64()`, `str.decodeBase64()`	See Encoding
`str.encodeCamelCase()`, `str.decodeCamelCase()`	See Encoding
`str.splitQuery()`	See Encoding
`str.md5()`, `str.sha1()`, `str.sha256()`	See Hashes

The replacement text in replace and replaceAll is used literally. $1 and $& are not replaced by captured groups; use replaceAllMapped for that.

Examples

s = "  Hello, World  ".trim();
print(s.length, "\n");
print(s.charAt(1), "\n");
print(s.charCodeAt(0), "\n");
print(s.indexOf("o"), " ", s.lastIndexOf("o"), "\n");
print(s.substring(7), "\n");
print(s.substring(0, -7), "\n");
print(s.substr(7, 3), "\n");
print(s.toUpperCase(), "\n");
return s.replace("l", "L") + " / " + s.replaceAll("l", "L");

Print output:

12
e
72
4 8
World
Hello
Wor
HELLO, WORLD

Output: HeLlo, World / HeLLo, WorLd

Splitting:

print("1,2,3".split(","), "\n");
print("a,,b,".split(",").length, "\n");
print("a,,b,".split(",", true), "\n");
return "a1b22c".split(/\d+/);

Print output:

[1, 2, 3]
4
[a, b]

Output: [a, b, c]

Write a regular expression as a literal: /pattern/flags. The pattern uses the browser's regular expression syntax. Supported flags:

i — ignore case
m — multi-line: ^ and $ match at line breaks
g — global: affects replace and match

There is no new RegExp(…) constructor, so a pattern cannot be built from a string at run time. Regular expressions have no lastIndex state.

Method	Returns
`regex.test(str)`	`true` if `str` contains a match
`regex.exec(str)`	A list with the whole first match followed by the captured groups, or `null` if nothing matches
`str.match(regex)`	Without `g`: the first matched string (not a list as in JavaScript), or `null`. With `g`: a list of all matched strings, or `null`
`str.matchAll(regex)`	A list of all matched strings (empty list if none). Groups are not included
`str.replace(regex, text)`	Replaces the first match, or all matches with `g`
`str.replaceAll(regex, text)`	Replaces all matches
`str.replaceAllMapped(regex, function)`	Calls `function(m)` for each match, where `m` is a list `[wholeMatch, group1, group2, …]`, and replaces the match with the returned string
`str.split(regex)`	Splits at every match

print(/^ab/i.test("ABC"), "\n");
print(/(\w+)@(\w+)\.com/.exec("mail joe@site.com now"), "\n");
print("a1b22c333".match(/\d+/), "\n");
print("a1b22c333".match(/\d+/g), "\n");
print("abc".match(/\d+/g), "\n");
print("DabcG DdefG".replace(/D(\w+)/g, "d"), "\n");
return "2024-01-05".replaceAllMapped(/(\d+)-(\d+)-(\d+)/, function (m) {
  return m[3] + "/" + m[2] + "/" + m[1];
});

Print output:

true
[joe@site.com, joe, site]
1
[1, 22, 333]
null
d d

Output: 05/01/2024

Function	Returns
`str.encodeUriComponent()`	The string with URL-unsafe characters percent-encoded (space becomes `%20`)
`str.decodeUriComponent()`	The decoded string
`str.splitQuery()`	A map of the decoded name/value pairs of a URL query string such as `a=1&b=2`
`str.encodeBase64()`	The UTF-8 bytes of the string, encoded as Base64
`str.decodeBase64()`	The decoded UTF-8 string
`str.decodeBase64(true)`	The decoded bytes as a list of numbers
`list.encodeBase64()`	A list of byte values (0–255) encoded as Base64
`str.encodeCamelCase()`	A camel-case name: characters other than letters, digits, `_`, `-` and space are removed, leading digits and underscores are removed, the text is lower-cased, and each letter after a space or hyphen (or a letter after a digit) is upper-cased
`str.decodeCamelCase()`	Each upper-case letter is replaced with a space and the lower-case letter
`str.md5()`	The MD5 hash of the UTF-8 bytes, as 32 hex characters
`str.sha1()`	The SHA-1 hash, as 40 hex characters
`str.sha256()`	The SHA-256 hash, as 64 hex characters
`sha1Hmac(key, message)`	The HMAC-SHA1 of `message` with `key`, encoded as Base64
`sha256Hmac(key, message)`	The HMAC-SHA256 of `message` with `key`, encoded as Base64

print("a b&c".encodeUriComponent(), "\n");
print("a%20b".decodeUriComponent(), "\n");
q = "a%20b=1&c=d".splitQuery();
print(q["a b"], " ", q.c, "\n");
print("abc123".encodeBase64(), "\n");
print("YWJjMTIz".decodeBase64(), "\n");
print("YWJj".decodeBase64(true), "\n");
print([104, 105].encodeBase64(), "\n");
print("Hello World 2nd".encodeCamelCase(), "\n");
print("helloWorld".decodeCamelCase(), "\n");
print("abc123".md5(), "\n");
print("abc123".sha1(), "\n");
print(sha1Hmac("key", "message"), "\n");
return "abc123".sha256();

Print output:

a%20b%26c
a b
1 d
YWJjMTIz
abc123
[97, 98, 99]
aGk=
helloWorld2Nd
hello world
e99a18c428cb38d5f260853678922e03
6367c48dd193d56ea7b0baad25b19455e529f5ee
IIjfdNXyFGtIFGyvSWU3fp0L46Q=

Output: 6ca13d52ca70c883e0f0bb101e425a89e8624de51db2d2392593af6a84118090

parseUrl(url) splits a URL into its parts. It returns a map with the keys scheme, host, path, port, fragment, query and queryParameters (a map of decoded query values), or null if the URL cannot be parsed. When the URL has no port, port is the default port of the scheme (80 for http, 443 for https).

u = parseUrl("https://example.com:8080/a/b?x=1&y=two#top");
print(u.scheme, " ", u.host, " ", u.port, "\n");
print(u.path, " ", u.query, " ", u.fragment, "\n");
return u.queryParameters.y;

Print output:

https example.com 8080
/a/b x=1&y=two top

Output: two

Strings and Regular Expressions

String Literals and Escapes

Joining Strings and Converting Values

String(value)

String Methods

Examples

Regular Expressions

Encoding and Hash Helpers

parseUrl(url)

DGLogik