Example. Adding specs to contains

[comp1110-1A]
  • Liam O'Connor, Fabian Muehlboeck

We can take the contains function from Example [comp1110-16] and annotate it with a specification. It holds no assumptions about the input parameters, so the function has no nontrivial preconditions. Its postcondition, however, captures the notion of correctness for this function:

/** Returns if an integer is contained in an integer array @param haystack is an integer array @param needle is the integer we want to search for @return true iff there exists some j such that haystack[j] == needle */ boolean contains(int[] haystack, int needle) { int i = 0; while(i < haystack.length) { // i <= haystack.length && forall 0 <= j < i, haystack[j] != needle if(needle == haystack[i]) { return true; } i = i + 1; } // i == haystack.length // forall 0 <= j < haystack.length, haystack[j] != needle return false; }

Note how the loop invariant, allows us to reason that our postcondition (the @return clause above) is satisfied by our function.

Context

    Specifications

    [comp1110-17]
    • Liam O'Connor

    What does it mean for software to be correct? Typically there are two components:

    • The software does what it's supposed to.
    • The software doesn't do what it's not supposed to.

    (often programmers acknowledge the former but forget the latter)

    How do we determine what the software is (and is not) supposed to do? This is where specifications come in.

    Definition. Preconditions and Postconditions

    [comp1110-18]
    • Liam O'Connor

    Specifications often take the form of preconditions and postconditions for a function.

    • Preconditions state any assumptions made about inputs or parameters to the function.
    • Postconditions state what the result(s) of a function will be, if successfully executed with inputs that satisfy the preconditions.

    Sometimes these pairings of pre and post-conditions are called the contract for the function. If the caller satisfies the preconditions, the function is "contractually obliged" to satisfy the postconditions.

    Writing Javadoc comments.

    [comp1110-19]
    • Liam O'Connor

    Javadoc is the standard Java documentation tool. Documentation for Java functions (such as we have seen for e.g. the Character class) are produced using this tool.

    In Javadoc, each function is annotated with a special documentation comment, which looks like a typical multi-line comment, except it starts with two asterisks (/**) rather than just one:

    /** A main function */ void main(String[] args) { IO.println("Hello"); }

    We can include special commands in our Javadoc comments which are picked up by the tool and treated specially. Javadoc includes markup specifically for the writing of specifications. We can describe our parameters (and any preconditions associated with them) using the @param markup, and the @return markup to describe our return value (and any postconditions associated with them).

    /** A function to compute the remainder left after dividing. @param numerator number to divide. (pre: >= 0) @param denominator number to divide by. (pre: > 0) @return an integer x with post: x = numerator % denominator */ int remainder(int numerator, int denominator) { int r = numerator; while (r >= denominator) { r = r - denominator; } return r; }

    Example. Adding specs to contains

    [comp1110-1A]
    • Liam O'Connor, Fabian Muehlboeck

    We can take the contains function from Example [comp1110-16] and annotate it with a specification. It holds no assumptions about the input parameters, so the function has no nontrivial preconditions. Its postcondition, however, captures the notion of correctness for this function:

    /** Returns if an integer is contained in an integer array @param haystack is an integer array @param needle is the integer we want to search for @return true iff there exists some j such that haystack[j] == needle */ boolean contains(int[] haystack, int needle) { int i = 0; while(i < haystack.length) { // i <= haystack.length && forall 0 <= j < i, haystack[j] != needle if(needle == haystack[i]) { return true; } i = i + 1; } // i == haystack.length // forall 0 <= j < haystack.length, haystack[j] != needle return false; }

    Note how the loop invariant, allows us to reason that our postcondition (the @return clause above) is satisfied by our function.

    Backlinks

      Example. Binary Search

      [comp1110-1J]
      • Liam O'Connor

      If we add a precondition to the spec of contains, that the input array is sorted, we can use a trick similar to our solution algorithm for our guessing game, which as we saw, can reduce the amount of iterations of the program from linear in the size of the input to logarithmic.

      The idea is that we consistently pick the middle index from the range of possible indices. If the value at this index is our target, we have found what we're looking for, and we're done. If the value at this index is larger than our target, that means our desired index is to the left, and reduces the range of possible indices by half. If it is smaller, then our desired index is to the other half, on the right of the selected midpoint.

      This narrows the range of possible indices, which permits us to repeat this technique until we reach single elements.

      /** Searches for a needle in a sorted haystack @param haystack a sorted (in ascending order) array of integers @param needle an integer to be searched for @return true iff there exists i, haystack[i] == needle */ boolean binarySearch(int[] haystack, int needle) { int lower = 0; int upper = haystack.length - 1; while(lower <= upper) { // INV: if there exists i, haystack[i] == needle, // then lower <= i <= upper int middle = (lower + upper) / 2; if(needle == haystack[middle]) { return true; } else if(needle > haystack[middle]) { lower = middle + 1; } else { upper = middle - 1; } } return false; }

      Definition. Binary Search Trees

      [comp1110-2V]
      • Liam O'Connor, Fabian Muehlboeck

      While we can replace linear search with binary search on sorted arrays to improve how many comparisons we have to do, this is not so straightforward with linked lists, even if sorted. The structure of the linked list requires linear traversal, rather than the random access required for binary search.

      Instead, we will store sorted data differently so that finding elements can be much more efficient. Each node of a binary tree contains some data (in our case, an integer) and two branches:

      //BST // - null (for an empty tree) // - a BST object (for a tree node) /** * INVARIANT: the values stored in all descendants * on the left are <= v * the values stored in all descendants * on the right are >= v */ class BST { BST(int v, BST l, BST r) { value = v; left = l; right = r; } int value; BST left; BST right; }
      • value is the integer at this node.
      • left is a tree of integers in the tree that are less than or equal to the value in the current node (Null if there are none).
      • right is a tree of integers in the tree that are greater than or equal to the value in the current node (Null if there are none).

      The BST has a Data Invariant to ensure the conditions on the values stored in the left and right children.

      Note. Omitting braces

      [comp1110-1G]
      • Liam O'Connor

      For for and while loops, as well as if statements, the braces may be omitted if the body consists of just one statement. For example, the body of contains (Example [comp1110-1A] and Example [comp1110-16]) can be rewritten as follows:

      for (int i = 0; i < haystack.length; i++) if (haystack[i] == needle) return true;

      However, this abbreviation can be a danger, because minor syntax errors can lead to unexpected behaviour. For example:

      for (int i = 0; i < haystack.length; i++) if (haystack[i] == needle) IO.println("Found it!") return true;

      This appears correct, but that's only because of indentation (which Java ignores). So this code is actually equivalent to:

      for (int i = 0; i < haystack.length; i++) if (haystack[i] == needle) IO.println("Found it!") return true;

      Quite a different program indeed!

      Example. Testing contains with assert

      [comp1110-1E]
      • Liam O'Connor, Fabian Muehlboeck

      Take the contains function again from Example [comp1110-1A] and Example [comp1110-16]. Let us test it using assert:

      void main() { int[] a1 = new int[]{1,2,3,4,5}; assert (contains(a1, 0) == false); assert (contains(a1,5)); assert (contains(a1,3)); int[] a2 = new int[]{-2, 0, 1000000}; assert (contains(a2, -2)); assert (!contains(a2,5)); }

      Try to make each of these tests fail by modifying only the function contains.

      Example. Time complexity of searching and sorting

      [comp1110-2F]
      • Liam O'Connor
      • Linear search through an array of \(n\) elements: If the target happens to be the first element, the algorithm stops immediately; this is the best case and takes constant time, \(\mathrm {O}(1)\). In the worst case the element is last or not present, so the algorithm must check all \(n\) elements. The worst-case running time is therefore \(\mathrm {O}(n)\).
      • Binary search on a sorted array. Each comparison eliminates half of the remaining elements. After one step at most \(\frac {n}{2}\) elements remain, then \(\frac {n}{4}\), then \(\frac {n}{8}\), and so on. After about \(\log _2 n\) steps only one element remains. Thus binary search runs in \(\mathrm {O}(\log n)\) time in the worst case.
      • Selection sort repeatedly scans the remaining part of the array to find the smallest element. Even if the array is already sorted, it still performs the same number of comparisons, roughly \(\frac {n(n-1)}{2}\). Its running time therefore grows like \(n^2\), so it is \(\mathrm {O}(n^2)\) in both the best and worst cases.
      • Insertion sort behaves differently. If the array is already sorted, each new element is compared once and left in place, so the running time grows linearly: \(\mathrm {O}(n)\). But if the array is in reverse order, each insertion shifts many elements and the total work grows like \(n^2\). Thus the best case is \(\mathrm {O}(n)\) and the worst case is \(\mathrm {O}(n^2)\).
      • Bubble sort with early exit is similar. If the list is already sorted, it finishes after one pass, which is \(\mathrm {O}(n)\). In the worst case — where one small element appears out of order towards the end of the list — it performs many passes and becomes \(\mathrm {O}(n^2)\).
      • Merge sort works differently. It divides the list in half, sorts each half, and then merges them. The list can be halved only about \(\log _2 n\) times, and each level of this process requires work proportional to \(n\) to perform the merges. The total work therefore grows like \(n \log n\). Unlike some previous sorts, this running time does not depend on the initial order of the input: both the best and worst cases are \(\mathrm {O}(n \log n)\).

      Related

        Loop invariants

        [comp1110-0W]
        • Liam O'Connor, Fabian Muehlboeck

        A loop invariant is a property that must be true of your variables at the start and end of each iteration of a loop. It typically takes the form of an equation or logical formula that relates the values of your variables together. They're not part of the programming language, but I will often write them down in a comment.

        When I speak of the loop invariant for a particular loop, I'm looking for a loop invariant that describes the variables with enough detail to be useful to show that my function is correct.

        When writing a loop, it is often helpful to figure out what the loop invariant is, as this will help you to convince yourself (and others) that the code you wrote is correct.

        For example, the loop invariant for Example [comp1110-0U] is that pos <= pwd.length() and that every character at an odd position in pwd[0..pos-1] is uppercase. Here pwd[0..pos-1] refers to a substring of pwd, including the — it is not valid Java, but just notation for me to write a loop invariant.

        This is true initially, as pos is zero and pwd[0..-1] is the empty string. Furthermore, it is true before and after each iteration, as we increase pos by 2 only after checking that pwd[pos] is uppercase.

        Finally, when the loop terminates not via the early return, that means that the loop guard must be false, i.e pos >= pwd.length(). Combined with our invariant that pos <= pwd.length(), we can conclude that pos == pwd.length() when the loop finishes. This means that, when the loop finishes, the other part of our invariant 'every character at an odd position in pwd[0..pos-1] is uppercase' refers to pwd[0..pwd.length()-1] which is just pwd. Thus, we can use loop invariants to show that our function computes the result it's supposed to.

        Example. Searching for an Element in an Array, Generally

        [comp1110-16]
        • Liam O'Connor, Fabian Muehlboeck
         boolean contains(int[] haystack, int needle) { int i = 0; while(i < haystack.length) { // i <= haystack.length && forall 0 <= j < i, haystack[j] != needle if(needle == haystack[i]) { return true; } i = i + 1; } // i == haystack.length // forall 0 <= j < haystack.length, haystack[j] != needle return false; }

        Specifications

        [comp1110-17]
        • Liam O'Connor

        What does it mean for software to be correct? Typically there are two components:

        • The software does what it's supposed to.
        • The software doesn't do what it's not supposed to.

        (often programmers acknowledge the former but forget the latter)

        How do we determine what the software is (and is not) supposed to do? This is where specifications come in.

        Definition. Preconditions and Postconditions

        [comp1110-18]
        • Liam O'Connor

        Specifications often take the form of preconditions and postconditions for a function.

        • Preconditions state any assumptions made about inputs or parameters to the function.
        • Postconditions state what the result(s) of a function will be, if successfully executed with inputs that satisfy the preconditions.

        Sometimes these pairings of pre and post-conditions are called the contract for the function. If the caller satisfies the preconditions, the function is "contractually obliged" to satisfy the postconditions.

        Writing Javadoc comments.

        [comp1110-19]
        • Liam O'Connor

        Javadoc is the standard Java documentation tool. Documentation for Java functions (such as we have seen for e.g. the Character class) are produced using this tool.

        In Javadoc, each function is annotated with a special documentation comment, which looks like a typical multi-line comment, except it starts with two asterisks (/**) rather than just one:

        /** A main function */ void main(String[] args) { IO.println("Hello"); }

        We can include special commands in our Javadoc comments which are picked up by the tool and treated specially. Javadoc includes markup specifically for the writing of specifications. We can describe our parameters (and any preconditions associated with them) using the @param markup, and the @return markup to describe our return value (and any postconditions associated with them).

        /** A function to compute the remainder left after dividing. @param numerator number to divide. (pre: >= 0) @param denominator number to divide by. (pre: > 0) @return an integer x with post: x = numerator % denominator */ int remainder(int numerator, int denominator) { int r = numerator; while (r >= denominator) { r = r - denominator; } return r; }

        Example. Adding specs to contains

        [comp1110-1A]
        • Liam O'Connor, Fabian Muehlboeck

        We can take the contains function from Example [comp1110-16] and annotate it with a specification. It holds no assumptions about the input parameters, so the function has no nontrivial preconditions. Its postcondition, however, captures the notion of correctness for this function:

        /** Returns if an integer is contained in an integer array @param haystack is an integer array @param needle is the integer we want to search for @return true iff there exists some j such that haystack[j] == needle */ boolean contains(int[] haystack, int needle) { int i = 0; while(i < haystack.length) { // i <= haystack.length && forall 0 <= j < i, haystack[j] != needle if(needle == haystack[i]) { return true; } i = i + 1; } // i == haystack.length // forall 0 <= j < haystack.length, haystack[j] != needle return false; }

        Note how the loop invariant, allows us to reason that our postcondition (the @return clause above) is satisfied by our function.

        bars magnifying-glass caret-down plus minus arrow-right xmark