String

The String operation applies a single transformation to a string value. It supports trimming, casing, replacement, truncation, and substring extraction with UTF-8-safe behaviour.

Replace with an empty Find changes nothing, and the Editor marks the Find field with a warning until it is filled.

Inputs

Port	Type	Required	Description
In	String or Binary	Yes	The value to transform. Binary must be valid UTF-8; non-UTF-8 bytes or any other type fail the Node, and its On Error verb resolves the failure.

Outputs

Port	Type	Default	Description
Out	String	""	The transformed string result.

Properties

Name	Type	Default	Description
Operation Type	StackedDataSet	Trim	The transformation to apply:
Trim			Removes leading/trailing ASCII whitespace.
Uppercase			Unicode-aware uppercase conversion.
Lowercase			Unicode-aware lowercase conversion.
Capitalize			Uppercases the first non-whitespace character.
Replace			Replaces all occurrences of a substring:
Find	String	""	Substring to find. Empty = no-op.
Replace with	String	""	Replacement string.
Case Insensitive	Boolean	false	Match regardless of letter case (Unicode-aware).
Truncate			Limits string length:
Length	Integer	20	Maximum output length.
Suffix	String	"..."	Appended only when truncation occurs.
Length is in bytes	Boolean	false	Measure in bytes instead of grapheme clusters.
Count suffix in total length	Boolean	false	When on, suffix must fit within Length.
Substring			Extracts a portion of the string:
Start	Integer	1	1-based, inclusive start position.
Length	Integer	20	Number of units to extract.
Length is in bytes	Boolean	false	Measure in bytes instead of grapheme clusters.
On Error	Combo	Stop this branch	Per-op On Error verb (Stop this branch / Continue with the last value / Continue with the fallback). See the Error Handling guide.

State on Reload

Output is preserved across restarts within the configured time window.

---

Input Conversion

• String values are used directly.
• Binary data is interpreted as UTF-8 if valid.
• Non-UTF-8 Binary (or any other type that slips past the port mask) invokes the On Error verb.

---

How It Works

1. Receive input — The operation receives In.

2. Validate — If the input is unconnected, Nil, non-UTF-8 Binary, or any type the port mask should have rejected, the On Error verb is applied.

3. Transform — The selected transformation is applied with its configuration.

4. Output — The resulting string is emitted on Out.

---

Examples

Data format

All inputs and outputs use MessagePack internally. The examples below show values in JSON notation for readability.

Trim

Operation Type: Trim   In: " alice "

Out: "alice"

Capitalize

Operation Type: Capitalize   In: " alice "

Out: " Alice "

Uppercase

Operation Type: Uppercase   In: " alice "

Out: " ALICE "

Replace

Operation Type: Replace   Find: "Bob"   Replace with: "Charlie"   In: "Hello, Bob!"

Out: "Hello, Charlie!"

Replace (case-insensitive)

Operation Type: Replace   Find: "error"   Replace with: "warning"   Case Insensitive: true   In: "ERROR: disk full"

Out: "warning: disk full" — matching is case-insensitive but non-matched text preserves its original casing.

Truncate

Operation Type: Truncate   Length: 20   Suffix: "..."   Count suffix in total length: false

In: "This is a very long sentence that needs truncation."

Out: "This is a very long ..." (suffix appended on top of the 20-character content)

With Count suffix in total length = true: Out: "This is a very lo..." (suffix fits inside 20)

Substring

Operation Type: Substring   Start: 2   Length: 3   Length is in bytes: false

In: "abcde" (Cyrillic example: "abcde")

Out: characters 2 through 4 of the input.

---

Additional Notes

• Whitespace for Trim: Only ASCII whitespace is trimmed (space, \t, \f, \v, \n, \r).
• UTF-8 safety: All operations ensure no partial UTF-8 code points are produced.
• Character semantics: Character-based counting uses Unicode grapheme clusters.
• Case-insensitive Replace: Uses ICU Unicode-aware case conversion for matching. Non-matched text preserves its original casing.
• Substring indexing: Uses 1-based start index, inclusive.
• Suffix behaviour: Appended only when truncation occurs. If the suffix alone would exceed Length (with Count suffix in total length on), the suffix is omitted.

---

Use Cases

• Cleaning and normalising string data from sensors or user input.
• Extracting substrings or truncating long values for display.
• Performing find-and-replace transformations in data pipelines.

---

Error Handling

String can hit these errors: an unconnected input, a Nil or non-UTF-8 Binary value on the input.

Any of these triggers the On Error verb you picked. See the Error Handling guide for the common On Error model; String’s options are:

Verb	What it does
Stop this branch (default)	This Node and its dependents stop; Out keeps its value and reads as a failed update.
Continue with the last value	Dependents run on the value Out already holds, not stamped as new; it reads as a failed update.
Continue with the fallback	Dependents run on Out’s per-output Fallback, stamped as this run’s value; it reads as a failed update. The Editor refuses a Task where the Fallback is unset.

For String, configure the per-output Fallback in Settings (under the Out port) with type String and the literal default value (e.g. "" or "N/A"); Continue with the fallback then emits that string on any error.

---

Limitations

• Only one transformation can be applied per operation; chain multiple String nodes for complex processing.
• Trim handles ASCII whitespace only; full Unicode whitespace requires upstream handling.