Method

Operator_Convert


Description

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

Notes

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.

Important

This is not currently supported for Android.


Advanced information

Constructors aren't called when doing a convert-to operation. That's 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 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
Var c As SomeClass = "12"
Var 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
Var 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 String)
  Self.FullName = name
End Sub

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

Var 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 String value:

Function Operator_Convert As String
  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:

Var 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:

Var v As Vector = 10
MessageBox(v)

Compatibility

Desktop, console, web and iOS project types on all supported operating systems.