---
title: "Text, numbers, time, and localization"
chapter: "10"
---

# Text, numbers, time, and localization

Correct business software needs deliberate value semantics.

## Text

`String` is immutable and uses UTF-16 code units. A `char` is not always a full
Unicode character. Use code points for operations that must handle
supplementary characters. Normalize Unicode when security or matching rules
require it.

## Numbers

Primitive integer arithmetic can overflow silently. Use `Math.addExact` and
related methods when overflow must fail. Floating point is approximate.
`BigDecimal` provides decimal arithmetic with explicit scale and rounding.
Compare numeric value with `compareTo`; `equals` also considers scale.

## Date and time

Use the `java.time` API:

- `Instant`: a point on the UTC timeline.
- `LocalDate`: calendar date without time zone.
- `LocalDateTime`: local date/time without zone or offset.
- `OffsetDateTime`: date/time with an offset.
- `ZonedDateTime`: date/time with a region and daylight-saving rules.
- `Duration` and `Period`: time-based and date-based amounts.

Store event timestamps as `Instant`; preserve the user's zone separately when
business meaning depends on it. Never assume every day has 24 hours across DST.

## Formatting and localization

Use `DateTimeFormatter`, `NumberFormat`, `Locale`, `ResourceBundle`, and
message formats. Parsing and display rules are locale-sensitive. Never parse a
machine protocol with the server's default locale.

## Feynman check

An `Instant` is one pin on the world's timeline. A `ZonedDateTime` is that pin
viewed through a city's wall clock and daylight-saving rules.