Library Conventions

Sather - A Language Tutorial
Prev | Chapter 12. Built-in classes | Next

# 12.6. Library Conventions

In addition to '`create`', there are a number of other naming conventions:

- Classes which are related should reflect this in their names. For example, there are many examples in the library of an abstraction, classes implementing the abstraction, and code testing implementations of the abstraction. For example, in the standard library the set abstraction is named `$SET, H_SET` is a hash table implementation, and the test code is `TEST_SET`.

- Some classes implement an immutable, 'mathematical' abstraction (eg. integers), and others implement mutable "object" abstractions that can be modified in place (eg. arrays). For most objects, the mutable, object semantics are natural and efficient. However, for classes such as sets, the semantics may be different from those of the traditional mathematical set entities.

- Classes with immutable semantics are given their 'mathematical' names: STR, `VEC`, `$SET`. When separate abstractions exist to handle value and reference semantics, the method `value` will be provided in the reference version to provide an immutable snapshop of the reference class.

- Conversions from a type `FOO` to a type `BAR` occur in two ways: by defining an appropriate '`create(f:FOO):BAR`' routine in `BAR` as seen above, or be defining a routine '`bar:BAR`' in `FOO`. For example, in the standard library conversion of a `FLT` to a `FLTD` is done by calling the routine '`fltd:FLTD`' defined in `FLT`.

- Methods which return a `BOOL` (called predicates), usually have the prefix '`is_`'. For example, '`is_prime`' tests integers for primality.

- Abstract classes that require a single method should be named after that method. For example, subtypes of `$HASH` define the method '`hash`'.

- If there is a single iterator in a container class which returns all of the items, it should be named '`elt!`'. If there is a single iterator which sets the items, it should be named '`set!`'. In general, iterators should have singular ('`elt!`') rather than plural ('`elts!`') names if the choice is arbitrary.

## 12.6.1. Object Identity

Many languages provide built-in pointer and structural equality and comparison. To preserve encapsulation, in Sather these operations must go through the class interface like every method. The '`=`' symbol is syntactic sugar for a call to '`is_eq`' (See also unnamedlink). '`is_eq:BOOL`' must be explicitly defined by the type of the left side for this syntax to be useful.

The `SYS` class (See unnamedlink) can be used to obtain equality based on pointer or structural notions of identity. This class also provides built-in mechanisms for comparison and hashing.

## IS_EQ

Classes which define their own notion of equality should subtype from `$IS_EQ`. This class is a common parameter bound in container classes. In the standard library, we have

    abstract class $IS_EQ is
       is_eq(e:$OB):BOOL;
    end;

Many classes define a notion of equality which is different than pointer equality. For example, two `STR` strings may be equal although, in general, strings are not unique.

    class STR < $IS_EQ is ...
       is_eq(arg:$OB):BOOL is ... end;
       ...
    end; -- class STR.

## Programmer defined hash functions and $HASH

Many container classes need to be able to compute hash values of their items. Just as with '`is_eq`', classes may subtype from `$HASH` to indicate that they know how to compute their own hash value. $HASH is defined in the library to be

    abstract class $HASH is
       hash:INT;
    end;

## Objects that can be copied and $COPY

To preserve class encapsulation, Sather does not provide a built-in way to copy objects. By convention, objects are copied by a class-defined routine '`copy`', and classes which provide this should subtype from `$COPY`. $COPY is defined in the standard library.

    abstract class $COPY is
       copy:SAME;
    end;

## 12.6.2. Nil and void

Reference class variables can be declared without being allocated. Unassigned reference or abstract type variables have the `void` value, indicating the non-existence of an object. However, for immutable types this unassigned value is not distinguished from other legitimate values; for example, the `void` of type `INT` is the value zero.

It is often algorithmically convenient to have a sentinel value which has a special interpretation. For example, hash tables often distinguish empty table entries without a separate bit indicating that an entry is empty. Because `void` is a legitimate value for immutable types, `void` can't be used as this sentinel value. For this reason, classes may define a '`nil`' value to be used to represent the non-existence of an immutable object. Such classes subtype from `$NIL` and define the routines '`nil:SAME`' and `'is_nil: BOOL`'.

The '`nil`' value is generally a rarely used or illegal value. For `INT`, it is the most negative representable integer. For floating point types, it is `NaN`. '`is_nil`' is necessary because `NaN` is defined by `IEEE` to not be equal to itself.

    abstract class $NIL is
       nil:SAME;
       is_nil:BOOL;
    end; -- anstract class $NIL

Prev | Home | Next
Basic Classes and Literal Forms | Up | Interfacing with Fortran