Constructing Strings

Literal strings, defined in your source code, are declared with double quotes and can be assigned to a String variable:

    String quote = "To be or not to be";

Java automatically converts the literal string into a String object and assigns it to the variable.

Strings keep track of their own length, so String objects in Java don’t require special terminators. You can get the length of a String with the length() method. You can also test for a zero length string by using isEmpty():

    int length = quote.length();
    boolean empty = quote.isEmpty();

Strings can take advantage of the only overloaded operator in Java, the + operator, for string concatenation. The following code produces equivalent strings:

    String name = "John " + "Smith";
    String name = "John ".concat("Smith");

Literal strings can’t (yet²) span lines in Java source files, but we can concatenate lines to produce the same effect:

    String poem =
        "'Twas brillig, and the slithy toves
" +
        "   Did gyre and gimble in the wabe:
" +
        "All mimsy were the borogoves,
" +
        "   And the mome raths outgrabe.
";

Embedding lengthy text in source code is not normally something you want to do. In Chapter 11, we’ll talk about ways to load Strings from files and URLs.

In addition to making strings from literal expressions, you can construct a String directly from an array of characters:

    char [] data = new char [] { 'L', 'e', 'm', 'm', 'i', 'n', 'g' };
    String lemming = new String( data );

You can also construct a String from an array of bytes:

    byte [] data = new byte [] { (byte)97, (byte)98, (byte)99 };
    String abc = new String(data, "ISO8859_1");

In this case, the second argument to the String constructor is the name of a character-encoding scheme. The String constructor uses it to convert the raw bytes in the specified encoding to the internally used encoding chosen by the runtime. If you don’t specify a character encoding, the default encoding scheme on your system is used.³

Conversely, the charAt() method of the String class lets you access the characters of a String in an array-like fashion:

    String s = "Newton";
    for ( int i = 0; i < s.length(); i++ )
        System.out.println( s.charAt( i ) );

This code prints the characters of the string one at a time.

The notion that a String is a sequence of characters is also codified by the String class implementing the interface java.lang.CharSequence, which prescribes the methods length() and charAt() as well as a way to get a subset of the characters.

Strings from Things

Objects and primitive types in Java can be turned into a default textual representation as a String. For primitive types like numbers, the string should be fairly obvious; for object types, it is under the control of the object itself. We can get the string representation of an item with the static String.valueOf() method. Various overloaded versions of this method accept each of the primitive types:

    String one = String.valueOf( 1 ); // integer, "1"
    String two = String.valueOf( 2.384f );  // float, "2.384"
    String notTrue = String.valueOf( false ); // boolean, "false"

All objects in Java have a toString() method that is inherited from the Object class. For many objects, this method returns a useful result that displays the contents of the object. For example, a java.util.Date object’s toString() method returns the date it represents formatted as a string. For objects that do not provide a representation, the string result is just a unique identifier that can be used for debugging. The String.valueOf() method, when called for an object, invokes the object’s toString() method and returns the result. The only real difference in using this method is that if you pass it a null object reference, it returns the String “null” for you, instead of producing a NullPointerException:

    Date date = new Date();
    // Equivalent, e.g., "Fri Dec 19 05:45:34 CST 1969"
    String d1 = String.valueOf( date );
    String d2 = date.toString();

    date = null;
    d1 = String.valueOf( date );  // "null"
    d2 = date.toString();  // NullPointerException!

String concatenation uses the valueOf() method internally, so if you “add” an object or primitive using the plus operator (+), you get a String:

    String today = "Today's date is :" + date;

You’ll sometimes see people use the empty string and the plus operator (+) as shorthand to get the string value of an object. For example:

    String two = "" + 2.384f;
    String today = "" + new Date();

Comparing Strings

The standard equals() method can compare strings for equality; they contain exactly the same characters in the same order. You can use a different method, equalsIgnoreCase(), to check the equivalence of strings in a case-insensitive way:

    String one = "FOO";
    String two = "foo";

    one.equals( two );             // false
    one.equalsIgnoreCase( two );   // true

A common mistake for novice programmers in Java is to compare strings with the == operator when they intend to use the equals() method. Remember that strings are objects in Java, and == tests for object identity; that is, whether the two arguments being tested are the same object. In Java, it’s easy to make two strings that have the same characters but are not the same string object. For example:

    String foo1 = "foo";
    String foo2 = String.valueOf( new char [] { 'f', 'o', 'o' }  );

    foo1 == foo2         // false!
    foo1.equals( foo2 )  // true

This mistake is particularly dangerous because it often works for the common case in which you are comparing literal strings (strings declared with double quotes right in the code). The reason for this is that Java tries to manage strings efficiently by combining them. At compile time, Java finds all the identical strings within a given class and makes only one object for them. This is safe because strings are immutable and cannot change. You can coalesce strings yourself in this way at runtime using the String intern() method. Interning a string returns an equivalent string reference that is unique across the VM.

The compareTo() method compares the lexical value of the String to another String, determining whether it sorts alphabetically earlier than, the same as, or later than the target string. It returns an integer that is less than, equal to, or greater than zero:

    String abc = "abc";
    String def = "def";
    String num = "123";

    if ( abc.compareTo( def ) < 0 )         // true
    if ( abc.compareTo( abc ) == 0 )        // true
    if ( abc.compareTo( num ) > 0 )         // true

The compareTo() method compares strings strictly by their characters’ positions in the Unicode specification. This works for simple text but does not handle all language variations well. The Collator class, discussed next, can be used for more sophisticated comparisons.

Searching

The String class provides several simple methods for finding fixed substrings within a string. The startsWith() and endsWith() methods compare an argument string with the beginning and end of the String, respectively:

    String url = "http://foo.bar.com/";
    if ( url.startsWith("http:") )  // true

The indexOf() method searches for the first occurrence of a character or substring and returns the starting character position, or -1 if the substring is not found:

    String abcs = "abcdefghijklmnopqrstuvwxyz";
    int i = abcs.indexOf( 'p' );     // 15
    int i = abcs.indexOf( "def" );   // 3
    int I = abcs.indexOf( "Fang" );  // -1

Similarly, lastIndexOf() searches backward through the string for the last occurrence of a character or substring.

The contains() method handles the very common task of checking to see whether a given substring is contained in the target string:

    String log = "There is an emergency in sector 7!";
    if  ( log.contains("emergency") ) pageSomeone();

    // equivalent to
    if ( log.indexOf("emergency") != -1 ) ...

For more complex searching, you can use the Regular Expression API, which allows you to look for and parse complex patterns. We’ll talk about regular expressions later in this chapter.

String Method Summary

Table 8-1 summarizes the methods provided by the String class. We’ve included several methods we have not discussed in this chapter to make sure you’re aware of other String capabilities. Feel free to try these methods out in jshell or look up the documentation online.

Parsing Primitive Numbers

In Java, numbers, characters, and booleans are primitive types—not objects. But for each primitive type, Java also defines a primitive wrapper class. Specifically, the java.lang package includes the following classes: Byte, Short, Integer, Long, Float, Double, Character, and Boolean. We talked about these in “Wrappers for Primitive Types”, but we bring them up now because these classes hold static utility methods that know how to parse their respective types from strings. Each of these primitive wrapper classes has a static “parse” method that reads a String and returns the corresponding primitive type. For example:

    byte b = Byte.parseByte("16");
    int n = Integer.parseInt( "42" );
    long l = Long.parseLong( "99999999999" );
    float f = Float.parseFloat( "4.2" );
    double d = Double.parseDouble( "99.99999999" );
    boolean b = Boolean.parseBoolean("true");

Alternately, the java.util.Scanner provides a single API for not only parsing individual primitive types from strings, but reading them from a stream of tokens. This example shows how to use it in place of the preceding wrapper classes:

    byte b = new Scanner("16").nextByte();
    int n = new Scanner("42").nextInt();
    long l = new Scanner("99999999999").nextLong();
    float f = new Scanner("4.2").nextFloat();
    double d = new Scanner("99.99999999").nextDouble();
    boolean b = new Scanner("true").nextBoolean();

Tokenizing Text

A common programming task involves parsing a string of text into words or “tokens” that are separated by some set of delimiter characters, such as spaces or commas. The first example contains words separated by single spaces. The second, more realistic problem involves comma-delimited fields.

    Now is the time for all good men (and women)...

    Check Number, Description,      Amount
    4231,         Java Programming, 1000.00

Java has several (unfortunately overlapping) APIs for handling situations like this. The most powerful and useful are the String split() and Scanner APIs. Both utilize regular expressions to allow you to break the string on arbitrary patterns. We haven’t talked about regular expressions yet, but in order to show you how this works we’ll just give you the necessary magic and explain in detail later in this chapter. We’ll also mention a legacy utility, java.util.StringTokenizer, which uses simple character sets to split a string. StringTokenizer is not as powerful, but doesn’t require an understanding of regular expressions.

The String split() method accepts a regular expression that describes a delimiter and uses it to chop the string into an array of Strings:

    String text = "Now is the time for all good men";
    String [] words = text.split("\s");
    // words = "Now", "is", "the", "time", ...

    String text = "4231,         Java Programming, 1000.00";
    String [] fields = text.split("\s*,\s*");
    // fields = "4231", "Java Programming", "1000.00"

In the first example, we used the regular expression \s, which matches a single whitespace character (space, tab, or carriage return). The split() method returned an array of eight strings. In the second example, we used a more complicated regular expression, \s*,\s*, which matches a comma surrounded by any number of contiguous spaces (possibly zero). This reduced our text to three nice, tidy fields.

With the new Scanner API, we could go a step further and parse the numbers of our second example as we extract them:

    String text = "4231,         Java Programming, 1000.00";
    Scanner scanner = new Scanner( text ).useDelimiter("\s*,\s*");
    int checkNumber = scanner.nextInt(); // 4231
    String description = scanner.next(); // "Java Programming"
    float amount = scanner.nextFloat();  // 1000.00

Here, we’ve told the Scanner to use our regular expression as the delimiter and then called it repeatedly to parse each field as its corresponding type. The Scanner is convenient because it can read not only from Strings but directly from stream sources (more in Chapter 11) such as InputStreams, Files, and Channels:

    Scanner fileScanner = new Scanner( new File("spreadsheet.csv") );
    fileScanner.useDelimiter( "\s*,\s* );
    // ...

Another thing that you can do with the Scanner is to look ahead with the “hasNext” methods to see if another item is coming:

    while( scanner.hasNextInt() ) {
      int n = scanner.nextInt();
      ...
    }

    String text = "Now is the time for all good men (and women)...";
    StringTokenizer st = new StringTokenizer( text );

    while ( st.hasMoreTokens() )  {
        String word = st.nextToken();
        ...
    }

    String text = "4231,     Java Programming, 1000.00";
    StringTokenizer st = new StringTokenizer( text, "," );

    while ( st.hasMoreTokens() )  {
       String word = st.nextToken();
       // word = "4231", "     Java Programming", "1000.00"
    }

Regex Notation

A regular expression describes a pattern in text. By pattern, we mean just about any feature you can imagine identifying in text from the literal characters alone, without actually understanding their meaning. This includes features, such as words, word groupings, lines and paragraphs, punctuation, case, and more generally, strings and numbers with a specific structure to them, such as phone numbers, email addresses, and quoted phrases. With regular expressions, you can search the dictionary for all the words that have the letter “q” without its pal “u” next to it, or words that start and end with the same letter. Once you have constructed a pattern, you can use simple tools to hunt for it in text or to determine if a given string matches it. A regex can also be arranged to help you dismember specific parts of the text it matched, which you could then use as elements of replacement text if you wish.

    "\d" // Java string that yields backslash "d"

    "\\"  // Java string yields two backslashes; regex yields one

    "A rose is $1.99."

    [abcxyz]

    [A-Za-z]

    [^A-F]    //  G, H, I, ..., a, b, c, ... etc.

    [A-F[G-Z]w]   // A-Z plus whitespace

    [a-p&&[l-z]]  // l, m, n, o, p
    [A-Z&&[^P]]  // A through Z except P

    "A rose is a rose is a rose"

    ^[Aa] rose  // matches "A rose" at the beginning of line
    [Aa] rose$  // matches "a rose" at end of line

    brose

    w+, w+ d+ d+|dd/dd/dd  // pattern 1 or pattern 2

    w+@[w.]*.(net|edu|gov)  // email address ending in .net, .edu, or .gov

The java.util.regex API

Now that we’ve covered the theory of how to construct regular expressions, the hard part is over. All that’s left is to investigate the Java API for applying these expressions.

    Pattern urlPattern = Pattern.compile("\w+://[\w/]*");

    Matcher matcher = urlPattern.matcher( myText );

    Boolean match = Pattern.matches( "\d+\.\d+f?", myText );

    String sample = "[email protected]";
    Boolean validEmail = Pattern.matches(".*@.*", sample);

    String sample = "[email protected]";
    Boolean validEmail = Pattern.matches("[^@]+@[^@]+", sample);

    String sample = "[email protected]";
    Boolean validEmail = Pattern.matches("[^@]+@[^@]+\.(com|org)", sample);

    String sample = "[email protected]";
    Boolean validEmail = Pattern.matches("[^@]+@[^@]+\.[a-z]+", sample);

    String sample = "[email protected]";
    Boolean validEmail = Pattern.matches("(?i)[^@]+@[^@]+\.[a-z]+", sample);

jshell> Pattern.matches("(?i)[^@]+@[^@]+\.[a-z]+", "[email protected]")
$1 ==> true

jshell> Pattern.matches("(?i)[^@]+@[^@]+\.[a-z]+", "[email protected]")
$2 ==> true

jshell> Pattern.matches("(?i)[^@]+@[^@]+\.[a-z]+", "oreilly.com")
$3 ==> false

jshell> Pattern.matches("(?i)[^@]+@[^@]+\.[a-z]+", "bad@oreilly@com")
$4 ==> false

jshell> Pattern.matches("(?i)[^@]+@[^@]+\.[a-z]+", "[email protected]")
$5 ==> true

jshell> Pattern.matches("[^@]+@[^@]+\.[a-z]+", "[email protected]")
$6 ==> false

    import java.util.regex.*;

    String text="A horse is a horse, of course of course...";
    String pattern="horse|course";

    Matcher matcher = Pattern.compile( pattern ).matcher( text );
    while ( matcher.find() )
      System.out.println(
        "Matched: '"+matcher.group()+"' at position "+matcher.start() );

    Matched: 'horse' at position 2
    Matched: 'horse' at position 13
    Matched: 'course' at position 23
    Matched: 'course' at position 33

    for (int i=1; i < matcher.groupCount(); i++)
    System.out.println( matcher.group(i) );

    String text = "Foo, bar ,   blah";
    String[] badFields = text.split(",");
    String[] goodFields = text.split( "\s*,\s*" );

    Pattern.compile(pattern).split(string);

The java.lang.Math Class

The java.lang.Math class is Java’s math library. It holds a suite of static methods covering all of the usual mathematical operations like sin(), cos(), and sqrt(). The Math class isn’t very object-oriented (you can’t create an instance of Math). Instead, it’s really just a convenient holder for static methods that are more like global functions. As we saw in Chapter 5, it’s possible to use the static import functionality to import the names of static methods and constants like this directly into the scope of our class and use them by their simple, unqualified names.

Table 8-3 summarizes the methods in java.lang.Math.

log(), pow(), and sqrt() can throw a runtime ArithmeticException. abs(), max(), and min() are overloaded for all the scalar values, int, long, float, or double, and return the corresponding type. Versions of Math.round() accept either float or double and return int or long, respectively. The rest of the methods operate on and return double values:

    double irrational = Math.sqrt( 2.0 ); // 1.414...
    int bigger = Math.max( 3, 4 );  // 4
    long one = Math.round( 1.125798 ); // 1

And just to highlight the convenience of that static import option, we can try these simple functions in jshell:

jshell> import static java.lang.Math.*

jshell> double irrational = sqrt(2.0)
irrational ==> 1.4142135623730951

jshell> int bigger = max(3,4)
bigger ==> 4

jshell> long one = round(1.125798)
one ==> 1

Math also contains the static final double values E and PI:

    double circumference = diameter  * Math.PI;

Math in Action

We’ve already touched on using the Math class and its static methods in “Accessing Fields and Methods”. We can use it again in making our game a little more fun by randomizing where the trees appear. The Math.random() method returns a random double greater than or equal to 0 and less that 1. Add in a little arithmetic and rounding or truncating and you can use that value to create random numbers in any range you need. In particular, converting this value into a desired range follows this formula:

    int randomValue = min + (int)(Math.random() * (max - min));

Try it! Try to generate a random 4-digit number in jshell. You could set the min to 1000 and the max to 10000, like so:

jshell> int min = 1000
min ==> 1000

jshell> int max = 10000
max ==> 10000

jshell> int fourDigit = min + (int)(Math.random() * (max - min))
fourDigit ==> 9603

jshell> fourDigit = min + (int)(Math.random() * (max - min))
fourDigit ==> 9178

jshell> fourDigit = min + (int)(Math.random() * (max - min))
fourDigit ==> 3789

To place our trees, we’ll need two random numbers for the x and y coordinates. We can set a range that will keep the trees on the screen by thinking about a margin around the edges. For the x coordinate, one way to do that might look like this:

private int goodX() {
    // at least half the width of the tree plus a few pixels
    int leftMargin = Field.TREE_WIDTH_IN_PIXELS / 2 + 5;
    // now find a random number between a left and right margin
    int rightMargin = FIELD_WIDTH - leftMargin;

    // And return a random number starting at the left margin
    return leftMargin + (int)(Math.random() * (rightMargin - leftMargin));
}

Set up a similar method for finding a y value and you should start to see something like the image shown in Figure 8-1. You could even get fancy and use the isTouching() method we discussed back in Chapter 5 to avoid placing any trees in direct contact with our physicist. Here’s our upgraded tree setup loop:

for (int i = field.trees.size(); i < Field.MAX_TREES; i++) {
    Tree t = new Tree();
    t.setPosition(goodX(), goodY());
    // Trees can be close to each other and overlap,
    // but they shouldn't intersect our physicist
    while(player1.isTouching(t)) {
        // We do intersect this tree, so let's try again
        t.setPosition(goodX(), goodY());
        System.err.println("Repositioning an intersecting tree...");
    }
    field.addTree(t);
}

Figure 8-1. Randomly distributed trees

Try quitting the game and launching it again. You should see the trees in different places each time you run the application.

Big/Precise Numbers

If the long and double types are not large or precise enough for you, the java.math package provides two classes, BigInteger and BigDecimal, that support arbitrary-precision numbers. These full-featured classes have a bevy of methods for performing arbitrary-precision math and precisely controlling rounding of remainders. In the following example, we use BigDecimal to add two very large numbers and then create a fraction with a 100-digit result:

    long l1 = 9223372036854775807L; // Long.MAX_VALUE
    long l2 = 9223372036854775807L;
    System.out.println( l1 + l2 ); // -2 ! Not good.
     
    try {
        BigDecimal bd1 = new BigDecimal( "9223372036854775807" );
        BigDecimal bd2 = new BigDecimal( 9223372036854775807L );
        System.out.println( bd1.add( bd2 ) ); // 18446744073709551614
     
        BigDecimal numerator = new BigDecimal(1);
        BigDecimal denominator = new BigDecimal(3);
        BigDecimal fraction =
            numerator.divide( denominator, 100, BigDecimal.ROUND_UP );
        // 100 digit fraction = 0.333333 ... 3334
    }
    catch (NumberFormatException nfe) { }
    catch (ArithmeticException ae) { }

If you implement cryptographic or scientific algorithms for fun, BigInteger is crucial. BigDecimal, in turn, can be found in applications dealing with currency and financial data. Other than that, you’re not likely to need these classes.

Local Dates and Times

The java.time.LocalDate class represents a date without time information for your local region. Think of a holiday such as May 4, 2019. Similarly, java.time.LocalTime represents a time without any date information. Perhaps your alarm clock goes off at 7:15 every morning. The java.time.LocalDateTime stores both date and time values for things like appointments with your eye doctor so you can keep reading books on Java. All of these classes offer static methods for creating new instances using either appropriate numeric values with of() or by parsing strings with parse(). Let’s pop into jshell and try creating a few examples.

jshell> import java.time.*

jshell> LocalDate.of(2019,5,4)
$2 ==> 2019-05-04

jshell> LocalDate.parse("2019-05-04")
$3 ==> 2019-05-04

jshell> LocalTime.of(7,15)
$4 ==> 07:15

jshell> LocalTime.parse("07:15")
$5 ==> 07:15

jshell> LocalDateTime.of(2019,5,4,7,0)
$6 ==> 2019-05-04T07:00

jshell> LocalDateTime.parse("2019-05-04T07:15")
$7 ==> 2019-05-04T07:15

Another great static method for creating these objects is now() which provides the current date or time or date-and-time as you might expect:

jshell> LocalTime.now()
$8 ==> 15:57:24.052935

jshell> LocalDate.now()
$9 ==> 2019-12-12

jshell> LocalDateTime.now()
$10 ==> 2019-12-12T15:57:37.909038

Great! After importing the java.time package, we can create instances of each of the Local… classes for specific moments or for “right now”. You may have noticed the objects created with now() include seconds and nanoseconds. You can supply those values to the of() and parse() methods if you want or need them. Not much exciting there, but once you have these objects, you can do a lot with them. Read on!

Comparing and Manipulating Dates and Times

One of the big advantages of using java.time classes is the consistent set of methods you have available for comparing and changing dates and times. For example, many chat applications will show you “how long ago” a message was sent. The java.time.temporal subpackage has just what we need: the ChronoUnit interface. It contains several date and time units such as MONTHS, DAYS, HOURS, MINUTES, etc. These units can be used to calculate differences. For example, we could calculate how long it takes us to create two example date-times in jshell using the between() method:

jshell> LocalDateTime first = LocalDateTime.now()
first ==> 2019-12-12T16:03:21.875196

jshell> LocalDateTime second = LocalDateTime.now()
second ==> 2019-12-12T16:03:33.175675

jshell> import java.time.temporal.*

jshell> ChronoUnit.SECONDS.between(first, second)
$12 ==> 11

A visual spot check shows that it did indeed take about 11 seconds to type in the line that created our second variable. You should check out the docs for ChronoUnit for a complete list of units available, but you get the full range from nanoseconds up to millennia.

Those units can also help you manipulate dates and times with the plus() and minus() methods. To set a reminder for one week from today, for example:

jshell> LocalDate today = LocalDate.now()
today ==> 2019-12-12

jshell> LocalDate reminder = today.plus(1, ChronoUnit.WEEKS)
reminder ==> 2019-12-19

Neat! But this reminder example brings up another bit of manipulation you may need to perfrom from time to time. You might want the reminder at a paricular time on the 19th. You can convert between dates or times and date-times easily enough with the atDate() or atTime() methods:

jshell> LocalDateTime betterReminder = reminder.atTime(LocalTime.of(9,0))
betterReminder ==> 2019-12-19T09:00

Now we’ll get that reminder at 9 o’clock AM. Except, what if we set that reminder in Atlanta and then flew to San Francisco? When would the alarm go off? LocalDateTime is, well, local! So the T09:00 portion is still 9 o’clock AM wherever we are when we run the program. But if we are handling something like a shared calendar and scheduling a meeting, we cannot ignore the different time zones involved. Fortunately the java.time package has thought of that, too.

Time Zones

The authors of the new java.time package certainly encourage you to use the local variations of the time and date classes where possible. Adding support for time zones means adding complexity to your app—they want you to avoid that complexity if possible. But there are many scenarios where support for time zones is unavoidable. You can work with “zoned” dates and times using the ZonedDateTime and OffsetDateTime classes. The zoned variant understands named time zones and things like daylight saving adjustments. The offset variant is a constant, simple numeric offset from UTC/Greenwich.

Most user-facing uses of dates and times will use the named zone approach so let’s look at created a zoned date-time. To attach a zone, we use the ZoneId class which has the commmon of() static method for creating new instances. You can supply a region zone as a String to get your zoned value.

jshell> LocalDateTime piLocal = LocalDateTime.parse("2019-03-14T01:59")
piLocal ==> 2019-03-14T01:59

jshell> ZonedDateTime piCentral = piLocal.atZone(ZoneId.of("America/Chicago"))
piCentral ==> 2019-03-14T01:59-05:00[America/Chicago]

And now you can do things like make sure your friends in Paris are able to join you at the correct moment using the verbose but aptly named withZoneSameInstant() method.

jshell> ZonedDateTime piAlaMode = piCentral.withZoneSameInstant(ZoneId.of("Europe/Paris"))
piAlaMode ==> 2019-03-14T07:59+01:00[Europe/Paris]

If you have other friends who aren’t conveniently located in a major metropolitan region but you want them to join as well, you can use the systemDefault() method of ZoneId to pickup their time zone programmatically.

jshell> ZonedDateTime piOther = piCentral.withZoneSameInstant(ZoneId.systemDefault())
piOther ==> 2019-03-14T02:59-04:00[America/New_York]

In our case, jshell was running on a laptop in the standard Eastern time zone (not during the daylight saving period) of the United States and piOther comes out exactly as hoped. The systemDefault() zone ID is a very handy way to quickly tailor date-times from some other zone to match what your user’s clock and calendar are most likely to say. In commercial applications you may want to let the user tell you their preferred zone, but systemDefault() is usually a good guess.

Parsing and Formatting Dates and Times

For creating and showing our local and zoned date-times using strings, we’be been relying on the default formats which follow ISO values and generally work wherever we need to accept or display dates and times. But as every programmer knows, “generally” is not “always”. Fortunately you can use the utility class java.time.format.DateTimeFormatter can help with both parsing input and formatting output.

The core of DateTimeFormatter centers on building a format string that governs both parsing and formatting. You build up your format with the pieces in Table 8-4. We are only listing a portion of the options available here, but these should get you through the bulk of the dates and times you will encounter. Note that case matters when using the characters mentioned!

To put together a common US short format, for example, you could use the ‘M’, ‘d’, and ‘y’ characters. You build the formatter using the static ofPattern() method. Now the formatter can be used (and reused) with the parse() method of any of the date or time classes.

jshell> import java.time.format.DateTimeFormatter

jshell> DateTimeFormatter shortUS = DateTimeFormatter.ofPattern("MM/dd/yy")
shortUS ==> Value(MonthOfYe ... (YearOfEra,2,2,2000-01-01)

jshell> LocalDate valentines = LocalDate.parse("02/14/19", shortUS)
valentines ==> 2019-02-14

jshell> LocalDate piDay = LocalDate.parse("03/14/19", shortUS)
piDay ==> 2019-03-14

And as we mentioned earlier, the formatter works in both directions. Just use the format() method of your formatter to produce a string representation of your date or time.

jshell> LocalDate today = LocalDate.now()
today ==> 2019-12-14

jshell> shortUS.format(today)
$30 ==> "12/14/19"

jshell> shortUS.format(piDay)
$31 ==> "03/14/19"

Of course, formatters work for times and date-times as well!

jshell> DateTimeFormatter military = DateTimeFormatter.ofPattern("HHmm")
military ==> Value(HourOfDay,2)Value(MinuteOfHour,2)

jshell> LocalTime sunset = LocalTime.parse("2020", military)
sunset ==> 20:20

jshell> DateTimeFormatter basic = DateTimeFormatter.ofPattern("h:mm a")
basic ==> Value(ClockHourOfAmPm)':'Value(MinuteOfHour,2)' 'Text(AmPmOfDay,SHORT)

jshell> basic.format(sunset)
$42 ==> "8:20 PM"

jshell> DateTimeFormatter appointment = DateTimeFormatter.ofPattern("h:mm a MM/dd/yy z")
appointment ==> Value(ClockHourOfAmPm)':'Value(MinuteOfHour,2)' ' ... 0-01-01)' 'ZoneText(SHORT)

jshell> ZonedDateTime dentist = ZonedDateTime.parse("10:30 AM 11/01/19 EST", appointment)
dentist ==> 2019-11-01T10:30-04:00[America/New_York]

jshell> ZonedDateTime nowEST = ZonedDateTime.now()
nowEST ==> 2019-12-14T09:55:58.493006-05:00[America/New_York]

jshell> appointment.format(nowEST)
$47 ==> "9:55 AM 12/14/19 EST"

Notice in the ZonedDateTime portion above that we put the time zone identifier (the z character) at the end—probably not where you were expecting it! We wanted to illustrate the power of these formats. You can design a format to accommodate a very wide range of input or output styles. Legacy data and poorly designed web forms come to mind as direct examples of where DateTimeFormatter can help you retain your sanity.

Parsing Errors

Even with all this parsing power at your fingertips, things will sometimes go wrong. And regrettably, the exceptions you see are often too vague to be immediately useful. Consider the following attempt to parse a time with hours, minutes, and seconds:

jshell> DateTimeFormatter withSeconds = DateTimeFormatter.ofPattern("hh:mm:ss")
withSeconds ==> Value(ClockHourOfAmPm,2)':'Value(MinuteOfHour,2)':'Value(SecondOfMinute,2)

jshell> LocalTime.parse("03:14:15", withSeconds)
|  Exception java.time.format.DateTimeParseException: Text '03:14:15' could not be parsed: Unable to obtain LocalTime from TemporalAccessor: {MinuteOfHour=14, MilliOfSecond=0, SecondOfMinute=15, NanoOfSecond=0, HourOfAmPm=3, MicroOfSecond=0},ISO of type java.time.format.Parsed
|        at DateTimeFormatter.createError (DateTimeFormatter.java:2020)
|        at DateTimeFormatter.parse (DateTimeFormatter.java:1955)
|        at LocalTime.parse (LocalTime.java:463)
|        at (#33:1)
|  Caused by: java.time.DateTimeException: Unable to obtain LocalTime from TemporalAccessor: {MinuteOfHour=14, MilliOfSecond=0, SecondOfMinute=15, NanoOfSecond=0, HourOfAmPm=3, MicroOfSecond=0},ISO of type java.time.format.Parsed
|        at LocalTime.from (LocalTime.java:431)
|        at Parsed.query (Parsed.java:235)
|        at DateTimeFormatter.parse (DateTimeFormatter.java:1951)
|        ...

Yikes! A DateTimeParseException will be thrown anytime the string input cannot be parsed. It will also be thrown in cases like our example above; the fields were correctly parsed from the string but they did not supply enough information to create a LocalTime object. It may not be obvious, but our time, “3:14:15” could be either mid-afternoon or very, very early in the morning. Our choice of the hh pattern for the hours turns out to be the culprit. We can either pick an hour pattern that uses an unambiguous 24-hour scale or we can add an explicit AM/PM element:

jshell> DateTimeFormatter valid1 = DateTimeFormatter.ofPattern("hh:mm:ss a")
valid1 ==> Value(ClockHourOfAmPm,2)':'Value(MinuteOfHour,2)' ... 2)' 'Text(AmPmOfDay,SHORT)

jshell> DateTimeFormatter valid2 = DateTimeFormatter.ofPattern("HH:mm:ss")
valid2 ==> Value(HourOfDay,2)':'Value(MinuteOfHour,2)':'Value(SecondOfMinute,2)

jshell> LocalTime piDay1 = LocalTime.parse("03:14:15 PM", valid1)
piDay1 ==> 15:14:15

jshell> LocalTime piDay2 = LocalTime.parse("03:14:15", valid2)
piDay2 ==> 03:14:15

So if you ever get a DateTimeParseException but your input looks like a correct match for the format, double check that your format itself includes everything necessary to create your date or time. One parting thought on these exceptions: you may need to use the non-mnemonic ‘u’ character for parsing years

There are many, many more details on DateTimeFormatter. More than most utility classes, it’s worth a trip to read the docs online.

Timestamps

One other popular date-time concept that java.time understands is the notion of a timestamp. Any situation where tracking the flow of information is required, you’ll need a record of exactly when the information is produced or modified. You will still see the java.util.Date class used to store these moments in time, but the java.time.Instant class carries everything you need for a timestamp and comes with all the other benefits of the other classes in the java.time package.

jshell> Instant time1 = Instant.now()
time1 ==> 2019-12-14T15:38:29.033954Z

jshell> Instant time2 = Instant.now()
time2 ==> 2019-12-14T15:38:46.095633Z

jshell> time1.isAfter(time2)
$54 ==> false

jshell> time1.plus(3, ChronoUnit.DAYS)
$55 ==> 2019-12-17T15:38:29.033954Z

If dates or times appear in your work, the java.time package makes for a welcome addition to Java. You now have a mature, well-designed set of tools for dealing with this data—no third-party libraries needed!