new classes tour

Author: travissarles

tutorials/tour/_posts/2017-02-13-classes.md

@@ -9,46 +9,105 @@ categories: tour
 num: 4
 next-page: traits
 previous-page: unified-types
+topics: classes
+assumed-knowledge: no-return-keyword, type-declaration-syntax, string-interpolation
 ---
 
-Classes in Scala are static templates that can be instantiated into many objects at runtime.
-Here is a class definition which defines a class `Point`:
+Classes in Scala are blueprints for creating objects. They can contain methods,
+values, and variables, which are collectively called _members_.
+
+## Defining a class
+A minimal class definition is simply the keyword `class` and
+an identifier:
+```tut
+class MyClass
+```
+However, a class will often have a primary constructor and a body as well. Here is an example class definition for a point:
 
 ```tut
 class Point(var x: Int, var y: Int) {
+
   def move(dx: Int, dy: Int): Unit = {
     x = x + dx
     y = y + dy
   }
+
   override def toString: String =
-    "(" + x + ", " + y + ")"
+    s"($x, $y)"
 }
 ```
 
-Classes in Scala are parameterized with constructor arguments. The code above defines two constructor arguments, `x` and `y`; they are both visible in the whole body of the class.
+This `Point` class has four members: the variables `x` and `y` and the methods `move` and
+`toString`. Unlike many other languages, the primary constructor is in the class signature `(var x: Int, var y: Int)`. The `move` method takes two integer arguments but does not return a value (the return type `Unit` corresponds to `void` in Java-like languages). `toString`, on the other hand, does not take any parameters but returns a `String` value. Since `toString` overrides the inherited `toString` method, it is tagged with the `override` keyword.
+
+## Constructors
+
+Constructors can have optional parameters by providing a default value like so:
 
-The class also includes two methods, `move` and `toString`. `move` takes two integer arguments but does not return a value (the return type `Unit` corresponds to `void` in Java-like languages). `toString`, on the other hand, does not take any parameters but returns a `String` value. Since `toString` overrides the pre-defined `toString` method, it is tagged with the `override` keyword.
+```tut
+class Point(var x: Int = 0, var y: Int = 0)
+
+val origin = new Point()
 
-Note that in Scala, it isn't necessary to say `return` in order to return a value. The value returned from a method is simply the last value in the method body. In the case of the `toString` method above, the expression after the equals sign is evaluated and returned to the caller.
+println(origin) // (0, 0)
+```
 
-Classes are instantiated with the `new` primitive, as follows:
+Optional parameters give you a lot of flexibility but if you still need more flexibility, you can create auxiliary constructors which are procedures (i.e. a `def` with no `=` and no return type).
 
 ```tut
-object Classes {
-  def main(args: Array[String]) {
-    val pt = new Point(1, 2)
-    println(pt)
-    pt.move(10, 10)
-    println(pt)
+class Point {
+  def this(x: Int, y: Int) {
+    this()
+    if (x > 100 || y > 100) println("Warning: Out of bounds")
   }
 }
 ```
+There are few requirements for auxiliary constructors:
+* They must start with `def this`
+* The parameters must _not_ be declared `val` or `var`
+* The first statement in the body must call the primary constructor or another auxiliary constructor. In the example above, the implicit primary constructor, `this()`, is called.
+
+## Member scope
+Methods are public by default. Use the `private` access modifier
+to hide them from outside of the class.
+```tut
+import scala.math._
+
+class Point(var x: Double, var y: Double) {
+  private def distanceFromOrigin = sqrt(x * x + y * y)
+
+  override def toString: String =
+    s"Point: ($x, $y), Distance from origin: $distanceFromOrigin"
+  }
+```
+
+You can also simply nest private methods inside of the public ones
+that use them:
+
+```tut
+import scala.math.sqrt
+
+class Point(var x: Double, var y: Double) {
 
-The program defines an executable application Classes in form of a top-level [singleton object](singleton-objects) with a `main` method. The `main` method creates a new `Point` and stores it in value `pt`. Note that values defined with the `val` construct are different from variables defined with the `var` construct (see class `Point` above) in that they do not allow updates; i.e. the value is constant.
+  override def toString: String = {
+    def distanceFromOrigin = sqrt(x * x + y * y)
 
-Here is the output of the program:
+    s"Point: ($x, $y), Distance from origin: $distanceFromOrigin"
+
+  }
+}
+```
+
+Primary constructor parameters with `val` and `var` are public. However, because `val`s are immutable, you can't write the following.
+```
+class Point(val x: Int, val y: Int)
+val point = new Point(1, 2)
+val.x = 3  // <-- does not compile
+```
 
+Parameters without `val` or `var` are private values, visible only within the class and its subclasses.
 ```
-(1, 2)
-(11, 12)
+class Point(x: Int, y: Int)
+val point = new Point(1, 2)
+val.x  // <-- does not compile
 ```