Reading 7: Abstraction Functions & Rep Invariants

Resuming our discussion of what makes a good abstract data type, the final, and perhaps most important, property of a good abstract data type is that it preserves its own invariants. An invariant is a property of a program that is always true, for every possible runtime state of the program, given it was true at the beginning. You may recall this concept of a preserved invariant from 6.1200 [formerly 6.042]. Immutability is one crucial invariant that we’ve already encountered: once created, an immutable object should always represent the same value, for its entire lifetime. But there are many other kinds of invariants, including types of variables (i: number means that i is always a number), or relationships between variables (e.g. when i is used to loop over the indices of an array, then 0 <= i < array.length is an invariant within the body of the loop).

Saying that the ADT preserves its own invariants means that the ADT is responsible for ensuring that its own invariants hold. This is done by hiding or protecting the variables involved in the invariants (e.g., using language features like private), and allowing access only through operations with well-defined contracts.

When an ADT preserves its own invariants, reasoning about the code becomes much easier. If you can count on the fact that strings are immutable, for example, then you can rule out the possibility that a string has been mutated when you’re debugging code that uses strings – or when you’re trying to establish an invariant for another ADT that uses strings. Contrast that with a mutable string type, which can be mutated by any code that has access to it. To reason about a bug or invariant involving a mutable string, you’d have to check all the places in the code where the string might be accessible.

const names: Array<string> = ["Huey", "Dewey", "Louie"];

Immutability

/**
 * This immutable data type represents a tweet from Twitter.
 */
class Tweet {

    public author: string;
    public text: string;
    public timestamp: Date;

    /**
     * Make a Tweet.
     * @param author    Twitter user who wrote the tweet
     * @param text      text of the tweet
     * @param timestamp date/time when the tweet was sent
     */
    public constructor(author: string, text: string, timestamp: Date) {
        this.author = author;
        this.text = text;
        this.timestamp = timestamp;
    }
}

let t: Tweet = new Tweet("justinbieber",
                    "Thanks to all those beliebers out there inspiring me every day",
                    new Date());
t.author = "rbmllr";

class Tweet {

    private readonly author: string;
    private readonly text: string;
    private readonly timestamp: Date;

    public constructor(author: string, text: string, timestamp: Date) {
        this.author = author;
        this.text = text;
        this.timestamp = timestamp;
    }

    /**
     * @returns Twitter user who wrote the tweet
     */
    public getAuthor(): string {
        return this.author;
    }

    /**
     * @returns text of the tweet
     */
    public getText(): string {
        return this.text;
    }

    /**
     * @returns date/time when the tweet was sent
     */
    public getTimestamp(): Date {
        return this.timestamp;
    }

}

/**
 * @returns a tweet that retweets t, one hour later
 */
function retweetLater(t: Tweet): Tweet {
    const d: Date = t.getTimestamp();
    d.setHours(d.getHours()+1);
    return new Tweet("rbmllr", t.getText(), d);
}

public getTimestamp(): Date {
    return new Date(this.timestamp.getTime());
}

/**
 * @returns an array of 24 inspiring tweets, one per hour today
 */
function tweetEveryHourToday(): Array<Tweet> {
    const array: Array<Tweet> = [];
    const date: Date = new Date();
    for (let i = 0; i < 24; i++) {
        date.setHours(i);
        array.push(new Tweet("rbmllr", "keep it up! you can do it", date));
    }
    return array;
}

public constructor(author: string, text: string, timestamp: Date) {
    this.author = author;
    this.text = text;
    this.timestamp = new Date(timestamp.getTime());
}

/**
 * Make a Tweet.
 * @param author    Twitter user who wrote the tweet
 * @param text      text of the tweet
 * @param timestamp date/time when the tweet was sent. Caller must never
 *                   mutate this Date object again!
 */
public constructor(author: string, text: string, timestamp: Date) {

class Zoo {
    private animals: Array<string>;

    public constructor(animals: Array<string>) {
        this.animals = animals;
    }

    public getAnimals(): Array<string> {
        return this.animals;
    }
}

let a: Array<string> = [];
a.push("lion", "tiger", "bear");
let zoo = new Zoo(a);
a.push("zebra");
console.log(a);
console.log(zoo.getAnimals());

let b = zoo.getAnimals();
b.push("flamingo");
console.log(a);

      /** Represents an immutable right triangle. */
      class RightTriangle {
/*A*/     private sides: Array<number>;

/*B*/     public readonly hypotenuse: number;

          /**
           * Make a right triangle.
           * @param legA, legB  the two legs of the triangle
           * @param hypotenuse  the hypotenuse of the triangle,
*C*        *           requires hypotenuse^2 = legA^2 + legB^2
           *           (within the error tolerance of double arithmetic)
           */
          public constructor(legA: number, legB: number, hypotenuse: number) {
/*D*/         this.sides = [ legA, legB ];
/*D*/         this.hypotenuse = hypotenuse;
          }

          /**
           * Get the two sides of the right triangle.
           * @returns two-element array with the triangle's side lengths
           */
          public getAllSides(): Array<number> {
/*E*/         return this.sides;
          }

          /**
           * @param factor to multiply the sides by
           * @returns a triangle made from this triangle by
           * multiplying all side lengths by factor.
           */
          public scale(factor: number): RightTriangle {
              return new RightTriangle(this.sides[0]*factor, this.sides[1]*factor, this.hypotenuse*factor);
          }

          /**
           * @returns a regular triangle made from this triangle.
           * A regular right triangle is one in which
           * both legs have the same length.
           */
          public regularize(): RightTriangle {
              const bigLeg: number = Math.max(this.sides[0], this.sides[1]);
              return new RightTriangle(bigLeg, bigLeg, this.hypotenuse);
          }

      }

public getSigners(): Array<Identity>

We now take a deeper look at the theory underlying abstract data types. This theory is not only elegant and interesting in its own right; it also has immediate practical application to the design and implementation of abstract types. If you understand the theory deeply, you’ll be able to build better abstract types, and will be less likely to fall into subtle traps.

In thinking about an abstract type, it helps to consider the relationship between two spaces of values.

The space of abstract values consists of the values that the type is designed to support, from the client’s point of view. For example, an abstract type for unbounded integers, like TypeScript’s BigInt, would have the mathematical integers as its abstract value space.

The space of representation values (or rep values for short) consists of the objects that actually implement the abstract values. For example, a BigInt value might be implemented using an array of digits, represented as number values. The rep space would then be the set of all such arrays.

In simple cases, an abstract type will be implemented as a single object, but more commonly a small network of objects is needed. For example, a rep value for Array might possibly be a linked list, a group of objects linked together by next and previous pointers. So a rep value is not necessarily a single object, but often something rather complicated.

Now of course the implementer of the abstract type must be interested in the representation values, since it is the implementer’s job to achieve the illusion of the abstract value space using the rep value space.

Suppose, for example, that we choose to use a string to represent a set of characters:

class CharSet {
    private s: string;
    ...
}

Then the rep space R contains strings, and the abstract space A is mathematical sets of characters. We can show the two value spaces graphically, with an arrow from a rep value to the abstract value it represents. There are several things to note about this picture:

• Every abstract value is mapped to by some rep value. The purpose of implementing the abstract type is to support operations on abstract values. Presumably, then, we will need to be able to create and manipulate all possible abstract values, and they must therefore be representable.
• Some abstract values are mapped to by more than one rep value. This happens because the representation isn’t a tight encoding. There’s more than one way to represent an unordered set of characters as a string.
• Not all rep values are mapped. In this case, the string “abbc” is not mapped, because we have decided that the rep string should not contain duplicates. This will allow us to terminate the remove method when we hit the first instance of a particular character, since we know there can be at most one.

In practice, we can only illustrate a few elements of the two spaces and their relationships; the graph as a whole is infinite. So we describe it by giving two things:

1. An abstraction function that maps rep values to the abstract values they represent:

AF : R → A

The arrows in the diagram above show the abstraction function. In the terminology of functions, the properties we discussed above can be expressed by saying that the function is surjective (also called onto), not necessarily injective (one-to-one) and therefore not necessarily bijective, and often partial.

2. A rep invariant that maps rep values to booleans:

RI : R → boolean

A rep invariant is a predicate over rep values.

For a rep value r, RI(r) is true if and only if r is mapped by AF. In other words, RI tells us whether a given rep value is well-formed. Alternatively, you can think of RI as a set: it’s the subset of rep values on which AF is defined.

For example, the diagram at the right showing a rep for CharSet that forbids repeated characters:

• RI(“a”) = true
• RI(“ac”) = true
• RI(“acb”) = true

but

• RI(“aa”) = false
• RI(“abbc”) = false

Rep values that obey the rep invariant are shown in the green part of the R space, and must map to an abstract value in the A space. Rep values that violate the rep invariant are shown in the red zone, and have no equivalent abstract value in the A space.

Both the rep invariant and the abstraction function should be documented in the code, right next to the declaration of the rep itself:

class CharSet {
    private s: string;
    // Rep invariant:
    //   s contains no repeated characters
    // Abstraction function:
    //   AF(s) = {s[i] | 0 <= i < s.length}
    ...
}

A common confusion about abstraction functions and rep invariants is that they are determined by the choice of rep and abstract value spaces, or even by the abstract value space alone. If this were the case, they would be of little use, since they would be saying something redundant that’s already available elsewhere.

The abstract value space alone doesn’t determine AF or RI: there can be several representations for the same abstract type. A set of characters could equally be represented as a string, as above, or as a bit vector, with one bit for each possible character. Clearly we need two different abstraction functions to map these two different rep value spaces.

It’s less obvious why the choice of both spaces doesn’t determine AF and RI. The key point is that defining a type for the rep, and thus choosing the values for the space of rep values, does not determine which of the rep values will be deemed to be legal, and of those that are legal, how they will be interpreted. Rather than deciding, as we did above, that the strings have no duplicates, we could instead allow duplicates, but at the same time require that the characters be sorted, appearing in nondecreasing order. This would allow us to perform a binary search on the string and thus check membership in logarithmic rather than linear time. Same rep value space – different rep invariant:

class CharSet {
    private s: string;
    // Rep invariant:
    //   s[0] <= s[1] <= ... <= s[s.length-1]
    // Abstraction function:
    //   AF(s) = {s[i] | 0 <= i < s.length}
    ...
}

Even with the same type for the rep value space and the same rep invariant, we might still interpret the rep differently by using different abstraction functions. Suppose the rep invariant admits any string of characters. Then we could define the abstraction function, as above, to interpret the array’s elements as the elements of the set. But there’s no a priori reason to let the rep decide the interpretation. Perhaps we’ll interpret consecutive pairs of characters as subranges, so that the string rep "acgg" is interpreted as two range pairs, [a-c] and [g-g], and therefore represents the set {a,b,c,g}. Here’s what the AF and RI would look like for that representation:

class CharSet {
    private String s;
    // Rep invariant:
    //   s.length is even
    //   s[0] <= s[1] <= ... <= s[s.length-1]
    // Abstraction function:
    //   AF(s) = union of { c | s[2i] <= c <= s[2i+1] }
    //           for all 0 <= i < s.length/2
    ...
}

The essential point is that implementing an abstract type means not only choosing the two spaces – the abstract value space for the specification and the rep value space for the implementation – but also deciding which rep values are legal, and how to interpret them as abstract values.

It’s critically important to write down these assumptions in your code, as we’ve done above, so that future programmers (and your future self) are aware of what the representation actually means. Why? What happens if different implementers disagree about the meaning of the rep?

class CharSet {
    private s: string;
    // Rep invariant:
    //   s.length is even
    //   s[0] <= s[1] <= ... <= s[s.length-1]
    // Abstraction function:
    //   AF(s) = union of { c | s[2i] <= c <= s[2i+1] }
    //           for all 0 <= i < s.length/2
    ...
}

class C {
    private s: string;
    private t: string;
    ...
}

class CharSet {
    private s: string;
    ...
}

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s[0] < s[1] < ... < s[s.length-1]

// AF(s) = union of { c | s[2i] <= c <= s[2i+1] }
//         for all 0 <= i < s.length/2
// RI: s.length is even, and s[0] <= s[1] <= ... <= s[s.length-1]

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s contains no character more than once

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: true

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s[0] < s[1] < ... < s[s.length-1]

// AF(s) = union of { c | s[2i] <= c <= s[2i+1] }
//         for all 0 <= i < s.length/2
// RI: s.length is even, and s[0] <= s[1] <= ... <= s[s.length-1]

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s contains no character more than once

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: true

/**
 * Modifies this set by adding c to the set.
 * @param c character to add; required to be one-character string.
 */
public add(c: string): void {
    s = s + c;
}

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s[0] < s[1] < ... < s[s.length-1]

// AF(s) = union of { c | s[2i] <= c <= s[2i+1] }
//         for all 0 <= i < s.length/2
// RI: s.length is even, and s[0] <= s[1] <= ... <= s[s.length-1]

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s contains no character more than once

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: true

/**
 * Modifies this set by removing c, if found.
 * If c is not found in the set, has no effect.
 * @param c character to remove; required to be one-character string.
 */
public remove(c: string): void {
    const position = s.indexOf(c);
    if (position >= 0) {
        s = s.substring(0, position) + s.substring(position+1, s.length);
    }
}

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s[0] < s[1] < ... < s[s.length-1]

// AF(s) = union of { c | s[2i] <= c <= s[2i+1] }
//         for all 0 <= i < s.length/2
// RI: s.length is even, and s[0] <= s[1] <= ... <= s[s.length-1]

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: s contains no character more than once

// AF(s) = {s[i] | 0 <= i < s.length}
// RI: true

/**
 * Test for membership.
 * @param c a one-character string.
 * @returns true iff this set contains c
 */
public contains(c: string): boolean {
    for (let i = 0; i < this.s.length; i += 2) {
        const low: string = this.s.charAt(i);
        const high: string = this.s.charAt(i+1);
        if (low <= c && c <= high) {
            return true;
        }
    }
    return false;
}

Example: rational numbers

class RatNum {

    private readonly numerator: bigint;
    private readonly denominator: bigint;

    // Rep invariant:
    //   denominator > 0
    //   numerator/denominator is in reduced form,
    //       i.e. gcd(|numerator|,denominator) = 1

    // Abstraction function:
    //   AF(numerator, denominator) = numerator/denominator

    /**
     * Make a new RatNum = (n / d).
     * @param n numerator
     * @param d denominator
     * @throws Error if d = 0
     */
    public constructor(n: bigint, d: bigint) {
        // reduce ratio to lowest terms
        const g = gcd(BigInt(n), BigInt(d));
        const reducedNumerator = n / g;
        const reducedDenominator = d / g;

        // make denominator positive
        if (d < 0n) {
            this.numerator = -reducedNumerator;
            this.denominator = -reducedDenominator;
        } else if (d > 0n) {
            this.numerator = reducedNumerator;
            this.denominator = reducedDenominator;
        } else {
            throw new Error('denominator is zero');
        }
        this.checkRep();
    }

}

Checking the rep invariant

// Check that the rep invariant is true
private checkRep(): void {
    assert(this.denominator > 0n);
    assert(gcd(abs(this.numerator), this.denominator) === 1n);
}

No null values in the rep

class CharSet {
    s: string;
}

class Thing {
    private i: number;
    private s: string;
    ...
}

// Rep invariant:
//    i is positive

private void checkRep() {

}

// Rep invariant:
//    the length of s is even

private void checkRep() {

}

Recall that a type is immutable if and only if a value of the type never changes after being created. With our new understanding of the abstract space A and rep space R, we can refine this definition: the abstract value should never change. But the implementation is free to mutate a rep value as long as it continues to map to the same abstract value, so that the change is invisible to the client. This kind of change is called a benevolent side-effect.

Here’s a simple example using an alternative rep for the RatNum type we saw earlier. This rep has a weaker rep invariant that doesn’t require the numerator and denominator to be stored in lowest terms:

class RatNum {

    private numerator: bigint;
    private denominator: bigint;

    // Rep invariant:
    //   denominator != 0

    // Abstraction function:
    //   AF(numerator, denominator) = numerator/denominator

    /**
     * Make a new RatNum = (n / d).
     * @param n numerator
     * @param d denominator
     * @throws Error if d = 0
     */
    public constructor(n: bigint, d: bigint) {
        if (d === 0n) throw new Error("denominator is zero");
        this.numerator = n;
        this.denominator = d;
        checkRep();
    }

    ...
}

This weaker rep invariant allows a sequence of RatNum arithmetic operations to simply omit reducing the result to lowest terms. But when it’s time to display a result to a human, we first simplify it:

    /**
     * @returns a string representation of this rational number
     */
    public toString(): string {
        const g = gcd(this.numerator, this.denominator);
        this.numerator /= g;
        this.denominator /= g;
        if (this.denominator < 0n) {
            this.numerator = -this.numerator;
            this.denominator = -this.denominator;
        }
        checkRep();
        return (this.denominator > 1n) ? (this.numerator + "/" + this.denominator)
                                 : (this.numerator + "");
    }

Notice that this toString implementation reassigns the private fields numerator and denominator, mutating the representation – even though it is an observer method on an immutable type! But, crucially, the mutation doesn’t change the abstract value. Dividing both numerator and denominator by the same common factor, or multiplying both by -1, has no effect on the result of the abstraction function, AF(numerator, denominator) = numerator/denominator. Another way of thinking about it is that the AF is a many-to-one function, and the rep value has changed to another that still maps to the same abstract value. So the mutation is harmless, or benevolent.

We’ll see other examples of benevolent side-effects in future readings. This kind of implementer freedom often permits performance improvements like caching, data structure rebalancing, and lazy cleanup.

It’s good practice to document the abstraction function and rep invariant in the class, using comments right where the private fields of the rep are declared. We’ve been doing that above.

When you describe the rep invariant and abstraction function, you must be precise.

It is not enough for the RI to be a generic statement like “all fields are valid.” The job of the rep invariant is to explain precisely what makes the field values valid or not.

As a function, if we take the documented RI and substitute in actual field values, legal or not, we should obtain a boolean result. Note that if we’re tempted to refer to the abstract value in our RI, we’ve put the cart before the horse: illegal rep values don’t have an abstract value, and we need to reject them in the RI by talking about the rep values alone.

It is not enough for the AF to offer a generic explanation like “represents a set of characters.” The job of the abstraction function is to define precisely how the concrete field values are interpreted.

As a function, if we take the documented AF and substitute in actual legal field values, we should obtain out a complete description of the single abstract value they represent. For example, for the CharSet abstraction function AF(s) = {s[i] | 0 <= i < s.length}, we can substitute a specific (legal) rep value like s="abbc", and get:
AF("abbc") = { "abbc"[i] | 0 <= i < "abbc".length } = { 'a', 'b', 'c' }.

But if we instead had a vague and ill-defined abstraction function like AF(s) = a set of characters, then substituting for s would not affect the righthand side at all. This definition does not say precisely which abstract set of characters corresponds to the rep value s="abbc".

Another piece of documentation that 6.102 asks you to write is a rep exposure safety argument. This is a comment that examines each part of the rep, looks at the code that handles that part of the rep (particularly with respect to parameters and return values from clients, because that is where rep exposure occurs), and presents a reason why the code doesn’t expose the rep.

Here’s an example of Tweet with its rep invariant, abstraction function, and safety from rep exposure fully documented:

// Immutable type representing a tweet.
class Tweet {

    private readonly author: string;
    private readonly text: string;
    private readonly timestamp: Date;

    // Rep invariant:
    //   author is a Twitter username (a nonempty string of letters, digits, underscores)
    //   text.length <= 280
    // Abstraction function:
    //   AF(author, text, timestamp) = a tweet posted by author, with content text,
    //                                 at time timestamp
    // Safety from rep exposure:
    //   All fields are private;
    //   author and text are Strings, so are guaranteed immutable;
    //   timestamp is a mutable Date, so Tweet() constructor and getTimestamp()
    //        make defensive copies to avoid sharing the rep's Date object with clients.

    // Operations (specs and method bodies omitted to save space)
    public constructor(author: string, text: string, timestamp: Date) { ... }
    public getAuthor(): string { ... }
    public getText(): string { ... }
    public getTimestamp(): Date { ... }
}

Notice that we don’t have any explicit rep invariant conditions on timestamp (aside from the conventional assumption that timestamp is not null, which we have for all object references). But we still need to include timestamp in the rep exposure safety argument, because the immutability property of the whole type depends on the abstract value remaining unchanged, and the abstraction function uses timestamp to map to the abstract value. Not only does the argument include what TypeScript can statically check (private fields and types), but it also references what the implementer actively does to enforce the rep invariant.

Compare the argument above with an example of a broken argument involving mutable Date objects.

Here are the arguments for RatNum.

// Immutable type representing a rational number.
class RatNum {
    private readonly numerator: bigint;
    private readonly denominator: bigint;

    // Rep invariant:
    //   denominator > 0
    //   numerator/denominator is in reduced form, i.e. gcd(|numerator|,denominator) = 1
    // Abstraction function:
    //   AF(numerator, denominator) = numerator/denominator
    // Safety from rep exposure:
    //   All fields are private, and all types in the rep are immutable.

    // Operations (specs and method bodies omitted to save space)
    public constructor(n: bigint, d: bigint) { ... }
    ...
}

Notice that an immutable rep is particularly easy to argue for safety from rep exposure.

// Mutable type representing Twitter users' followers.
class FollowGraph {
    private readonly followersOf: Map<string,Set<string>>;

    // Rep invariant:
    //    all strings in followersOf are Twitter usernames
    //           (i.e., nonempty strings of letters, digits, underscores)
    //    no user follows themselves, i.e. x is not in followersOf.get(x)
    // Abstraction function:
    //    AF(followersOf) = the follower graph where Twitter user x is followed by user y
    //                      if and only if followersOf.get(x).has(y)
    // Safety from rep exposure:
    //    All fields are private, and ..???..

    // Operations (specs and method bodies omitted to save space)
    public constructor() { ... }
    public addFollower(user: string, follower: string): void { ... }
    public removeFollower(user: string, follower: string): void { ... }
    public getFollowers(user: string): Set<string> { ... }
}

What an ADT specification may talk about

Since we’ve just discussed where to document the rep invariant and abstraction function, now is a good moment to update our notion of what a specification may talk about.

The specification of an abstract type T – which consists of the specs of its operations – should only talk about things that are visible to the client. This includes parameters, return values, and exceptions thrown by its operations. Whenever the spec needs to refer to a value of type T, it should describe the value as an abstract value, i.e. mathematical values in the abstract space A.

The spec should not talk about details of the representation, or elements of the rep space R. It should consider the rep itself (the private fields) invisible to the client, just as method bodies and their local variables are considered invisible. That’s why we write the rep invariant and abstraction function as ordinary comments within the body of the class, rather than TypeDoc comments above the class. Writing them as TypeDoc comments would commit to them as public parts of the type’s specification, which would interfere with rep independence and information hiding.

Now let’s bring a lot of pieces together. An enormous advantage of a well-designed abstract data type is that it encapsulates and enforces properties that we would otherwise have to stipulate in a precondition. For example, instead of a spec like this, with an elaborate precondition:

/**
 * @param set1 is a sorted set of characters with no repeats
 * @param set2 is likewise
 * @returns characters that appear in one set but not the other,
 *  in sorted order with no repeats
 */
static exclusiveOr(set1: string, set2: string): string;

We might instead use an ADT that captures the desired property:

/**
 * @returns characters that appear in one set but not the other
 */
static exclusiveOr(set1: SortedCharSet, set2: SortedCharSet): SortedCharSet;

This hits all our targets:

• it’s safer from bugs, because the required condition (sorted with no repeats) can be enforced in exactly one place, the SortedCharSet type, and because static checking comes into play, preventing values that don’t satisfy this condition from being used at all, with an error at compile-time.

• it’s easier to understand, because it’s much simpler, and the name SortedCharSet conveys what the programmer needs to know.

• it’s more ready for change, because the representation of SortedCharSet can now be changed without changing exclusiveOr or any of its clients.

Many of the places where we used preconditions earlier in this course would have benefited from a custom ADT instead.

/**
 * Find tweets written by a particular user.
 *
 * @param tweets an array of tweets with distinct timestamps, not modified by this function.
 * @param username Twitter username (a nonempty sequence of letters, digits, and underscores)
 * @returns all and only the tweets in the array whose author is username,
 *         in the same order as in the input array.
 */
function writtenBy(tweets: Array<Tweet>, username: string): Array<Tweet> { ... }

How to establish invariants

/** Represents an immutable right triangle. */
class RightTriangle {
    private sides: number[];

    // Rep invariant:
    //   sides.length = 3
    //   sides[i] > 0 for all i
    //   sides[0]^2 + sides[1]^2 = sides[2]^2 (within the error tolerance of double arithmetic)

    // Abstraction function:
    //   AF(sides) = the right triangle with legs sides[0] and sides[1], and hypotenuse sides[2]


    /**
     * Make a right triangle.
     * @param legA, legB  the two legs of the triangle, must be positive
     * @param hypotenuse  the hypotenuse of the triangle, also positive,
     *           requires hypotenuse^2 = legA^2 + legB^2
     *           (within the error tolerance of double arithmetic)
     */
    public constructor(legA: number, legB: number, hypotenuse: number) {
        this.sides = new Array<number>(legA, legB, hypotenuse);
    }

    /**
     * Get all the sides of the triangle.
     * @returns three-element array with the triangle's side lengths
     */
    public getAllSides(): Array<number> {
        return this.sides;
    }

    /**
     * @returns length of the triangle's hypotenuse
     */
    public getHypotenuse(): number {
        return this.sides[2];
    }

    /**
     * @param factor to multiply the sides by, must be >0
     * @returns a triangle made from this triangle by
     * multiplying all side lengths by factor.
     */
    public scale(factor: number): RightTriangle {
        return new RightTriangle(this.sides[0]*factor, this.sides[1]*factor, this.sides[2]*factor);
    }

    /**
     * @returns a regular triangle made from this triangle.
     * A regular right triangle is one in which
     * both legs have the same length.
     */
    public regularize(): RightTriangle {
        const bigLeg: number = Math.max(this.sides[0], this.sides[1]);
        return new RightTriangle(bigLeg, bigLeg, this.sides[2]);
    }

}

Abstract data types are at the heart of software construction for correctness, clarity, and changeability.

Recall the test-first programming approach for:

Writing a method

Writing an abstract data type

Writing a program

• An invariant is a property that is always true of an ADT object instance, for the lifetime of the object.
• A good ADT preserves its own invariants. Invariants must be established by creators and producers, and preserved by observers and mutators.
• The rep invariant specifies legal values of the representation, and should be checked at runtime with checkRep().
• The abstraction function maps a concrete representation to the abstract value it represents.
• The rep of an immutable ADT may change, as long as the abstract value it represents doesn’t change.
• Representation exposure threatens both representation independence and invariant preservation.
• An invariant should be documented, by comments or even better by assertions like checkRep(), otherwise the invariant is not safe from bugs.

The topics of today’s reading connect to our three properties of good software as follows:

• Safe from bugs. A good ADT preserves its own invariants, so that those invariants are less vulnerable to bugs in the ADT’s clients, and violations of the invariants can be more easily isolated within the implementation of the ADT itself. Stating the rep invariant explicitly, and checking it at runtime with checkRep(), catches misunderstandings and bugs earlier, rather than continuing on with a corrupt data structure.

• Easy to understand. Rep invariants and abstraction functions explicate the meaning of a data type’s representation, and how it relates to its abstraction.

• Ready for change. Abstract data types separate the abstraction from the concrete representation, which makes it possible to change the representation without having to change client code.