Function implementation in String Builder
- Last UpdatedMay 21, 2025
- 5 minute read
- PI System
- PI Server 2024 R2
- PI Server
In String Builder, you can use several text manipulation functions, as well as the Format function.
Text extraction and case manipulation
You can use functions to manipulate the case of a string and to extract certain sections.
The syntax for text manipulation functions in String Builder is described in the following table:
|
Left(string, length) |
Returns a string that contains the specified number of characters (length) from the left of the input (string). Example: Left("Temperature",4) returns Temp |
|
Right(string, length) |
Returns a string that contains the specified number of characters (length) from the right of the input (string). Example: Right("GasTemp",4) returns Temp |
|
Mid(string, start, [length]) |
length is optional. Returns a sub-string from the specified position (start) of the input (string). When number of characters (length) is included, returns the specified number of characters. Example: Mid("GasPressure",4,8) returns Pressure |
|
UCase(string) |
Converts string to uppercase. Example: UCase("Temperature") returns TEMPERATURE |
|
LCase(string) |
Converts string to lowercase. Example: LCase("TEMPERATURE") returns temperature |
|
Trim(string) |
Removes blanks on both sides of string. Example: Trim(" Temperature ") returns Temperature |
|
RTrim(string) |
Removes trailing blanks from string. Example: RTrim(" Temperature ") returns " Temperature" |
|
LTrim(string) |
Removes leading blanks from string. Example: LTrim(" Temperature ") returns "Temperature " |
|
Replace(string1, string2, string3) |
The function searches string1 for string2, then replaces string2 with string3. Example: Replace("Temperature","Temp","External Temp") returns "External Temperature" |
You can also nest text manipulation functions.
-
For example, for an attribute named GasPressure, you can use the Mid function in combination with the UCase function to return the following expression: GASPR
Mid(UCase("%Attribute%"), 1, 5);
-
Alternatively, for the same attribute, you can use the Mid function in combination with the LCase function to return the following expression: pressure
Mid(LCase("%Attribute%"), 4, 8);
Beginning with PI AF 2018, you can nest functions in any position, not the first position only. In the following examples, all functions return the expression: a2c
Replace(Mid("abc",1,3),"b","2");
Replace("abc",Mid("abc",2,1),"2");
Replace("abc","b",Mid("123",2,1));
Format function
The Format function enables you to convert real numbers, integers, and time stamps to a string according to the format and optional culture specification.
Note: Unlike other string functions, the syntax of Format(DateTime, ... ) follows C# syntax.
The syntax for Function implementation in String Builder is described in the following table:
|
Real numbers |
Format(real, format) Format (real, format, culture) |
Format follows Performance Equation (PE) style syntax, such as "%0.3f", where the number before the decimal indicates the minimum total number of characters to output, pre-padding with blanks, and the number after the decimal indicates the number of digits to display after the decimal point. Culture is optionally specified using an Internet Engineering Task Force (IETF) language tag, such as "en", "en-US", "de", which specifies the language and optional culture and regions. |
|
Integer numbers |
Format(integer, format) Format(integer, format, culture) |
Format follows PE style syntax, such as "%4d", where the number indicates the minimum total number of characters to output, pre-padding with blanks as necessary. Culture is optionally specified using an IETF language tag, such as "en", "en-US", "de", which specifies the language and optional culture and regions. |
|
Time stamps |
Format(datetime, format) Format(datetime, format, culture) |
Format follows C# DateTime.ToString(format) syntax, and can be either a pre-defined syntax, or a custom syntax. DateTime format uses invariant culture settings. To display dates and times for a specific culture, add an IETF language tag, such as "fr-FR" and "fr-CA", as described in the MSDN article Table of Language Culture Names, Codes, and ISO Values Method. For more information on date and time formats, see Format strings for time substitution parameters. |
|
Arrays |
Format(array, delimiter) Format(array, delimiter, format) Format(array, delimiter, format, culture) |
Delimiter uses white space " " as the default delimiter, unless another delimiter character is specified. In addition, format and culture can optionally be specified, using the same syntax as real and integer numbers above. For example, the following String Builder data reference to an array (with values 11.12, 15.98, and 99.154) that specifies a "-" delimiter, a "%3.3.f", and a "Fr-fr" culture: Format('..\|TestArray',"-","%3.3f","Fr-fr"); produces a value of 11,120-15,980-99,154. |
|
New line |
NewLine() |
Ensures that a new line is displayed in the output value. For example, when a;Newline();b; is entered, the output value is displayed as: a b |
Numeric format example
Suppose you want to format the Environment PI point value that you have already retrieved
from the Cracking Process parent element. In the String Builder Data Reference window, you would select the row that contains the string expression, click 
and select Functions > Format(Real, "%3.3f") to modify the expression:
The Value field changes from 43.3071403505214 to 43.307.
To change the cultural value from the US default to a Spanish culture format, you would select Functions > Format(Real, "%3.3f", "en-US") and change the "en-US" string to "es":
The Value field changes from 43.307 to 43,307.
Note: Be sure the data type you specify matches the attribute data type. You would encounter errors, for example, if you specify "%3.2f" for an integer type attribute value or "%3d" for a floating point attribute value.
Date time format example
Suppose you want to retrieve and format the In Service Date value from the Condenser child element:
In the parent element Power and Steam Generation, you would create an attribute named Condenser Service Date. Use the syntax .\childElement|Attribute, and enter '.\Condenser|In Service Date' in the String Builder Data Reference window:
The In Service Date value is retrieved and displayed in the Value field: 2/25/2009 12:00:00 AM.
To change the format from the US default to Universal full date in German culture format, you would alter the expression to read Format(.\Condenser|In Service Date,"U","de"). The Condenser Service Date attribute value format is converted accordingly:
