Common Visual Basic Functions

This final section includes a brief listing of the functions built-in to the Visual Basic language, many of which you will use regularly in your applications. Also listed here are some members of the FCL that replicate features that were part of the Visual Basic language before .NET, but were moved into the Framework for more general access. For the exact syntax required to use these functions, access the Visual Studio online help.

Conversion Functions

The conversion functions allow you to convert data of one Visual Basic data type to another. It's not a free-for-all, so don't go converting the string "hello" to an integer and expect it to work. But converting numbers from one numeric type to another, or converting values between string and numeric types, generally work just fine.

All of these statements (except CType) have the same basic syntax:

dest = CXxxx(source) 

where source is the value to be converted by CXxxx. You don't have to assign the result to a variable; you can use the result anywhere you would use a similar literal or variable value. Table 6-9 lists the built-in conversion functions.

Table 6-9. Visual Basic Conversion Functions

Function	Description
CBool	Converts a value to a Boolean.
CByte	Converts a value to a Byte.
CChar	Converts a value to a Char. If the source value is a string, only the first character is converted.
CDate	Converts a value to a Date. If the source value is a string, it must be in a valid date or time format.
CDbl	Converts a value to a Double.
CDec	Converts a value to a Decimal.
CInt	Converts a value to an Integer.
CLng	Converts a value to a Long.
CObj	Converts a value to an Object. This is useful when you want to store a value type as an Object instance.
CSByte	Converts a value to an SByte.
CShort	Converts a value to a Short.
CSng	Converts a value to a Single.
CType	Converts a value to any defined type, class, or interface, either in your application or in the FCL. The syntax is: CType(source, newType) where newType is a data type. For instance: CType(5, String) converts the Integer 5 to a String. As with other conversion functions, you can't convert data from one type to another if the types are incompatible, or if there is no conversion available that knows how to generate the target type from the source type. Operator overloading, discussed in Chapter 12, provides a way to let the CType function convert between types that would otherwise be incompatible.
CUInt	Converts a value to a UInteger.
CULng	Converts a value to a ULong.
CUShort	Converts a value to a UShort.

Date-Related Functions

Visual Basic includes several functions designed to manage date and time values. Table 6-10 lists these functions. Most of these functions accept one or more source arguments, and return either Date, String, or numeric result.

Table 6-10. Visual Basic Date-Related Functions and Properties

Function	Description
DateAdd	Adds or subtracts time or date value to a starting date. For instance, you can add 12 minutes, or subtract three years, from a given date.
DateDiff	Returns the difference between two date or time values. You can specify the interval, such as months or seconds.
DatePart	Returns one component of a date or time, such as the hour or the year.
DateSerial	Returns a Date built from specific month, day, and year values.
DateString	Returns the current date as a string. You can also set the date on the local computer using this keyword.
DateValue	Returns the date portion of a combined date and time value; the time portion is discarded.
Day	Returns the day from a given date value.
FormatDateTime	Formats a given date or time as a string, using a small set of predefined formats. This function is included for backward compatibility with older VBScript code.
Hour	Returns the hour from a given time value.
IsDate	Indicates whether the data supplied to this function is a valid date or not.
Minute	Returns the minute from a given time value.
Month	Returns the month from a given date value.
MonthName	Returns the name of a month for a numeric month value.
Now	Returns the current date and time. Equivalent to TimeOfDay.
Second	Returns the seconds from a given time value.
TimeOfDay	Returns the current date and time. Equivalent to Now.
Timer	Returns the number of seconds that have elapsed since midnight of the current day. This function is reset to zero each midnight.
TimeSerial	Returns a Date built from specific hour, minute, and second values.
TimeString	Returns the current time as a string. You can also set the time on the local computer using this keyword.
TimeValue	Returns the time portion of a combined date and time value; the date portion is discarded.
Today	Returns the current date.
Weekday	Returns an integer that indicates the day of the week.
WeekdayName	Returns the name of a weekday for an integer day of the week.
Year	Returns the year from a given date value.

Variables created as System.DateTime (or Visual Basic Date) each include several properties and methods that provide features similar to the functions listed in Table 6-10. For instance, the Second property returns the number of seconds.

Dim meetingTime As Date meetingTime = #11/7/2005 8:00:03am# MsgBox(meetingTime.Second)   ' Displays '3' MsgBox(Second(meetingTime))  ' Also displays '3' 

You can use either the intrinsic Visual Basic functions or the equivalent System.DateTime methods and properties in your code. Each technique provides the same result.

Numeric Functions

Visual Basic programmers just love working with numbers; it's in their blood. Fortunately, Visual Basic includes lots of features for working wonders with numbers. In addition to the standard data manipulation operators, Table 6-11 lists several number-related functions.

Table 6-11. Visual Basic Number-Related Functions

Function	Description
Fix	Truncates the decimal portion of a number, returning only the whole portion. Similar to the Int function.
FormatCurrency	Formats a given number as a currency value, using a small set of predefined formats. This function is included for backward compatibility with older VBScript code.
FormatNumber	Formats a given number as a general number, using a small set of predefined formats. This function is included for backward compatibility with older VBScript code.
FormatPercent	Formats a given number as a percentage, using a small set of predefined formats. This function is included for backward compatibility with older VBScript code.
Hex	Formats a number as hexadecimal, and returns its string representation.
Int	Returns the whole number that is less than or equal to the supplied value. Similar to the Fix function.
IsNumeric	Indicates whether the data supplied to this function is a valid number or not.
Oct	Formats a number as octal, and returns its string representation.
Val	Extracts the first valid number from a string and returns it.

The .NET Framework includes the System.Math class, which contains several math-related function members. Some of these, such as Round, Sin, and Log, were implemented as intrinsic functions in Visual Basic 6.0, but have been moved from the language to the Math class in .NET.

Visual Basic also includes several functions used for financial and accounting calculations. These functions were also included in Visual Basic 6.0. As they are not relevant to the project discussed in this book, I will only list their names here: DDB, FV, IPmt, IRR, MIRR, NPer, NPV, Pmt, PPmt, PV, Rate, SLN, and SYD.

String Functions

String manipulation is a core part of Windows programming. The new XML features included with .NET are really just fancy string-manipulation routines, although with the complexities hidden from view. Visual Basic includes many functions designed to manipulate strings and characters. They are listed in Table 6-12.

Table 6-12. Visual Basic String-Related Functions

Function	Description
Asc, AscW	Returns the numeric ASCII or Unicode value for a character.
Chr, ChrW	Given a number, these functions return the matching ASCII or Unicode character.
Filter	Returns an array that is a subset of a source array, but including only those elements that matched a pattern.
Format	Formats number, date, and time values using predefined or custom formatting codes.
GetChar	Extracts a single character from a larger string.
InStr	Returns the position of a substring within a larger string.
InStrRev	Returns the position of a substring within a larger string, searching from the end of the string until the beginning.
Join	Returns a string built from a concatenation of an array of strings.
LCase	Converts a string to its lowercase equivalent.
Left	Returns the left-most portion of a string.
Len	Returns the length of a string.
LSet	Left-aligns a string within a larger string of spaces.
LTrim	Removes spaces from the start of a string.
Mid	Extracts a substring from the middle of a larger string.
Mid Statement	Modifies a range of characters in an existing string with new content. This is not a function, but a special Visual Basic statement. Its syntax varies considerably from that of most other Visual Basic features.
Replace	Replaces occurrences of a substring with another substring, all within a larger string.
Right	Returns the right-most portion of a string.
RSet	Right-aligns a string within a larger string of spaces.
RTrim	Removes spaces from the end of a string.
Space	Generates a string containing a specified number of space characters. Similar to the StrDup function.
Split	Splits a string into an array of substrings based on a delimiter.
Str	Converts a number to its string representation.
StrComp	Compares two strings, and returns an integer indicating their sort order.
StrConv	Converts a string to a new format based on a conversion code. Some of the conversions involve changing the case of the content.
StrDup	Generates a string containing a specified number of a given character. Similar to the Space function, but works with any character.
StrReverse	Reverses the characters in a string.
Trim	Removes spaces from the start and end of a string.
UCase	Converts a string to its uppercase equivalent.

As with most functions, these functions return a new string or value, leaving the original string or source values intact. The lone exception is the Mid Statement, which modifies the source string.

Variables created as System.String (or Visual Basic String) each include several properties and methods that provide features similar to the functions listed in Table 6-12. For instance, the Length property returns the number of characters in the string.

Dim simpleString As String = "abc" MsgBox(simpleString.Length)  ' Displays '3' MsgBox(Len(simpleString))    ' Also displays '3' 

You can use either the intrinsic Visual Basic functions or the equivalent System.String methods and properties in your code. Each technique provides the same result, although the syntax details and options may vary.

Other Functions

Visual Basic includes several functions that refuse to be squeezed into any of the other categories. Table 6-13 documents these functions.

Table 6-13. Visual Basic Miscellaneous Functions

Function	Description
DirectCast	Converts a value from one data type to another. Similar to the TryCast and CType functions.
ErrorToString	Returns the string representation of an error code. This only works with the system error codes previously available in Visual Basic 6.0, although these codes are still available in .NET.
IsArray	Indicates whether the data supplied to this function is a valid array or not.
IsDBNull	Indicates whether the data supplied to this function is a valid NULL database value or not.
IsError	Indicates whether the data supplied to this function is a valid error condition or not.
IsNothing	Indicates whether the data supplied to this function is undefined, or set to Nothing.
IsReference	Indicates whether the data supplied to this function is a reference type or a value type.
QBColor	Returns a color code from a small set of predefined colors.
RGB	Returns a color code built from the individual red, green, and blue components.
SystemTypeName	Given a Visual Basic data type name, this function returns the equivalent .NET data type name.
TryCast	Converts a value from one data type to another. Similar to the DirectCast and CType functions.
TypeName	Returns a data type name that summarizes the data type of the supplied content. The returned string is not necessarily the name of the value's actual data type.
VarType	Returns a code indicating the general data type of the supplied content.