%Is

This special method tests an object, or a field of an object, to determine its type or what it contains.

All special method names and keywords are case-insensitive.

Syntax

{connection->}%Is(keyword, object1)

object2->%Is(keyword, "field")

Syntax elements

connectionA connection object. The default connection object does not have to be named (although it can be).

object1An expression that may or may not evaluate to an internal object. A non-object always causes %Is to return zero, irrespective of the keyword.

object2An expression that evaluates to an internal object.

fieldAn expression that evaluates to a field name in object2. Note that it must be quoted.

keywordSelects a required operation:

NullReturns non-zero if object1 or field is null.

ObjectReturns non-zero if object1 is a (non-array) object or if field contains an object.

ArrayReturns non-zero if object1 is an array object or if field contains an array.

BooleanReturns non-zero if field contains a Boolean.

NumberReturns non-zero if field contains a number.

StringReturns non-zero if field contains a string.

UndefinedReturns non-zero if field is undefined.

Applicability

Internal objects only.

Comments

Note that in the second variant of the method an object2 is required, and field cannot evaluate to an object; in either case a run time exception will be thrown.

The Undefined keyword is useful to check for the presence of a field without throwing an exception.

Examples

Tests the type of objects:

MyArrayObject = %Array()
MyNewObject   = %New()
MyNullObject  = %Null()

IF %Is(Array,  MyArrayObject) THEN PRINT "This object is an array "  ELSE PRINT "FAIL"
IF %Is(Object, MyNewObject)   THEN PRINT "This object is an object " ELSE PRINT "FAIL"
IF %Is(Null,   MyNullObject)  THEN PRINT "This object is null "      ELSE PRINT "FAIL"

Tests the type of fields:

Vehicle = %New()
Engine  = %New()
Engine->Fuel = "Diesel"

Vehicle->Year      = 2018
Vehicle->Make      = "Suzuki"
Vehicle->Emissions = %Array()
Vehicle->Engine    = Engine
Vehicle->Warranty  = %Null()
Vehicle->Imported  = (bool)1

IF Vehicle->%Is(Number,    "Year")      THEN PRINT "This field is a number "  ELSE PRINT "FAIL"
IF Vehicle->%Is(String,    "Make")      THEN PRINT "This field is a string "  ELSE PRINT "FAIL"
IF Vehicle->%Is(Array,     "Emissions") THEN PRINT "This field is an array "  ELSE PRINT "FAIL"
IF Vehicle->%Is(Object,    "Engine")    THEN PRINT "This field is an object " ELSE PRINT "FAIL"
IF Vehicle->%Is(Null,      "Warranty")  THEN PRINT "This field is null "      ELSE PRINT "FAIL"
IF Vehicle->%Is(Boolean,   "Imported")  THEN PRINT "This field is boolean "   ELSE PRINT "FAIL"
IF Vehicle->%Is(Undefined, "TaxBand")   THEN PRINT "This field is undefined " ELSE PRINT "FAIL"

See also

%Array, %New, %Null