pointertype

Syntax A pointerType is one of:

 (a)[unchecked] pointer to collectionId
   % Short form: ^ collectionId
 (b)[unchecked] pointer to classId
   % Short form: ^ classId
 (c)[unchecked] pointer to typeSpec
   % Short form: ^ typeSpec

Description   A variable declared as a pointer type is used to locate an element of a collection or class or a value of a type. The new statement creates a new element (or value) and places the element's location in a pointer variable. The free statement destroys an element located by a pointer variable.

Example   Using a collection, declare a list or records and allocate one record.

        var list : collection of
            record
                contents : string ( 10 )
                next : pointer to list
            end record
        var first : pointer to list
        new list, first
Example   Create a collection that will represent a binary tree.

        var tree : collection of
            record
                name : string ( 10 )
                left, right : pointer to tree
            end record
        
        var root : pointer to tree
        new tree, root
        tree ( root ).name := "Adam"
Example   Using a class, create an object of that class. The object is located by the start pointer. The name field of the object is set to Ed. 

        class node
            export var next, var name
            name : string ( 25 )
            next : pointer to node  % Short form: next : ^ node
        end node
        var start : pointer to node % Short form: var start : ^ node
        new node, start         % Short form: new start
        node ( start ) . name := "Ed"   % Short form: start->name:="Ed"
Details   For collections and classes, a pointer is effectively a subscript (an index) for that collection or class. Pointers can be assigned, compared for equality and passed as parameters.

The keywords pointer to can be replaced by the short form ^, as in

        var first : ^ item
Given a pointer p that locates an object of class or collection C, the object is referenced as C(p) or as the short form ^ p. A field f of the object is referenced as C(p).f or ^p.f or as the short form p->f. For example, in the class given above, the name field of the object located by the start pointer can be set to Alice by:

        start -> name := "Alice"
Pointers to types use the same notation, except that pointers to types are not allowed to use the form typeSpec(p). See class for an example of the use of a class with pointers.

The carat ^ is called the dereferencing operator and has the highest precedence. For example, in ^ p.a, the carat applies to p and not to p.a. To apply ^ to all of p.a, use parentheses: ^(p.a). Several carats can appear in a row, for example,

        var r : ^ ^ int
declares a pointer to a pointer to an integer and ^ ^ r is the notation for referencing the integer.

A reference cannot begin with a left parenthesis, but can be surrounded by ^(…), as in ^ (q.b). If f is a parameterless function declared without parentheses that returns a pointer, the form ^ f calls f before dereferencing the pointer.

By default, all pointers are checked. This means there is a run time test to make sure that references such as C(p) actually locate elements, i.e., that p is initialized, is not nil and is not dangling (locating an object that has been freed). This checking requires extra space (the implementation attaches a time stamp to each pointer and object) and time. In high-performance programs in which this extra space and time are not acceptable, the pointer can be declared to be unchecked. When this is done, the program becomes dangerous and it is the programmer's responsibility to make sure that all pointer usage is valid.

If this is not the case, the program becomes susceptible to uncontrolled crashes.

Checked pointers cannot be assigned to unchecked pointers nor vice versa. However, you may, at your peril, use an implementation-dependent type cheat, to convert a checked pointer to a unchecked pointer, as in:

        type checkedPtr : ^ R
        type uncheckedPtr : unchecked ^ R
        var c : checkedPtr          % c is an checked pointer
        var u : uncheckedPtr        % u is an unchecked pointer
        …
        u := cheat (uncheckedPtr, d)    % This is a type cheat
Unchecked pointers are equivalent to the pointers of the C language, which are inherently error prone and cause difficult to locate bugs. An entire collection (but not a class) can be declared unchecked, in which case all of its pointers are implicitly unchecked. See collection.

See also   inherit lists for a description of the assignability rules for pointers. See classes and collections for more details about the use of pointers. See also new and free statements. See also nil, objectclass and anyclass.