The following table summarizes Visual Basic's elementary data types.

The System namespace also provides integer data types that specify their number of bits explicitly. For example, Int32 represents a 32-bit integer. Using these values instead of Integer emphasizes the fact that the variable uses 32 bits. That can sometimes make code clearer. For example, suppose that you need to call an application programming interface (API) function that takes a 32-bit integer as a parameter. In Visual Basic 6, a Long uses 32 bits but in Visual Basic .NET, an Integer uses 32 bits. You can make it obvious that you are using a 32-bit integer by giving the parameter the Int32 type.

The data types that explicitly give their sizes are Int16, Int32, Int64, UInt16, UInt32, and UInt64.

The Integer data type is usually the fastest of the integral types. You will generally get better performance using Integers than you will with the Char, Byte, Short, Long, or Decimal data types. You should stick with the Integer data type unless you need the extra range provided by Long and Decimal, or you need to save space with the smaller Char and Byte data types. In many cases, the space savings you will get using the Char and Byte data types isn't worth the extra time and effort, unless you are working with a very large array of values.

Note that you cannot safely assume that a variable's storage requirements are exactly the same as its size. In some cases, the program may move a variable so that it begins on a boundary that is natural for the hardware platform. For example, if you make a structure containing several Short (2-byte) variables, the program may insert 2 extra bytes between them so they can all start on 4-byte boundaries because that may be more efficient for the hardware. For more information on structures, see Chapter 26, "Classes and Structures."

Some data types also come with some additional overhead. For example, an array stores some extra information about each of its dimensions.

Data type characters identify a value's data type. The following table lists the data type characters of Visual Basic.

You can specify a variable's data type by adding a data type character after a variable's name when you declare it. When you use the variable later, you can omit the data type character if you like. For example, the following code declares variable num_desserts as a Long and satisfaction_quotient as a Double. It then assigns values to these variables.

Dim num_desserts&
Dim satisfaction_quotient#

num_desserts = 100
satisfaction_quotient# = 1.23

If you have Option Explicit turned off, you can include a data type character the first time you use the variable to determine its data type. If you omit the character, Visual Basic picks a default data type based on the value you assign to the variable.

If the value you assign is an integral value that will fit in an Integer, Visual Basic makes the variable an Integer. If the value is too big for an Integer, Visual Basic makes the variable a Long. If the value contains a decimal point, Visual Basic makes the variable a Double.

The following code shows the first use of three variables (Option Explicit is off). The first statement sets the variable an_integer equal to the value 100. This value fits in an Integer, so Visual Basic makes the variable an Integer. The second statement sets a_long equal to 10000000000. That value is too big to fit in an Integer, so Visual Basic makes it a Long. The third statement sets a_double to 1.0. That value contains a decimal point, so Visual Basic makes the variable a Double.

an_integer = 100
a_long = 10000000000
a_double = 1.0

If you set a variable equal to a True or False, Visual Basic makes it a Boolean.

In Visual Basic, you surround date values with # characters. If you assign a variable to a date value, Visual Basic gives the variable the Date data type. The following code assigns Boolean and Date variables:

a_boolean = True
a_date = #12/31/2007#

In addition to data type characters, Visual Basic provides a set of literal type characters that determine the data type of literal values. These are values that you explicitly type into your code in statements such as assignment and initialization statements. The following table lists the literal type characters of Visual Basic.

A literal type character determines the data type of a literal value in your code and may indirectly determine the data type of a variable assigned to it. For example, suppose that the following code is the first use of the variables i and ch (with Option Explicit turned off).

i = 123L
ch = "X"c

Normally, Visual Basic would make i an Integer, because the value 123 fits in an Integer. Because the literal value 123 ends with the L character, however, the value is a Long, so the variable i is also a Long.

Similarly, Visual Basic would normally make variable ch a String because the value "X" looks like a string. The c following the value tells Visual Basic to make this a Char variable instead.

Visual Basic also lets you precede a literal integer value with &H to indicate that it is hexadecimal (base 16) or &O to indicate that it is octal (base 8). For example, the following three statements set the variable flags to the same value. The first statement uses the decimal value 100, the second uses the hexadecimal value &H64, and the third uses the octal value &O144.

flags = 100       ' Decimal 100.
flags = &H64  ' Hexadecimal &H64 = 6 * 16 + 4 = 96 + 4 = 100.
flags = &O144 ' Octal &O144 = 1 * 64 + 4 * 8 + 4 = 64 + 32 + 4 = 100.

Debug.WriteLine(flags)      ' Decimal.
Debug.WriteLine(Hex(flags)) ' Hexadecimal.
Debug.WriteLine(Oct(flags)) ' Octal.

Sometimes you must use literal type characters to make a value match a variable's data type. For example, consider the following code:

Dim ch As Char
ch = "X"  ' Error because "X" is a String.
ch = "X"c ' Okay because "X"c is a Char.

Dim amount As Decimal
amount = 12.34  ' Error because 12.34 is a Double.
amount = 12.34D ' Okay because 12.34D is a Decimal.

The first assignment tries to assign the value "X" to a Char variable. This throws an error because "X" is a String value so it won't fit in a Char variable. Although it is obvious to a programmer that this code is trying to assign the character X to the variable, Visual Basic thinks the types don't match.

The second assignment statement works because it assigns the Char value "X"c to the variable. The next assignment fails when it tries to assign the Double value 12.34 to a Decimal variable. The final assignment works because the value 12.34D is a Decimal literal.

The following code shows another way to accomplish these assignments. This version uses the data type conversion functions CChar and CDec to convert the values into the proper data types. The following section, "Data Type Conversion," has more to say about data type conversion functions.

ch = CChar("X")
amount = CDec(12.34)

Using data type characters, literal type characters, and the Visual Basic default data type assignments can lead to very confusing code. You cannot expect every programmer to notice that a particular variable is a Single because it is followed by ! in its first use, but not in others. You can make your code less confusing by using variable declarations that include explicit data types.

Normally, you assign a value to a variable that has the same data type as the value. For example, you assign a string value to a String variable, you assign an integer value to an Integer variable, and so forth. Whether you can assign a value of one type to a variable of another type depends on whether the conversion is a narrowing or widening conversion.

Dim an_integer As Integer
Dim a_long As Long
...
an_integer = a_long

Dim an_integer As Integer
Dim a_string As String
...
an_integer = a_string

Dim an_employee As Employee
Dim a_person As Person
...
an_employee = a_person

Dim an_integer As Integer
Dim a_byte As Byte
...
a_byte = CByte(an_integer)

Dim an_integer As Integer
Dim a_long As Long = 100
an_integer = Ctype(a_long, Integer)

Dim dessert_obj As Object = New Dessert("Ice Cream")
Dim my_dessert As Dessert
my_dessert = DirectCast(dessert_obj, Dessert)

Dim an_integer As Integer = 100
Dim a_long As Long
a_long = DirectCast(an_integer, Long)

Dim txt_entered As String = "112358"
Dim num_entered As Integer
...
num_entered = CInt(txt_entered) ' Use CInt.
num_entered = Integer.Parse(txt_entered) ' Use Integer.Parse.

Dim i As Integer = Convert.ToInt32("17")

Dim txt As String = num_employees.ToString()

MessageBox.Show(angle.ToString("0.00"))

The complete syntax for a variable declaration is as follows:

[attribute_list] [accessibility] [Shared] [Shadows] [ReadOnly] _
Dim [WithEvents] name [(bounds_list)] [As [New] type] _
[= initialization_expression]

All declarations have only one thing in common: They contain a variable's name. Other than the name, different declarations may have nothing in common. Variable declarations with different forms can use or omit any other piece of the general declaration syntax. For example, the following two declarations don't share a single keyword:

Dim i = 1           ' Declare private Integer named i. (Option Explicit Off)
Public j As Integer ' Declare public Integer named j.

The many variations supported by a variable declaration make the general syntax rather intimidating. In most cases, however, declarations are straightforward. The previous two declarations are fairly easy to understand.

The following sections describe the pieces of the general declaration in detail.

Public Class OrderItem
    <XmlText()>
    Public ItemName As String

    <XmlAttributeAttribute(AttributeName:="Cost")>
    Public Price As Decimal

    <XmlAttributeAttribute()>
    Public Quantity As Integer
End Class

<OrderItem Cost="1.25" Quantity="12">Cookie</OrderItem>

order1.NumOrders = 100            ' Use order1 to set NumOrders = 100.
MessageBox.Show(order1.NumOrders) ' Use order1 to display 100.
MessageBox.Show(order2.NumOrders) ' Use a different Order to Display 100.
Order.NumOrders = 101             ' Use the class to set NumOrders = 101.
MessageBox.Show(Order.NumOrders)  ' Use the class to display 101.

Public Class Person
    Public LastName As String
    Public EmployeeId As String
End Class

Public Class Employee
    Inherits Person
    Public Shadows EmployeeId As Long
End Class

Public Class Manager
    Inherits Employee
    Public Shadows LastName As String
End Class

Private Sub TestShadows()
    Dim txt As String = ""

    Dim mgr As New Manager
    mgr.LastName = "Manager Last Name"
    mgr.EmployeeId = 1

    Dim emp As Employee = CType(mgr, Employee)
    emp.LastName = "Employee Last Name"
    emp.EmployeeId = 2

    Dim per As Person = CType(mgr, Person)
    per.LastName = "Person Last Name"
    per.EmployeeId = "A"

    txt &= "Manager: " & mgr.EmployeeId & ": " & mgr.LastName & vbCrLf
    txt &= "Employee: " & emp.EmployeeId & ": " & emp.LastName & vbCrLf
    txt &= "Person: " & per.EmployeeId & ": " & per.LastName & vbCrLf

    txtResults.Text = txt
    txtResults.Select(0, 0)
End Sub
                                                  

Manager: 2: Manager Last Name
Employee: 2: Person Last Name
Person: A: Person Last Name

Public Sub SetPersonEmployeeId(ByVal employee_id As String)
    Dim per As Person = CType(Me, Person)
    per.EmployeeId = employee_id
End Sub

Public Sub SetManagerLastName(ByVal last_name As String)
    MyBase.LastName = last_name
End Sub

Public Class EmployeeCollection
    Public ReadOnly MaxEmployees As Integer = 100
    ...
End Class

Public Class EmployeeCollection
    Public ReadOnly MaxEmployees As Integer

    Public Sub New()
        MaxEmployees = 100
    End Sub

    Public Sub New(ByVal max_employees As Integer)
        MaxEmployees = max_employees
    End Sub
    ...
End Class

Dim num_people As Integer
Private num_people As Integer

WithEvents

The WithEvents keyword tells Visual Basic that the variable is of a specific object type that may raise events that you will want to catch. For example, the following code declares the variable Face as a PictureBox object that may raise events you want to catch:

Private WithEvents Face As PictureBox

When you declare a variable with the WithEvents keyword, Visual Basic creates an entry for it in the left drop-down list in the module's code window, as shown in Figure 15-1.

Figure 15.1. Visual Basic creates a drop-down entry for variables declared WithEvents.

If you select the object in the left drop-down list, Visual Basic fills the right drop-down list with the object's events that you might want to catch, as shown in Figure 15-2.

Figure 15.2. When you select an object declared WithEvents in the left drop-down list, Visual Basic fills the right drop-down list with events you might want to catch.

If you select an event, Visual Basic creates a corresponding empty event handler. Letting Visual Basic automatically generate the event handler in this way is easier and safer than trying to type the event handler yourself, creating all of the required parameters by hand.

Declaring variables using the WithEvents keyword is a powerful technique. You can make the variable point to an object to catch its events. Later, if you want to process events from some other object using the same event handlers, you can set the variable to point to the new object. If you no longer want to receive any events, you can set the variable to Nothing.

Unfortunately, you cannot declare an array using the WithEvents keyword. That means you cannot use a simple declaration to allow the same event handlers to process events from more than one object. However, you can achieve this by using the AddHandler method to explicitly set the event handler routines for a series of objects. For more information on this technique, see the section "Catching Events" in Chapter 26.

Public Sub ParseString(ByVal [String] As String)
    Dim values() As String = Split([String])
    ...
End Sub

Private customers(100) As Customer
Private orders(100, 10) As Order
Private customers2(0 To 100) As Customer
Private orders2(0 To 100, 0 To 10) As Order

Private customers(100) As Customer
For i As Integer = 0 To 100
    customers(i) = New Customer
Next i

Dim a1(10) As Integer
Dim a2() As Integer

ReDim a1(20)
ReDim a2(0 To 20)

Dim a1(,,) As Integer

ReDim a1(10, 20, 30)

Dim emp1 As Employee
emp1 = New Employee

Dim emp2 As New Manager

Dim emp1 As New Employee
Dim emp2 As New Employee("Rod", "Stephens")

Dim cx As Single

Dim message = "Hello!"

Dim x = 1.234

Dim num_employees As Integer = 0

Dim emp1 As Employee = New Employee("Rod", "Stephens")
Dim emp2 As New Employee("Rod", "Stephens")

Dim emp3 As New Employee With {.FirstName = "Rod", .LastName = "Stephens"}

Dim fibonacci() As Integer = {1, 1, 2, 3, 5, 8, 13, 21, 33, 54, 87}

Dim numbers() = {1, 2, 3}
Dim strings() = {"A", "B", "C"}
Dim objects() = {"A", 12, 1.23}

Dim int_values(,) As Integer =
{
    {1, 2, 3},
    {4, 5, 6}
}
Dim txt As String = ""
For i As Integer = 0 To 1
    For j As Integer = 0 To 2
        txt &= int_values(i, j)
    Next j
    txt &= vbCrLf
Next i

123
456

Dim str_values(,,) As String =
{
    {
        {"000", "001", "002"},
        {"010", "011", "012"}
    },
    {
        {"100", "101", "102"},
        {"110", "111", "112"}
    }
}
Dim txt As String = ""
For i As Integer = 0 To 1
    For j As Integer = 0 To 1
        txt &= "[ "
        For k As Integer = 0 To 2
            txt &= str_values(i, j, k) & " "
        Next k
        txt &= "] "
    Next j
    txt &= vbCrLf
Next i

[ 000 001 002 ] [ 010 011 012 ]
[ 100 101 102 ] [ 110 111 112 ]

Dim int_values(,) As Integer =
{
    {1, 2, 3},
    {4, 5}
}

Dim employees(0 To 10) As Employee

Dim employees() As Employee =
{
    New Employee("Alice", "Andrews"),
    New Employee("Bart", "Brin"),
    New Employee With {.FirstName = "Cindy", .LastName="Cant"},
    New Employee With {.FirstName = "Dan", .LastName="Diver"},
    New Employee,
    New Employee,
    Nothing,
    Nothing
}

Dim book_node As XElement =
    <Book>
        <Title>The Bug That Was</Title>
        <Year>2010</Year>
        <Pages>376</Pages>
    </Book>

Starting with Visual Basic 2010, collection classes that provide an Add method such as List, Dictionary, and SortedDictionary have their own initialization syntax. Instead of using an equals sign as you would with an array initializer, use the From keyword followed by the values that should be added to the collection surrounded by curly braces.

For example, the following code initializes a new List(Of String):

Dim pies As New List(Of String) From {
    "Apple", "Banana", "Cherry", "Coconut Cream"
}

The items inside the braces must include all of the values needed by the collection's Add method. For example, the Dictionary class's Add method takes two parameters giving the key and value that should be added.

The following code initializes a Dictionary(Of String, String). The parameters to the class's Add method are an item's key and value so, for example, the value 940-283-1298 has the key Alice Artz.

Later you could look up Alice's phone number by searching the Dictionary for the item with key "Alice Artz."

Dim phone_numbers As New Dictionary(Of String, String) From {
    {"Alice Artz", "940-283-1298"},
    {"Bill Bland", "940-237-3827"},
    {"Carla Careful", "940-237-1983"}
}

<Extension()>
Sub Add(ByVal the_stack As Stack(Of String), ByRef value As String)
    the_stack.Push(value)
End Sub

Dim orders As New Stack(Of String) From {
    "Art", "Beatrice", "Chuck"
}

Private num_employees, num_customers As Integer

Private emps, custs As Integer, cust As String

Private emps, custs As Integer, cust As String = "Cozmo"

Private emps As Integer = 5, custs As Integer = 10, cust As String = "Cozmo"

Private num_employees, num_customers As Integer, num_orders As Long

Dim i, j, k, R, C As Integer
Dim X, Y, Z As Single

The Option Explicit and Option Strict compiler options play an important role in variable declarations.

When Option Explicit is set to On, you must declare all variables before you use them. If Option Explicit is Off, Visual Basic automatically creates a new variable whenever it sees a variable that it has not yet encountered. For example, the following code doesn't explicitly declare any variables. As it executes the code, Visual Basic sees the first statement, num_managers = 0. It doesn't recognize the variable num_managers, so it creates it. Similarly, it creates the variable i when it sees it in the For loop.

Option Explicit Off
Option Strict Off

Public Class Form1
    ...
    Public Sub CountManagers()
        num_managers = 0
        For i = 0 To m_Employees.GetUpperBound(0)
            If m_Employees(i).IsManager Then num_managrs += 1
        Next i

        MessageBox.Show(num_managers)
    End Sub
    ...
End Class

Keeping Option Explicit turned off can lead to two very bad problems. First, it silently hides typographical errors. If you look closely at the preceding code, you'll see that the statement inside the For loop increments the misspelled variable num_managrs instead of the correctly spelled variable num_managers. Because Option Explicit is off, Visual Basic assumes that you want to use a new variable, so it creates num_managrs. After the loop finishes, the program displays the value of num_managers, which is zero because it was never incremented.

The second problem that occurs when Option Explicit is off is that Visual Basic doesn't really know what you will want to do with the variables it creates for you. It doesn't know whether you will use a variable as an Integer, Double, String, or PictureBox. Even after you assign a value to the variable (say, an Integer), Visual Basic doesn't know whether you will always use the variable as an Integer or whether you might later want to save a String in it.

To keep its options open, Visual Basic creates undeclared variables as generic objects. Then it can fill the variable with just about anything. Unfortunately, this can make the code much less efficient than it needs to be. For example, programs are much better at manipulating integers than they are at manipulating objects. If you are going to use a variable as an integer, creating it as an object makes the program run much slower.

Example program TimeGenericObjects, which is available for download on the book's web site, uses the following code to demonstrate the difference in speed between using variables with explicit types and variables of the generic Object type:

Dim num_trials As Integer = Integer.Parse(txtNumTrials.Text)

Dim start_time As DateTime
Dim stop_time As DateTime
Dim elapsed_time As TimeSpan

start_time = Now
For i As Integer = 1 To num_trials

Next i
stop_time = Now
elapsed_time = stop_time.Subtract(start_time)
lblIntegers.Text = elapsed_time.TotalSeconds.ToString("0.000000")
Refresh()

start_time = Now
For j = 1 To num_trials

Next j
stop_time = Now
elapsed_time = stop_time.Subtract(start_time)
lblObjects.Text = elapsed_time.TotalSeconds.ToString("0.000000")

                                                  

The code executes two For loops. In the first loop, it explicitly declares its looping variable to be of type Integer. In the second loop, the code doesn't declare its looping variable, so Visual Basic automatically makes it an Object when it is needed. In one test, the second loop took more than 60 times as long as the first loop.

The second compiler directive that influences variable declaration is Option Strict. When Option Strict is turned off, Visual Basic silently converts values from one data type to another, even if the types are not very compatible. For example, Visual Basic will allow the following code to try to copy the string s into the integer i. If the value in the string happens to be a number (as in the first case), this works. If the string is not a number (as in the second case), this throws an error at runtime.

Dim i As Integer
Dim s As String
s = "10"
i = s       ' This works.
s = "Hello"
i = s       ' This Fails.

If you turn Option Strict on, Visual Basic warns you of possibly illegal conversions at compile time. You can still use conversion functions such as CInt, Int, and Integer.Parse to convert a string into an Integer, but you must take explicit action to do so.

To avoid confusion and ensure total control of your variable declarations, you should always turn on Option Explicit and Option Strict.

For more information on Option Explicit and Option Strict (including instructions for turning these options on), see the "Project" section in Chapter 2, "Menus, Toolbars, and Windows."

A variable's scope tells which other pieces of code can access it. For example, if you declare a variable inside a subroutine, only code within that subroutine can access the variable. The four possible levels of scope are (in increasing size of scope) block, procedure, module, and namespace.

For i As Integer = 1 To 5
    Dim j As Integer = 3
    If i = j Then
         Dim M As Integer = i + j
         Debug.WriteLine("M: " & M)
    Else
         Dim N As Integer = i * j
         Debug.WriteLine("N: " & N)
    End If

    Dim k As Integer = 123
    Debug.WriteLine("k: " & k)
Next i

Public Sub AddOrderItem(ByVal order_object As Order, ByVal order_item As OrderItem)
    order_object.OrderItems.Add(order_item)
End Sub

Private Class Lender
    Public Sub DisplayLoanAmount()
        MessageBox.Show(m_LoanAmount)
    End Sub

    Private m_LoanAmount As Decimal
    ...
End Class

A parameter declaration for a subroutine, function, or property procedure defines the names and types of the parameters passed into it. Parameter declarations always have non-static procedure scope. Visual Basic creates parameter variables when a procedure begins and destroys them when the procedure ends. The subroutine's code can access the parameters, but code outside of the routine cannot.

For example, the following subroutine takes an integer as a parameter. The subroutine calls this value employee_id. Code within the subroutine can access employee_id, whereas code outside of the subroutine cannot.

Public Sub DisplayEmployee(ByVal employee_id As Integer)
    ...
End Sub

Whereas a parameter's basic scope is straightforward (non-static procedure scope), parameters have some special features that complicate the situation. Although this isn't exactly a scoping issue, it's related closely enough to scope that it's worth covering here.

You can declare a parameter ByRef or ByVal (ByVal is the default if you use neither keyword). If you declare the variable ByVal, the routine makes its own local parameter variable with procedure scope just as you would expect.

If you declare a parameter with the ByRef keyword, the routine does not create a separate copy of the parameter variable. Instead, it uses a reference to the parameter you pass in, and any changes the routine makes to the value are reflected in the calling subroutine.

For example, the following code includes two routines that double their parameters. Subroutine DoubleItByVal declares its parameter with the ByVal keyword. This routine makes a new variable named X and copies the value of its parameter into that variable. The parameter X is available within the subroutine, the routine multiplies it by 2, and then exits. At that point, the parameter variable goes out of scope and is destroyed.

Subroutine DoubleItByRef declares its parameter with the ByRef keyword. This routine's variable X is a reference to the variable passed into the routine. The subroutine doubles X and that doubles the variable in the calling code.

Subroutine TestParameters calls each of these routines. It declares a variable named value, passes it to subroutine DoubleItByVal, and displays the result after DoubleItByVal returns. Because DoubleItByVal declares its parameter ByVal, the variable value is not changed so the result is 10.

Subroutine TestParameters then calls subroutine DoubleItByRef and displays the result after the call returns. Subroutine DoubleItByRef declares its parameter ByRef so the variable value is changed to 20.

Sub DoubleItByVal(ByVal X As Single)
    X*= 2
End Sub
Sub DoubleItByRef(ByRef X As Single)
    X*= 2
End Sub
Sub TestParameters()
    Dim value As Single

    value = 10
    DoubleItByVal(value)
    Debug.WriteLine(value)

    value = 10
    DoubleItByRef(value)
    Debug.WriteLine(value)
End Sub

Even this more complex view of how procedures handle parameters has exceptions. If you pass a literal value or the result of an expression into a procedure, there is no variable to pass by reference, so Visual Basic must create its own temporary variable. In that case, any changes made to a ByRef parameter are not returned to the calling routine, because that code did not pass a variable into the procedure. The following code shows statements that pass a literal expression and the result of an expression into the DoubleItByRef subroutine:

DoubleItByRef(12)    ' Literal expression.
DoubleItByRef(X + Y) ' Result of an expression.

Another case where a ByRef parameter does not modify a variable in the calling code is when you omit an optional parameter. For example, the following subroutine takes an optional ByRef parameter. If you call this routine and omit the parameter, Visual Basic creates the employee_id parameter from scratch so the subroutine can use it in its calculations. Because you called the routine without passing it a variable, the subroutine does not update a variable.

Sub UpdateEmployee(Optional ByRef employee_id As Integer = 0)
   ...
End Sub

Probably the sneakiest way a ByRef variable can fail to update a variable in the calling routine is if you enclose the variable in parentheses. The parentheses tell Visual Basic to evaluate their contents as an expression, so Visual Basic creates a temporary variable to hold the result of the expression. It then passes the temporary variable into the procedure. If the procedure's parameter is declared ByRef, it updates the temporary variable, but not the original variable, so the calling routine doesn't see any change to its value.

The following code calls subroutine DoubleItByRef, passing the variable value into the routine surrounded with parentheses. The DoubleItByRef subroutine doubles the temporary variable Visual Basic creates, leaving value unchanged.

DoubleItByRef((value))

Keep these issues in mind when you work with parameters. Parameters have non-static procedure scope but the ByRef keyword can sometimes carry their values outside of the routine.

For more information on routines and their parameters, see Chapter 17.

Property procedures are routines that can represent a variable-like value. To other pieces of the program, property procedures look just like variables, so they deserve mention in this chapter.

The following code shows property procedures that implement a Name property. The Property Get procedure simply returns the value in the private variable m_Name. The Property Set procedure saves a new value in the m_Name variable.

Private m_Name As String

Property Name() As String
    Get
        Return m_Name
    End Get
    Set(ByVal Value As String)
        m_Name = Value
    End Set
End Property

A program could use these procedures exactly as if there were a single public Name variable. For example, if this code is in the Employee class, the following code shows how a program could set and then get the Name value for the Employee object named emp:

emp.Name = "Rod Stephens"
MessageBox.Show(emp.Name)

You might want to use property procedures rather than a public variable for several reasons. First, the routines give you extra control over the getting and setting of the value. For example, you could use code to validate the value before saving it in the variable. The code could verify that a postal code or phone number has the proper format and throw an error if the value is badly formatted.

You can set breakpoints in property procedures. Suppose that your program is crashing because a piece of code is setting an incorrect value in a variable. If you implement the variable with property procedures, you can set a breakpoint in the Property Set procedure and stop whenever the program sets the value. This can help you find the problem relatively quickly.

Property procedures let you set and get values in formats other than those you want to actually use to store the value. For example, the following code defines Name property procedures that save a name in m_FirstName and m_LastName variables. If your code would often need to use the last and first names separately, you could also provide property procedures to give access to those values separately.

Private m_LastName As String
Private m_FirstName As String

Property MyName() As String
    Get
        Return m_FirstName & " " & m_LastName
    End Get
    Set(ByVal Value As String)
        m_FirstName = Value.Split(" "c)(0)
        m_LastName = Value.Split(" "c)(1)
    End Set
End Property

Finally, you can use property procedures to create read-only and write-only variables. The following code shows how to make a read-only NumEmployees property procedure and a write-only NumCustomers property procedure. (Write-only property procedures are unusual but legal.)

Public ReadOnly Property NumEmployees() As Integer
    Get
         ...
    End Get
End Property

Public WriteOnly Property NumCustomers() As Integer
    Set(ByVal Value As Integer)
        ...
    End Set
End Property

You don't need to remember all of the syntax for property procedures. If you type the first line and press Enter, Visual Basic fills in the rest of the empty property procedures. If you use the keyword ReadOnly or WriteOnly, Visual Basic only includes the appropriate procedure.

Visual Basic 2010 introduced auto-implemented properties. These are simple properties that do not have separate property procedures. You declare the property's name and Visual Basic automatically creates the necessary backing variables and property procedures behind the scenes.

The following code shows a simple FirstName property:

Public Property FirstName As String

You can give a property a default value as in the following code:

Public Property FirstName As String = "<missing>"

You cannot use the ReadOnly or WriteOnly keywords with auto-implemented properties. If you want to make a read-only or write-only property, you need to write Get and Set procedures as described earlier.

The advantage of auto-implemented properties is that you don't need to write as much code. The disadvantage is that you can't set breakpoints in the property procedures.

An enumerated type is a discrete list of specific values. You define the enumerated type and the values allowed. Later, if you declare a variable of that data type, it can take only those values.

For example, suppose that you are building a large application where users can have one of three access levels: clerk, supervisor, and administrator. You could define an enumerated type named AccessLevel that allows the values Clerk, Supervisor, and Administrator. Now, if you declare a variable to be of type AccessLevel, Visual Basic will only allow the variable to take those values.

The following code shows a simple example. It defines the AccessLevel type and declares the variable m_AccessLevel using the type. Later the MakeSupervisor subroutine sets m_AccessLevel to the value AccessLevel.Supervisor. Note that the value is prefixed with the enumerated type's name.

Public Enum AccessLevel
    Clerk
    Supervisor
    Administrator
End Enum

Private m_AccessLevel As AccessLevel ' The user's access level.

' Set supervisor access level.
Public Sub MakeSupervisor()
    m_AccessLevel = AccessLevel.Supervisor
End Sub

The syntax for declaring an enumerated type is as follows:

[attribute_list] [accessibility] [Shadows] Enum name [As type]
    [attribute_list] value_name [= initialization_expression]
    [attribute_list] value_name [= initialization_expression]
   ...
End Enum

Most of these terms, including attribute_list and accessibility, are similar to those used by variable declarations. See the section "Variable Declarations" earlier in this chapter for more information.

The type value must be an integral type and can be Byte, Short, Integer, or Long. If you omit this value, Visual Basic stores the enumerated type values as integers.

The value_name pieces are the names you want to allow the enumerated type to have. You can include an initialization_expression for each value if you like. This value must be compatible with the underlying data type (Byte, Short, Integer, or Long). If you omit a value's initialization expression, the value is set to one greater than the previous value. The first value is zero by default.

In the previous example, Clerk = 0, Supervisor = 1, and Administrator = 2. The following code changes the default assignments so Clerk = 10, Supervisor = 11, and Administrator = −1:

Public Enum AccessLevel
    Clerk = 10
    Supervisor
    Administrator = −1
End Enum

Usually, all that's important about an enumerated type is that its values are unique, so you don't need to explicitly initialize the values.

Note that you can give enumerated values the same integer value either explicitly or implicitly. For example, the following code defines several equivalent AccessLevel values. The first three values, Clerk, Supervisor, and Administrator, default to 0, 1, and 2, respectively. The code explicitly sets User to 0, so it is the same as Clerk. The values Manager and SysAdmin then default to the next two values, 1 and 2 (the same as Supervisor and Administrator, respectively). Finally, the code explicitly sets Superuser = SysAdmin.

Public Enum AccessLevel
    Clerk
    Supervisor
    Administrator
    User = 0
    Manager
    SysAdmin
    Superuser = SysAdmin
End Enum

This code is somewhat confusing. The following version makes it more obvious that some values are synonyms for others:

Public Enum AccessLevel
    Clerk
    Supervisor
    Administrator

    User = Clerk
    Manager = Supervisor
    SysAdmin = Administrator
    Superuser = Administrator
End Enum
                                                  

You can get an effect similar to enumerated types using integer variables and constants, as shown in the following code. This code does roughly the same thing as the previous examples.

Public Const Clerk As Integer = 0
Public Const Supervisor As Integer = 1
Public Const Administrator As Intger = 2

Private m_AccessLevel As Integer ' The user's access level.

' Set supervisor access level.
Public Sub MakeSupervisor()
    m_AccessLevel = Supervisor
End Sub

Declaring an enumerated type has a couple of advantages over using integers and constants, however. First, it prevents you from assigning nonsense values to the variable. In the previous code, you could set m_AccessLevel to 10, which wouldn't make any sense.

Using an enumerated data type allows Visual Basic to verify that the value you are assigning to the variable makes sense. You can only set the variable equal to one of the values in the enumerated type or to the value stored in another variable of the same enumerated type.

If you really need to set an enumerated variable to a calculated value for some reason, you can use the CType function to convert an integer value into the enumerated type. For example, the following statement uses the value in the variable integer_value to set the value of the variable m_AccessLevel. Making you use CType to perform this type of conversion makes it less likely that you will set an enumerated value accidentally.

m_AccessLevel = CType(integer_value, AccessLevel)

Another benefit of enumerated types is that they allow Visual Basic to provide IntelliSense help. If you type m_AccessLevel =, Visual Basic provides a list of the allowed AccessLevel values.

A final benefit of enumerated types is that they provide a ToString method that returns the textual name of the value. For example, the following code displays the message "Clerk":

Dim access_level As AccessLevel = Clerk
MessageBox.Show(access_level.ToString())

Example program AccessLevelEnum, which is available for download on the book's web site, makes an AccessLevel Enum and then displays the results returned by calling ToString for each of its values.

If you have a value that can take only a fixed number of values, you should probably make it an enumerated type. Also, if you discover that you have defined a series of constants to represent related values, you should consider converting them into an enumerated type. Then you can gain the benefits of the improved Visual Basic type checking and IntelliSense.

An anonymous type is an object data type that is built automatically by Visual Basic and never given a name for the program to use. The type is used implicitly by the code that needs it and is then discarded.

The following code uses LINQ to select data from an array of BookInfo objects named m_BookInfo. It begins by using a LINQ query to fill variable book_query with the selected books. It then iterates through the results stored in book_query, adding information about the selected books to a string. It finishes by displaying the string in a text box.

Dim book_query =
    From book In m_BookInfo
    Where book.Year > 1999
    Select book.Title, book.Pages, book.Year
    Order By Year

Dim txt As String = ""
For Each book In book_query
    txt &= book.Title & " (" & book.Year & ", " &
        book.Pages & " pages)" & ControlChars.CrLf
Next book
txtResult.Text = txt

The book_query variable is an ordered sequence containing objects that hold the data selected by the query: Title, Pages, and Year. This type of object doesn't have an explicit definition; it is an anonymous type created by Visual Basic to hold the selected values Title, Pages, and Year. If you hover the mouse over the book_query variable in the code editor, a tooltip appears giving the variable's data type as:

System.Linq.IOrderedSequence(Of <anonymous type>)

Later, the code uses a For Each loop to enumerate the objects in book_query. The looping variable book must have the same type as the items in the sequence. The code does not explicitly give the variable's data type, so Visual Basic can infer it. If you hover the mouse over the book variable in the code editor, a tooltip appears giving the variable's data type as:

<anonymous type>

You are not really intended to use anonymous types explicitly. For example, you shouldn't need to declare a new object of the anonymous type. They are intended to support LINQ. Although you won't use anonymous types explicitly, it's still helpful to understand what they are.

For more information on LINQ, see Chapter 21.

Most relational databases have a concept of a null data value. A null value indicates that a field does not contain any data. It lets the database distinguish between valid zero or blank values and non-existing values. For example, a null value in a text field means there is no data in the field and a blank value means the field contains a value that happens to be blank.

You can create a nullable variable in Visual Basic by adding a question mark either to the variable's name or after its data type. You can also declare the variable to be of type Nullable(Of type). For example, the following code declares three nullable integers:

Dim i As Integer?
Dim j? As Integer
Dim k As Nullable(Of Integer)

To make a nullable variable "null," set it equal to Nothing. The following code makes variable num_choices null:

num_choices = Nothing

To see if a nullable variable contains a value, use the Is operator to compare it to Nothing. The following code determines whether the nullable variable num_choices contains a value. If the variable contains a value, the code increments it. Otherwise the code sets the value to 1.

If num_choices IsNot Nothing Then
    num_choices += 1
Else
    num_choices = 1
End If

Calculations with nullable variables use "null-propagation" rules to ensure that the result makes sense. For example, if a nullable integer contains no value, it probably doesn't make sense to add another number to it. (What is null plus three?)

If one or more operands in an expression contains a null value, the result is a null value. For example, if num_choices in the previous example contains a null value, then num_choices + 1 is also a null value. (That's why the previous code checks explicitly to see whether num_choices is null before incrementing its value.)

Example program NullableTypes, which is available for download on the book's web site, demonstrates nullable types.

In many respects, a constant is a lot like a read-only variable. Both variable and constant declarations may have attributes, accessibility keywords, and initialization expressions. Both read-only variables and constants represent a value that the code cannot change after it is assigned.

The syntax for declaring a constant is as follows:

[attribute_list] [accessibility] [Shadows] _
Const name [As type] = initialization_expression

For the general meanings of the various parts of a constant declaration, see the section "Variable Declarations" earlier in this chapter. The following sections describe differences between read-only variable and constant declarations.

Private Const MAX_VALUES As Integer = CInt(123.45)
Private Const MASK_READ As Long = &H1000&
Private Const MASK_WRITE As Long = &H2000&
Private Const MASK_READ_WRITE As Long = MASK_READ Or MASK_WRITE
Private Const MAX_ACCESS_LEVEL As AccessLevel = AccessLevel.SuperUser

A delegate is an object that refers to a subroutine, function, or other method. The method can be an instance method provided by an object, a class's shared method, or a method defined in a code module. A delegate variable acts as a pointer to a subroutine or function. Delegate variables are sometimes called type-safe function pointers.

The Delegate keyword defines a delegate class and specifies the parameters and return type of the method to which the delegate will refer.

The following code uses a Delegate statement to declare the StringDisplayerType to be a delegate to a subroutine that takes a string as a parameter. Next, the code declares the variable m_DisplayStringRoutine to be of this type. This variable can hold a reference to a subroutine that takes a string parameter. The code then sets the variable equal to the ShowStringInOutputWindow subroutine. Finally, the code invokes the delegate's subroutine, passing it a string.

' Define a StringDisplayerType delegate to be a pointer to a subroutine
' that has a string parameter.
Private Delegate Sub StringDisplayerType(ByVal str As String)

' Declare a StringDisplayerType variable.
Dim m_DisplayStringRoutine As StringDisplayerType

' Assign the variable to a subroutine.
m_DisplayStringRoutine = AddressOf ShowStringInOutputWindow

' Invoke the delegate's subroutine.
m_DisplayStringRoutine("Hello world")

The delegate in the preceding example holds a reference to a subroutine defined in a code module. A delegate can also hold the address of a class's shared method or an instance method. For example, suppose the Employee class defines the shared function GetNumEmployees that returns the number of employees loaded. Suppose that it also defines the instance function ToString that returns an Employee object's first and last names.

Example program UseDelegates, which is available for download on the book's web site, uses the following code to demonstrate delegates for both of these functions:

Dim emp As New Employee("Rod", "Stephens")

' Use a delegate pointing to a shared class method.
Private Delegate Function NumEmployeesDelegate() As Integer

Private Sub btnShared_Click() Handles btnShared.Click
    Dim show_num As NumEmployeesDelegate
    show_num = AddressOf Employee.GetNumEmployees
    MessageBox.Show(show_num().ToString, "# Employees")
End Sub

' Use a delegate pointing to a class instance method.
Private Delegate Function GetNameDelegate() As String
Private Sub btnInstance_Click() Handles btnInstance.Click
    Dim show_name As GetNameDelegate
    show_name = AddressOf emp.ToString
    MessageBox.Show(show_name(), "Name")
End Sub
                                                  

First, it declares and initializes an Employee object named emp. It then defines a delegate named NumEmployeesDelegate, which is a pointer to a function that returns an integer. The btnShared_Click event handler declares a variable of this type, sets it to the address of the Employee class's shared GetNumEmployees function, and calls the function. Then the code defines a delegate named GetNameDelegate, which is a pointer to a function that returns a string. The btnInstance_Click event handler declares a variable of this type, sets it to the address of the emp object's ToString function, and then calls the function.

These examples are somewhat contrived because the code could easily invoke the subroutines and functions directly without delegates, but they show how a program can save a delegate pointing to a subroutine or function and then call it later. A real application might set the delegate variable's value and only use it much later.

A particular delegate variable could hold references to different methods, depending on the program's situation. For example, different subroutines might generate output on a form, on the printer, or into a bitmap file. The program could set a delegate variable to any of these routines. Later, the program could invoke the variable's routine without needing to know which routine will actually execute.

Another useful technique is to pass a delegate variable into a subroutine or function. For example, suppose that you are writing a subroutine that sorts an array of Customer objects. This routine could take as a parameter a delegate variable that references the function to use when comparing the objects in the array. By passing different functions into the routine, you could make it sort customers by company name, contact name, customer ID, total past sales, or anything else you can imagine.

Delegates are particularly confusing to many programmers, but understanding them is worth a little extra effort. They can add an extra dimension to your programming by essentially allowing you to manipulate subroutines and functions as if they were data.

Many development teams adopt naming conventions to make their code more consistent and easier to read. Different groups have developed their own conventions, and you cannot really say that one of them is best. It doesn't really matter which convention you adopt. What is important is that you develop some coding style that you use consistently.

One rather simple convention is to use lowercase_letters_with_underscores for variables with routine scope, MixedCaseLetters for variables with module and global scope, and ALL_CAPS for constants of any scope. Use the prefixes m_ and g_ to differentiate between module and global scope, and an abbreviation to give an object's data type. For example, the following statement defines a module-scope PictureBox variable:

Private m_picCanvas As PictureBox

Routine names are generally MixedCase.

Many developers carry these rules a bit further and add type prefix abbreviations to all variables, not just objects. For example, this statement declares an integer variable:

Dim iNumEmployees As Integer

If you apply these rules strictly enough, you should never need to assign one variable to another variable's value, unless the two have the same type abbreviation. If you see a statement that mixes variable types, you should examine the code more closely to see if there is a real data type mismatch problem. For example, the following statement should make the developer suspicious because it's assigning an Integer value to a Long variable:

mlngNumEmployees = intNumAbsent + intNumPresent

Some developers extend the rules to cover all programming objects, including functions and subroutines. For example, a global function that returns a string might be named gstrGetWebmasterName.

Generally, this scope and type information is more important the farther you are from a variable's declaration. If you declare a variable inside a subroutine, a developer can usually remember the variable's data type. If there is any doubt, it's easy to scroll up and review the variable's declaration.

In contrast, if a variable is declared globally in an obscure code module that developers rarely need to read, a programmer may have trouble remembering the variable's scope and data type. In that case, using prefixes to help the developers' memory can be important.

No matter which convention you use, the most important piece of a name is the descriptive part. The name mblnDL tells you that the value is a module-scope Boolean, but it doesn't tell you what the value means (and variables with such terrible names are all too common). The name mblnDataIsLoaded is much more descriptive.

Building an all-encompassing naming convention that defines abbreviations for every conceivable type of data, control, object, database component, menu, constant, and routine name takes a lot of time and more space than it's worth in a book such as this. For an article that describes the conventions used by Microsoft Consulting Services, go to support.microsoft.com/kb/110264. It explains everything, including data type abbreviations, making the first part of a function name contain a verb (GetUserName rather than UserName), and commenting conventions.

Naming and coding conventions make it easier for other programmers to read your code. Look over the Microsoft Consulting Services conventions or search the Web for others. Select the features that you think make the most sense and ignore the others. It's more important that you write consistent code than that you follow a particular set of rules.

Two of the most important things you control with a variable declaration are its data type and its visibility. Visibility combines scope (the piece of code that contains the variable such as a For loop, subroutine, or module), accessibility (the code that is allowed to access the variable determined by keywords such as Private, Public, and Friend), and lifetime (when the variable has been created and not yet destroyed).

To avoid confusion, explicitly declare the data type whenever possible and use the most limited scope possible for the variable's purpose. Turn Option Explicit and Option Strict on to allow the IDE to help you spot potential scope and type errors before they become a problem.

Code that uses LINQ complicates matters somewhat. When you use LINQ, it is generally not possible to declare explicitly every variable's data type. A LINQ query returns a sequence of objects that have an anonymous type. If you enumerate over the sequence, the looping variable will be of the same anonymous type. In those cases, when you cannot explicitly declare a variable's type, use extra caution to make the code easy to understand so you can fix and maintain it later. For more information on LINQ, see Chapter 21.

Parameters, property procedures, and constants have similar data types and scope issues. Once you become comfortable with variable declarations, they should give you little trouble.

One of the most important steps you can take to make your code easier to debug and maintain is to make your code consistent. A good naming convention can help. Review the guidelines used by Microsoft Consulting Services, and adopt the pieces that make the most sense to you.

When you know how to declare variables, you are ready to learn how to combine them. Chapter 16, "Operators," explains the symbols (such as +, 2, and ^) that you can use to combine variables to produce new results.