Handling a base and radix

If you need to perform calculations using bases other than 10, use the parseInt method of the java.lang.Integer class, as shown in these examples:

Integer.parseInt("1", 2)     // Int = 1
Integer.parseInt("10", 2)    // Int = 2
Integer.parseInt("100", 2)   // Int = 4
Integer.parseInt("1", 8)     // Int = 1
Integer.parseInt("10", 8)    // Int = 8

Writing a pure function

However, in functional programming (FP) you’d never do this. As written, this method can short-circuit a caller’s code, and that’s something you never do in FP. (You might think of it as something you’d never do to another developer, or want another developer to do to you.) Instead, a pure function always returns the type that its signature shows. Therefore, in FP you’d write this function like this instead:

def makeInt(s: String): Option[Int] = {
    try {
        Some(s.toInt)
    } catch {
        case e: NumberFormatException => None
    }
}

This function is declared to return Option[Int], meaning that if you give it a "10", it will return a Some(10), and if you give it "Yo", it returns a None.

import scala.util.Try
def makeInt(s: String): Option[Int] = Try(s.toInt).toOption

makeInt("a")            // None
makeInt("1")            // Some(1)
makeInt("2147483647")   // Some(2147483647)
makeInt("2147483648")   // None

If you prefer to return Try from your function instead of Option you can write it like this:

import scala.util.{Try, Success, Failure}
def makeInt(s: String): Try[Int] = Try(s.toInt)

The advantage of using Try is that when things go wrong, it returns the reason for the failure inside a Failure object:

makeInt("1")   // Success(1)
makeInt("a")   // Failure(java.lang.NumberFormatException: For input string: "a")

Document methods that throw exceptions

These days I don’t like methods that throw exceptions, but if for some reason they do, I prefer that the behavior is documented. Therefore, if you’re going to allow an exception to be thrown, consider adding an @throws Scaladoc comment to your method:

@throws(classOf[NumberFormatException])
def makeInt(s: String) = s.toInt

This approach is required if the method will be called from Java code, as described in TODO:LINK:AddExceptionAnnotationsToScalaMethodsRecipe.

asInstanceOf

Depending on your needs you can also cast “with the flow” using asInstanceOf:

val b: Byte = 1          // Byte = 1

b.asInstanceOf[Short]    // Short = 1
b.asInstanceOf[Int]      // Int = 1
b.asInstanceOf[Long]     // Long = 1
b.asInstanceOf[Float]    // Float = 1.0
b.asInstanceOf[Double]   // Double = 1.0

For instance, if you have a Byte and a method wants a Double, you can use this technique:

// a method that wants a Double
def meWantDouble(d: Double): Unit = println(d.getClass)

// cast the Byte to Double when calling it
meWantDouble(b.asInstanceOf[Double])

BigInt

The BigInt constructor is overloaded, giving you nine different ways to construct one, including giving it an Int, Long, or String:

val i: Int = 101
val l: Long = 102
val s = "103"

val b1 = BigInt(i)   // BigInt = 101
val b2 = BigInt(l)   // BigInt = 102
val b3 = BigInt(s)   // BigInt = 103

BigInt also has isValid* and to* methods to help you cast a BigInt value to the numeric types:

• isValidByte, toByte

• isValidChar, toChar

• isValidDouble, toDouble

• isValidFloat, toFloat

• isValidInt, toInt

• isValidLong, toLong

• isValidShort, toShort

BigDecimal

Similarly, BigDecimal can be constructed in these ways:

BigDecimal(100.asInstanceOf[Int])     // BigDecimal = 100
BigDecimal(100.asInstanceOf[Long])    // BigDecimal = 100
BigDecimal(100.asInstanceOf[Float])   // BigDecimal = 100.0
BigDecimal(100.asInstanceOf[Double])  // BigDecimal = 100

BigDecimal has all the same isValid* and to* methods that the other types have. It also *Exact methods that work like this:

BigDecimal(100).toBigIntExact     // Some(100)
BigDecimal(100.5).toBigIntExact   // None

BigDecimal(100).toIntExact        // Int = 100
BigDecimal(100.5).toIntExact      // java.lang.ArithmeticException
BigDecimal(100.5).toLongExact     // java.lang.ArithmeticException
BigDecimal(100.5).toByteExact     // java.lang.ArithmeticException
BigDecimal(100.5).toShortExact    // java.lang.ArithmeticException

See the BigInt and BigDecimal Scaladoc for even more methods.

Random length ranges

Scala makes it easy to create a random-length range of numbers, which is especially useful for testing:

// random length ranges
0 to r.nextInt(10)   // Range 0 to 9
0 to r.nextInt(10)   // Range 0 to 3
0 to r.nextInt(10)   // Range 0 to 7

Remember that you can always convert a Range to a sequence if that’s what you need:

(0 to r.nextInt(10)).toList     // List(0, 1, 2, 3, 4)
(0 to r.nextInt(10)).toVector   // Vector(0, 1, 2)
(0 to r.nextInt(10)).toStream   // Stream(0, ?)

A for/yield loop gives you a nice way to modify the values in the sequence:

for (i <- 0 to r.nextInt(10)) yield i * 10

That approach yields sequences like these:

Vector(0, 10, 20, 30)
Vector(0, 10)
Vector(0, 10, 20, 30, 40, 50, 60, 70, 80)

Fixed-length ranges with random values

Another approach is to create a sequence of known length, filled with random numbers:

val seq = for (i <- 1 to 5) yield r.nextInt(100)

That approach yields sequences that contain five random integers, like these:

Vector(99, 6, 40, 77, 19)
Vector(1, 75, 87, 55, 39)
Vector(46, 40, 4, 82, 92)

You can do the same thing with nextFloat and nextDouble:

val seq = for (i <- 1 to 5) yield r.nextFloat
val seq = for (i <- 1 to 5) yield r.nextDouble

Shuffling an existing sequence

Another common need is to “randomize” an existing sequence. To do that, use the Random class shuffle method:

import scala.util.Random
val x = List(1, 2, 3)

Random.shuffle(x)   // List(3, 1, 2)
Random.shuffle(x)   // List(2, 3, 1)

Getting a random element from a sequence

If you have an existing sequence and want to get a single random element from it, you can use this function:

import scala.util.Random

def getRandomElement[A](list: Seq[A], random: Random): A =
    list(random.nextInt(list.length))

Here are a few examples of how to use this method:

val r = scala.util.Random

// integers
val ints = (1 to 100).toList
getRandomElement(ints, r)    // Int = 66
getRandomElement(ints, r)    // Int = 11

// strings
val names = List("Hala", "Helia", "Hannah", "Hope")
getRandomElement(names, r)   // Hala
getRandomElement(names, r)   // Hannah

to

A simple way to create a range is with the to method:

scala> val r = 1 to 5
r: scala.collection.immutable.Range.Inclusive = Range(1, 2, 3, 4, 5)

You can set an optional step with the by method:

val r = 1 to 10 by 2   // Range(1, 3, 5, 7, 9)
val r = 1 to 10 by 3   // Range(1, 4, 7, 10)

Ranges are commonly used in for loops:

scala> for (i <- 1 to 3) println(i)
1
2
3

until

When creating a Range you can use until instead of to:

scala> for (i <- 1 until 3) println(i)
1
2

until doesn’t include the last element you specify, as shown in these examples:

(1 to 3).toVector            // Vector(1, 2, 3)
(1 until 3).toVector         // Vector(1, 2)

(1 to 10 by 3).toVector      // Vector(1, 4, 7, 10)
(1 until 10 by 3).toVector   // Vector(1, 4, 7)

Discussion

Another approach to creating a sequence is to use the range method that’s available on sequence objects:

Vector.range(1, 3)      // Vector(1, 2)
Vector.range(1, 6, 2)   // Vector(1, 3, 5)
List.range(1, 6, 2)     // List(1, 3, 5)

As shown in those examples, the second parameter is not included in the result, so it works like the until method, and the third parameter is the step.

Finally, note that you can use the same approaches with characters:

('d' to 'h').toVector       // Vector(d, e, f, g, h)
('d' until 'h').toVector    // Vector(d, e, f, g)
('a' to 'f').by(2).toList   // List(a, c, e)

1 to

(1 to 10 by 3).toVector      // Vector(1, 4, 7, 10)
(1 to 10).by(3).toVector     // Vector(1, 4, 7, 10)
1.to(10).by(3).toVector      // Vector(1, 4, 7, 10)
1.until(10).by(3).toVector   // Vector(1, 4, 7)

fill and tabulate

Depending on your needs, another way to initially populate a sequence is to use the fill and tabulate methods that are available on sequence objects:

Vector.fill(3)("yo")             // Vector(yo, yo, yo)
Vector.tabulate(3)(n => n * n)   // Vector(0, 1, 4)
Vector.tabulate(4)(n => n * n)   // Vector(0, 1, 4, 9)

A few more examples of these methods are included in the recipes on the collections classes.

The f string interpolator

The f string interpolator, which is discussed in detail in Recipe 1.4, provides simple number formatting capabilities:

val pi = scala.math.Pi   // Double = 3.141592653589793
println(f"${pi}%1.5f")   // 3.14159

A few more examples demonstrate the technique:

// floating-point
f"${pi}%1.2f"    // String = 3.14
f"${pi}%1.3f"    // String = 3.142
f"${pi}%1.5f"    // String = 3.14159
f"${pi}%6.2f"    // String = "  3.14"
f"${pi}%06.2f"   // String = 003.14

// whole numbers
val x = 10000
f"${x}%d"        // 10000
f"${x}%2d"       // 10000
f"${x}%8d"       // "   10000"
f"${x}%-8d"      // "10000   "

If you prefer the explicit use of the format method that’s available to strings, write the code like this instead:

"%06.2f".format(pi)   // String = 003.14

Commas, locales, and integers

If you need to add commas to integer values, use NumberFormat’s getIntegerInstance method:

import java.text.NumberFormat
val formatter = NumberFormat.getIntegerInstance

formatter.format(10000)     // String = 10,000
formatter.format(1000000)   // String = 1,000,000

You can set a locale with getIntegerInstance and the Locale class:

import java.util.Locale

val formatter = NumberFormat.getIntegerInstance(Locale.GERMANY)

formatter.format(1000)      // 1.000
formatter.format(10000)     // 10.000
formatter.format(100000)    // 100.000
formatter.format(1000000)   // 1.000.000

Commas, locales, and floating-point values

You can handle floating-point values with a formatter returned by getInstance:

val formatter = NumberFormat.getInstance

formatter.format(12.34)        // 12.34
formatter.format(1234.56)      // 1,234.56
formatter.format(1234567.89)   // 1,234,567.89

You can also set a locale with getInstance:

val formatter = NumberFormat.getInstance(Locale.GERMANY)

formatter.format(12.34)        // 12,34
formatter.format(1234.56)      // 1.234,56
formatter.format(1234567.89)   // 1.234.567,89

Currency

For currency output, use the getCurrencyInstance formatter:

val formatter = NumberFormat.getCurrencyInstance

formatter.format(123.456789)   // $123.46
formatter.format(12345.6789)   // $12,345.68
formatter.format(1234567.89)   // $1,234,567.89

Use a Locale to handle international currency:

import java.util.{Currency, Locale}

val deCurrency = Currency.getInstance(Locale.GERMANY)
val formatter = java.text.NumberFormat.getCurrencyInstance
formatter.setCurrency(deCurrency)

formatter.format(123.456789)   // EUR123.46
formatter.format(12345.6789)   // EUR12,345.68
formatter.format(1234567.89)   // EUR1,234,567.89

If you don’t use a currency library you’ll probably want to use BigDecimal, which also works with getCurrencyInstance:

import java.text.NumberFormat
import scala.math.BigDecimal.RoundingMode

var b = BigDecimal("10000")
b = b.setScale(2, RoundingMode.DOWN)

val formatter = NumberFormat.getCurrencyInstance

formatter.format(b)   // String = $10,000.00

Here’s a BigDecimal example that uses a locale:

import java.util.Locale
val formatter = NumberFormat.getCurrencyInstance(Locale.GERMANY)
var b = BigDecimal("1234567.891").setScale(2, RoundingMode.DOWN)

formatter.format(b)   // String = 1.234.567,89 €

Custom formatting patterns

You can also create your own formatting patterns with the DecimalFormat class. Just create the pattern you want, then apply the pattern to a number using the format method, as shown in these examples:

import java.text.DecimalFormat

val df = new DecimalFormat("0.##")
df.format(123.45)        // 123.45 (type = String)
df.format(123.4567890)   // 123.46
df.format(.1234567890)   // 0.12
df.format(1234567890)    // 1234567890

val df = new DecimalFormat("0.####")
df.format(.1234567890)   // 0.1235
df.format(1234.567890)   // 1234.5679
df.format(1234567890)    // 1234567890

val df = new DecimalFormat("#,###,##0.00")
df.format(123)           // 123.00
df.format(123.4567890)   // 123.46
df.format(1234.567890)   // 1,234.57
df.format(1234567890)    // 1,234,567,890.00

See the Java DecimalFormat class for more formatting pattern characters (and a warning that, in general, you shouldn’t create a direct instance of DecimalFormat).

“Now”

To create instances to represent the current date and time, use the now methods that are available on the new classes in the API:

import java.time._

LocalDate.now       // 2019-01-20
LocalTime.now       // 12:19:26.270
LocalDateTime.now   // 2019-01-20T12:19:26.270
Instant.now         // 2019-01-20T19:19:26.270Z
ZonedDateTime.now   // 2019-01-20T12:44:53.466-07:00[America/Denver]

The results of those methods demonstrate the data that’s stored in each type.

Past or future

To create dates and times in the past or future, use the of factory methods on each of the classes shown. For example, here are a few ways to create java.time.LocalDate instances with its of factory methods:

val squirrelDay = LocalDate.of(2020, 1, 21)
val squirrelDay = LocalDate.of(2020, Month.JANUARY, 21)
val squirrelDay = LocalDate.of(2020, 1, 1).plusDays(20)

Note that with LocalDate, January is represented by 1 (not 0).

java.time.LocalTime has five of* factory methods, including these:

LocalTime.of(hour: Int, minute: Int)
LocalTime.of(hour: Int, minute: Int, second: Int)

LocalTime.of(0, 0)    // 00:00
LocalTime.of(0, 1)    // 00:01
LocalTime.of(1, 1)    // 01:01
LocalTime.of(23, 59)  // 23:59

These intentional exceptions help demonstrate the valid values for minutes and hours:

LocalTime.of(23, 60)  // DateTimeException: Invalid value for MinuteOfHour,
                      // (valid values 0 - 59): 60

LocalTime.of(24, 1)   // DateTimeException: Invalid value for HourOfDay,
                      // (valid values 0 - 23): 24

java.time.LocalDateTime has nine of* factory method constructors, including these:

LocalDateTime.of(year: Int, month: Int, dayOfMonth: Int, hour: Int, minute: Int)
LocalDateTime.of(year: Int, month: Month, dayOfMonth: Int, hour: Int, minute: Int)
LocalDateTime.of(date: LocalDate, time: LocalTime)

java.time.ZonedDateTime has seven of* factory method constructors, including these:

of(int year, int month, int dayOfMonth, int hour, int minute, int second,
   int nanoOfSecond, ZoneId zone)
of(LocalDate date, LocalTime time, ZoneId zone)
of(LocalDateTime localDateTime, ZoneId zone)
ofInstant(Instant instant, ZoneId zone)

Here’s an example of the second method:

val zdt = ZonedDateTime.of(
    LocalDate.now,
    LocalTime.now,
    ZoneId.of("America/New_York")
)

// result: 2019-01-20T13:05:28.119-05:00[America/New_York]

While I’m in the neighborhood, a few other java.time.ZoneId values look like this:

ZoneId.of("Europe/Paris")
ZoneId.of("Asia/Tokyo")
ZoneId.of("America/New_York")
ZoneId zoneId = ZoneId.of("UTC+1")   // an offset from UTC (Greenwich) time

java.time.Instant has three of* factory methods:

Instant.ofEpochMilli(epochMilli: Long)
Instant.ofEpochSecond(epochSecond: Long)
Instant.ofEpochSecond(epochSecond: Long, nanoAdjustment: Long)

Instant.ofEpochMilli(100)   // Instant = 1970-01-01T00:00:00.100Z

The Instant class is nice for many reasons, including giving you the ability to calculation the time duration between two instants:

import java.time.{Instant, Duration}

val start = Instant.now                     // Instant = 2019-01-20T19:31:59.467Z
Thread.sleep(2000)
val stop = Instant.now                      // Instant = 2019-01-20T19:32:01.472Z
val delta = Duration.between(start, stop)   // Duration = PT2.005S
delta.toMillis                              // Long = 2194
delta.toNanos                               // Long = 2194000000

Predefined formatters

DateTimeFormatter provides fifteen predefined formatters you can use. This example shows how to use a formatter with a LocalDate:

import java.time.format.DateTimeFormatter
val d = LocalDate.now   // 2019-01-19

val f = DateTimeFormatter.BASIC_ISO_DATE
f.format(d)             // 20190119

These examples show what the other date formatters look like:

ISO_LOCAL_DATE     // 2019-01-19
ISO_DATE           // 2019-01-19
BASIC_ISO_DATE     // 20190119
ISO_ORDINAL_DATE   // 2019-019
ISO_WEEK_DATE      // 2019-W03-6

Locale formatters

Create locale formatters using these static DateTimeFormatter methods:

• ofLocalizedDate

• ofLocalizedTime

• ofLocalizedDateTime

• ofLocalizedDate

You also apply one of four java.time.format.FormatStyle values when creating a localized date:

• SHORT

• MEDIUM

• LONG

• FULL

This example demonstrates how to use ofLocalizedDate with a LocalDate and FormatStyle.FULL:

import java.time.LocalDate
import java.time.format.{DateTimeFormatter, FormatStyle}

val d = LocalDate.of(2019, 12, 25)
val f = DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL)
f.format(d)   // 12/25/19

Using the same technique, this is what the four format styles look like:

SHORT    // 12/25/19
MEDIUM   // Dec 25, 2019
LONG     // December 25, 2019
FULL     // Wednesday, December 25, 2019

Custom patterns with ofPattern

You can also create custom patterns by specifying your own formatting strings. Here’s an example of the technique:

import java.time.LocalDate
import java.time.format.DateTimeFormatter

val d = LocalDate.now  //2019-01-20
val f = DateTimeFormatter.ofPattern("yyyy-MM-dd")
f.format(d)   // 2019-01-20

Here are a few other common patterns:

"MM/dd/yyyy"       // 01/20/2019
"MMM dd, yyyy"     // Jan 20, 2019
"E, MMM dd yyyy"   // Sun, Jan 20 2019

This example demonstrates how to format a LocalTime:

import java.time.LocalTime
import java.time.format.DateTimeFormatter

val t = LocalTime.now
val f = DateTimeFormatter.ofPattern("h:mm a")
f.format(t)   // 6:48 PM

These are two time patterns I commonly use:

"h:mm a"       // 6:48 PM
"HH:mm:ss a"   // 18:48:33 PM

With a LocalDateTime you can format both date and time output:

import java.time.LocalDateTime
import java.time.format.DateTimeFormatter

val t = LocalDateTime.now
val f = DateTimeFormatter.ofPattern("MMM dd, yyyy h:mm a")
f.format(t)   // Jan 20, 2019 6:52 PM

See the DateTimeFormatter class for a complete list of predefined formats and formatting pattern characters that are available.

LocalDate

This example shows the default format for LocalDate:

val d = LocalDate.parse("2010-12-10")   // LocalDate = 2010-12-10

If you try to pass a string into parse with the wrong format, you’ll get an exception:

val d = LocalDate.parse("2010/12/10")   // java.time.format.DateTimeParseException

To accept a string in a different format, create a formatter for the desired pattern:

import java.time.format.DateTimeFormatter

val df = DateTimeFormatter.ofPattern("yyyy/MM/dd")
val d = LocalDate.parse("2010/12/10", df)   // LocalDate = 2010-12-10

LocalTime

These examples demonstrate the default format for java.time.LocalTime:

val t = LocalTime.parse("01:02")     //01:02
val t = LocalTime.parse("13:02:03")  //13:02:03

Notice that each field requires a leading 0:

val t = LocalTime.parse("1:02")      //java.time.format.DateTimeParseException
val t = LocalTime.parse("1:02:03")   //java.time.format.DateTimeParseException

These examples demonstrate several ways of using formatters:

import java.time.format.DateTimeFormatter

LocalTime.parse("00:00", DateTimeFormatter.ISO_TIME)
    // 00:00
LocalTime.parse("23:59", DateTimeFormatter.ISO_LOCAL_TIME)
    // 23:59
LocalTime.parse("23 59 59", DateTimeFormatter.ofPattern("HH mm ss"))
    // 23:59:59
LocalTime.parse("11 59 59 PM", DateTimeFormatter.ofPattern("hh mm ss a"))
    // 23:59:59

LocalDateTime

This example demonstrates the default format for java.time.LocalDateTime:

val s = "2019-07-22T12:13:14"
val ldt = LocalDateTime.parse(s)   // 2019-07-22T12:13:14

These examples demonstrate several ways of using formatters:

val s = "1999-12-31 23:59"
val f = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm")
val ldt = LocalDateTime.parse(s, f)
    // 1999-12-31 23:59

val s = "1999-12-31 11:59:59 PM"
val f = DateTimeFormatter.ofPattern("yyyy-MM-dd hh:mm:ss a")
val ldt = LocalDateTime.parse(s, f)
    // 1999-12-31 11:59:59 PM

Instant

java.time.Instant only has one parse method that requires a date/time stamp in the proper format:

Instant.parse("1970-01-01T00:01:02.00Z")   // 1970-01-01T00:01:02Z
Instant.parse("2019-07-22T23:59:59.00Z")   // 2019-07-22T23:59:59Z

ZonedDateTime

These examples demonstrate the default formats for java.time.ZonedDateTime:

ZonedDateTime.parse("2019-12-31T23:59:59-06:00")
    // 2019-12-31T23:59:59-06:00

ZonedDateTime.parse("2019-12-31T23:59:59-00:00[US/Mountain]")
    // 2019-12-31T23:59:59-07:00[US/Mountain]

These examples demonstrate several ways of using formatters:

import java.time.ZonedDateTime
import java.time.format.DateTimeFormatter._

val zdt = ZonedDateTime.parse("2020-01-01T01:02:03Z", ISO_ZONED_DATE_TIME)
    // 2020-01-01T01:02:03Z

ZonedDateTime.parse("2019-12-31T23:59:59+01:00", ISO_DATE_TIME)
    // 2019-12-31T23:59:59+01:00

ZonedDateTime.parse("2020-02-29T00:00:00-05:00", ISO_OFFSET_DATE_TIME)
    // 2020-02-29T00:00-05:00

ZonedDateTime.parse("Sat, 29 Feb 2020 00:01:02 GMT", RFC_1123_DATE_TIME)
    // 2020-02-29T00:01:02Z