View source for Dynamic type testing

Sometimes, you need to decide at run-time if a variable 
(or [[Glossary#Expression|expression]]) refers to an instance of a specific class or type.
Well, it is almost always better to rely on [[dynamic dispatch]], but, in some situations, it can be necessary
to explicitly test the [[Glossary#DynamicType|dynamic type]] of some expression.
While other languages provide a cast operator to do (unsafe) type casting, Liberty Eiffel provides you three operators for doing that:
the 
[[#AssignmentTest|<tt>?:=</tt>]] assignment test operator, 
the [[#ForcedAssignment|<tt>::=</tt>]] forced assignment statement as well as the 
traditional [[#AssignmentAttempt|<tt>?=</tt>]] assignment attempt statement.

For some examples about dynamic type testing, check also the 
<tt>tutorial/downcasting.e</tt> file.

Please note that assignment testing cannot be used with [[Expanded_or_reference|expanded types]], for which [[dynamic dispatch]] is not applicable.

<div id="AssignmentTest">
== The <tt>?:=</tt> assignment test ==
</div>
The assignment test <tt>?:=</tt> is a [[library_class:BOOLEAN|<tt>BOOLEAN</tt>]] expression
allowing you to check if the given right-hand side expression refers to an object which conforms to
some explicitly written type.
As an example, you can use the <tt>?:=</tt> operator as follows to check that 
some <tt>expression</tt> actually holds an instance which could be assigned to some 
variable declared with <tt>SOME_TYPE</tt>:
 if {SOME_TYPE} ?:= expression then
     print ("The 'expression' denotes something which can be held by the variable declared of type SOME_TYPE.")
 else
     print ("Something else which is non Void.")
 end
It evaluates <tt>expression</tt> and returns <tt>True</tt> if the resulting object 
can be legally assigned to some variable declared of type <tt>SOME_TYPE</tt>. 
To take now a more concrete example using existing types of our library:
 if {FAST_ARRAY[INTEGER]} ?:= my_collection then
     print ("Expression 'my_collection' is either Void or conforms to FAST_ARRAY[INTEGER].")
 else
     print ("Something else which is non Void.")
 end
In the previous example, <tt>my_collection</tt> is declared of type 
[[library_class:COLLECTION|<tt>COLLECTION</tt>]]<tt>[</tt>[[library_class:INTEGER|<tt>INTEGER</tt>]]<tt>]</tt>.
As explained below, [[library_class:COLLECTION|<tt>COLLECTION</tt>]]<tt>[</tt>[[library_class:STRING|<tt>STRING</tt>]]<tt>]</tt> would make the previous code 
invalid thus rejected by the compiler.

To avoid testing impossible situations which are probably coding mistakes, one cannot use any 
type for the right-hand side of a <tt>?:=</tt> test expression.
The rule is simple and naturally related to the rule used for an ordinary assignment 
(the common well known <tt>:=</tt> assignment).
Consider the following general example:
 if {SOME_TYPE} ?:= some_expression then
     ...
 else
     ...
 end
The check performed by the compiler is that an expression of type <tt>SOME_TYPE</tt> could be 
legally assigned to some variable declared of the 
[[Glossary#StaticType|static type]] of <tt>some_expression</tt>.
Actually, this simply means that you trust the type system and that you really want to reject 
invalid or, to say the least, weird code.
Because of the redefinition mechanism, the validation check for the <tt>?:=</tt> operator is only 
performed at the class where it appears, and is '''not''' revalidated in subtypes even if they 
redefine the static type of <tt>some_expression</tt>.
The latest decision was driven by our experimentations. 
We made this decision because the strict rule would reject mostly valid situations.
Similar checks are performed for all other statements of the same family 
(the [[#ForcedAssignment|<tt>::=</tt>]] statement 
and the [[#AssignmentAttempt|<tt>?=</tt>]] statement).

As we have seen previously, the left-hand side operand of the <tt>?:=</tt> type test can be some 
explicit type name.
The second form of the <tt>?:=</tt> test operator is to be used in place of the 
explicit type, some [[Syntax diagrams#Writable|writable]] entity as in:
 if my_variable ?:= expression then
    ...
 else
    ...
 end
which evaluates to <tt>True</tt> iff the actual content of <tt>expression</tt> 
''could be assigned'' to <tt>my_variable</tt>.
Note that the assignment is '''not''' performed.
This variant avoids the need to repeat the static type of <tt>my_variable</tt> here.
It is also because the <tt>?:=</tt> type test operator is often used in conjunction with 
the [[#ForcedAssignment|<tt>::=</tt>]] forced assignment.

<div id="ForcedAssignment">

== The <tt>::=</tt> forced assignment ==
</div>
The <tt>::=</tt> forced assignment statement allows you to actually perform an assignment
proved valid at runtime with a corresponding [[#AssignmentTest|<tt>?:=</tt>]] assignment 
test.
As an example, the following code would always work without any possible 
runtime error:
 if destination_variable ?:= source_variable then
     destination_variable ::= source_variable
 else
     -- Handle this case specially...
 end
Actually, the <tt>?:=</tt> test can be considered as the precondition of the <tt>::=</tt> part.
In non <tt>-boost</tt> mode, when some <tt>::=</tt> statement is executed but does not
satisfy the <tt>?:=</tt> condition, you get an error at runtime.
In <tt>-boost</tt> mode no runtime check is performed and the runtime cost of a 
<tt>::=</tt> statement is exactly the runtime cost of a common 
<tt>:=</tt> statement.
A very low cost indeed.
Usage of <tt>::=</tt> can be slightly more efficient (and result in simpler code) than 
similar code using the traditional [[#AssignmentAttempt|<tt>?=</tt>]] assignment attempt.
Besides, it helps debugging because it will raise an exception when your assumption is not 
correct.

As explained for the [[#AssignmentTest|<tt>?:=</tt>]] assignment test, one can not use 
any combination of static types.
The same checks are performed for the <tt>::=</tt> statement.
To summarize checks that are performed, please consider:
 my_variable ::= expression
The entity <tt>my_variable</tt> must be a valid [[Syntax diagrams#Writable|writable]].
The declaration type of <tt>my_variable</tt> must be a possible valid source type of some 
normal assignment into some destination variable declared with the 
[[Glossary#StaticType|static type]] of <tt>expression</tt>.
Finally, the check in performed only where the <tt>::=</tt> is written.

<div id="AssignmentAttempt">

== The <tt>?=</tt> assignment attempt ==
</div>
The traditional assignment attempt <tt>?=</tt> statement is still supported for 
historical reasons.
Indeed, now that we have both the 
[[#AssignmentTest|<tt>?:=</tt>]] assignment test and
the [[#ForcedAssignment|<tt>::=</tt>]] forced assignment
statement, the <tt>?=</tt> statement is no longer necessary.
In the long-term future, let's say, one or two years, usage of 
<tt>?:=</tt> and <tt>::=</tt> may become the preferred coding style.
Again, there is no rush, and the traditional 
<tt>?=</tt> will be supported for some more years.
From a compiler writer's point of view, the support for <tt>?=</tt> is really cheap because
it is implemented in terms of <tt>?:=</tt> and <tt>::=</tt>.

Furthermore, it is easy and elegant to explain <tt>?=</tt> as a simple 
source code transformation using only <tt>?:=</tt> and <tt>::=</tt>.
Consider the following <tt>?=</tt> usage:
 destination_variable ?= source_variable
If the value of <tt>source_variable</tt> cannot be legally assigned
to <tt>destination_variable</tt>, the <tt>destination_variable</tt> will be set to 
[[Void|<tt>Void</tt>]] instead of the value of the <tt>source_variable</tt>.
Note that if <tt>source_variable</tt> actually contains <tt>Void</tt>, 
<tt>destination_variable</tt> will always be reset with <tt>Void</tt>.
Finally, the previous <tt>?=</tt> example can be translated into
the equivalent form:
 if destination_variable ?:= source_variable then
    destination_variable ::= source_variable
 else
    destination_variable := Void
 end
Note that the previous transformation scheme may not work for all kinds of 
right-hand side [[Glossary#Expression|expressions]]
because the transformation scheme incurs two evaluations of the right-hand side
part.
To be valid, the previous transformation scheme assumes that the right-hand side 
expression incurs no [[Glossary#SideEffect|side effect]].
Anyway, this transformation scheme is just here to explain the semantic of
the <tt>?=</tt>  statement and not as a general translation scheme to patch 
your (not so obsolete) code.

As explained for the [[#AssignmentTest|<tt>?:=</tt>]] assignment test,
one can not use any combination of [[Glossary#StaticType|static type]] on 
both sides of <tt>?=</tt> operator.
The very same kind of checks are performed for the <tt>?=</tt> statement.
To summarize checks, now consider:
 my_variable ?= expression
The entity <tt>my_variable</tt> must be a valid [[Syntax diagrams#Writable|writable]].
The declaration type of <tt>my_variable</tt> must be a possible source type of some normal
assignment into some destination variable declared with the 
[[Glossary#StaticType|static type]] of <tt>expression</tt>.
Finally, as usual the check is performed only where the <tt>?=</tt> statement is written.

Assuming that type <tt>TRUCK</tt> and type <tt>APPLE</tt> are completely distinct types (i.e.
you are not allowed to perform an assignment of <tt>TRUCK</tt> into <tt>APPLE</tt>
nor of <tt>APPLE</tt> into <tt>TRUCK</tt>), the following assignment attempt is statically
rejected, which is good news:
 my_apple ?= my_truck -- hopefully this is statically rejected!
You can always workaround by using the following trick:
     a_any := a_truck
     an_apple ?= a_any -- This is valid, APPLE conforms to ANY
The example above is clearly a weird one, but you could need something like this if you have two 
unrelated classes with a common heir. And at least the code shows that you know what you are doing.
This situation should arise in extremely rare situations only, that are not worth to be explained 
here.