Nil

From Xojo Documentation

Language Keyword

Used to determine if an object is nil (no value).

Usage

expression = Nil

Notes

Nil means no value. When an object is first instantiated, it is automatically initialized to Nil. Some functions will return a Nil value under certain circumstances. GetOpenFolderItem will return Nil if the user clicks the Cancel button when GetOpenFolderItem presents the standard open file dialog box.

Nil is a constant of its own datatype, not an Object. It can convert itself to any object class, any array type, or any of the pointer types (Ptr, WindowPtr, CString, PString, WString, and CFStringRef).

You can pass Nil for any of the string parameter types above (CString, PString, WString), but not for String. Passing Nil is not the same as passing the empty string, "". Passing Nil means you want to pass a null pointer. Passing "" means you want to pass a non-null pointer to the representation of "" for the declared format.

If you try to access an object that has a Nil value, a NilObjectException error will be generated. If you don't handle the exception, execution will stop. If you are testing the application in the IDE, you can choose Project ↠ Break on Exceptions to halt execution whenever a runtime exception error occurs and open the Debugger.

If the code executes in a built application, the user will see a generic error message before the application quits.

To prevent this, you should always test for Nil values, either with an If statement or by including a Try or Exception block at the end of the method.

Sample Code

This example uses Nil to determine if the user clicked the Cancel button in the standard open file dialog box presented by the GetOpenFolderItem function.

Dim f As New FolderItem("test.txt")
If f <> Nil Then
// use the FolderItem
End If

This example uses an Try...Catch block to handle NilObjectExceptions.

Dim d As Dictionary
Try
d.Value("Name") = "Mary"
Catch err As NilObjectException
ErrorLabel.Text = err.Message
End Try

See Also

RuntimeException class; Exception, Try statements; NilObjectException error.