This chapter is from the book
This chapter is from the book
This chapter is from the book
1.7 Scaladoc
Java programmers use Javadoc to navigate the Java API. Scala has its own variant, called Scaladoc (see Figure 1–1).
)
Navigating Scaladoc is a bit more challenging than Javadoc. Scala classes tend to have many more convenience methods than Java classes. Some methods use features that you haven’t learned yet. Finally, some features are exposed as they are implemented, not as they are used. (The Scala team is working on improving the Scaladoc presentation, so that it can be more approachable to beginners in the future.)
Here are some tips for navigating Scaladoc, for a newcomer to the language.
You can browse Scaladoc online at www.scala-lang.org/api, but it is a good idea to download a copy from www.scala-lang.org/downloads#api and install it locally.
Unlike Javadoc, which presents an alphabetical listing of classes, Scaladoc’s class list is sorted by packages. If you know the class name but not the package name, use the filter in the top left corner (see Figure 1–2).
){kind=link}
Figure 1–2 The filter box in Scaladoc
Click on the X symbol to clear the filter.
Note the O and C symbols next to each class name. They let you navigate to the class (C) or the companion object (O).
Scaladoc can be a bit overwhelming. Keep these tips in mind.
- Remember to look into RichInt, RichDouble, and so on, if you want to know how to work with numeric types. Similarly, to work with strings, look into StringOps.
- The mathematical functions are in the package scala.math, not in any class.
- Sometimes, you’ll see functions with funny names. For example, BigInt has a method unary_-. As you will see in Chapter 11, this is how you define the prefix negation operator -x.
- A method tagged as implicit is an automatic conversion. For example, the BigInt object has conversions from int and long to BigInt that are automatically called when needed. See Chapter 21 for more information about implicit conversions.
- Methods can have functions as parameters. For example, the count method in StringOps requires a function that returns true or false for a Char, specifying which characters should be counted:
def count(p: (Char) => Boolean) : Int
You supply a function, often in a very compact notation, when you call the method. As an example, the call s.count(_.isUpper) counts the number of uppercase characters. We will discuss this style of programming in much more detail in Chapter 12.
- You’ll occasionally run into classes such as Range or Seq[Char]. They mean what your intuition tells you—a range of numbers, a sequence of characters. You will learn all about these classes as you delve more deeply into Scala.
- Don’t get discouraged that there are so many methods. It’s the Scala way to provide lots of methods for every conceivable use case. When you need to solve a particular problem, just look for a method that is useful. More often than not, there is one that addresses your task, which means you don’t have to write so much code yourself.
Finally, don’t worry if you run into the occasional indecipherable incantation, such as this one in the StringOps class:
def patch [B >: Char, That](from: Int, patch: GenSeq[B], replaced: Int) (implicit bf: CanBuildFrom[String, B, That]): That
Just ignore it. There is another version of patch that looks more reasonable:
def patch(from: Int, that: GenSeq[Char], replaced: Int): StringOps[A]
If you think of GenSeq[Char] and StringOps[A] as String, the method is pretty easy to understand from the documentation. And it’s easy to try it out in the REPL:
"Harry".patch(1, "ung", 2) // Yields "Hungry"