The game of Roulette centers around a wheel with thirty-eight numbered bins. The numbers include 0, 00 (double zero), 1 through 36. The table has a surface marked with spaces on which players can place bets. The spaces include the 38 numbers, plus a variety of additional bets, which will be detailed below. After the bets are placed by the players, the wheel is spun by the house, a small ball is dropped into the spinning wheel; when the wheel stops spinning, the ball will come to rest in one of the thirty-eight numbered bins, defining the winning number. The winning number and all of the related winning bets are paid off; the losing bets are collected. Roulette bets are all paid off using odds, which will be detailed with each of the bets, below.

The numbers from 1 to 36 are colored red and black in an arbitrary pattern. They fit into various ranges, as well as being even or odd, which defines many of the winning bets related to a given number. The numbers 0 and 00 are colored green, they fit into none of the ranges, and are considered to be neither even nor odd. There are relatively few bets related to the zeroes. The geometry of the betting locations on the table defines the relationships between number bets.

There are a variety of bets available on the Roulette table. Each bet has a payout, which is stated as n:1 where n is the multiplier that defines the amount won based on the amount bet.

A $5 bet at 2:1 will win $10. After you are paid, there will be $15 sitting on the table, your original $5 bet, plus your $10 additional winnings.

Roulette Table Layout

The table is divided into two classes of bets. The “inside” bets are the 38 numbers and small groups of numbers; these bets all have relatively high odds. The “outside” bets are large groups of numbers, and have relatively low odds. If you are new to casino gambling, see Odds and Payouts for more information on odds and why they are offered.

The following bets are the “outside” bets. Each of these involves a group of twelve to eighteen related numbers. None of these outside bets includes 0 or 00. The only way to bet on 0 or 00 is to place a straight bet on the number itself, or use the five-number combination bet.

Perhaps because Roulette is a relatively simple game, elaborate betting systems have evolved around it. Searches on the Internet turn up a many copies of the same basic descriptions for a number of betting systems. Our purpose is not to uncover the actual history of these systems, but to exploit them for simple OO design exercises. Feel free to research additional betting systems or invent your own.

The Martingale system starts with a base wagering amount, w, and a count of the number of losses, c, initially 0. Each loss doubles the bet; any given spin will place an amount of w*2 ^c on a 1:1 proposition (for example, red). When a bet wins, the loss count is reset to zero; resetting the bet to the base amount, w. This assures that a single win will recoup all losses.

Note that the casinos effectively prevent successful use of this system by imposing a table limit. At a $10 Roulette table, the limit may be as low as $1,000. A Martingale bettor who lost six times in a row would be facing a $640 bet, and after the seventh loss, their next bet would exceed the table limit. At that point, the player is unable to recoup all of their losses. Seven losses in a row is only a 1 in 128 probability; making this a relatively likely situation.

Another system is to wait until some number of losses have elapsed. For example, wait until the wheel has spun seven reds in a row, and then bet on black. This can be combined with the Martingale system to double the bet on each loss as well as waiting for seven reds before betting on black.

Another betting system is called the 1-3-2-6 system. The idea is to avoid the doubling of the bet at each loss and running into the table limit. Rather than attempt to recoup all losses in a single win, this system looks to recoup all losses by waiting for four wins in a row. The sequence of numbers (1, 3, 2 and 6) are the multipliers to use when placing bets after winning. At each loss, the sequence resets to the multiplier of 1. At each win, the multiplier is advanced through the sequence. After one win, the bet is now 3w. After a second win, the bet is reduced to 2w, and the winnings of 4w are “taken down” or removed from play. In the event of a third win, the bet is advanced to 6w. Should there be a fourth win, the player has doubled their money, and the sequence resets.

Another method for tracking the lost bets is called the Cancellation system or the Labouchere system. The player starts with a betting budget allocated as a series of numbers. The usual example is 1, 2, 3, 4, 5, 6, 7, 8, 9. Each bet is sum of the first and last numbers in the last. In this case 1+9 is 10. At a win, cancel the two numbers used to make the bet. In the event of all the numbers being cancelled, reset the sequence of numbers and start again. For each loss, however, add the amount of the bet to the end of the sequence as a loss to be recouped.

Here's an example of the cancellation system using 1, 2, 3, 4, 5, 6, 7, 8, 9.

A player could use the Fibonacci Sequence to structure a series of bets in a kind of cancellation system. The Fibonacci Sequence is 1, 1, 2, 3, 5, 8, 13, .... At each loss, the sum of the previous two bets -- the next number in the sequence -- becomes the new bet amount. In the event of a win, the last two numbers in the sequence are removed. This allows the player to easily track our accumulated losses, with bets that could recoup those losses through a series of wins.

To provide a starting point for the development effort, we have to identify the objects and define their responsibilities. The central principle behind the allocation of responsibility is encapsulation; we do this by attempting to isolate the information or isolate the processing that must be done. Encapsulation assures that the methods of a class are the exclusive users of the fields of that class. It also makes each class very loosely coupled with other classes; this permits change without a ripple through the application. For example, each Outcome contains both the name and the payout odds. That way each Outcome can be used to compute a winning amount, and no other element of the simulation needs to share the odds information or the payout calculation.

In a few cases, we have looked forward to anticipate some future considerations. One such consideration is the house “rake”, also known as the “vigorish”, “vig”, or commission. In some games, the house makes a 5% deduction from some payouts. This complexity is best isolated in the Outcome class. Roulette doesn't have any need for a rake, since the presence of the 0 and 00 on the wheel gives the house a little over 5% edge on each bet. We'll design our class so that this can be added later when we implement Craps.

In reading the background information and the problem statement, we noticed a number of nouns that seemed to be important parts of the game we are simulating.

One common development milestone is to be able to develop a class model in the Unified Modeling Language (UML) to describe the relationships among the various nouns in the problem statement. Building (and interpreting) this model takes some experience with OO programming. In this first part, we'll avoid doing extensive modeling. Instead we'll simply identify some basic design principles. We'll focus in on the most important of these nouns and describe the kinds of classes that you will build.

The following table summarizes some of the classes and responsibilities that we can identify from the problem statement. This is not the complete list of classes we need to build. As we work through the exercises, we'll discover additional classes and rework some of these preliminary classes more than once.

The class Player has the most important responsibility in the application, since we expect to update the algorithms this class uses to place different kinds of bets. Clearly, we need to cleanly encapsulate the Player, so that changes to this class have no ripple effect in other classes of the application.

A good preliminary task is to review these responsibilities to confirm that a complete cycle of play is possible. This will help provide some design details for each class. It will also provide some insight into classes that may be missing from this overview.

A good way to structure this task is to do a Class-Reponsibility-Collaborators (CRC) walkthrough. As preparation, get some 5" x 8" notecards. On each card, write down the name of a class, the responsibilities and the collaborators. Leave plenty of room around the responsibilities and collaborators to write notes. We've only identified five classes, so far, but others always show up during the walkthrough.

During the walkthrough, we identify areas of responsibility, allocate them to classes of objects and define any collaborating objects. An area of responsibility is a thing to do, a piece of information, a result. Sometimes a big piece of responsibility can be broken down into smaller pieces, and those smaller pieces assigned to other classes. There are a lot of reasons for decomposing, the purpose of this book is to explore many of them in depth. Therefore, we won't justify any of our suggestions until later in the book. For now, follow along closely to get a sense of where the exercises will be leading.

The basic processing outline is the responsibility of the Game class. To start, locate the Game card.

You should continue this tour, working your way through spinning the Wheel to get a list of winning Outcomes. From there, the Game can get all of the Bets from the Table and see which are based on winning Outcomes and which are based on losing Outcomes. The Game can notify the Player of each losing Bet, and notify the Player of each winning Bet, using the Outcome to compute the winning amount.

This walkthrough will give you an overview of some of the interactions among the objects in the working application. You may uncover additional design ideas from this walkthrough. The most important outcome of the walkthrough is a clear sense of the responsibilities and the collaborations required to create the necessary application behavior.

The first class we will tackle is a small class that encapsulates each outcome. This class will contain the name of the outcome as a String, and the odds that are paid as an integer. We will use these objects when placing a bet and also when defining the Roulette wheel.

There will be several hundred instances of this class on a given Roulette table. The bins on the wheel, similarly, collect various Outcomes together. The minimum set of Outcome instances we will need are the 38 numbers, Red and Black. The other instances add details to our simulation.

In Roulette, the amount won is a simple multiplication of the amount bet and the odds. In other games, however, there may be a more complex calculation because the house keeps 5% of the winnings, called the “rake”. While it is not part of Roulette, it is good to have our Outcome class designed to cope with these more complex payout rules.

Also, we know that other casino games, like Craps, are stateful. An Outcome may change the game state. We can foresee reworking this class to add in the necessary features to change the state of the game.

While we are also aware that some odds are not stated as x:1, we won't include these other kinds of odds in this initial design. Since all Roulette odds are x:1, we'll simply assume that the denominator is always 1. We can forsee reworking this class to handle more complex odds, but we don't need to handle the other cases yet.

On Object Identity

Our design will depend on matching Outcome objects between the wheel and bets placed on the table. The wheel will select the winning Outcomes, the player will be placing bets on Outcomes and the table will be holding bets that contain Outcomes. We need a simple test to see if two Outcomes are the same.

Additionally, as we look forward, the Java Set and Map depend on the hashCode method and equals method of each object in the collection.

When we read the Application Program Interface (API) definitions, we see that the default test for equality between two objects is to simply compare the object's hashcodes. Further, an object's hashcode is simply a unique integer, perhaps the address of the object. This means that each distinct object will tend to have distinct hashcodes, even if the objects are otherwise indistinguishable.

This default behavior of objects is shown by the following example:

Example 4.1. Object Identity

Outcome oc1 = new Outcome( "Any Craps", 8, 1 ); 
System.out.println( "oc1 = " + oc1 );
Outcome oc2 = new Outcome( "Any Craps", 8, 1 ); 
System.out.println( "oc2 = " + oc2 );
System.out.println( "equal = " + (oc1 == oc2) );

	Here we create an instance of Outcome.
	Here we create a second instance of Outcome. Because we have not provided our own equals and hashCode methods, these two objects are distinct.

This fragment produced the following output.

oc1 = Outcome@7ced01
oc2 = Outcome@1ac04e8
equal = false

Each individual Outcome object has a distinct address, and a distinct hashcode. This makes them not equal according to the default methods inherited from Object. However, we would like to have two of these objects test as equal and hash to the same location in a Map.

We need to have these two Outcome objects compare as equal and have the same hashCode. This is accomplished by overiding inherited methods with class-specific processing. In this case, we'll need to do the following:

1. Provide a method for equals that compares the name of the Outcome instead of the hashcode.

2. Provide a method for hashCode that computes a hashcode based only on the name of the Outcome instead of the address of the object in memory. The String class has an intern method that looks up the given String in a private set of unique Strings and returns one of those private String objects. By using this set of Strings, we can be assured that two distinct instances of Outcome with the same name will also have the same hashcode and will compare as equal.

In Python, the names of the methods change, but the approach of defining an equality test as well as a hash code is the same. The __hash__ method should compute the integer hashcode of the Outcome instance. The __eq__ method and __ne__ method should also be defined to compare Outcome names.

Ordinarily, instances of a class are considered mutable in Python, and unsuitable for keys to a dictionary or map. In this case, however, we have designed Outcomes to be immutable. By providing a method for __hash__ that uses the name of the Outcome, we provide an immutable hash function that gives the same hash value to all Outcomes with the same name.

Outcome contains a single outcome on which a bet can be placed. In Roulette, each spin of the wheel has a number of Outcomes. For example, the “1” bin has the following winning Outcomes: “1”, “Red”, “Odd”, “Low”, “Column 1”, “Dozen 1-12”, “Split 1-2”, “Split 1-4”, “Street 1-2-3”, “Corner 1-2-4-5”, “Five Bet”, “Line 1-2-3-4-5-6”, “00-0-1-2-3”, “Dozen 1”, “Low” and “Column 1”.

Methods

• int winAmount(int amount);

  Multiplies this Outcome's odds by the given amount. The product is returned.

• An easy-to-read String output method is also very handy. This should return a String representation of the name and the odds. A form that looks like 1-2 Split (17:1) works nicely. In Java, this is done as follows.

  public String toString();
  

  In Python, the following declaration is used.

  def __str__(self):

  For some tips on how to do this, see Formatting in Java. Python formatting is done more simply, using the % operator.

Formatting in Java

For the very-new-to-Java, there are a variety of ways of implementing toString. Those who are more experienced in Java can skip this section.

• String concatenation works neatly, but has some caveats. First, it tends to create a lot of intermediate objects. It isn't the best for high-volume, high-performance programs. Second, when assembling numeric results, additional ()'s are required; something that first-time programmers find unexpected.

• StringBuffer assembly works a little better. It doesn't create as many intermediate objects as simple String concatenation. However, it is a bit more wordy.

• The java.text.MessageFormat class is perhaps the nicest way to produce these kinds of formatted strings.

Example of simple String concatenation. In this case, we depend on a certain amount of automatic string conversion. This technique requires that the very first element be a String, and that any arithmetic operations have additional ()'s to permit them to be done first as numeric values before being converted to a string.

Example 4.2. Java Simple toString Implementation

public String toString() {
    return name + " (" + odds + ":1)"; 
}

We assemble a string from the name, some literals, and an implicit conversion of the odds to a string.

Example of StringBuffer construction. In this case, we append a number of strings into the StringBuffer.

Example 4.3. Java StringBuffer toString Implementation

public String toString() {
    StringBuffer result= new StringBuffer(); 
    result.append( name ).append( " (" ).
        append( odds ).append( ":1)" ); 
    return result.toString(); 
}

	Create an empty StringBuffer.
	Append various strings to the StringBuffer.
	Return a final String from the StringBuffer.

Example of using a MessageFormat object. In this case, a simple String message template will have the values inserted into it. The {0} markers show where values from the array of Objects are inserted into the output message. Eventually, the message template can be extracted to a ResourceBundle. While not essential for learning OO design, this is a good objective for high-quality software.

Example 4.4. Java MessageFormat toString Implementation

public String toString() {
    Object[] values= { name, new Integer(odds) }; 
    String msgTempl= "{0} ({1}:1)"; 
    return MessageFormat.format( msgTempl, values ); 
}

	Create an array of objects that will be converted to Strings and inserted into the message.
	Create the template message.
	Insert the objects into the template message, returning the new String.

There are two deliverables for this exercise. Both will have Javadoc comments or Python docstrings.

The Roulette wheel has 38 bins, identified with a number and a color. Each of these bins defines a number of closely related winning Outcomes. At this time, we won't enumerate each of the 38 Bins of the wheel and each of the winning Outcomes (from two to fourteen in each Bin); we'll save that for a later exercise. At this time, we'll define the Bin class, and use this class to contain a number of Outcome objects.

Two of the Bins have relatively few Outcomes. Specifically, the 0 Bin only contains the basic “0” Outcome and the “00-0-1-2-3” Outcome. The 00 Bin, similarly, only contains the basic “00” Outcome and the “00-0-1-2-3” Outcome.

The other 36 Bins contain the straight bet, split bets, street bet, corner bets, line bets and various outside bets (column, dozen, even or odd, red or black, high or low) that will win if this Bin is selected. Each number bin has from 12 to 14 individual winning Outcomes.

Some Outcomes, like red or black, occur in as many as 18 individual Bins. Other Outcomes, like the straight bet numbers, each occur in only a single Bin. We will have to be sure that our Outcome objects are shared appropriately by the Bins.

Since a Bin is just a collection of individual Outcome objects, we have to select a collection class to contain the objects. In Java we have five basic choices, with some variations based on performance needs. In Python, we have two basic choices.

Bin contains a collection of Outcomes which reflect the winning bets that are paid for a particular bin on a Roulette wheel. In Roulette, each spin of the wheel has a number of Outcomes. Example: A spin of 1, selects the “1” bin with the following winning Outcomes: “1”, “Red”, “Odd”, “Low”, “Column 1”, “Dozen 1-12”, “Split 1-2”, “Split 1-4”, “Street 1-2-3”, “Corner 1-2-4-5”, “Five Bet”, “Line 1-2-3-4-5-6”, “00-0-1-2-3”, “Dozen 1”, “Low” and “Column 1”. These are collected into a single Bin.

Constructors

In addition to the default constructor that makes an empty Bin, Java programmers may find it helpful to create a two additional constructors to initialize the collection from other collections.

• Bin();

  Creates an empty Bin. Outcomes can be added to it later.

• Bin(Outcome[] outcomes);

  Creates an empty Bin using the this() statement to invoke the default constructor. It then loads that collection using elements of the given array.

• Bin(Collection outcomes);

  Creates an empty Bin using the this() statement to invoke the default constructor. It then loads that collection using an iterator over the given Collection. This relies on the fact that all classes that implement Collection will provide the iterator; the constructor can convert the elements of the input collection to a proper Set.

The array constructor will initialize the outcomes Set from an array of Outcomes. This allows the following kind of constructor call from another class.

Example 5.1. Java Bin Construction

    Outcome five= new Outcome( "00-0-1-2-3", 6 );
    Outcome[] ocZero = {
        new Outcome("0", 35 ), five }; 
    Outcome[] ocZeroZero = {
        new Outcome("00", 35 ), five }; 
    Bin zero= new Bin( ocZero ); 
    Bin zerozero= bew Bin( ocZeroZero );

	This creates ocZero, which is an array of references to two objects: the “0” Outcome and the “00-0-1-2-3” Outcome.
	This creates ocZeroZero, which is an array of references to two objects: the “00” Outcome and the “00-0-1-2-3” Outcome.
	This creates zero, which is the final Bin, built from ocZero, which has both “0” and “five”.

Bin contains a collection of Outcomes which reflect the winning bets that are paid for a particular bin on a Roulette wheel. In Roulette, each spin of the wheel has a number of Outcomes. Example: A spin of 1, selects the “1” bin with the following winning Outcomes: “1”, “Red”, “Odd”, “Low”, “Column 1”, “Dozen 1-12”, “Split 1-2”, “Split 1-4”, “Street 1-2-3”, “Corner 1-2-4-5”, “Five Bet”, “Line 1-2-3-4-5-6”, “00-0-1-2-3”, “Dozen 1”, “Low” and “Column 1”. These are collected into a single Bin.

Constructors

Python programmers should provide an initializer that uses the * modifier so that all of the individual arguments appear as a single list within the initializer.

• def __init__(self, *outcomes):

This constructor can be used as follows.

Example 5.2. Python Bin Construction

    five= Outcome( "00-0-1-2-3", 6 )
    zero= Bin( Outcome("0",35), five ) 
    zerozero= Bin( Outcome("00",35), five ) 

	This creates zero Bin, which is based on references to two objects: the “0” Outcome and the “00-0-1-2-3” Outcome.
	This creates zerozero, which is based on references to two objects: the “00” Outcome and the “00-0-1-2-3” Outcome.

There are two deliverables for this exercise. Both will have Javadoc comments or Python docstrings.

The wheel has two responsibilities: it is a container for the Bins and it picks one of the Bins at random. We'll also have to look at how to initialize the various Bins.

Container Implementation. Since the Wheel is 38 Bins, it is a collection. We can review our survey of the Java collections in Java Collections and the Python collections in Python Collections for some guidance here. In this case, the choice of Bin will be selected by a random numeric index. For Java programmers, this makes the java.util.Vector very appealing. Python programmers will find that a List will do very nicely.

One consequence of using a Vector is that we have to choose an index for the various Bins. While each Bin contains a variety of individual Outcomes, the single number Outcome is unique to each Bin. The numbers 1 to 36 become the index to their respective Bins. We have a small problem, however, with 0 and 00: we need two separate indexes. While 0 is a valid index into a Vector, what do we do with 00?

Since the index of the Bin doesn't have any significance at all, we can assign the Bin that has the 00 Outcome to position 37 in the Vector. This gives us a unique place for all 38 Bins.

Random Selection. In order for the Wheel to select a Bin at random, we'll need a random number from 0 to 37 that we can use an an index. The random number generator in java.util.Random does everything we need. We can use the generator's public int nextInt(int n); method to return integers.

Python programmers can use the random module. This module offers a choice function which picks a random value from a sequence. This is ideal for returning a randomly selected Bin from our list of Bins. For some cautions on casual use of modules in Python, see Using Python Modules.

Initialization. Each instance of Bin has a list of Outcomes. The 0 and 00 Bins only have two Outcomes. The other numbers have anywhere from twelve to fourteen Outcomes. Constructing the entire collection of Bins would be a tedious undertaking. We'll apply a common OO design technique of deferred binding and work on that algorithm later, after we have the basic design for the Wheel finished.

Wheel contains the 38 individual bins on a Roulette wheel, plus a random number generator. It can select a Bin at random, simulating a spin of the Roulette wheel.

For those new to Java, see Java Subclass Constructors.

class PlayerRandom extends Player {
    public PlayerRandom( Table aTable ) {
        super( aTable );
    }
}

For those new to Python, see Python Subclass Constructors.

class PlayerRandom( Player ):
    def __init__( self, aTable ):
        Player.__init__( self, aTable )

There are three deliverables for this exercise. The new class and the unit test will have Javadoc comments or Python docstrings.

It is clear that enumerating each Outcome in the 38 Bins is a tedious undertaking. Most Bins contain about fourteen individual Outcomes. It is often helpful to create a class that is used to build an instance of another class. This is a design pattern sometimes called a Builder. We'll design an object that builds the various Bins and assigns them to the Wheel. This will fill the need left open in the design of the Wheel class.

Additionally, we note that the complex algorithms to construct the Bins are only tangential to the operation of the Wheel object. While not essential to the design of the Wheel class, we find it is often helpful to segregate these rather complex builder methods into a separate class.

The BinBuilder class will have a method that enumerates the contents of each of the 36 number Bins, building the individual Outcome instances. We can then assign these Outcome objects to the Bins of a Wheel instance. We will use a number of steps to create the various types of Outcomes, and depend on the Wheel to assign each Outcome object to the correct Bin.

Looking at the layout of a Roulette table gives us a number of geometric rules for determining the various Outcomes that are combinations of individual numbers. These rules apply to the numbers from one to thirty-six. A different -- and much simpler -- set of rules applies to 0 and 00. First, we'll survey the table geometry, then we'll develop specific algorithms for each kind of bet.

The Bins for zero and double zero can easily be enumerated. Each bin has a straight number bet Outcome, plus the Five Bet Outcome (00-0-1-2-3, which pays 6:1).

One other thing we'll probably want are handy names for the various kinds of odds. While can define an Outcome as Outcome( "Number 1", 35 ), this is a little opaque. A slightly nicer form is Outcome( "Number 1", RouletteGame.StraightBet ). These are specific to a game, not general features of all Outcomes. We haven't designed the game yet, but we can provide a stub class with these these outcome odds definitions.

Internationalization and Localization

An an advanced topic, we need to avoid hard coding the names of the bets. Both Java and Python provide extensive tools for localization (l10n) of programs. Since both applications already use Unicode strings, they support non-Latin characters, handling much of the internationalization (i18n) part of the process.

Java Localization. This application's bet names should be fetched from resource bundles so that we can change the bet names without making changes to BinBuilder and all of the various subclasses of Player that use various kinds of bets.

There are number of localization features in Java. We can specify a Locale object, which provides a number of defaults for the formatters in the java.text package and resource bundles with Strings that will be displayed to people.

We won't dwell on the l10n issue. However, the right preparation for l10n is to isolate all Strings used for messages, and format all dates and numbers with formatters found in the java.text package. In this case, our Outcome names may be displayed, and should be isolated into a separate object. Even something as simple as blackBetName = "Black"; will set the stage for fetching strings from resource bundles.

Python Localization. Python localization depends on the locale and gettext modules. The locale module provides a number of functions and constants to help format dates and times for the user's selected locale. The gettext module provides a mechanism for getting translated text from a message catalog with messages in a variety of languages.

We won't dwell on the l10n issue. However, the right preparation for l10n is to isolate all Strings used for messages, and format all dates and numbers with formatters found in the locale module. In this case, our Outcome names may be displayed, and should be isolated into a separate object. Even something as simple as blackBetName = _("Black") will set the stage for fetching strings from a gettext message catalog.

In order to define the _(string) function, the following fragment should be used. While not ubiquitous in Python programs, doing this now establishes a standard practice that will permit easy localization of an application program.

Example 7.1. Python Localization

import gettext
gettext.NullTranslations().install() 
print _("String To Be Translated") 

	This constructs an instance of NullTranslations. This is then installed as a function named _, which finds a translation for the default C-locale string. This class does nothing; but it can be replaced with the GNUTranslations class, which uses a message catalog to replace the default strings with localized strings.
	This shows how to use the _ function to translate a default C-locale string to a localized string.

Straight bet Outcomes are the easiest to generate.

Split bet Outcomes are more complex because of the various cases: corners, edges and down-the-middle.

We note that there are two kinds of split bets: left-right pairs and up-down pairs. The left-right pairs all have the form (n, n+1). The up-down paris have the form (n, n+3). We can look at the number 5 as being part of 4 different pairs: (4,4+1), (5,5+1), (2,2+3), (5,5+3). The corner number 1 is part of 2 split bets: (1,1+1), (1,1+3).

We can generate the “left-right” split bets by iterating through the left two columns; the numbers 1, 4, 7, ..., 34 and 2, 5, 8, ..., 35.

Similarly, for the numbers 1 through 33, we can generate the “up-down” split bets. For each number, n, we generate a “n, n+3” split bet. This Outcome belongs to two Bins: n and n+3.

Street bet Outcomes are very simple.

We can generate the street bets by iterating through the twelve rows of the layout.

Corner bet Outcomes are as complex as split bets because of the various cases: corners, edges and down-the-middle.

Eacb corner has four numbers, n, n+1, n+3, n+4. We can generate the corner bets by iterating through the numbers 1, 4, 7, ..., 31 and 2, 5, 8, ..., 32. For each number, n, we generate four corner bets: “n, n+1, n+3, n+4” corner bet. This Outcome object belongs to four Bins.

We generate corner bets by iterating through the lines between rows and columns. There are two lines between the three columns, and 11 lines between the 12 rows. The column lines are to the right of the first two columns. Similarly the row lines are below the first 11 rows.

Line bet Outcomes are similar to street bets. However, these are based around the 11 lines between the 12 rows.

For lines s numbered 0 to 10, the numbers on the line bet can be computed as follows: 3s+1, 3s+2, 3s+3, 3s+4, 3s+5, 3s+6. This Outcome object belongs to six individual Bins.

Dozen bet Outcomes require enumerating all twelve numbers in each of three groups.

Column bet Outcomes require enumerating all twelve numbers in each of three groups. While the outline of the algorithm is the same as the dozen bets, the enumeration of the individual numbers in the inner loop is slightly different.

The even money bet Outcomes are relatively easy to generate.

BinBuilder creates the Outcomes for all of the 38 individual Bin on a Roulette wheel.

There are three deliverables for this exercise. The new classes will have Javadoc comments or Python docstrings.

A Bet is an amount that the player has wagered on a specific Outcome. This class has the responsibilty for maintaining the association between an amount, an Outcome, and a specific Player.

This is the classic record declaration: a passive association among data elements. The only methods we can see are three pairs of getters and setters to get and set each of the three attributes.

The general scenario is to have a Player construct a number of Bet instances. The wheel is spun to select a winning Bin. Then each of the Bet objects will be checked to see if they are winners or losers. A winning Bet has an Outcome that matches one in the winning Bin; winners will return money to the Player. All other bets are losers, which remove the money from the Player.

Building Bets. In the long run, we'll need to build a variety of bets. Building a Bet involves two parts: an Outcome and an amount. There are several places to get Outcomes. First, we can create an Outcome object as part of constructing a Bet. Here's what it might look like in Java.

Bet myBet= new Bet( new Outcome("red",2), 25 )

A better choice is to get Outcome obects from the Wheel. To do this, we'd have to make sure that we saved Outcomes from the BinBuilder. We'd also have add specific Outcome getters to the Wheel. We could, for example, include a getBlack method that returns an instance of the black Outcome. In Python, for example, we might have a method function like the following.

class Wheel( object ):
...
    def getBlack( self ):
        return self.black

A third approach is to keep a Map (in Python, a dictionary) that maps an Outcome's string name to the relevant Outcome object. Our BinBuilder can accumulate this Map, and we can get Outcomes out of the Map with a getter method like the following.

Outcome getOutcome( String name ) {
    return outcomeMap.get(name);
}

For now, we'll build Outcomes manually in order to produce a good test of the Bet class.

Bet associates an amount and an Outcome. In a future round of design, we can also associate a it with a Player.

There are two deliverables for this exercise. The new classes will have Javadoc comments or Python docstrings.

The Table has the responsibility to keep the Bets created by the Player. Additionally, the house imposes table limits on the minimum amount that must be bet and the maximum that can be bet. Clearly, the Table has all the information required to evaluation these conditions.

It isn't clear where the responsibility lies for determining winning and losing bets. The money placed on Bets on the Table is “at risk” of being lost. If the bet is a winner, the house pays the Player an amount based on the Outcome's odds and the Bet's amount. If the bet is a loser, the amount of the Bet is forfeit by the Player. Looking forward to stateful games like Craps, we'll place the responsibility for determining winners and losers with the game, and not with the Table object.

Our second open question is the timing of the payment for the bet from the player's stake. In a casino, the payment happens when the bet is placed on the table. In our Roulette simulation, this is a subtlety that doesn't have any practical consequences. We could deduct the money as part of bet creation, or we could deduct the money as part of resolving the spin of the wheel. In other games, however, there may several events and several opportunities for additional bets. For example, splitting a hand in blackjack, or placing additional odds bets in Craps. Because we can't allow a player to bet more than their stake, we should deduct the payment as the bet is created.

A consequence of this is a change to our definition of the Bet class. We don't need to compute the amount that is lost. Rather than deduct the money when the bet resolved, we've decided that the money is deducted from the Player's stake as part of creating the Bet. This will become part of the design of Player and Bet.

Looking forward a little, a stateful game like Craps will introduce a subtle distinction that may be appropriate for a future subclass of Table. When the game is in the point off state, some of the bets on the table are not allowed, and others become inactive. When the game is in the point on state, all bets are allowed and active. In Craps parlance, some bets are “not working” or “working” depending on the game state. This does not apply to the version of Table that will support Roulette.

Container Implementation. A Table is a collection of Bets. We need to choose a concrete class for the collection of the bets. We can review our survey of the Java collections in Java Collections and the Python collections in Python Collections for some guidance here. In this case, the bets are placed in no particular order, and are simply visited in an arbitrary order for resolution. We can use a Java LinkedList for this. Since the number of bets varies, we can't use a Python tuple; a list will do.

Table Limits. Table limits can be checked by providing a public method isValid that compares the total of a new prospective amount plus all existing Bets to the table limit. This can be used by the Player to evaluate each potential bet prior to creating it.

In the unlikely event of the Player object creating an illegal Bet, we can also throw (or raise) an exception to indicate that we have a design error that was not detected via unit testing. This should be a subclass of Exception that has enough information to debug the problem with the Player that attempted to place the illegal bet.

Additionally, the game can check the overall state of a Player's Bets to be sure that the table minimum is met. We'll need to provide a public method isValid that is used by the game. In the event of the minimum not being met, there are serious design issues, and an exception should be thrown. Generally, this situation arises because of a bug where the Player should have declined to bet rather than placing incorrect bets that don't meet the table minimum.

Bet Resolution. An important consideration is the collaboration between Table and some potential game class for resolving bets. The Table has the collection of Bets, each of which has a specific Outcome. The Wheel selects a Bin, which has a collection of Outcomes. All bets with a winning outcome will be resolved as a winner.

Because some games are stateful, and the winning and losing bets depend on game state, we will defer the details of the collaboration design until we get to the Game class. For now, we'll simply collect the Bets.

Adding and Removing Bets. A Table contains Bets. Instances of Bet are added by a Player. Later, Bets will be removed from the Table by the Game. When a bet is resolved, it must be deleted. Some games, like Roulette resolve all bets with each spin. Other games, like Craps, involve multiple rounds of placing and resolving some bets, and leaving other bets in play.

For Bet deletion to work, we have to provide a method to remove a bet. When we look at Game and bet resolution we'll return to bet deletion. It's import not to over-design this class at this time; we will often add features as we develop designs for additional use cases.

There are two classes to design: the InvalidBet exception and the Table class.

 InvalidBet extends Exception {
}

class  InvalidBet ( Exception ): 
    pass 

There are three deliverables for this exercise. Each of these will have complete Javadoc comments or Python docstring comments.

The RouletteGame's responsibility is to cycle through the various steps of the game procedure, getting bets from the player, spinning the wheel and resolving the bets. This is an active class that makes use of the classes we have built so far. The hallmark of an active class is longer or more complex methods. This is distinct from most of the classes we have considered so far, which have relatively trivial methods that are little more than getters and setters of instance variables.

The sequence of operations in one round of the game is the following.

Matching Algorithm. This class has the responsibility for matching the collection of Outcomes in the Bin of the Wheel with the collection of Outcomes of the Bets on the Table. We have two collections that must be matched: Bin and Table. We'll need to structure a loop or nested loops to compare individual elements from these two collections.

We could use a loop to visit each Outcome in the winning Bin. For each Outcome, we would then visit each of the Bets contained by the Table. A Bet's Outcome that matches the Bin's Outcome is a winner and is paid off. The other bets are losers. This involves two nested loops: one to visit the winning Outcomes of a Bin and one to visit the Bets of a Table.

The alternative is to visit each Bet contained by the Table. Since the winning Bin is defined by a Set, we can exploit set membership methods to test for presence or absence of an Bet's Outcome in that Bin's Set. If the Bin contains the Outcome, the Bet is a winner; otherwise the Bet is a loser. This only requires a single loop to visit the Bets of a Table.

Player Interface. The Game collaborates with Player. We have a “chicken and egg” problem in decomposing the relationship between these classes. We note that the Player is really a complete hierarchy of subclasses, each of which provides a different betting strategy. For the purposes of making the Game work, we can develop our unit tests with a stub for Player that simply places a single kind of Bet. We'll call this player “Passenger57” because it always bets on Black. In several future exercises, we'll revisit this design to make more sophisticated players.

For some additional design considerations, see the sidebar Additional Design Considerations. This provides some more advanced game options that our current design can be made to support. We'll leave this as an exercise for the more advanced student.

There are two classes to design: a stub Player that we can use for testing, and the actual Game.

There are three deliverables for this exercise. The stub does not need documentation, but the other classes do need complete Javadoc or Python docstrings.

We have been studiously ignoring an elephant standing in the saloon. This is the problem of testing an application that includes a random number generator (RNG). There are two questions raised:

We'll address this first issue by developing some scaffolding that permits controlled testing. There are three approaches to replacing the random behavior with something more controlled. One approach is to subclass Wheel to create a more testable version without the random number generator. An alternative to changing wheel is to define a subclass of java.util.Random (or Python's random) that isn't actually random. A third approach is to record the sequence of random numbers actually generated from a particular seed value and use this to define the exected test results. For more information on this third alternative, see On Random Numbers.

Good testability is achieved when there are no changes to the target software. For this reason, we don't want to have two versions of Wheel, one for testing and one for normal operations.

Instead of having two versions of Wheel, it's slightly better to have a random number generator that creates a known sequence with which we can test. To get this known sequence, we have a choice between creating a non-random subclass of java.util.Random or controlling the seed for the random number generator used by Wheel. Both will produce a known sequence of non-random values.

One consequence of either of these decisions is that we have to make the random number generator in Wheel more visible. Our favorite approach to making something more visible is to assign an object through an official interface method or possible as part of the constructor. In the case of Wheel, we'd jave our overall simulation or test assign an appropriate number generating object to the instance of Wheel rather than have Wheel privately create a generator.

When we are doing testing, we can associate a Wheel with an instance of NonRandom, or an instance of Random initialized with a known seed. For actual use, we can then associate a Wheel with an instance of java.util.Random; this will either use the RNG's default constructor to assure unpredictability.

We'll need an additional constructor for Wheel that allows us to provide an appropriately initialized generator. Our current constructor secretly creates an instance of a RNG, using the RNG's default constructor. We'll need an additional method that provides an RNG, already initialized with an appropriate value.

For Python programmers, this is handled as a second parameter with a default value.

Note that, consistent with our principle of deferred binding, we don't have to choose exactly which implementation we will use. By allowing Wheel to take either an instance of Random initialized with a given seed or an instance of a new subclass, NonRandom, we have given ourselves the flexibility to choose either implementation. We'll provide specifications for NonRandom, but using a fixed seed for Random is seen by some as simpler.

We'll present the design modification for Wheel first. This will be followed by design information for NonRandom in both Java and Python.

There are five deliverables for this exercise. All of these deliverables need appropriate Javadoc comments or Python docstrings.

We have now built enough infrastructure that we can begin to add a variety of players and see how their betting strategies work. Each player is betting algorithm that we will evaluate by looking at the player's stake to see how much they win, and how long they play before they run out of time or go broke.

The Player has the responsibility to create bets and manage the amount of their stake. To create bets, the player must create legal bets from known Outcomes and stay within table limits. To manage their stake, the player must deduct money when creating a bet, accept winnings or pushes, report on the current value of the stake, and leave the table when they are out of money.

We have an interface that was roughed out as part of the design of Game and Table. In designing Game, we put a placeBets method in Player to place all bets. We expected the Player to create Bets and use the placeBet method of Table class to save all of the individual Bets.

In an earlier exercise, we built a stub version of Player in order to test Game. See Passenger57 Class. When we finish creating the final superclass, Player, we will also revise our Passenger57 to be a subclass of Player, and rerun our unit tests to be sure that our more complete design still handles the basic test cases correctly.

Our objective is to have a new abstract class, Player, with two new concrete subclasses: a revision to Passenger57 and a new player that follows the Martingale betting system.

We'll defer some of the design required to collect detailed measurements for statistical analysis. In this first release, we'll simply place bets.

There are four design issues tied up in Player: tracking stake, keeping within table limits, leaving the table, and creating bets. We'll tackle them in separate subsections.

Tracking the Stake. One of the more important features we need to add to Player are the methods to track the player's stake. The initial value of the stake is the player's budget. There are two significant changes to the stake.

We'll have to design an interface that will create Bets, reducing the stake. and will be used by Game to notify the Player of the amount won.

Additionally, we will need a method to reset the stake to the starting amount. This will be used as part of data collection for the overall simulation.

Table Limits. Once we have our superclass, we can then define the Martingale player as a subclass. This player doubles their bet on every loss, and resets their bet to a base amount on every win. In the event of a long sequence of losses, this player will have their bets rejected as over the table limit. This raises the question of how the table limit is represented and how conformance with the table limit is assured. We put a preliminary design in place in Roulette Table Class. There are several places where we could isolate this responsibility.

We recommend the second choice: adding a isValid method to the Table class. This has the consequence of allocating responsibility to Table, and permits us to have more advanced games where some bets are not allowed during some game states. It also obligates Player to validate each bet with the Table. It also means that at some point, the player may be unable to place a legal bet.

We could also implement this by adding to the responsibilities of the existing placeBet method. For example, we could return true if the bet was accepted, and false if the bet violated the limits or other game state rules. We prefer to isolate responsibility and create a second method rather than pile too much into a single method.

Leaving the Table. In enumerating the consequences of checking for legal bets, we also uncovered the issue of the Player leaving the game. We can identify a number of possible reasons for leaving: out of money, out of time, won enough, and unwilling to place a legal bet. Since this decision is private to the Player, we need a way of alerting the Game that the Player is finished placing bets.

There are three mechanisms for alerting the Game that the Player is finished placing bets.

We recommend adding a method to Player to indicate when Player is done playing. This gives the most flexibility, and it permits Game to cycle until the player withdraws from the game.

A consequence of this decision is to rework the Game class to allow the player to exit. This is relatively small change to interrogate the Player before asking the player to place bets.

Creating Bets from Outcomes. Generally, a Player will have a few Outcomes on which they are betting. Many systems are similar to the Martingale system, and place bets on only one of the Outcomes. These Outcome objects are usually created during player initialization. From these Outcomes, the Player can create the individual Bet instances based on their betting strategy.

We'll design the base class of Player and a specific subclass, Martingale. This will give us a working player that we can test with.

There are six deliverables for this exercise. The new classes must have Javadoc comments or Python docstrings.

We can now use our application to generate some more usable results. We can perform a number of simulation runs and evaluate the long-term prospects for the Martingale betting system. We want to know a few things about the game:

The Simulator will be an active class with a number of responsibilities

At this point, we'll need for formalize some definitions, just to be crystal clear on the responisbility allocation.

The sequence of operations for the simulator looks like this.

Both this overall Simulator and the Game collaborate with the Player. The Simulator's collaboration, however, initalizes the Player and then monitor's the changes to the Player's stake. We have to design two interfaces for this collaboration.

Player Initialization. The Simulator will initialize a Player for 250 cycles of play, assuming about one cycle each minute, and about four hours of patience. We will also initialize the player with a generous budget of the table limit, 100 betting units. For a $10 table, this is $1,000 bankroll.

Currently, the Player class is designed to play one session and stop when their duration is reached or their stake is reduced to zero. We have two alternatives for reinitializing the Player at the beginning of each session.

While the first solution is quite simple, there are some advantages to creating a PlayerFactory. If we create an Abstract Factory, we have a single place that creates all Players. Further, when we add new player subclasses, we introduce these new subclasses by creating a new subclass of the factory. In this case, however, only the main program creates instances of Player, reducing the value of the factory. While design of the factory is a good exercise, we can scrape by with adding setter methods to the Player class.

Player Interrogation. The Simulator will interrogate the Player after each cycle and capture the current stake. An easy way to manage this detailed data is to create a List that contains the stake at the end of each cycle. The length of this list and the maximum value in this list are the two metrics the Simulator gathers for each session.

Our list of maxima and durations are created sequentially during the session and summarized sequentially at the end of the session. A Java LinkedList will do everything we need. For a deeper discussion on the alternatives available in the collections framework, see Java Collections.

Statistical Summary. The Simulator will interrogate the Player after each cycle and capture the current stake. We don't want the sequence of stakes for each cycle, however, we want a summary of all the cycles in the session. We can save the length of the sequence as well as the maximum of the sequence to determine these two aggregate performance parameters for each session. Our objective is to run several session simulations to get averages and a standard deviations for duration and maximum stake. This means that the Simulator needs to retain these statistical samples. We will defer the detailed design of the statistical processing, and simply keep the duration and maximum values in Lists for this first round of design.

Simulator exercises the Roulette simulation with a given Player placing bets. It reports raw statistics on a number of sessions of play.

Handling Lists of Values in Java

Python programmers can skip this tip because Python can use lists of simple integer values. Using the map and reduce functions, Python programmers can implement handy statistical functions.

Java programmers can't easily accumulate a List of int values. This is because a primitive int value is not an object. The usual solution is to make an Integer value from the int, and put the Integer object into the list.

When getting values back out of the list, there is a two-step dance: cast the item in the list to be an Integer, then get the int value of that object. The following examples show this as two steps.

Example 13.1. Java Explicit Iteration Through a List of Integers

Integer tempMax = (Integer)iterator.next()) 
int aMax = tempMax.intValue(); 

	This gets the next Object from the iterator, and casts this to be an Integer.
	This gets the primitive int value from the Integer object.

Some people prefer the following. It is short, a little confusing to first-time programmers, but a common idiom.

Example 13.2. Java Compressed Iteration Through a List of Integers

int aMax = ((Integer)iterator.next()).intValue();

There are five deliverables for this exercise. Each of these classes needs complete Javadoc or Python docstring comments.

The SevenReds player waits for seven red wins in a row before betting black. This is a subclass of Player. We can create a subclass of our main Simulator to use this new SevenReds class.

We note that our previous players (Passenger57 and Martingale) are stateless: they place the same bets over and over until they are cleaned out or their playing session ends. This SevenReds player has two states: waiting and betting. In the waiting state, they are simply counting the number of reds. In the betting state, they have seen seven reds and are now playing the Martingale system on black. We will defer serious analysis of this stateful betting until some of the more sophisticated subclasses of Player. For now, we will simply use an integer to count the number of reds.

Currently, the player is not informed of the final outcome unless they place a bet. We designed the Game to evaluate the Bet instances and notify the Player of just their Bets that were wins or losses. We will need to add a method to Player to be given the overall list of winning Outcomes even when the Player has not placed a bet.

Once we have updated the design of Game to notify Player, we can add the new SevenReds class. Note that we are can intoduce each new betting strategy via creation of new subclasses. A relatively straightforward update to our simulation main program allows us to use these new subclasses. The previously working subclasses are left in place, allowing graceful evolution by adding features with minimal rework of existing classes.

In addition to waiting for the wheel to spin seven reds, we will also follow the Martingale betting system to track our wins and losses, assuring that a single win will recoup all of our losses. This makes SevenReds a further specialization of Martingale. We will be using the basic features of Martingale, but doing additional processing to determine if we should place a bet or not.

Introducing a new subclass should be done by upgrading the main program. See Soapbox on Composition for comments on the ideal structure for a main program. Additionally, see our Why does the Game class run the sequence of steps? Isn't that the responsibility of some “main program?” FAQ entry and Why are we making the random number generator more visible? Isn't object design about encapsulation? FAQ entry for more discussion.

Soapbox on Composition

Generally, a solution is composed of a number of objects. However, the consequences of this are often misunderstood. Since the solution is a composition of objects, it falls on the main method to do just the composition and nothing more.

Our ideal main program creates and composes the working set of objects. In this case, it should decode the command-line parameters, and use this information to create and initialize the simulation objects, then start the processing. For these simple exercises, however, we're omitting the parsing of command-line parameters, and simply creating the necessary objects directly.

Our main program should, therefore, look something like the following:

Example 14.1. Java Main Program

Random theRNG= new Random(); 
Wheel theWheel= new Wheel( theRNG );
Table theTable= new Table();
Game theGame= new Game( theWheel, theTable );
Player thePlayer= new SevenReds( table ); 
Simulator sim= new Simulator( theGame, thePlayer );
sim.gather(); 

	This can also use NonRandom. The idea is that we build up the functionality of Wheel by composition. We compose the wheel of the bins plus the number generator.
	This can also be Martingale or Passenger57 (who always bets on black). Again, we have assembled the final simulation by composition of a Wheel (and its generator), the Table and the specific Player algorithm.
	This is the actual work of the application, done by the Simulator, using the Game and Player objects built by main.

In many instances, the construction of objects is not done directly by the main method. Instead, the main method will construct a base group of Abstract Factory and Builder objects. Given these objects and the command-line parameters, the application objects can be built. The application objects then collaborate to perform the required functions.

SevenReds is a Martingale player who places bets in Roulette. This player waits until the wheel has spun red seven times in a row before betting black.

There are five deliverables from this exercise. The new classes will require complete Javadoc comments or Python docstrings.

Currently, the Simulator class collects two Lists. One has the length of a session, the other has the maximum stake during a session. We need to create some descriptive statistics to summarize these stakes and session lengths.

We will design a Statistics class with responsibility to retain and summarize a list of numbers and produce the average (also known as the mean) and standard deviation. The Simulator can then use this this Statistics class to get an average of the maximum stakes from the list of session-level measures. The Simulator can also apply this Statistics class to the list of session durations to see an average length of game play before going broke.

We can encapsulate this statistical processing in two ways: we could extend an existing class or we could delegate the statistical functions to a separate class. If we extend the library java.util.List, we can add the needed statistical summary features; given this new class, we can replace the original List of sample values with a StatisticalList that both saves the values and computes descriptive statistics. In addition to delegation, we have two choices for implementation of this extended version of List, giving us three alternative designs.

Alternative three -- a separate statistical class -- has the most reuse potential. We'll create a simple class with two methods: mean and stdev to compute the mean and standard deviation of a List of Integer objects. This can be used in a variety of contexts, and allows us the freedom to switch List implementation classes without any other changes.

The detailed algorithms for mean and standard deviation are provided in Statistical Algorithms.

Since our processes are relative simple, stateless algorithms, we don't need any instance variables. Consequently, we'll never need to create an instance of this class. As with Java.lang.Math, all of these methods can be declared as static, making them features of the class itself.

For those programmers new to statistics, this section covers the Sigma operator, Σ.

Equation 15.1. Basic Summation

The Σ operator has three parts to it. Below it is a bound variable, i and the starting value for the range, written as i=0. Above it is the ending value for the range, usually something like n. To the right is some function to execute for each value of the bound variable. In this case, a generic function, f(i). This is read as “sum f(i) for i in the range 0 to n”.

One common definition of Σ uses a closed range, including the end values of 0 and n. However, since this is not a helpful definition for software, we will define Σ to use a half-open interval. It has exactly n elements, including 0 and n-1; mathematically, .

Consequently, we prefer the following notation, but it is not often used. Since statistical and mathematical texts often used 1-based indexing, some care is required when translating formulae to programming languages that use 0-based indexing.

Equation 15.2. Summation with Half-Open Interval

Our two statistical algorithms have a form more like the following function. In this we are applying some function, f(), to each value, x_i of an array. When computing the mean, there is no function. When computing standard deviation, the function involves subtracting and multiplying.

Equation 15.3. Summing Elements of an Array, x

We can transform this definition directly into a for loop that sets the bound variable to all of the values in the range, and does some processing on each value of the List of Integers. This is the Java implementation of Sigma. This computes two values, the sum, sum and the number of elements, n.

Example 15.1. Java Sigma Iteration

int sum= 0;
for( int i= 0; i != theList.size(); ++i ) { 
    int xi= ((Integer)theList.get(i)).intValue(); 
    // int fxi = processing of xi 
    sum += fxi;
}
int n= theList.size();

	Get the size of theList. Execute the body of the loop for all values of i in the range 0 to the number of elements-1.
	Fetch item i from theList. This is an Object, which we cast to be an Integer. We then get the int value of this item and assign it to xi.
	For simple mean calculation, this statement does nothing. For standard deviation, however, this statement computes the measure of deviation from the average.

This is the Python implemention of Sigma. This computes two values, the sum, sum and the number of elements, n.

Example 15.2. Python Sigma Iteration

sum= 0
for i in range(len(theList)): 
    xi= theList[i] 
    # fxi = processing of xi 
    sum += fxi
n= len(theList)

	Get the length of theList. Execute the body of the loop for all values of i in the range 0 to the number of elements-1.
	Fetch item i from theList and assign it to xi.
	For simple mean calculation, this statement does nothing. For standard deviation, however, this statement computes the measure of deviation from the average.

More advanced Python programmers may be aware that there are several ways to shorten this loop down to a single expression using the sum function as well as list displays.

In the usual mathematical notation, an integer index, i is used. In Java or Python it isn't necessary to use the formal integer index. Instead, an iterator can be used to visit each element of the list, without actually using an explicit numeric counter. In Java, the use of an iterator is shown below.

Example 15.3. Java Sample Values by Iterator

int sum= 0;
for( Iterator i= theList.iterator(); i.hasNext();  ) { 
    int xi= ((Integer)i.next()).intValue(); 
    // int fxi = processing of xi 
    sum += fxi;
}
int n= theList.size();

	Get an Interator over all items of theList. Execute the body of the loop for all items in the iterator.
	Fetch the next item from the Interator, i. This is an Object, which we cast to be an Integer. We then get the int value of this item and assign it to xi.
	For simple mean calculation, this statement does nothing. For standard deviation, however, this statement computes the measure of deviation from the average.

In Python, the iterator is implied, and the processing simplifies to the following.

Example 15.4. Python Sample Values by Iterator

for xi in theList: 
    # fxi = processing of xi 
    sum += fxi
n= len(theList)

	Execute the loop assigning each item of of theList to xi.
	For simple mean calculation, this statement does nothing. For standard deviation, however, this statement computes the measure of deviation from the average.

These iterator-based formulations can be slightly faster when using a LinkedList because this class is optimized for exactly this kind of sequential access.

Computing the mean of a list of values is relatively simple. The mean is the sum of the values divided by the number of values in the list. Since the statistical formula is so closely related to the actual loop, we'll provide the formula, followed by an overview of the code.

Equation 15.4. Mean

The definition of the Σ mathematical operator leads us to the following method for computing the mean:

The standard deviation can be done a few ways, but we'll use the formula shown below. This computes a deviation measurement as the square of the difference between each sample and the mean. The sum of these measurements is then divided by the number of values times the number of degrees of freedom to get a standardized deviation measurement. Again, the formula summarizes the loop, so we'll show the formula followed by an overview of the code.

Equation 15.5. Standard Deviation

The definition of the Σ mathematical operator leads us to the following method for computing the standard deviation:

IntegerStatistics computes several simple descriptive statistics of Integer values in a List.

There are three deliverables for this exercise. These classes will include the complete Javadoc comments or Python dostring.

Here is some standard deviation unit test data, some intermediate results and the correct answers given to 6 significant digits. Your answers should be the same to the precision shown.

One possible betting strategy is to bet completely randomly. This serves as an interesting benchmark for other betting strategies.

We'll write a subclass of Player which steps through all of the bets available on the Wheel, selecting one or more of the available outcomes at random. This Player, like others, will have a fixed initial stake and a limited amount of time to play.

The Wheel class can provide an Iterator over the collection of Bin instances. We could revise Wheel to provide a binIterator method that we can use to return all of the Bins. From each Bin, we will need an iterator we can use to return all of the Outcomes.

To collect a list of all possible Outcomes, we would use the following algorithm:

To place a random bet, we would use the following algorithm:

PlayerRandom is a Player who places bets in Roulette. This player makes random bets around the layout.

There are five deliverables from this exercise. The new classes need Javadoc comments or Python docstrings.