Methods and Properties

Methods and properties use member syntax to work with values and objects.

A method call uses parentheses:

object.method(arguments);

A property read does not use parentheses:

object.property;

Methods perform actions or calculations. Properties expose named values.

A method is called with a target value, a dot, the method name, and an argument list.

value.to_string();
text.parse_num();
items.size();
window.show();

The target expression is evaluated first. Then the arguments are evaluated from left to right. Then the method is invoked.

result = object.method(a + 1, b + 2);

Parentheses are required for a method call, even when the method has no arguments.

items.size();        // method call
items.size;          // property read or method reference, depending on object

A method call produces a value and can be used inside a larger expression.

if(value.is_num_notnan() && value > 0)
{
    print(value.to_string());
};

Expr has several kinds of methods:

• value methods on built-in value types, such as numbers and strings
• methods on built-in objects, such as arrays, maps, timers, GUI controls, serial objects, and image objects
• methods defined inside Expr classes
• callable-object methods, such as `call(…)` on function references and method references

Examples:

(123).to_hex();       // number method
'123'.parse_num();    // string method
array(1, 2).size();   // array object method

Built-in functions are different. They are called without a target object:

str(123);             // built-in function
(123).to_string();    // method

Numbers, strings, `none()`, and object values support common type-check methods.

value.is_none();
value.is_nan();
value.is_num();
value.is_num_notnan();
value.is_string();

Numbers also provide conversion helpers.

(255).to_string();
(255).to_hex();
(255).to_bin();

Strings provide parsing helpers.

'123'.parse_num();
'FF'.parse_hex();
'true'.parse_bool();

For the detailed type and conversion method list, see Type system.

Built-in object constructors return objects with their own method sets.

items = array(1, 2, 3);
items.add(4);
items.size();
 
settings.SomeSetting();

Object methods are implemented by the object type. If an object does not implement a requested method, Expr raises a runtime error.

items.unknown_method();    // error

Object methods usually return one of these:

• a result value
• `true` or `false` as a boolean-style number
• the object itself, to allow method chaining
• `none()` when there is no useful value

Method chaining depends on the object method returning the object.

win = window()
    .title('Setup')
    .size(360, 220);

Not every method supports chaining.

Methods in Expr classes are declared with `function` inside the class body.

class Counter(start)
{
    value = start;
 
    function Inc()
    {
        value += 1;
        return value;
    }
 
    function Read()
    {
        return this.value;
    }
}
 
c = Counter(10);
c.Inc();              // 11
c.Read();             // 11

Only `function` declarations inside a class become methods.

Method calls on class instances use the same syntax as built-in object method calls.

object.Method(a, b);

Method overloading by argument count is not supported for user-defined Expr class methods. Use different method names when different behavior is needed.

`this` is available inside class constructors and class methods.

It refers to the current object instance.

class Counter(start)
{
    value = start;
 
    function Add(amount)
    {
        this.value += amount;   // not supported as property assignment
    }
}

Direct property assignment through `this.value = …` or `this.value += …` is not supported. Assign the field by its bare name inside object context.

class Counter(start)
{
    value = start;
 
    function Add(amount)
    {
        value += amount;
        return this.value;
    }
}

Use `this.field` when you need to read a field explicitly, especially when a local variable or parameter has the same name.

class Tool(numberIn)
{
    number = numberIn;
 
    function Set(newNumber)
    {
        this.SetNumber(newNumber);
    }
 
    function SetNumber(valueIn)
    {
        number = valueIn;
    }
}

For an explicit method call:

object.Method(arguments);

Expr asks the target object for `Method`.

Inside a class method, a bare function-style call can resolve to a method on `this` before falling back to root/session functions and built-in functions.

class Counter(start)
{
    value = start;
 
    function Add(amount)
    {
        value += amount;
        return value;
    }
 
    function AddTwice(amount)
    {
        return Add(amount) + Add(amount);
    }
}

In this example, `Add(amount)` inside `AddTwice()` calls the object method.

Use `this.Add(amount)` when you want the method call to be explicit.

A class method can be referenced without calling it.

class DialogScript()
{
    function OnClick()
    {
        print('clicked');
    }
 
    function Build()
    {
        btn = textbutton();
        btn.on_click(this.OnClick);
    }
}

`this.OnClick` is a method reference. It can be passed to APIs that expect a callback.

Method references are object values. Like function references, they can be invoked with `call(…)` when the receiving object expects a callable value.

callback = this.OnClick;
callback.call();

Callback argument rules depend on the object or host API that invokes the callback.

A property read uses dot syntax without parentheses.

object.property;

For Expr class instances, object fields can be read as properties.

class Point(xIn, yIn)
{
    x = xIn;
    y = yIn;
}
 
p = Point(10, 20);
p.x;                  // 10
p.y;                  // 20

`this.property` reads a property from the current object.

class Point(xIn, yIn)
{
    x = xIn;
    y = yIn;
 
    function Sum()
    {
        return this.x + this.y;
    }
}

Built-in objects may also expose properties. The available properties depend on the object type.

If a property does not exist, Expr raises a runtime error.

p.z;                  // error if z is not defined

Direct assignment to a property is not supported.

object.property = 10;      // not supported
this.property = 10;        // not supported
object.property += 1;      // not supported

To change object state from outside an object, use a method provided by that object.

slider.value(50);
window.title('Setup');

To change an Expr class field from inside a constructor or method, assign the field by bare name.

class Counter(start)
{
    value = start;
 
    function Set(valueNew)
    {
        value = valueNew;
    }
}

This rule is important: `this.value` reads the field, but `value = …` updates the field when there is no local variable named `value`.

Inside a method, `set` creates a local variable. It does not update an object field.

class Counter(start)
{
    value = start;
 
    function Preview()
    {
        set value = this.value + 1;
        return value;
    }
}

The object field remains unchanged.

Plain assignment updates an existing local variable first. If no matching local variable exists, object context can update or create an object field.

class Counter(start)
{
    value = start;
 
    function Inc()
    {
        value += 1;
        return value;
    }
}

For full assignment rules, see Variables and assignment.

items.size;           // property read or reference, not a call
items.size();         // method call

this.value = 5;       // not supported

Use bare field assignment inside methods:

value = 5;

class C()
{
    value = 1;
 
    function Test()
    {
        set value = 2;
        return this.value;
    }
}

`this.value` still reads the object field, which is `1`.

Previous: Built-in functions

Next: Built-in methods