Chapter 4. Outcome Class

Chapter 4. Outcome Class
	Part I. Roulette

Table of Contents

Fields
Constructors
Methods

In addition to defining the fundamental Outcome on which all gambling is based, this chapter provides a sidebar discussion on the notion of object identity and object equality. This is important because we will be dealing with a number of individual Outcome objects, and we need to be sure we can test for equality of two different objects. This is different from the test for identity which asks if we have two references to the same object.

Overview

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:

Provide a method for equals that compares the name of the Outcome instead of the hashcode.
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.


Questions and Answers		Design