CircleScript: Functions Reference
This article is a complete reference for all built-in CircleScript functions, organized by category. Functions follow the format [$functionName(args)], where args is a comma-delimited list of values. Arguments can be wrapped in double quotes.
| NOTE CircleScript functions are evaluated at content assembly time. Functions that fetch external content (dynamic_web_fetch, dynamic_title_web_fetch) make outbound HTTP requests at that point. Ensure referenced URLs are accessible at send time. |
In this article
- Data functions
- DateTime functions
- Logic functions
- Math functions
- String functions
Data functions
| Function | Syntax | Description |
| base64 | [$base64(arg)] | Base-64 encode a string using URL-safe characters. Useful for obfuscating link parameters. Same as base64_url. |
| base64_data | [$base64_data(arg)] | Base-64 encode a string using standard (non-URL-safe) characters. |
| base64_url | [$base64_url(arg)] | Base-64 encode a string with URL-safe characters. Useful for obfuscating link parameters. |
| dynamic_title_web_fetch | [$dynamic_title_web_fetch(URL, [regex], [groupId])] | Fetch content from a URL and extract a title. If regex and groupId are specified, returns the matched group. Otherwise extracts <title> tag contents, or the full response if no title tag is found. URL must start with http:// or https://. |
| dynamic_web_fetch | [$dynamic_web_fetch(URL)] | Fetch and return the full content from a given URL. URL must start with http:// or https://. |
| money | [$money(decimal_value, [format])] | Format a decimal value as currency. Defaults to $1,234.50 format. To round to the nearest dollar, pass "%1$,.0f" as the format argument. |
| sha1 | [$sha1(arg)] | Return a SHA1 40 hex-character digest of the input string. |
| sha256 | [$sha256(arg)] | Return a SHA256 64 hex-character digest of the input string. |
| urlencode | [$urlencode(arg)] | URL-encode a string. Useful for encoding link parameters that may contain special characters. |
| urlencode2 | [$urlencode2(arg)] | URL-encode a string twice. Use when a parameter will itself be used inside another URL. |
DateTime functions
| Function | Syntax | Description |
| currentdate | [$currentdate([format_string])] | Write the current date using the given format string. Defaults to MM/dd/yyyy if no format is specified. |
| dateadd | [$dateadd(part, count, [date])] | Add a quantity to a date. part can be minute, hour, day, month, or year. date is optional — current time is used by default. |
| datediff | [$datediff(part, startDate, [endDate])] | Return the difference between two dates. part can be minute, hour, day, month, or year. endDate is optional — current time is used by default. |
| datepart | [$datepart(part, [date])] | Extract a specific part of a date. part can be minute, hour, day, dayofweek, dayofyear, month, or year. date is optional — current time is used by default. |
| formatdate | [$formatdate(date, [format_string])] | Format a date value using the given format string. Defaults to MM/dd/yyyy if no format is specified. |
| parsedate | [$parsedate(date_string, parse_format, [render_format])] | Parse a date string using the given format. Outputs with a custom render format, or sortable date down to the minute by default. |
Logic functions
Logic functions write alternate content based on comparisons. For all logic functions: if on_equal is not specified, "true" is used. If otherwise is not specified, blank is used.
| Function | Syntax | Description |
| contains | [$contains(value, substring, [on_equal], [otherwise])] | Write alternate content based on whether one string contains another. Example: [$contains([-domain-],yahoo,[$/legal/yahoo])] |
| ends_with | [$ends_with(value, suffix, [on_equal], [otherwise])] | Write alternate content based on whether a string ends with a given suffix. Example: [$ends_with([-time-],AM,morning,evening)] |
| greater_than / gt | [$greater_than(lhs, rhs, [on_equal], [otherwise])] [$gt(lhs, rhs, [on_equal], [otherwise])] | Write alternate content based on whether one integer is greater than another. Example: [$gt([-points-],10000,[$/message/high-points])] |
| greater_than_or_equal / gteq | [$greater_than_or_equal(lhs, rhs, [on_equal], [otherwise])] [$gteq(lhs, rhs, [on_equal], [otherwise])] | Write alternate content based on whether one integer is greater than or equal to another. |
| if_equal | [$if_equal(lhs, rhs, [on_equal], [otherwise])] | Write alternate content based on string equality. Example: [$if_equal([-domain-],yahoo.com,[$/messages/yahoo],[$/messages/default])] |
| less_than / lt | [$less_than(lhs, rhs, [on_equal], [otherwise])] [$lt(lhs, rhs, [on_equal], [otherwise])] | Write alternate content based on whether one integer is less than another. Example: [$lt([-points-],10000,[$/message/low-points])] |
| less_than_or_equal / lteq | [$less_than_or_equal(lhs, rhs, [on_equal], [otherwise])] [$lteq(lhs, rhs, [on_equal], [otherwise])] | Write alternate content based on whether one integer is less than or equal to another. |
| starts_with | [$starts_with(value, prefix, [on_equal], [otherwise])] | Write alternate content based on whether a string starts with a given prefix. Example: [$starts_with([-code-],XP-,[$/message/xp-message],[$/message/default-message])] |
| shuffle | [$shuffle(arg)] | Randomly shuffle the elements of the input. |
Math functions
| Function | Syntax | Description |
| calc | [$calc(arg)] | Calculate the result of a mathematical expression. |
| ceiling | [$ceiling(arg)] | Return the smallest integer value greater than or equal to the given argument. |
| divide | [$divide(n1, n2, ...)] | Divide the arguments in order. |
| floor | [$floor(arg)] | Return the largest integer value less than or equal to the given argument. |
| mod | [$mod(n1, n2)] | Perform a modulus operation over the arguments. |
| multiply | [$multiply(n1, n2, ...)] | Multiply the given arguments. Works for integer and decimal values. Returns blank if any argument is blank or not a valid number. |
| random | [$random([range1, [range2]])] | Return a random number. [$random()] returns a random long. [$random(limit)] returns a number between 0 and limit. [$random(origin,limit)] returns a number between origin and limit. Returns a long or float depending on the type of arguments. |
| round | [$round(arg)] | Return the nearest integer to the given argument, rounding up on .5 values. |
| sum | [$sum(n1, n2, ...)] | Sum the given arguments. |
String functions
| Function | Syntax | Description |
| escapehtml | [$escapehtml(arg)] | Escape HTML characters in a string. Example: [$escapehtml(<name>)] → <name> |
| indexof | [$indexof(str, substring)] | Return the character position of a substring within a string, or -1 if not found. |
| left_pad | [$left_pad(str, length, fill)] | Return a string of the specified length, padded on the left with the fill pattern. |
| lower | [$lower(str)] | Convert a string to lowercase. |
| remove_param | [$remove_param(url, param_name)] | Remove a named parameter from a valid URL. Parameter names are case-sensitive. |
| replace | [$replace(str, pattern, [replacement])] | Return a copy of the string with the given pattern replaced. If replacement is omitted, the pattern is removed. |
| right_pad | [$right_pad(str, length, [fill])] | Return a string of the specified length, padded on the right with the fill pattern. |
| substring | [$substring(str, start, [stop])] | Return a substring starting at the specified index, up to but not including the optional stop index. |
| title | [$title(arg)] | Title Case a string — capitalizes the first letter of each word. |
| title_case | [$title_case(arg)] | Convert a string to lowercase and then capitalize the first letter of each word. |
| truncate | [$truncate(content, maxLength)] | Truncate a value to the given length. If truncated, the result ends with an ellipsis (…). |
| unescapehtml | [$unescapehtml(arg)] | Un-escape HTML characters in a string. Example: [$unescapehtml(<name>)] → <name> |
| upper | [$upper(str)] | Convert a string to uppercase. |