rewrote singleton objects tour

Author: travissarles

tutorials/tour/_posts/2017-02-13-singleton-objects.md

@@ -10,65 +10,111 @@ num: 13
 
 next-page: xml-processing
 previous-page: pattern-matching
+assumed-knowledge: classes, methods, private-methods, packages
 ---
 
-Methods and values that aren't associated with individual instances of a [class](classes.html) belong in *singleton objects*, denoted by using the keyword `object` instead of `class`.
+A singleton object is an instance of a new class. There is exactly one instance of each singleton object. They do not have constructors so they cannot be instantiated.
 
+# Defining a singleton object
+Like with classes, the simplest form of an object is the keyword `object` and an identifier:
+```tut
+object Box
+```
+
+Here's an example of an object with a method:
 ```
-package test
+package logging
 
-object Blah {
-  def sum(l: List[Int]): Int = l.sum
+object Logger {
+  def info(message: String): Unit = println(s"INFO: $message")
 }
 ```
+The method `info` can be imported from anywhere in the program. Creating utility methods like this is a common use case for singleton objects (however, more sophisticated logging techniques exist). Let's see how to use `info` in another package:
 
-This `sum` method is available globally, and can be referred to, or imported, as `test.Blah.sum`.
+```
+import logging.Logger.info
 
-Singleton objects are sort of a shorthand for defining a single-use class, which can't directly be instantiated, and a `val` member at the point of definition of the `object`, with the same name. Indeed, like `val`s, singleton objects can be defined as members of a [trait](traits.html) or class, though this is atypical.
+class Project(name: String, daysToComplete: Int)
 
-A singleton object can extend classes and traits. In fact, a [case class](case-classes.html) with no [type parameters](generic-classes.html) will by default create a singleton object of the same name, with a [`Function*`](http://www.scala-lang.org/api/current/scala/Function1.html) trait implemented.
+val project1 = new Project("TPS Reports", 1)
+val project2 = new Project("Website redesign", 5)
+info("Created projects")  // Prints "INFO: Created projects"
+```
 
-## Companions ##
+The `info` method becomes visible in the scope of the package using `import logging.Logger.info`. You could also use `import logging.Logger._` to import everything from Logger.
 
-Most singleton objects do not stand alone, but instead are associated with a class of the same name. The “singleton object of the same name” of a case class, mentioned above, is an example of this. When this happens, the singleton object is called the *companion object* of the class, and the class is called the *companion class* of the object.
+## Companion objects
 
-[Scaladoc](https://wiki.scala-lang.org/display/SW/Introduction) has special support for jumping between a class and its companion: if the big “C” or “O” circle has its edge folded up at the bottom, you can click the circle to jump to the companion.
+A singleton object with the same name as a class is called a _companion object_. Conversely, the class is the object's companion class. The companion class and object can access each other's private members. Use a companion object for methods and values which are not specific to instances of the companion class.
+```
+import scala.math._
 
-A class and its companion object, if any, must be defined in the same source file. Like this:
+class Circle(val radius: Double) {
+  def area: Double = Circle.calculateArea(radius)
+}
 
-```tut
-class IntPair(val x: Int, val y: Int)
+object Circle {
+  def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0)
+}
 
-object IntPair {
-  import math.Ordering
+val circle1 = new Circle(5.0)
 
-  implicit def ipord: Ordering[IntPair] =
-    Ordering.by(ip => (ip.x, ip.y))
-}
+circle1.area
 ```
 
-It's common to see typeclass instances as [implicit values](implicit-parameters.html), such as `ipord` above, defined in the companion, when following the typeclass pattern. This is because the companion's members are included in the default implicit search for related values.
+The `class Circle` contains the val `radius` which is specific to each instance whereas the `object Circle` contains the method `calculateArea` which is the same for every instance.
 
-## Notes for Java programmers ##
+A common pattern to simplify calls to the companion object's members from the companion class is to import everything:
+```
+import java.time.LocalDateTime;
+import java.time.DayOfWeek
 
-`static` is not a keyword in Scala. Instead, all members that would be static, including classes, should go in a singleton object instead. They can be referred to with the same syntax, imported piecemeal or as a group, and so on.
+object Event {
+  private def _isOnTheWeekend(date: LocalDateTime) = Array(DayOfWeek.SATURDAY, DayOfWeek.SUNDAY).contains(date.getDayOfWeek)
+}
 
-Frequently, Java programmers define static members, perhaps `private`, as implementation aids for their instance members. These move to the companion, too; a common pattern is to import the companion object's members in the class, like so:
+class Event(name: String, date: LocalDateTime) {
+  import Event._
 
+  def isOnTheWeekend: Boolean = _isOnTheWeekend(date)
+}
+
+val event = new Event("Dotty Days", LocalDateTime.of(2020, 2, 2, 9, 0, 0))
+event.isOnTheWeekend  // true
 ```
-class X {
-  import X._
 
-  def blah = foo
-}
+The `class Event` imports `_isOnTheWeekend` from the `object Event`. To make a member inaccessible from outside, use `private[this]`.
+
+Note: If a class or object has a companion, both must be defined in the same file. To define them in the REPL, you must enter `:paste` and then paste in the class and companion object code.
+
+## Sharing global state
+
+Objects can also be used to store global state (i.e. contain mutable fields), though this is not thread safe and should only be used in special cases.
 
-object X {
-  private def foo = 42
+```
+package ids
+
+object UserIdGenerator {
+  private var lastId = 0
+  def newId: Int = {
+    lastID += 1
+    lastID
+  }
 }
 ```
+Because there is only one instance of UserIdGenerator, there is also only one instance of the `lastId` variable. Any call to `newId` from anywhere in the program will update `lastId`.
+```
+package users
+
+import ids.UserIDGenerator.newId
 
-This illustrates another feature: in the context of `private`, a class and its companion are friends. `object X` can access private members of `class X`, and vice versa. To make a member *really* private to one or the other, use `private[this]`.
+class User(id: Int)
 
-For Java convenience, methods, including `var`s and `val`s, defined directly in a singleton object also have a static method defined in the companion class, called a *static forwarder*. Other members are accessible via the `X$.MODULE$` static field for `object X`.
+val user1 = new User(newId)  // lastId gets updated to 1
+val user2 = new User(newId)  // lastId gets updated to 2
+```
+
+## Notes for Java programmers ##
 
-If you move everything to a companion object and find that all you have left is a class you don't want to be able to instantiate, simply delete the class. Static forwarders will still be created.
+`static` is not a keyword in Scala. Instead, all members that would be static, including classes, should go in a singleton object instead.
+When using a companion object from Java code, the members will be defined in a companion class with a `static` modifier. This is called _static forwarding_. It occurs even if you haven't defined a companion class yourself.