# `string` Functions

Use `string` functions in rules to manipulate text strings in asset JSON at runtime.

For instance, a `string` function can replace all occurrences of one string with another or convert strings from uppercase to lowercase. If a user enters a dashboard title in the wizard using all lowercase letters, the `string` function changes the text to sentence case at runtime.

## `toUpperCase`

Parameters: `Object object`

Returns: `Object`

Recursive: Supported

Description: Converts all characters in an object to uppercase. The object can be a single string or a JSON object with multiple strings

### Example

This sample JSON:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "hello world",
    "greeting2" : "salut world",
    "greeting3" : "hallo world"
  },
  "list" : ["hello world", "salut world", "hallo world"]
}
```

And the rule:

```json
{
    "action": "set",
    "description": "Convert all strings to upper case",
    "path": "$.objecttest",
    "value" : "${string:toUpperCase(Rules.CurrentNode)}"
}
```

Returns:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "HELLO WORLD",
    "greeting2" : "SALUT WORLD",
    "greeting3" : "HALLO WORLD"
  },
  "list" : ["HELLO WORLD", "SALUT WORLD", "HALLO WORLD"]
}
```

## `toLowerCase`

Parameters: `Object object`

Returns: `Object`

Recursive: Supported

Description: Converts all characters in a string to lowercase.

### Example

This sample JSON:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "Hello World",
    "greeting2" : "Salut World",
    "greeting3" : "Hallo World"
  },
  "list" : ["Hello World", "Salut World", "Hallo World"]
}
```

And the rule:

```json
{
    "action": "set",
    "description": "Convert all strings to lower case",
    "path": "$.objecttest",
    "value" : "${string:toLowerCase(Rules.CurrentNode)}"
}
```

Returns:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "hello world",
    "greeting2" : "salut world",
    "greeting3" : "hallo world"
  },
  "list" : ["hello world", "salut world", "hallo world"]
}
```

## `replace`

Parameters: `Object object`, `String oldStr`, `String newStr`

Returns: `Object`

Recursive: Supported

Description: Returns a new object with all occurrences of `oldStr` replaced with `newStr`.

### Example

This sample JSON:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "Hello World"
  },
  "list" : ["Hello World"]
}
```

And the rule:

```json
{
    "action": "set",
    "description": "Replace all Hello instances with Goodbye",
    "path": "$.objecttest",
    "value" : "${string:replace(Rules.CurrentNode, 'Hello', 'Goodbye')}"
}
```

Returns:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "Goodbye World"
  },
  "list" : ["Goodbye World"]
}
```

## `replaceAll`

Parameters: `Object object`, `String regex`, `String newStr`

Returns: `Object`

Recursive: Supported

Description: Replaces all substrings of this string that match the given [regular expression](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#sum).

### Example

This sample JSON:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "Hello World"
  },
  "list" : ["Hello World"]
}
```

And the rule:

```json
{
    "action": "set",
    "description": "Replace all 'l' instances with 'L'",
    "path": "$.objecttest",
    "value" : "${string:replaceAll(Rules.CurrentNode, 'l.?', 'L')}"
}
```

Returns:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "HeLLo WorLd"
  },
  "list" : ["HeLLo WorLd"]
}
```

## `replaceFirst`

Parameters: `Object object`, `String regex`, `String newStr`

Returns: `Object`

Recursive: Supported

Description: Replaces the first substring of this string that matches the given [regular expression](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#sum).

### Example

This sample JSON:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "Hello World"
  },
  "list" : ["Hello World"]
}
```

And the rule:

```json
{
    "action": "set",
    "description": "Replace the first 'l' instance with 'L'",
    "path": "$.objecttest",
    "value" : "${string:replaceFirst(Rules.CurrentNode, 'l.?', 'L')}"
}
```

Returns:

```json
"objecttest" : {
  "obj" : {
    "greeting1" : "HeLlo World"
  },
  "list" : ["HeLlo World"]
}
```

## `split`

Parameters: `Object object`, `String regex`

Returns: `Object`

Recursive: Supported

Description: Parses a string and splits it into an array defined by the specified delimiter represented by the given [regular expression](https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html#sum).

### Example

This function call:

```
${string:split('one:two:three', ':')}
```

Results in array of strings:

```
['one','two','three']
```

## `match`

Parameters: `Object object`, `String regex`

Returns: `Object`

Recursive: Supported

Description: Performs complex regular expression matching and returns an array of matching results.

### Example

To capture items surrounded by square double quote and square brackets:

```json
{
  "match" : "${string:match('[\"foo\"][\"bar\"][\"baz\"]', '\\[\\\"(.*?)\\\"\\]')}"
}
```

Returns the following array:

```json
{
  "match" : "[\"foo\",\"bar\",\"baz\"]"
}
```

## `join`

Parameters: `Object object`, `String delimiter`

Returns: `Object`

Recursive: Supported

Description: Creates a string from an array of strings and separates each item by the specified delimiter.

### Example

This function call:

```
${string:join(['foo','bar','baz'], ':')}
```

Results in:

```
"foo:bar:baz"
```

## `qualifyNamespace`

Parameters: `String name`

Returns: `String`

Recursive: Not supported

Description: Adds a Salesforce namespace and the `__` delimiter to a given name if a namespace is available. If there is no namespace, the name is returned without alteration.

### Example

This sample JSON:

```json
{
    "fieldName" : "myName"
}
```

With:

```json
"${string:qualifyNamespace(Variables.fieldName)}"
```

Returns:

```json
{
    "fieldName" : "myNamespace__myName"
}
```

## `hash`

Parameters: `Object object`, `int length`

Returns: `Object`

Recursive: Supported

Description: Returns the hash value for the given string. Useful for determining Salesforce ID lengths and uniqueness. Uses the SHA-256 algorithm to determine the hash value.

### Example

This function call returns a truncated hash value:

```json
{
    "hash" : "${string:hash('00D000000000001EAA', 5)}"
}
```

Results in:

```json
{
    "hash" : "336d4"
}
```