See Array? No, cArray!

This tutorial demonstrates some of the functionality provided by the cArray class. These methods provide a means to manipulate and inspect an array.

VB has a wide variety of arrays that can be created, but only a few methods to aid in managing them. Some of the most basic functionality need to be built by hand. That is where cArray comes to help.

cArray is not a class you instantiate. The methods are publicy available by typing cArray.[method name]. Being constantly available gives easy access to these methods without having to worry about keeping track of some utility object.

This tutorial will demonstrate a few of the basic methods that can help in managing arrays with common tasks.

Many times an array may not have been initialized to a valid array. There is no built-in way to determine if the array is still uninitialized (I am aware of the use of Not to test the array, but is non-intuitive.) cArray provides the function cArray.IsNull to determine if an array has been dimmed.

    Dim Strings() As String
    Debug.Print "Is uninitialized: "; cArray.IsNull(Strings)
    ' output
    ' Is uninitialized: True

Another task performed is initializing an array to set of values. Currenty in VB the method used to set values is to manually set each element in the array, or loop and set each value per loop iteration. Using cArray.NewArray an initialized array can be created and initialized to the specified values.

    Strings = cArray.NewArray(ciString, "Five", "Four", "Three", "Two", "One")

    Debug.Print "LBound: "; LBound(Strings)
    Debug.Print "UBound: "; UBound(Strings)
    ' output
    ' LBound: 0
    ' UBound: 4

    Dim i As Long
    For i = 0 to 4
        Debug.Print "Element at index "; i; " = "; Strings(i)
    Next i
    ' output
    ' Element at index 0 = Five
    ' Element at index 1 = Four
    ' Element at index 2 = Three
    ' Element at index 3 = Two
    ' Element at index 4 = One

Once an array has been initialized, the index for a specific value can be retrieved by performing a cArray.IndexOf function call. This function allows the array to be in any order and still perform a search.

    Debug.Print "Index of 'Two': "; cArray.IndexOf(Strings, "Two")
    ' output
    ' Index of 'Two': 3

A more efficient search is the cArray.BinarySearch. In order for this type of search to be successful the array must be sorted. Sorting an array is a trivial task using cArray. To sort an array the cArray.Sort function is used.

    cArray.Sort Strings

    For i = 0 To 4
        Debug.Print "Element at index "; i; " = "; Strings(i)
    Next i
    ' output
    ' Element at index 0 = Five
    ' Element at index 1 = Four
    ' Element at index 2 = One
    ' Element at index 3 = Three
    ' Element at index 4 = Two

    Debug.Print "Index of 'Two': "; cArray.BinarySearch(Strings, "Two")
    ' output
    ' Index of 'Two': 4

Another aspect of arrays that are needed is the length or number of elements. To retrieve the number of elements in an array use the cArray.GetLength function. This function returns the total number of elements across all dimensions, unless a specific dimension is specified, then only the number of elements in that dimension is returned.

    Debug.Print "Number of elements: "; cArray.GetLength(Strings)
    ' output
    ' Number of elements: 5

    Dim TwoDimensions(1, 1) As Long
    Debug.Print "Number of elements: "; cArray.GetLength(TwoDimensions)
    ' output
    ' Number of elements: 4

    Debug.Print "Number of dimensions: "; cArray.GetRank(TwoDimensions)
    ' output
    ' Number of dimensions: 2

One operation that is performed is the copying of elements from one array to another array. Using cArray.CopyEx a portion of an array can be copied to a destination array.

    Dim ThreeStrings(2) As String

    ' copies a total of 3 elements starting at index 2 in Strings 
    ' into ThreeStrings starting at index 0.
    cArray.CopyEx Strings, 2, ThreeStrings, 0, 3

    For i = 0 To 2
        Debug.Print ThreeStrings(i)
    Next i
    ' output
    ' One
    ' Three
    ' Two

This tutorial shows several of the functions always available by using the cArray class function. It provides many functions used to manipulate and inspect arrays without the need to maintain an object to perform these common tasks.

For more information about the functions provided by cArray please refer to cArray in the Docs.