Hi, Readers.
Yesterday we discussed the dates calculation in Business Central. For more information, see Dynamics 365 Business Central: How to use Date and Time Functions (Get Today, Yesterday, Tomorrow, First and Last day of the month…)
In this post, I would like to summarize the String Functions for Business Central. Hope this will help. (Some samples from Microsoft DOCS)
Let’s go.
ConvertStr Method
ConvertStr Method: Replaces all chars in source found in FromCharacters with the corresponding char in ToCharacters and returns the converted string. If the length of the FromCharacters parameter and the ToChars parameter are different, an exception is thrown. If the parameter FromCharacters or the parameter ToChars is empty, the source is returned unmodified. Each element in source is only converted ONCE a double-replacement cannot happen.
NewString := Text.ConvertStr(String: String, FromCharacters: String, ToCharacters: String)
Example:
The message window displays the following text:
Remark:
The characters in the FromCharacters parameter are replaced by the characters in the ToCharacters parameter.
If the lengths of the FromCharacters and ToCharacters strings are not equal, then a run-time error occurs.
If either the FromCharacters or the ToCharacters strings are empty, then the source is returned unchanged.
CopyStr Method
CopyStr Method: Copies a substring of any length from a specific position in a string (text or code) to a new string.
NewString := Text.CopyStr(String: String, Position: Integer [, Length: Integer])
Example:
The message window displays the following text:
Remark:
If Position combined with Length exceeds the length of the string, all the characters from Position to the end of the string are returned.
DelChr Method
DelChr Method: Deletes chars contained in the which parameter in a string based on the contents on the where parameter. If the where parameter contains an equal-sign, then all occurrences of characters in which is deleted from the current value. If the where parameter contains a less-than, then the characters are only deleted when they are first in the string. If the where parameter contains a greater-than, then the characters are only deleted when they are the last in the string. If the where parameter contains any other char, an exception is thrown. If the where parameter or the which parameter is empty, the source is returned unmodified. The which parameter is to be considered as an array of chars to delete where the order does not matter.
NewString := Text.DelChr(String: String [, Where: String] [, Which: String])
Example01: The method deletes every W and s that is either the first or last character in String.
The message window displays the following text:
Example02: The method deletes every s and x from String.
The message window displays the following text:
Example03: If T, e, l, or y is the last character in String, the method deletes them.
The message window displays the following text:
Example04: If T, h, s, i, or space is the first character in String, the method deletes them.
The message window displays the following text:
Example05: The method removes any spaces from the start of String.
The message window displays the following:
Example06: The method removes all spaces.
The message window displays the following:
Remark:
The DELCHR method is case-sensitive.
If you omit the Which parameter, then the method deletes spaces from String based on the contents of the Where parameter as follows:
- If Where contains =, then all the spaces are deleted from String.
- If Where contains <, then all the spaces at the start of String are deleted.
- If Where contains >, then all the spaces at the end of String are deleted.
- If Where contains any other character, then an error is returned.
- If Where is empty, then String is returned unchanged.
If you use the Where and the Which parameters, then the method deletes from String the characters that are contained in the Which parameter based on the contents of the Where parameter as follows:
- If Where contains =, then every occurrence of the characters in Which are deleted from String.
- If Where contains <, then the characters in Which are only deleted if they occur at the start of String.
- If Where contains >, then the characters in Which are deleted only if they occur at the end of String.
- If Where contains any other character, then an error is returned.
- If Where is empty, then String is returned unchanged.
- If Which is empty, then String is returned unchanged.
The Which parameter contains an array of the characters that you want to delete. The order of the characters is of no significance. If String contains a character that is specified in Which, it is deleted from String.
DelStr Method
DelStr Method: Deletes a substring inside a string (text or code).
NewString := Text.DelStr(String: String, Position: Integer [, Length: Integer])
Example:
The message window displays the following:
Remark:
If you omit Length, all the characters starting with Position are deleted until the end of the string.
If you omit Length and Position is less than 1, then an error is returned.
If you omit Length and Position is greater than the length of String, then String is returned unchanged.
IncStr Method
IncStr Method: Increases a positive number or decrease a negative number inside a string by one (1).
NewString := Text.IncStr(String: String)
Example:
The message window displays the following:
Remark:
If String contains more than one number, then only the number closest to the end of the string is changed. For example, ‘A10B20’ is changed to ‘A10B21’ and ‘a12b12c’ to ‘a12b13c’.
If String contains a negative number, then it is decreased by one. For example, ‘-55’ is changed to ‘-56’.
Zero (0) is considered a positive number. Therefore, it is increased it by one. For example, ‘A0’ is changed to ‘A1’.
When String contains a number such as 99, it is increased to 100 and the length of the output string is: LEN(String) + 1. For example, ‘a12b99c’ is changed to ‘a12b100c’.
If String does not contain any number, the output string is an empty string. For example, ‘aaa’ is changed to ”.
INCSTR only increments integer numbers within strings, not decimals. For example, if you call INCSTR on the string a99.99b then the result is a99.100b.
InsStr Method
InsStr Method: Inserts a substring into a string.
NewString := Text.InsStr(String: String, SubString: String, Position: Integer)
Example:
The message window displays the following:
Remarks:
If SubString is empty, then String is returned unchanged.
If Position is less than 1, an error is returned.
If Position is greater than the length of String, SubString is added at the end of String. For example, INSSTR("Thomas","AAA",999) returns ‘ThomasAAA’.
LowerCase Method
LowerCase Method: Converts all letters in a string to lowercase.
NewString := Text.LowerCase(String: String)
Example:
The message window displays the following:
UpperCase Method
UpperCase Method: Converts all letters in a string to uppercase.
NewString := Text.UpperCase(String: String)
Example:
The message window displays the following:
MaxStrLen Method
MaxStrLen Method: Gets the maximum defined length of a variant variable. Calling this method always results in a run-time exception.
MaxLength := Text.MaxStrLen(Variant: Variant)
Example:
The message window displays the following:
Remark:
If you call this method on a Variant, it returns an error.
StrLen Method
StrLen Method: Gets the length of a string you define.
Length := Text.StrLen(String: String)
Example:
The message window displays the following:
Remark:
The difference between the STRLEN method and the MAXSTRLEN Method is that the STRLEN returns the actual number of characters in the input string, whereas MAXSTRLEN returns the maximum defined length of the input string.
In Dynamics 365 Business Central, if you call STRLEN on a Variant, then you get an error that the contents of the parameter are not valid. In earlier versions of Dynamics 365, if you call STRLEN on a Variant, then 0 is returned.
PadStr Method
PadStr Method: Changes the length of a string to a specified length. If the string is shorter than the specified length, length spaces are added at the end of the string to match the length. If the string is longer than the specified length, the string is truncated. If the specified length is less than 0, an exception is thrown.
NewString := Text.PadStr(String: String, Length: Integer [, FillCharacter: String])
Example:
The message window displays the following:
Remark:
If you omit FillCharacter and String is shorter than Length, then spaces are added at the end of String to match Length.
If you omit FillCharacter and String is longer than Length, then String is truncated.
SelectStr Method
SelectStr Method: Retrieves a substring from a comma-separated string.
NewString := Text.SelectStr(Number: Integer, CommaString: String)
Example:
The message window displays the following:
Remark:
SELECTSTR treats string values as OPTIONS. This means that identical values in different strings are not allowed.
Any trailing commas are removed before the operation starts.
If Number is less than 1 or greater than the number of real values (excluding trailing commas) in the string, then an error is returned.
Quotes are not supported. For example, a,b,”c,d”,e is treated as a five-element substring where substring 4 is d”.
StrPos Method
StrPos Method: Searches for the first occurrence of substring inside a string.
Position := Text.StrPos(String: String, SubString: String)
Example01:
The message window displays the following:
Example02:
The message window displays the following:
Remark:
The STRPOS method returns the position of the first occurrence of the substring.
If SubString cannot be found, then the method returns zero.
If String or SubString is empty, then the method returns zero.
StrSubstNo Method
StrSubstNo Method: Replaces %1, %2, %3… and #1, #2, #3… fields in a string with the values you provide as optional parameters. For example, StrSubstNo(‘Test %1 %3 %1’, 555, 666, 777) returns “Test 555 777 555”.
NewString := Text.StrSubstNo(String: String [, Value1: Any,…])
Example:
The message window displays the following:
StrCheckSum Method
StrCheckSum Method: Calculates a checksum for a string that contains a number. If the source is empty, 0 is returned. Each char in the source and in the weight must be a numeric character 0-9, otherwise an exception is thrown. If the WeightString parameter is shorter then the source, it is padded with ‘1’ up until the length of source. If the WeightString parameter is longer than the source, an exception is thrown.
CheckNumber := Text.StrCheckSum(String: String [, WeightString: String] [, Modulus: Integer])
Example: This example shows how to use the STRCHECKSUM method to calculate a checksum.
The formula is: (7 – (4×1 + 3×2 + 7×3 + 8×4) MOD 7) MOD 7=0
The message window displays the following:
Format Method
Format Method: Formats a value into a string.
String := System.Format(Value: Any, Length: Integer, FormatString: String)
Example01:
The Regional and Language settings on the computer on which you run the code affect how the string is displayed. For example, on a computer that has the regional format set to English (United States), the message window displays the following:
Example02:
The message window displays the following:
Remark:
For the Length parameter, the following rules apply:
- If Length = 0 then the entire value is returned (default).
- If Length > 0 then the returned string will be exactly Length characters.If Value is less than Length characters, then either leading or trailing spaces are inserted, depending on the format that you select.If Value exceeds Length characters, then String is truncated to Length characters.
- If Length < 0 then the returned string will not have leading or trailing spaces.If Value is less than Length characters, the length of String will equal the length of Value.If Value exceeds Length characters, then String is truncated to Length characters.
For the Format parameter, see Format Property for more information.
The FormatNumber parameter specifies the format that you want to use. The basic options for the Decimal data type are as follows:
- <Sign><Integer Thousand><Decimals> is Format 0
- <Sign><Integer><Decimals> is Format 1
- <Sign><Integer><Decimals><Comma,.> is Format 2
- <Integer Thousand><Decimals><Sign,1> is Format 3
- <Integer><Decimals><Sign,1> is Format 4
Evaluate Method
Evaluate Method: Evaluates a string representation of a value into its typical representation. The result is assigned to a variable.
[Ok := ] System.Evaluate(var Variable: Any, String: String [, Number: Integer])
Example: This example shows how to use the EVALUATE method when it is called with four different types of variables.
The message window displays the following:
END
The following post is an example of what can be created using the above methods. Hope it can be a reference.
Dynamics 365 Business Central: How to prevent users from entering special characters inside an input field
Hope this will help.
Thanks for your reading.
ZHU
コメント