Strings Module

The Strings module contains functions useful for manipulating string values.

 Public Function Asc(ByVal [String] As Char) As Integer Public Function Asc(ByVal [String] As String) As Integer 

The Asc function returns the ASCII value of the character or the first character in the string.

NOTE

The ASCII value returned depends on the current ASCII codepage being used by the current thread.

 Public Function AscW(ByVal [String] As String) As Integer Public Function AscW(ByVal [String] As Char) As Integer 

The AscW function returns the Unicode value of the character or the first character in the string.

 Public Function Chr(ByVal CharCode As Integer) As Char 

The Chr function returns a character representing the given ASCII character value.

NOTE

The ASCII value returned depends on the current ASCII codepage being used by the current thread.

 Public Function ChrW(ByVal CharCode As Integer) As Char 

The ChrW function returns a character representing the given Unicode character value.

 Public Function Filter(ByVal Source() As Object, _   ByVal Match As String, Optional ByVal Include As Boolean = True, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As String() Public Function Filter(ByVal Source() As String, _   ByVal Match As String, Optional ByVal Include As Boolean = True, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As String() 

The Filter function returns a one-dimensional array of strings representing the members of the Source array filtered on the Match parameter. If Include is True , the array contains all elements of Source that contain Match as a substring. If Include is False , the array contains all elements of Source that do not contain Match as a substring.

 Public Function Format(ByVal Expression As Object, _   Optional ByVal Style As String = "") As String 

The Format function formats a value based on the specified format string. See Format Strings at the end of this section for more information on format strings.

 Public Function FormatCurrency(ByVal Expression As Object, _     Optional ByVal NumDigitsAfterDecimal As Integer = -1, _     Optional ByVal IncludeLeadingDigit As TriState = _       TriState.UseDefault, _     Optional ByVal UseParensForNegativeNumbers As TriState = _       TriState.UseDefault, _     Optional ByVal GroupDigits As TriState = TriState.UseDefault) _     As String 

The FormatCurrency function formats a value into a currency string. The currency format used is the current system currency format at runtime.

 Public Function FormatDate(ByVal Expression As Date, _   Optional ByVal NamedFormat As DateFormat = DateFormat.GeneralDate) _   As String 

The FormatDate function formats a value based on the specified date format.

 Public Function FormatNumber(ByVal Expression As Object, _   Optional ByVal NumDigitsAfterDecimal As Integer = -1, _   Optional ByVal IncludeLeadingDigit As TriState = _     TriState.UseDefault, _   Optional ByVal UseParensForNegativeNumbers As TriState = _     TriState.UseDefault, _   Optional ByVal GroupDigits As TriState = TriState.UseDefault) _   As String 

The FormatNumber function formats a value into a number string. The number format used is the current system number format at runtime.

 Public Function FormatPercent(ByVal Expression As Object, _   Optional ByVal NumDigitsAfterDecimal As Integer = -1, _   Optional ByVal IncludeLeadingDigit As TriState = _     TriState.UseDefault, _   Optional ByVal UseParensForNegativeNumbers As TriState = _     TriState.UseDefault, _   Optional ByVal GroupDigits As TriState = TriState.UseDefault) _   As String 

The FormatPercent function formats a value into a percentage string. The number format used is the current system number format at runtime.

 Public Function GetChar(ByVal str As String, ByVal Index As Integer) _   As Char 

The GetChar function returns the character position specified by Index .

 Public Function InStr(ByVal String1 As String, _   ByVal String2 As String, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As Integer Public Function InStr(ByVal Start As Integer, _   ByVal String1 As String, ByVal String2 As String, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As Integer 

The InStr function returns an Integer specifying the start position of the first occurrence of one string within another.

 Public Function InStrRev(ByVal StringCheck As String, _   ByVal StringMatch As String, Optional ByVal Start As Integer = -1, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As Integer 

The InStrRev function returns an Integer specifying the start position of the last occurrence of one string within another.

 Public Function Join(ByVal SourceArray() As Object, _   Optional ByVal Delimiter As String = " ") As String Public Function Join(ByVal SourceArray() As String, _   Optional ByVal Delimiter As String = " ") As String 

The Join function returns a string that represents the concatenation of all the values passed in. If Delimiter is supplied, the string is used to separate each value in the string.

 Public Function LCase(ByVal Value As String) As String Public Function LCase(ByVal Value As Char) As Char 

The LCase function converts a string into all lowercase.

 Public Function Left(ByVal str As String, ByVal Length As Integer) _   As String 

The Left function returns the specified number of characters in the string, starting from the beginning of the string.

 Public Function Len(ByVal Expression As String) As Integer Public Function Len(ByVal Expression As Byte) As Integer Public Function Len(ByVal Expression As Char) As Integer Public Function Len(ByVal Expression As Int16) As Integer Public Function Len(ByVal Expression As Int32) As Integer Public Function Len(ByVal Expression As Int64) As Integer Public Function Len(ByVal Expression As Single) As Integer Public Function Len(ByVal Expression As Double) As Integer Public Function Len(ByVal Expression As Boolean) As Integer Public Function Len(ByVal Expression As Decimal) As Integer Public Function Len(ByVal Expression As Date) As Integer Public Function Len(ByVal Expression As Object) As Integer 

The Len function returns the number of characters required to store the value in a file using the functions in the FileSystem module.

 Public Function LSet(ByVal Source As String, ByVal Length As Integer) _   As String 

The LSet function returns a string of the specified length. If the Source parameter is less than Length characters long, the returned string is padded at the end with spaces.

 Public Function LTrim(ByVal str As String) As String 

The LTrim function returns the str parameter with all leading spaces removed.

 Public Function Mid(ByVal str As String, ByVal Start As Integer) _   As String Public Function Mid(ByVal str As String, ByVal Start As Integer, _   ByVal Length As Integer) As String 

The Mid function returns the specified number of characters from the middle of a string. If no Length parameter is specified, the rest of the string is returned.

It is also possible to use the Mid function to assign a string into another string. The following example prints the string abxxef .

 Dim s As String = "abcdef" Mid(s, 3, 2) = "xx" Console.WriteLine(s) 

When Mid assignment is done, the string value on the right-hand side of the assignment replaces the characters in the right-hand side string indicated by the Start and Length parameters of the function. Only the number of characters in the right-hand side string is replaced , and no more than the number of characters selected by the Mid function are replaced.

Style

In previous versions of Visual Basic, Mid assignment could be faster than using Left , Mid , and Right to compose a new string. However, in Visual Basic .NET, there is no performance advantage to Mid assignment. The System.Text.StringBuilder class can be used instead when changes need to be made to a string and performance is important.

 Public Function Replace(ByVal Expression As String, _   ByVal Find As String, ByVal Replacement As String, _   Optional ByVal Start As Integer = 1, _   Optional ByVal Count As Integer = -1, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As String 

The Replace function returns a string in which a specified substring has been replaced with another substring a specified number of times.

 Public Function Right(ByVal str As String, ByVal Length As Integer) _   As String 

The Right function returns the specified number of characters in the string, starting from the end of the string.

 Public Function RSet(ByVal Source As String, ByVal Length As Integer) _   As String 

The RSet function returns a string of the specified length. If the Source parameter is less than Length characters long, the returned string is padded at the beginning with spaces.

 Public Function RTrim(ByVal str As String) As String 

The RTrim function returns the str parameter with all trailing spaces removed.

 Public Function Space(ByVal Number As Integer) As String 

The Space function returns a string consisting of the specified number of spaces.

 Public Function Split(ByVal Expression As String, _   Optional ByVal Delimiter As String = " ", _   Optional ByVal Limit As Integer = -1, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As String() 

The Split function returns an array of substrings that represent the partitioning of the original string. The original string is partitioned based on the Delimiter parameter. The Limit parameter determines how many substrings will be returned.

 Public Function StrComp(ByVal String1 As String, _   ByVal String2 As String, _   Optional ByVal Compare As CompareMethod = CompareMethod.Binary) _   As Integer 

The StrComp function compares two strings using the alphanumeric sort values of the corresponding character of each string. If String1 sorts before String2 , the function returns “1. If String1 sorts after String2 , the function returns 1. If the two strings sort the same, the function returns 0.

 Public Function StrConv(ByVal str As String, _   ByVal Conversion As VbStrConv, _   Optional ByVal LocaleID As Integer = 0) As String 

The StrConv function converts the specified string into a new string using the specified conversion and locale.

 Public Function StrDup(ByVal Number As Integer, _   ByVal Character As Object) As Object Public Function StrDup(ByVal Number As Integer, _   ByVal Character As Char) As String Public Function StrDup(ByVal Number As Integer, _   ByVal Character As String) As String 

The StrDup function returns a string that consists of the given character repeated a specified number of times.

 Public Function StrReverse(ByVal Expression As String) As String 

The StrReverse function returns a string that is the reverse of the specified string.

 Public Function Trim(ByVal str As String) As String 

The Trim function returns the str parameter with all leading and trailing spaces removed.

 Public Function UCase(ByVal Value As String) As String Public Function UCase(ByVal Value As Char) As Char 

The UCase function converts a string into all uppercase.

Format Strings

A format string controls how the Format function formats a value into a string. By default, an empty format string will convert the value to a string using the current regional settings of the computer at runtime. Format also has a set of predefined formats that can be used to format values in a standard way. And, finally, user -defined formats can be composed using special characters.

Predefined Formats

The predefined formats are named formats. To use a predefined format, you supply the name of the format as the Style parameter of the Format function. Tables A-2 through A-4 list the predefined formats.

Table A-2. Numeric Predefined Formats

Format Name	Description
"General Number", "G", or "g"	Displays a number with no thousands separator.
"Currency", "C", or "c"	Displays a number as a currency value, using the current regional settings.
"Fixed", "F", or "f"	Displays a number with at least one digit to the left of a decimal point and at least two digits to the right of a decimal point.
"Standard", "N", or "n"	Displays a number in the same format as the Fixed format, except that a thousands separator will be used if needed.
"Percent"	Displays a number as a percentage with the percentage sign.
"P" or "p"	Displays a number in the same format as the Percent format, except that a thousands separator will be used if needed.
"Scientific"	Displays a number in scientific format with two significant digits.
"E" or "e"	Displays a number in scientific format with six significant digits.
"D" or "d"	Displays a number as a whole decimal (base 10) number.
"X" or "x"	Displays a number as a whole hexadecimal (base 16) number.

Table A-3. Date/Time Predefined Formats

Format Name	Description
"General Date" or "G"	Displays a date and time using the current general date regional setting.
"Long Date" or "D"	Displays a date using the current long date regional setting.
"Medium Date"	Displays a date using a medium date format.
"Short Date" or "d"	Displays a date using the current short date regional setting.
"Long Time" or "T"	Displays a time using the current long time regional setting.
"Medium Time"	Displays a time in a 12- hour format with hours, minutes, seconds, and an AM/PM designator.
"Short Time" or "t"	Displays a time using the 24-hour format.
"f"	Displays a date and time using the long date and short time regional settings.
"F"	Displays a date and time using the long date and long time regional settings.
"g"	Displays a date and time using the short date and long time regional settings.
"M" or "m"	Displays the month and day of a date value.
"R" or "r"	Displays a date and time as Greenwich Mean Time (GMT).
"s"	Displays a date and time as a sortable index.
"u"	Displays a date and time as a GMT sortable index.
"U"	Displays a date and time as GMT using the long date and long time regional settings.
"Y" or "y"	Displays the year and month of a date value.

Table A-4. Other Predefined Formats

Format Name	Description
"Yes/No"	Displays "No" if the value is 0, "Yes" otherwise .
"True/False"	Displays "False" if the value is 0, "True" otherwise.
"On/Off"	Displays "Off" if the value is 0, "On" otherwise.

User-Defined Formats

A user-defined format string uses special characters to indicate how the value should be formatted. Tables A-5 and A-6 list the characters that can be used to create format strings.

These are some examples of user-defined numeric format strings.

 Format(10, "")               ' Result:10 Format(41, "000")            ' Result: 041 Format(3.5, "0.00")          ' Result: 3.50 Format(35, "#,##0")          ' Result: 35 Format(1000, "#,##0")        ' Result: 1,000 Format(1394.34, "$#,##0.00") ' Result: 94.34 Format(.124, "0.00%")        ' Result: 12.40% Format(.124, "0.00E-00")     ' Result: 1.24E-01 

Table A-5. Numeric User-Defined Format Characters

Character	Description
None	Displays a number.
	Displays a digit, or a zero if there is no matching digit.
#	Displays a digit, or nothing if there is no matching digit.
.	Displays a decimal point using the current regional setting. This character determines where characters to the right and to the left of the decimal point begin and end.
%	Displays a percentage sign and formats the number as a percentage.
,	Displays a thousands separator, if needed, using the current regional setting.

Table A-6. Date/Time User-Defined Format Characters

Character	Description
:	Displays a time separator using the current regional setting.
d or %d	Displays the day as a number without a leading zero.
dd	Displays the day as a number with a leading zero.
ddd	Displays the day as an abbreviated day of the week (for example, "Sun") using the current regional setting.
dddd	Displays the day as a day of the week (for example, "Sunday") using the current regional setting.
M or %M	Displays the month as a number without a leading zero.
MM	Displays the month as a number with a leading zero.
MMM	Displays the month as an abbreviated month name (for example, "Jan") using the current regional setting.
MMMM	Displays the month as a month name (for example, "January") using the current regional setting.
gg	Displays the period/era string of the date (for example, "A.D.").
h or %h	Displays the hour as a number without leading zeros.
hh	Displays the hour as a number with leading zeros using the 12-hour clock.
H or %H	Displays the hour as a number without leading zeros using the 24-hour clock.
HH	Displays the hour as a number with leading zeros using the 24-hour clock.
m or %m	Displays the minute as a number without leading zeros.
mm	Displays the minute as a number with leading zeros.
s or %s	Displays the seconds as a number without leading zeros.
ss	Displays the seconds as a number with leading zeros.
f, ff, fff, etc., or %f	Displays the fractions of seconds. Each "f" represents a decimal place (so "f" is tenths of a second, "ff" is hundredths of a second, and so on). Up to seven f's can be used.
t or %t	Displays "a" for hours before noon, "p" for hours after noon but before midnight.
tt	Displays "AM" for hours before noon, "PM" for hours after noon but before midnight.
y or %y	Displays the year number (0 “9) without leading zeros.
yy	Displays the year in two-digit numeric format with a leading zero.
yyy	Displays the year in four-digit numeric format without leading zeros.
yyyy	Displays the year in four-digit numeric format with leading zeros.
z or %z	Displays the time zone offset without a leading zero.
zz	Displays the time zone offset with a leading zero.
zzz	Displays the full time zone offset.

These are some examples of user-defined date format strings.

 Format(#8/23/70 3:43:12AM#, "M/d/yy")    ' Result: 8/23/70 Format(#8/23/70 3:43:12AM#, "d-MMM")     ' Result: 23-Aug Format(#8/23/70 3:43:12AM#, "d-MMMM-yy") ' Result: 23-August-1970 Format(#8/23/70 3:43:12AM#, "d MMMM")    ' Result: 23 August Format(#8/23/70 3:43:12AM#, "MMMM yy")   ' Result: August 70 Format(#8/23/70 3:43:12AM#, "hh:mm tt")  ' Result: 03:43 AM Format(#8/23/70 3:43:12AM#, "h:mm:ss")   ' Result: 3:43:12 

Within a format string, the backslash character ( \ ) causes the next character to be put into the output instead of being interpreted as a format character. The backslash itself is not displayed. (To display a backslash, you have to use two backslashes.) For example:

 ' Result is: Phone # is 206-555-1212 Format(2065551212, "Phone \# is: ###-###-####") ' Result is: C:\Test10.txt Format(10, "C\:\Test10\.txt") 

Strings in quotation marks are also copied directly into the output. The quotes themselves are not displayed. (To display a double quote character, you must precede it by a backslash.) For example:

 ' Result is: Phone # is 206-555-1212 Format(2065551212, "Phone ""#"" is: ###-###-####") ' Result is: The value is "10". Format(10, "The value is \""##\""\.") 

Numeric formats can format differently based on the value of the number being formatted. If the format string has two formats separated by a semicolon, the first format applies to values equal to or greater than zero, while the second format applies to values less than zero. If the format string has three formats separated by semicolons, the first format applies to positive values, the second format applies to negative values, and the third format applies to zero values. If a format string with three formats omits the second format, the first format is used for both positive and negative numbers . For example:

 Format(1234, "$#,##0;($#,##0)")          ' Result: ,234 Format(-1234, "$#,##0;($#,##0)")         ' Result: (,234) Format(1234, "$#,##0;($#,##0);\Z\e\r\o") ' Result: ,234 Format(0, "$#,##0;($#,##0);\Z\e\r\o")    ' Result: Zero Format(1234, "$#,##0;;\Z\e\r\o")   ' Result: ,234 Format(0, "$#,##0;;\Z\e\r\o")      ' Result: Zero