Operator Convert

From Xojo Documentation

Global Method

Operator_Convert(rightSide As Type)

Supported for all project types and targets.

Used to convert from one type to another, providing custom functionality.

Global Method

Operator_Convert() As Type

Supported for all project types and targets.

Used to convert from one type to another, providing custom functionality.


When you use the convert-to form of the operator (the one with a parameter), the compiler needs to create a new object implicitly so that you can copy data into it. When you use a convert-to operator, the compiler needs to create a new instance of the item it located the Operator_Convert method on, and then it calls that method to complete the conversion. When it creates the new instance of the item, it does not call any constructors for it. The Operator_Convert method takes the place of the constructor.

When you use a convert-from operator (the one without a parameter), the compiler doesn't have to do any extra work. Whenever an implicit (or explicit) conversion needs to take place, the compiler looks for the convert-from operator, and if it finds one, it calls it. The function itself already does all of the conversion work.

Advanced Information

Constructors aren't called when doing a convert-to operation. That's simply something to be aware of. If you're doing required work in your constructor, you'll need to perform that work yourself in the conversion. This generally won't need to happen, since most constructors simply initialize things to sensible values, and conversion operations would do exactly the same thing. But if you are doing some sort of Declare work, it may still be necessary. For instance, let's say that you were doing some sort of COM work on Windows. Your Operator_Convert method had better call CoInitialize just to be on the safe side.

Another issue with convert-to operators is that they won't work for interfaces. There's no way for the compiler to instantiate a new instance of an interface. That means the following code can be quite confusing:

Interface SomeInterface
Sub Operator_Convert(rhs As String)
End Interface
Class SomeClass
Implements SomeInterface
Sub Operator_Convert(rhs As String)
End Sub
End Class
Dim c As SomeClass = "12"
Dim c1 As SomeInterface = "32"

This code may look perfectly sensible, but you will get a compile error at about c1 = "32". The problem is that the compiler cannot create a new instance of SomeInterface, even though it is perfectly legal to do so for SomeClass.

Sample Code

A Person class using Operator Convert:

// Person is a class with a property FullName As Text
Dim p1 As New Person
p1.FullName = "Bob Roberts"

// You can define an Operator_Convert method on Person to allow
// the name to be assigned directly:
Sub Operator_Convert(name As Text)
Self.FullName = name
End Sub

Now you can write code like this, which takes a Text value and converts-to to a new instance of Person:

Dim p2 As Person
p2 = "Bob Roberts" // p2.FullName = "Bob Roberts"

You can also define an Operator_Convert method on Person which converts-from the Person to a Text value:

Function Operator_Convert As Text
Return Self.FullName
End Function

// This allows you to write code like this,
// which converts from a Person to a Text value for use by a Label:
Label1.Text = p2

The following code converts to a Vector from an Integer (The Vector class is defined in Operator_Add.) The Operator_Convert method is added to the Vector class.

Sub Operator_Convert(rhs As Integer)
Self.x = rhs
Self.y = rhs
End Sub

You use this definition of the Operator_Convert method like this:

Dim v As Vector
v = 10 // both elements of V get the value 10

Note that the New operator is not needed here. This is because the assignment operator is returning a new instance of Vector. If you were to write v=New Vector, it would create one instance of Vector but that would be overwritten by the assignment statement.

The second type of conversion is a "convert-to" conversion. Use this when you want to convert the class to another type. In the following example, the Vector is converted to a string that represents its square length.

Function Operator_Convert As String
Return Str(Self.x ^ 2 + Self.y ^ 2)
End Function

After defining both forms of Operator_Convert, you can use them with code like this:

Dim v As Vector = 10

The first line invokes the data type conversion in the first example and assigns 10 to both elements of the Vector object. The second line computes the square length and returns it as a String.

See Also

Operator Overloading