Microsoft Dynamics NAV String Function

CONVERTSTR Function (STRING)

CONVERTSTR Function is used to converts some characters in a string.

NewString := CONVERTSTR(String, FromCharacters, ToCharacters) ·         The characters in the FromCharacters parameter are replaced by the characters in the ToCharacters parameter. ·         A run-time error occurs if the lengths of the FromCharacters and ToCharacters strings are not equal. ·         If either the FromCharacters or the ToCharacters strings are empty the source is returned unchanged.

Example

OriginalString     :=            'Want to leave without saving?'

FromChars          :=           ‘lws’

ToChars                :=            ‘LWS’

NewString := CONVERTSTR(OriginalString, FromChars, ToChars);

MESSAGE (OriginalString);           ->     Want to leave without saving?

MESSAGE(NewString);                  ->    Want to Leave Without Saving?

COPYSTR Function (STRING)

COPYSTR function is used to copies a substring of any length from a specific position in a string (text or code) to a new string.

NewString := COPYSTR(String, Position [, Length])

·         If you omit Length, the resulting string includes all the characters from Position to the end of the string.

·         If Position is less than 1 or Length is less than 0, an error is returned.

·         If Position is beyond the length of the current string, an empty string is returned.

·         If Position combined with Length exceeds the length of the string, all the characters from Position to the end of the string are returned.

Example

Str             := 'Using the COPYSTR function';

Position   := 7;

Length := 8;

NewStr := COPYSTR(Str, Position, Length); 

MESSAGE(Str);                                   -> Using the COPYSTR function

MESSAGE(NewStr);       -> the COPY

DELCHR Function (STRING)

Deletes one or more characters in a string.

NewString := DELCHR(String [, Where] [, Which])

The DELCHR function is case-sensitive.

If you do not define any characters in the Where and Which parameters, the equals sign (=) is used as the default for Where and spaces are used as the default for Which, which deletes all the spaces from the string.

·         If you omit the Which parameter, the function 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 beginning 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, the function deletes from String the characters 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 beginning of String.

·         If Where contains >, then the characters in Which are only deleted 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.

Example

String := 'Windy Solutions';

Where := '<>';

Which := 'Ws';

NewString := DELCHR(String, Where, Which); 

MESSAGE(String);                          -> Windy Solutions

MESSAGE(NewString);              ->   indy Solution

 The function deletes every W and s that is either the first or last character in String.

Example

String := 'This is an example';

Where := '=';

Which := 'sx';

NewString := DELCHR(String, Where, Which);

MESSAGE(String);                         ->                This is an example

MESSAGE(NewString);              ->                Thi i an eample

The function deletes every s and x from String.

DELSTR Function (STRING)

Deletes a substring inside a string (text or code).

NewString := DELSTR(String, Position [, Length])

·         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.

Example

Str := 'Adjusting prices - Please wait';

Position := 11; // Remove the word 'prices' and a blank

Length := 7;

NewStr := DELSTR(Str, Position, Length);

MESSAGE(Str);                                   -> Adjusting prices - Please wait

MESSAGE(NewStr);       -> Adjusting - Please wait

FORMAT Function (STRING)

Formats function used to convert a value or date into a string.

String := FORMAT(Value [, Length] [, FormatStr/FormatNumber]) 

MESSAGE('The formatted value: >%1<', FORMAT(-123456.78, 15, 3));

MyDate := 033108D;

MESSAGE(FORMAT(MyDate));                  ->            03/31/08

INCSTR Function (STRING)

Increases a positive number or decrease a negative number inside a string by one (1).

NewString := INCSTR(String)

·         If String contains more than one number, 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, it is decreased by one. For example, '-55' is changed to '-56'.

·         Zero (0) is considered a positive number, so 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 ''.

Example

One := ‘102DOC100’

Two := INCSTR(One);

MESSAGE(‘The value is %1 \ %2 ’,One,Two);       -> 102DOC100, 102DOC101

INSSTR Function (STRING)

Inserts a substring into a string.

NewString := INSSTR(String, SubString, Position)

·         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'.

Text constant	ENU value
Text000	'Press ENTER to continue'
Text001	'or ESC'
Text002	'The test string before INSSTR is called:\'
Text003	'The resulting string after INSSTR is called:\

Str                          := Text000;

SubString             := Text001;

NewStr                 := INSSTR(Str, SubString, 13);

MESSAGE(Text002 + '>%1<', Str);

MESSAGE(Text003 + '>%1<', NewStr);

The first message window displays the following:

The test string before INSSTR is called:

>Press ENTER to continue<

The second message window displays the following:

The resulting string after INSSTR is called:

>Press ENTER or ESC to continue<

LOWERCASE Function (STRING)

Converts all letters in a string to lowercase.

Example

Str := 'The Entries are Sorted by Name';

MESSAGE(Text001, Str);                                       ->  The Entries are Sorted by Name

Lower := LOWERCASE(Str);

MESSAGE(Text002, Lower);            ->  the entries are sorted by name

MAXSTRLEN Function (STRING)

Returns the maximum defined length of a string variable.

MaxLength := MAXSTRLEN(String)

·         If you call this function on a Variant, it returns an error.

Example

Assume that City has been defined as a text variable with a maximum length of 30.

Text constant	ENU value
Text000	‘Atlanta’
Text001	'The MAXSTRLEN function returns: %1,\'
Text002	'while the STRLEN function returns: %2'

City                        :=  Text000;

MaxLength         := MAXSTRLEN(City);

Length                  := STRLEN(City);

MESSAGE(Text001 + Text002, MaxLength, Length);

The message window displays the following:

The MAXSTRLEN function returns: 30

while the STRLEN function returns: 7

PADSTR Function (STRING)

Changes the length of a string to a length that you define.

NewString := PADSTR(String, Length [, FillCharacter])

·         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.

Example

Text constant			ENU value
Text000			'13 characters'
Text001			'Four'
Text002			'Before PADSTR is called:\'
Text003			'>%1<, has the length %2\'
Text004			'>%3<, has the length %4\'
Text005			'After PADSTR is called:\'

Str1 := Text000;

Str2 := Text001;

Len1 := STRLEN(Str1);

Len2 := STRLEN(Str2);

MESSAGE(Text002 + Text003 + Text004, Str1, Len1, Str2 Len2);

Str1 := PADSTR(Str1, 5); // Truncate the length to 5

Str2 := PADSTR(Str2, 15, 'w'); // Concatenate w's until length = 15

Len1 := STRLEN(Str1);

Len2 := STRLEN(Str2)

MESSAGE(Text005 + Text003 + Text004, Str1, Len1, Str2, Len2);

The first message window displays the following:

Before PADSTR is called:

>13 characters< has the length 13

>Four< has the length 4

The second message window displays the following:

After PADSTR is called:

>13 ch< has the length 5

>Fourwwwwwwwwwww< has the length 15

SELECTSTR Function (STRING)

Retrieves a substring from a comma-separated string.

NewString := SELECTSTR(Number, CommaString)

·         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 begins.

·         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".

Example

Text constant	ENU value
Text000	'This,is a comma,separated,string'
Text001	'The calls to SELECTSTR return:\'

CommaStr := Text000;

SubStr1 := SELECTSTR(2, CommaStr); // Pick out the 2nd substring

SubStr2 := SELECTSTR(4, CommaStr); // Pick out the 4th substring

SubStr3 := SELECTSTR(1,"11,22,33,,55,,,");

SubStr4 := SELECTSTR(4,"11,22,33,,55,,,");

SubStr5 := SELECTSTR(6,"11,22,33,,55,,,");

MESSAGE(Text001 + '>%1<\' + '>%2<\' + '>%3<\' + '>%4<\' + '>%5<\', SubStr1, SubStr2, SubStr3, SubStr4, SubStr5);

The message window displays the following text:

The calls to SELECTSTR return:

>is a comma<

>string<

>11<

><

(The fifth SELECSTR statement returns an error.)

STRCHECKSUM Function (STRING)

Calculates a checksum for a string that contains a number.

CheckNumber :=STRCHECKSUM(String [, WeightString] [, Modulus])

Example

This example shows how to use the STRCHECKSUM function to calculate a checksum.

This example requires that you create the following text constants in the C/AL Globals window.

Text constant			ENU value
Text000			'The number: %1\'
Text001			'has the checksum: %2'
StrNumber := '4378'; Weight := '1234'; Modulus := 7; CheckSum := STRCHECKSUM(StrNumber, Weight, Modulus); MESSAGE(Text000 + Text001, StrNumber, CheckSum);

The formula is:

(7 - (4x1 + 3x2 + 7x3 + 8x4) MOD 7) MOD 7=0

The message window displays the following:

The number: 4378

has the checksum: 0

STRLEN Function (STRING)

Returns the length of a string you define.

Length := STRLEN(String)

·         The difference between the STRLEN function and the MAXSTRLEN Function (STRING) is that the STRLEN returns the actual number of characters in the input string, while MAXSTRLEN returns the maximum defined length of the input string.

·         If you call STRLEN on a Variant, 0 is returned.

Example

Text constant	ENU value
Text000	‘Atlanta’
Text001	'The MAXSTRLEN function returns: %1,\'
Text002	'while the STRLEN function returns: %2'

City                        :=  Text000;

MaxLength         := MAXSTRLEN(City);

Length                  := STRLEN(City);

MESSAGE(Text001 + Text002, MaxLength, Length);

The message window displays the following:

The MAXSTRLEN function returns: 30

while the STRLEN function returns: 7

STRPOS Function (STRING)

Searches for the first occurrence of substring inside a string.

Position := STRPOS(String, SubString)

·         The STRPOS function returns the position of the first occurrence of the substring.

·         If SubString cannot be found, then the function returns zero.

·         If String or SubString is empty, then the function returns zero.

Example

Pos1 := StrPos("abc","");                 -> returns 0

Pos2 := StrPos("abc","c");               -> returns 3

Pos3 := StrPos("abc","bc");             -> returns 2

Pos4 := StrPos("abc","x");               -> returns 0

STRSUBSTNO Function (STRING)

Replaces %1, %2, %3... and #1, #2, #3... fields in a string with the values you provide as optional parameters.

NewString := STRSUBSTNO(String [,Value1, …])

If the string representation is shorter than the length of the specifier, then it is left aligned.

For example, StrSubstNo("Test %1 '#2##' #3", 1,2,3) returns "Test 1 '2   ' 3 ".

In this example, the following substitutions are made:

%1 is replaced by '1' because a % field is replaced by the specified value in its full length.

'#2##' is replaced by '2 space space space' because the value is shorter than the field and therefore, the 2 is left aligned and field is four characters long.

#3 is replaced by '3 space' because the 3 is left aligned and the field is two characters long

If the string is longer, then a series of asterisks are inserted to indicate overflow.

For example, StrSubstNo("Test %1 '###2' #3", 'Thomas','Thomas',0) returns "Test Thomas '****' 0 ".

In this example the following substitutions are made:

%1 is replaced by Thomas because a %1 field is replaced by the specified value in its full length.

'#2##' is replaced by 'space space space space' because the value is removed and each character is replaced by a space.

#3 is replaced by 'space space' because the value is removed and each character is replaced by a space.

You can have several references to the same value.

For example, StrSubstNo("Test %1 %3 %1", 555, 666, 777) returns "Test 555 777 555".

If one of the values is null, then it is treated as an empty string.

Example

Text constant	ENU value
Text000	'The balance of account %1 is $ %2'
Text001	'The string before STRSUBSTNO has been called:\%1'
Text002	'The string after STRSUBSTNO has been called:\%1'

Str := Text000;

AccountNo := 3452; (INTEGER)

Balance := 2345 + 5462; (DECIMAL)

MESSAGE(Text001, Str);

Str := STRSUBSTNO(Str, AccountNo, Balance);

MESSAGE(Text002, Str);

The first message window displays the following text:

The string before STRSUBSTNO has been called:

The balance of account %1 is $ %2

The second message window displays the following text:

The string after STRSUBSTNO has been called:

The balance of account 3452 is $ 7,807

UPPERCASE Function (STRING)

Converts all letters in a string to uppercase.

NewString := UPPERCASE(String)

Example

Lower := 'Outstanding Order Status';

MESSAGE(Lower);                            ->                 Outstanding Order Status

Upper := UPPERCASE(Lower);

MESSAGE(Upper);                          ->            OUTSTANDING ORDER STATUS