Inspection and Identification of Variables

OOo Basic contains numerous functions to inspect and identify variables (see Table 12 ). These routines are frequently used when you call a function and aren't certain of the return type. These routines are also useful for debugging. For example, you could use these functions to verify that a return type is valid.

Table 12: Variable inspection functions in OOo Basic.
Function	Description
IsArray	Is the variable an array?
IsDate	Does the string contain a valid date?
IsEmpty	Is the variable an empty Variant variable?
IsMissing	Is the variable a missing argument?
IsNull	Is the variable an unassigned object?
IsNumeric	Does the string contain a valid number?
IsObject	Is the variable an object?
IsUnoStruct	Is the variable a UNO structure?
TypeName	Return the type name of the object as a String.
VarType	Return the variable type as an Integer.

Use IsArray to see if a variable is an array (see Listing 23 ). If IsArray returns True, it does not imply that the variable has data or even that it is dimensioned-merely that it exists and is defined as an array. The UBound and LBound functions, as already discussed, return the upper and lower bounds of the array.

Listing 23: Use IsArray to see if a variable is an array.

 Dim n As Long      'This is NOT an array Dim a() As String  'This is an array Dim b(5)           'This is an array Dim v As Variant   'This is not an array yet Print IsArray(v)   'False Print IsArray(n)   'False Print IsArray(a)   'True Print IsArray(b()) 'True ReDim v(3)         'It is an array now! Print IsArray(v()) 'True

Use the IsDate function to test if a string contains a valid date (see Listing 24 ). The arguments are converted to a string before they are used, so numeric arguments return False. The IsDate function tests more than just syntax; it checks to see if the string contains a valid date. The same check is not made on the time component of the string.

Listing 24: IsDate verifies that a string contains a valid date.

 Print IsDate("December 1, 1582 2:13:42") 'True Print IsDate("2:13:42")                  'True Print IsDate("12/1/1582")                'True Print IsDate(Now)                        'True Print IsDate("26:61:112")                'True Print IsDate(True)                       'False converts to string first Print IsDate(32686.22332)                'False converts to string first Print IsDate("02/29/2003")               'False, only 28 days in February 2003

Like the IsDate function, the IsNumeric function looks at strings (see Listing 25 ). If the argument is not entirely a solitary valid number, except for leading or trailing spaces and enclosing quotation marks, it returns False.

Listing 25: IsNumeric is very picky about what it accepts.

 Print IsNumeric(" 123")    'True Print IsNumeric(" 12 3")   'False Print IsNumeric(1.23)      'True Print IsNumeric("123abc")  'False Print IsNumeric(True)      'False Print IsNumeric(Now)       'False

Variant variables start with no value at all; they are initially empty. Object variables are initialized with the value null. Use the functions IsEmpty and IsNull to test these conditions. Use the IsObject function to determine if a variable is an object.

 Dim v As Variant   'Starts as not initialized, Empty Dim o As Object    'Initialized to null Print IsObject(v)  'False  No, a Variant is not an Object Print IsObject(o)  'True   Yes, this is an Object Print IsEmpty(v)   'True   Variants start as Empty, not initialized Print IsNull(v)    'False  To be null, a Variant must contain something Print IsEmpty(o)   'False  Variants start as Empty, not Objects Print IsNull(o)    'True   Objects start as null v = o Print IsObject(v)  'True   The variant just became an Object. Print IsEmpty(v)   'False  Variant now contains a value (an Object) Print IsNull(v)    'True   Variant contains a null Object

Use the IsMissing function to determine if an optional argument is missing. Usually, some default value is used if an argument is missing.

 Sub TestOptional   Print "Arg is ";ExampleOptional()         'Arg is missing   Print "Arg is ";ExampleOptional("hello")  'Arg is hello End Sub Function ExampleOptional(Optional x) As String   ExampleOptional = IIF(IsMissing(x), "Missing", CStr(x)) End Function

Tip	Computer scientists typically refer to structures using the shortened name "struct."

Use the function IsUnoStruct to determine if a variable contains a structure defined by OpenOffice.org.

 Dim v Print IsUnoStruct(v)                               'False v = CreateUnoStruct("com.sun.star.beans.Property") 'Create a UNO Print IsUnoStruct(v)                               'True

Use the TypeName function for a string representation of the variable's type. The VarType function returns an integer corresponding to the variable type. Table 13 contains a list of the possible types. The first column, labeled BASIC, indicates if the type is common to BASIC and therefore likely to be seen. The other values represent types that are internal to OOo. OOo Basic typically maps internal types to standard OOo Basic types, so you aren't likely to see these other types. They are, however, contained in the source code and they are included for completeness.

Table 13: Variable types and names .
BASIC	VarType	TypeName	Len	Description
yes		Empty		Variant variable is not initialized
yes	1	Null		No valid data in an Object variable
yes	2	Integer	2	Integer variable
yes	3	Long	4	Long Integer variable
yes	4	Single	4	Single floating-point variable
yes	5	Double	8	Double floating-point variable
yes	6	Currency	8	Currency variable
yes	7	Date	8	Date variable
yes	8	String	strlen	String variable
yes	9	Object		Object variable
no	10	Error	2	Internal OOo type
yes	11	Boolean	1	Boolean variable
yes	12	Variant		Variant variables act like any type
no	13	DataObject		Internal OOo type
no	14	Unknown Type		Internal OOo type
no	15	Unknown Type		Internal OOo type
no	16	Char	1	Internal OOo type, a single text character
yes	17	Byte	1	Internal OOo type, but you can use CByte to create one
no	18	UShort	2	Internal OOo type, unsigned short integer (16 bits)
no	19	ULong	4	Internal OOo type, unsigned long (32 bits)
no	20	Long64	8	Internal OOo type, long (64 bits)
no	21	ULong64	8	Internal OOo type, unsigned long (64 bits)
no	22	Int	2	Internal OOo type, integer (16 bits)
no	23	UInt	2	Internal OOo type, unsigned integer (16 bits)
no	24	Void		Internal OOo type, no value
no	25	HResult		Internal OOo type
no	26	Pointer		Internal OOo type, pointer to something
no	27	DimArray		Internal OOo type
no	28	CArray		Internal OOo type
no	29	Userdef		Internal OOo type, user -defined
no	30	Lpstr	strlen	Internal OOo type, long pointer to a string
no	31	Lpwstr	strlen	Internal OOo type, long pointer to a "Wide" Unicode string
no	32	Unknown Type		Internal core string type
no	33	WString	strlen	Internal OOo type, "Wide" Unicode string
no	34	WChar	2	Internal OOo type, "Wide" Unicode character
no	35	Int64	8	Internal OOo type, integer (64 bits)
no	36	UInt64	8	Internal OOo type, unsigned integer (64 bits)

Use the TypeLen function to determine how many bytes a variable uses. The returned value is hard coded for every value except for the strings, which return the length of the string. Array variables always return a length of zero. The macro in Listing 26 generates all of the standard BASIC types, places them into an array, and builds a string containing the type, length, and type name, as shown in Figure 7 .

Figure 7: Variable types, lengths, and names.

Listing 26: ExampleTypes is found in the Misc module in this chapter's source code files as SC08.sxw.

 Sub ExampleTypes   Dim b As Boolean   Dim c As Currency   Dim t As Date   Dim d As Double   Dim i As Integer   Dim 1 As Long   Dim o As Object   Dim f As Single   Dim s As String   Dim v As Variant   Dim n As Variant   Dim ta()   Dim ss$   n = null   ta() = Array(v, n, i, 1, f, d, c, t, s, o, b, CByte(3))   For i = LBound(ta()) To UBound(ta())     ss = ss & ADPTypeString(ta(i))   Next   MsgBox ss, 0, "Type, Length, and Name" End Sub Function ADPTypeString(v) As String   Dim s As String              'Hold the return string   Dim i As Integer             'Dummy integer value   s = s & "Type = "            'Leading type string   i = VarType(v)               'Get the type   If i < 10 Then s = S & "0"   'Leading zero if required   s = s & CStr(i)              'Add the type number   If IsArray(v) Then     s = s & " ("     i = i AND NOT 8192     If i < 10 Then s = S & "0" 'Leading zero if required     s = s & CStr(i) & ")"      'Add the type number   Else     s = s & " Len = "            'Leading length string     i = TypeLen(v)               'What is the length     If i < 10 Then s = S & "0"   'Leading zero if required     s = s & CStr(i)              'Add in the length   End If   s = s & " Name = "           'Leading Name string   s = s & TypeName(v)& CHR$(10)'Add in the name and a new-line character   ADPTypeString = s            'Return value for the function End Function

The function ADPTypeString does the work of generating the display string. It gives special handling to arrays, because the returned type numbers for arrays are completely different than the type numbers for the standard variables. At least they seem that way until you start looking very closely at the numbers . If the thought of twiddling bits makes you tremble, skip the rest of this paragraph. The value returned by VarType for an array always has bit 14 set-a 1 followed by 13 zeros in binary. This is 8192 in decimal and 2000 in hexadecimal. The IsArray function is implemented by checking bit 14 of the VarType. If you clear bit 14, the number that remains tells you what numeric type is used for the array. The NOT operator clears every bit that is set and sets every bit that is clear, so NOT 8192 provides the number with every bit set except for bit 14. If you AND this with the type, it clears bit 14, leaving the rest of the bits intact.

 i = i AND NOT 8192

The length of an array is always returned as zero, so I didn't include this by VarType in Listing 26. The code in Listing 27 is similar to Listing 26 but the types are arrays. Notice that the type name for array types contains parentheses "()" following the name (see Figure 8 ).

Figure 8: Types, lengths, and names for array variables.

Listing 27: ExampleTypes is found in the Misc module in this chapter's source code files as SC08.sxw.

 Sub ExampleTypesArray   Dim b() As Boolean   Dim c() As Currency   Dim t() As Date   Dim d() As Double   Dim i() As Integer   Dim 1() As Long   Dim o() As Object   Dim f() As Single   Dim s() As String   Dim v() As Variant   Dim ta(), j%   Dim ss$   ta() = Array(i, 1, f, d, c, t, s, o, b, v)   For j% = LBound(ta()) To UBound(ta())     ss = ss & ADPTypeString(ta(j%))   Next   MsgBox ss, 0, "Type, Length, and Name" End Sub