Objects and classes - Data Structures and Problem Solving Using Java - page 79

Section we show the parts of the documentation most typically used by
programmers.
Figure 3.7 shows one section of the online documentation for the library
class java.math.BigInteger . Missing is the section that provides an overview
of the class in something resembling English (compare with Figure 3.5 to see
this missing preamble). The missing preamble tells us, among other things,
that BigIntegers , like Strings are immutable: once we create a BigInteger , its
value cannot change.
Next is a list of fields, which in our case are constants ZERO and ONE . If we
were to click on the hyperlink for ZERO or ONE , we would get a more complete
description that tells us these are public static final entities.
The next section lists the available constructors. There are actually six,
but only one is shown in our abbreviated listing, and it requires a String .
Again, if one clicks on the constructor name, the hyperlink takes us to a more
complete description, shown in Figure 3.8. Among other things, we find that
if the String contains extraneous whitespace, the constructor will fail and
throw an exception. These are the kinds of details that are always worth
knowing about.
Next we see a host of methods (again, this is an abbreviated list). Two
important methods are equals and toString ; since they are specifically listed
here, we can be sure that BigIntegers can be safely compared with equals
and output with a reasonable representation. Also present is a compareTo
method, and if we click on the hyperlink, we find that the general behavior
for compareTo is identical to the compareTo method in the String class. This is
not an accident, as we will see in Chapter 4. Also notice that by looking at
the signatures and the brief descriptions we can see that methods such as
add and multiply return newly created BigInteger objects, leaving the origi-
nals untouched. This is of course required, since BigInteger is an immutable
class.
Later in this Chapter we will use the BigInteger class as a component to
implement our own BigRational class ⎯ a class that will represent rational

numbers.

additional constructs

3.6

Three additional keywords are this , instanceof , and static . The keyword
this has several uses in Java; two are discussed in this section. The key-
word instanceof also has several general uses; it is used here to ensure that
a type-conversion can succeed. Likewise, static has several uses. We have
already discussed static methods. This section covers the static field and
static initializer .