CS U370 Assignment #5.
Assigned:  Tuesday, 2 November 2004
Due: Wednesday, 10 November 2004

You will design, specify, and implement (in Java) an IntBag ADT
whose informal specification is given below.

Collaboration between students is forbidden on this assignment.
You are responsible for keeping your code hidden from all other
students.  Part of your grade will be determined by how well
you hide your code, part of your grade will be determined by
how well you follow the instructions for submitting your code,
part of your grade will depend upon the correctness of your
design and your code, part of your grade will depend upon the
quality of the comments in your code, and part of your grade
will depend upon the formatting and readability of your code.

Turn in your work on this assignment before 4 pm on the due
date by sending electronic mail to

    will@ccs.neu.edu

with subject

    CSU370 assignment 5

and a body that consists of nothing but your IntBag.java
file.  That file should begin with a block comment that lists

    1.  Your name, as you want the instructor to write it.
    2.  Your email address.
    3.  Any remarks that you wish to make to the instructor.

That block comment should be followed by a second block
comment that contains an algebraic specification of the
operations (except for equals and toString) of the IntBag ADT.

That second block comment should be followed by your code for
the public IntBag class.  That class declaration should be
followed by any other class declarations that are part of
your implementation of the IntBag ADT; if present, these
other class declarations should *not* be public.

Late assignments may be discounted, and very late assignments
may be discarded.

--------------------------------------------------

Your assignment is to write the code for a single file,
IntBag.java, that contains an algebraic specification of the
IntBag ADT (as a comment) and also implements that ADT.  Note
that IntBag.java must be part of the default package.  A small
test program will be made available in

    /course/csu370wc/Assignments/A5

--------------------------------------------------

Informal specification of the IntBag ADT.

The IntBag ADT is an immutable abstract data type.  It shall
be implemented by a single file named IntBag.java.  This code
shall be in the default package, and shall define a public
class named IntBag that defines one public constructor with
no arguments, and also defines the following public methods,
which are dynamic methods, and have no side effects:

    public boolean isEmpty();      // returns true iff this IntBag is empty
    public int     size();         // returns number of elements in this IntBag
    public int     sum();          // returns sum of elements in this IntBag

    public IntBag  adjoin(int);    // returns IntBag with one more element
    public int     least();        // returns least element of this IntBag
    public IntBag  butLeast();     // returns IntBag with all but the least
    public IntBag  union(IntBag);  // returns union of this IntBag with that
    public IntBag  except(int);    // returns this IntBag except that element

    // Returns the number of subbags whose sum equals the argument.
    public int     countTies(int);
    // Returns the number of subbags whose sum exceeds the argument.
    public int     countWins(int);

    public boolean equals(Object); // overrides inherited equals method
    public String  toString();     // overrides inherited toString method

The IntBag ADT is analogous to the IntSet ADT of assignment 3.
Its client syntax is different, however, and will be explained
by example.

    IntBag ib0 = new IntBag();  // ib0 is an IntBag with no elements

    ib0.isEmpty();              // returns true, because ib0 is empty
    ib0.size();                 // returns 0, because ib0 contains 0 elements
    ib0.sum();                  // returns 0, the sum of its elements

    ib0.countTies(0);           // returns 1, because there is one subbag
                                //     whose sum is 0
    ib0.countWins(41);          // returns 0, because there are no subbags
                                //     whose sum exceeds 41

    ib0.except(27);             // returns an empty IntBag

    IntBag ib17 = ib0.adjoin(17);       // ib17 = { 17 }
    IntBag ib27 = ib0.adjoin(27);       // ib27 = { 27 }
    IntBag ib227 = ib27.union(ib27);    // ib227 = { 27, 27 }
    IntBag ib3 = ib17.union(ib227);     // ib3 = { 17, 27, 27 }

    ib3.size();                         // returns 3
    ib3.sum();                          // returns 71 = 17 + 27 + 27
    ib3.countTies(44);                  // returns 2
    ib3.countWins(44);                  // returns 2

    ib3.least();                        // returns 17
    ib3.butLeast();                     // returns { 27, 27 }
    ib3.butLeast().equals(ib227);       // returns true
    ib3.except(27);                     // returns { 17, 27 }
    ib3.except(27).equals(ib27.union(ib17)); // returns true

    ib3.toString();             // returns something like "{ 17, 27, 27 }"

Note:  Although the least and butLeast operations are not defined
on an empty bag, the except operation is defined on all bags.

--------------------------------------------------