X++ string runtime functions are built-in methods that let you manipulate, compare, and inspect text values at runtime in Dynamics 365 Finance and Operations (and older AX versions). They are called as methods on string variables or directly with a string argument, and they execute when the code runs, not at compile time.
What Are X++ String Runtime Functions?
In X++, strings are immutable objects of the System.String type (the .NET type), but the language provides a set of runtime functions that operate on them. These functions are part of the X++ standard library and are available in any class, form, or table method. They are distinct from the str intrinsic functions (like strLen or strScan) which are compiled directly; runtime functions are actual method calls that resolve at runtime.
Common runtime functions include subStr(), strFind(), strLwr(), strUpr(), trimStart(), trimEnd(), replace(), split(), and toUpper()/toLower(). They are called with dot notation, like myString.subStr(1, 5) or strFind(myString, "needle").
How Runtime Functions Differ from Intrinsic Functions
Intrinsic functions (e.g., strLen, strCmp) are compiled to inline code and are very fast, but they are limited to a fixed set of operations. Runtime functions are more flexible because they can be overridden or extended in derived classes, and they support method chaining. For example, you can write nameStr.trimStart().subStr(0, 10).toUpper() in a single expression. However, runtime calls are slightly slower due to method dispatch overhead, so for tight loops on large strings, intrinsic functions may be preferred.
Essential Runtime Functions and Their Syntax
Here are the most commonly used runtime string functions in X++ with examples:
subStr(int start, int length)– Extracts a substring starting at 1-based positionstartforlengthcharacters. Example:"Hello".subStr(2, 3)returns"ell".strFind(string str, string needle)– Returns the 1-based position of the first occurrence ofneedleinstr, or 0 if not found. Example:strFind("abc", "b")returns 2.strLwr()/strUpr()– Convert to lowercase/uppercase. Example:"Hello".strLwr()returns"hello".trimStart()/trimEnd()– Remove leading/trailing whitespace. Example:" x ".trimEnd()returns" x".replace(string old, string new)– Replaces all occurrences ofoldwithnew. Example:"a-b-c".replace("-", "_")returns"a_b_c".split(string delimiter)– Returns a container (or array) of substrings split bydelimiter. Example:"a,b,c".split(",")returns a container with 3 elements.
How to Use Them in Code: Examples
Suppose you have a customer name in a variable custName and you want to extract the first name (assuming space-separated). You could write:
str custName = "John Doe";
int spacePos = strFind(custName, " ");
if (spacePos > 0)
{
str firstName = custName.subStr(1, spacePos - 1);
info(firstName); // outputs "John"
}
Another example: cleaning a phone number by removing dashes and spaces:
str phone = "(555) 123-4567";
phone = phone.replace("(", "").replace(")", "").replace(" ", "").replace("-", "");
info(phone); // outputs "5551234567"
Note that replace() returns a new string; the original is unchanged because strings are immutable.
Common Pitfalls and Misconceptions
One frequent mistake is assuming strings are mutable. In X++, strings are immutable; any operation that seems to modify a string actually returns a new string. You must assign the result back to a variable if you want to keep it.
Another pitfall is off-by-one errors with subStr and strFind. Both use 1-based indexing, unlike .NET’s 0-based Substring. For example, "Hello".subStr(1, 1) returns "H", not "e".
Also, strFind returns 0 when the needle is not found, not -1 as in some languages. Always check for > 0 before using the position.
Performance and Best Practices
For simple operations on short strings, performance is rarely an issue. However, if you are processing thousands of records, avoid calling runtime functions inside loops if you can use intrinsic functions instead. For example, use strLen() instead of .Length (though .Length is a property, not a function, and it is fast). Use strCmp() for case-sensitive comparisons instead of .CompareTo().
When building large strings, avoid repeated concatenation with + because each concatenation creates a new string. Instead, use System.Text.StringBuilder if you are in a .NET interop context, or use the strFmt() function for formatting.
Alternatives and Related Functions
Besides runtime functions, X++ offers intrinsic functions like strLen, strCmp, strScan, and strNFind that are compiled inline. There is also the strFmt() function for formatted output, and the match() function for regular expressions (via .NET). For complex pattern matching, you can use the System.Text.RegularExpressions.Regex class through .NET interop.
If you need to work with arrays of strings, consider using a container or a List from the System.Collections.Generic namespace. The split() function returns a container, which you can iterate with a for loop.
Frequently Asked Questions
Is there a way to check if a string contains a substring?
Yes, use strFind(str, "sub") > 0 or the .NET method str.Contains("sub"). The latter is a runtime method on the string object, but it is case-sensitive. For case-insensitive, convert both to lower or upper first.
How do I split a string into a list of words?
Use split(" ") to get a container of words. For example, str words = "one two three"; container c = words.split(" "); then iterate with for (int i = 1; i <= conLen(c); i++) and conPeek(c, i).
Can I use regular expressions in X++?
Yes, by using .NET interop. For example, System.Text.RegularExpressions.Regex::IsMatch(str, pattern) returns a boolean. You need to reference the System.Text.RegularExpressions namespace.
Why does my string not change after calling replace()?
Because strings are immutable. The replace() function returns a new string with the replacements; you must assign it to a variable. For example, myStr = myStr.replace("a", "b");
What is the difference between strFind and strScan?
Both find a substring, but strScan is an intrinsic function that is faster and also supports a starting position parameter. strFind is a runtime function and always scans from the beginning. For most uses, strScan is preferred for performance.
How do I convert a string to an integer safely?
Use str2Int() which returns 0 if conversion fails, or System.Convert::ToInt32() which throws an exception on failure. For robust code, check with str2Int() and handle 0 as a possible invalid input.
Related
- C++ String Data Type: How std::string Works
- Snowflake Split String Into Columns: SQL Methods
- Snowflake SPLIT Syntax: Arrays, Examples, and Tips
Try it: the Formula Explainer: paste any formula and see each function and reference in plain English.
More in Formulas & functions
- Freeze Values in Excel Formulas: A Step-by-Step GuideTo stop a formula result changing, copy the formula cell or range and paste it back as values:…
- P Value in Excel: Formulas for Common Statistical TestsTo calculate a p value in Excel, choose a test that matches your data, then use its worksheet…
- Excel Combine Cells With Dates and Text: FormulasTo combine a date in A2 with text in B2, use =TEXT(A2,"mmmm d, yyyy")&" "&B2. If A2 contains…
- VLOOKUP Examples in Excel: Formulas That WorkVLOOKUP finds a value in the first column of a range and returns a value from another column…
- How to Find Standard Deviation in Excel With FormulasTo find standard deviation in Excel, enter =STDEV.S(B2:B9) for a sample or =STDEV.P(B2:B9) for an entire population, replacing…
- Excel Formula Not Calculating Until You Press Enter?If an Excel formula updates only after you press Enter, first check whether calculation is set to Automatic:…
Sources: Function behaviour and menu paths: Microsoft Support documentation for Excel. Method & sources
Spotted an error in this guide? Let us know.