> ## Class BirtStr

> The BirtStr class provides functions to manipulate strings, for example, to concatenate strings, trim extra spaces, get parts of a string, and display strings in lower or upper case. This class is static. The application cannot create instances of the class.

> ### BirtStr.charLength

> This function returns the length of a given string.

> Syntax

> BirtStr.charLength( source )

> Parameter

> source

> The string to evaluate.

> Returns

> The number of characters in the specified string.

> Examples

> The following example returns the length of a specific string:

> BirtStr.charLength( "Julie Murphy" ) // returns 12

> The following example returns the length of each value in the CustomerName field:

> BirtStr.charLength( row["CustomerName"] )

> ### BirtStr.concat

> This function returns the string that results from concatenating specified strings.

> Syntax

> BirtStr.concat( source1, ..., sourceN )

> Parameter

> source1, ..., sourceN

> The strings to concatenate.

> Returns

> The string that results from concatenating a series of strings.

> Example

> The following example returns a full address by concatenating values from multiple fields:

> BirtStr.concat( row["AddressLine1"], ", ", row["AddressLine2"], ", ", row["City"], " ", row["PostalCode"], "row["State"], ", ", row["Country"] )

> ### BirtStr.indexOf

> This function returns the position of a specified substring in a given string.

> Syntax

> BirtStr.indexOf( target, source, start )

> Parameters

> target

> The substring to search for. The search is case-sensitive.

> source

> The string in which to look for a specified substring.

> start

> Optional. The position in the source string where the search starts. If you omit this argument, the function starts the search from the first character of the string.

> Returns

> The numerical position of the substring in the string. The first character of a string starts at 0. If the substring is not found, the function returns -1.

> Examples

> The following example returns the numeric position of specified characters in specific strings:

> BirtStr.indexOf( " ", "Julie Murphy" ) // returns 5
> BirtStr.indexOf( "-", "ModelA-1234-567" ) // returns 6
> BirtStr.indexOf( "-", "ModelA-1234-567", 7 ) // returns 11

> The following example uses BirtStr.indexOf( ) in conjunction with BirtStr.left( ) to display the characters that precede the space character in a customer name. The BirtStr.left( ) function extracts a substring of a specified length, starting from the first character. In this example, the length of the substring to display is equal to the numerical position of the space character.

> spaceCharPosition = BirtStr.indexOf( " ", row["customerName"] );
> displayFirstName = BirtStr.left( row["customerName"], spaceCharPosition );

> If the customer name is Julie Murphy, the expression returns Julie.

> ### BirtStr.left

> This function extracts a substring of a specified length from a string, starting from the left-most, or first, character.

> Syntax

> BirtStr.left( source, n )

> Parameters

> source

> The string from which to extract a substring.

> n

> The number of characters to extract, starting from the first character.

> Returns

> A substring of a specific length.

> n | If you omit n, the number of characters to extract, the function returns the first character only.

> n | If n is zero, the function returns an empty string.

> n | If n is greater than the length of the string, the function returns the entire string.

> Examples

> The following example returns substrings of various lengths from specific strings:

> BirtStr.left( "Julie Murphy", 5 ) // returns Julie
> BirtStr.left( "Julie Murphy", 12 ) // returns Julie Murphy

> The following example uses BirtStr.indexOf( ) in conjunction with BirtStr.left( ) to display the characters that precede the space character in a customer name. The BirtStr.left( ) function extracts a substring of a specified length, starting from the first character. In this example, the length of the substring to display is equal to the numerical position of the space character.

> spaceCharPosition = BirtStr.indexOf( " ", row["customerName"] );
> displayFirstName = BirtStr.left( row["customerName"], spaceCharPosition );

> If the customer name is Julie Murphy, the expression returns Julie.

> ### BirtStr.right

> This function extracts a substring of a specified length from a string, starting from the right-most, or last, character.

> Syntax

> BirtStr.right( source, n )

> Parameters

> source

> The string from which to extract a substring.

> n

> The number of characters to extract, starting from the last character.

> Returns

> A substring of a specific length.

> n | If you omit n, the number of characters to extract, the function returns the last character only.

> n | If n is zero, the function returns an empty string.

> n | If n is greater than the length of the string, the function returns the entire string.

> Examples

> The following example returns substrings of various lengths from specific strings:

> BirtStr.right( "Julie Murphy", 6 ) // returns Murphy
> BirtStr.right( "Julie Murphy", 12 ) // returns Julie Murphy

> The following example uses BirtStr.right( ) in conjunction with the BirtStr.indexOf( ) and BirtStr.charLength( ) functions to display the characters that appear after the space character in a customer name. This example assumes that the number of characters after the hyphen varies. Therefore, the length of the entire string (returned by BirtStr.charLength( )) minus the length up to the hyphen (returned by BirtStr.indexOf( )) is the number of characters to display.

> spaceCharPosition = BirtStr.indexOf( " ", row["customerName"] );
> displayLastName = BirtStr.right( row["customerName"], (BirtStr.charLength( row["customerName"] - (spaceCharPosition + 1)) )

> If the customer name is Julie Murphy, the expression returns Murphy. If the customer name is Kwai Li, the expression returns Li.

> ### BirtStr.search

> This function returns the position of a specified substring in a given string. The substring can contain wildcard characters.

> Syntax

> BirtStr.search( pattern, source, index )

> Parameters

> pattern

> The string pattern to search for. The search is case-insensitive. You can use the following wildcard characters in a pattern:

> n | An asterisk ( * ) matches zero or more characters, including spaces. For example, t*n matches tn, tin, and teen.

> n | A question mark (?) matches exactly one character. For example, t?n matches tan, ten, tin, and ton. It does not match teen or tn.

> To match a literal asterisk or question mark in a string, precede those characters with two backslash characters (\\). For example, to find the substring R*10, use the following string pattern:

> "R\\*10"

> source

> The string in which to look for a specified substring.

> index

> Optional. The position in the source string where the search starts. If you omit this argument, the function starts the search from the first character of the string.

> Returns

> The numerical position of the substring in the string. The first character of a string starts at 0. If the substring is not found, the function returns -1.

> Examples

> The following example returns the numeric position of specified string patterns in specific strings:

> BirtStr.search( "XM?", "XMS-ModelA-1234-567" ) // returns 0
> BirtStr.search( "ModelA*", "XMS-ModelA-1234-567" ) // returns 4
> BirtStr.search( "-", "XMS-ModelA-1234-567", 4 ) // returns 10

> The following example searches for the string pattern, S*A, in each value in the ProductCode field. If the product code is KBS5412A, the expression returns 2.

> BirtStr.search( "S*A", row["ProductCode"] )

> The following example uses BirtStr.search( ) in conjunction with BirtStr.left( ) to display the characters that precede the string pattern, -Model*, in a product name. The BirtStr.left( ) function extracts a substring of a specified length, starting from the first character. In this example, the length of the substring to display is equal to the numerical position of the string pattern.

> stringPatternPosition = BirtStr.search( "-Model*", row["productName"] );
> displayString = BirtStr.left( row["productName"], stringPatternPosition );

> If the product name is XMS-ModelA-1234, the expression returns XMS.

> ### BirtStr.toLower

> This function converts all letters in a string to lowercase.

> Syntax

> BirtStr.toLower( source )

> Parameter

> source

> The string to convert to lowercase.

> Returns

> The specified string in all lowercase letters

> Example

> The following example displays all the values in the productLine field in lowercase:

> BirtStr.toLower( row["productLine"] )

> ### BirtStr.toUpper

> This function converts all letters in a string to uppercase.

> Syntax

> BirtStr.toUpper( source )

> Parameter

> source

> The string to convert to uppercase.

> Returns

> The specified string in all uppercase letters

> Example

> The following example displays all the values in the customerName field in uppercase:

> BirtStr.toUpper( row["customerName"] )

> ### BirtStr.trim

> This function returns a string with all leading and trailing blank characters removed. It does not remove blank characters between words.

> Syntax

> BirtStr.trim( source )

> Parameter

> source

> The string from which to remove leading and trailing blank characters.

> Returns

> A string with all leading and trailing blank characters removed.

> Example

> The following example uses BirtStr.trim( ) to remove all leading and trailing blank characters from values in the FirstName and LastName data fields.

> BirtStr.trim( row["FirstName"]) + " " + BirtStr.trim(row["LastName"] )

> ### BirtStr.trimLeft

> This function returns a string with all leading and trailing blank characters removed. It does not remove blank characters between words.

> Syntax

> BirtStr.trimLeft( source )

> Parameter

> source

> The string from which to remove leading blank characters.

> Returns

> A string with all leading blank characters removed.

> Example

> The following example concatenates a literal string with each value in the customerName field. BirtStr.trimLeft( ) removes all blank characters preceding the customerName value so that there are no extra blank characters between the literal string and the customerName value.

> "Customer name: " + BirtStr.trimLeft( row["customerName"] )

> ### BirtStr.trimRight

> This function returns a string with all trailing blank characters removed. It does not remove blank characters between words.

> Syntax

> BirtStr.trimRight( source )

> Parameter

> source

> The string from which to remove trailing blank characters.

> Returns

> A string with all trailing blank characters removed.

> Example

> The following example concatenates each value in the Comment field with a semicolon, then with a value in the Action field. BirtStr.trimRight( ) removes all blank characters after the Comment value so that there are no extra blank characters between the Comment string and the semicolon.

> BirtStr.trimRight( row["Comment"]) + "; " + row["Action"] )

(c) Copyright Actuate Corporation 2009