Formatting

VERSION 1.0.0-rc.3 PUBLIC PREVIEW

formatDuration and formatDistance turn seconds and meters into display strings, and round larger values more coarsely. The SDK formats its own durations and distances with them, such as the routing module’s labels.

formatDuration

1
import { formatDuration } from '@tomtom-org/maps-sdk/core';
2
import { calculateRoute } from '@tomtom-org/maps-sdk/services';
3

4
formatDuration(20);     // undefined: under 30 seconds
5
formatDuration(30);     // "1 min"
6
formatDuration(100);    // "2 min"
7
formatDuration(1800);   // "30 min"
8
formatDuration(3599);   // "1 hr 00 min"
9
formatDuration(36120);  // "10 hr 02 min"
10

11
formatDuration(3660, { hours: 'h', minutes: 'm' }); // "1 h 01 m"
12

13
const routes = await calculateRoute({ locations: [[4.9, 52.37], [4.48, 51.92]] });
14
formatDuration(routes.features[0].properties.summary.travelTimeInSeconds);

Rounds to the nearest minute. From one hour on, it shows hours and two-digit minutes.
Returns string | undefined: undefined for 0, undefined or anything that rounds to zero minutes.
The second argument (TimeDisplayUnits) sets the hours and minutes labels, 'hr' and 'min' by default.

formatDistance

1
import { formatDistance } from '@tomtom-org/maps-sdk/core';
2

3
// metric (default)
4
formatDistance(2);       // "2 m"
5
formatDistance(237);     // "240 m"
6
formatDistance(950);     // "1 km"
7
formatDistance(2850);    // "2.9 km"
8
formatDistance(283520);  // "284 km"
9
formatDistance(-999);    // "-1 km"
10

11
// imperial_us: feet, then miles with fractions
12
formatDistance(100, { type: 'imperial_us' });     // "330 ft"
13
formatDistance(205.95, { type: 'imperial_us' });  // "¼ mi"
14
formatDistance(5309.7, { type: 'imperial_us' });  // "3½ mi"
15

16
// imperial_uk: yards, then miles with fractions
17
formatDistance(150.88, { type: 'imperial_uk' });  // "170 yd"
18
formatDistance(4344.3, { type: 'imperial_uk' });  // "2¾ mi"
19

20
formatDistance(1500, { kilometers: 'KM' });       // "1.5 KM"

`type`	Short distances	From ⅛ mile / 1 km
`'metric'`	`m`: one decimal below 10 m, rounded to 10 m from 10 m, to 100 m from 500 m	`km`: one decimal below 10 km, whole above
`'imperial_us'`	`ft` below ⅛ mi	`mi`: ¼ steps below 3 mi, ½ steps below 10 mi, whole above
`'imperial_uk'`	`yd` below ⅛ mi	`mi`, as `imperial_us`

The second argument (DistanceDisplayUnits) sets the type and labels: meters, kilometers, feet, yards, miles.
Returns string: '' for null or undefined.

Global configuration

The displayUnits global option sets the defaults for both functions, and so for every distance and duration the SDK displays:

1
import { TomTomConfig, formatDistance, formatDuration } from '@tomtom-org/maps-sdk/core';
2

3
TomTomConfig.instance.put({
4
    displayUnits: {
5
        distance: { type: 'imperial_us' },
6
        time: { hours: 'h', minutes: 'm' }
7
    }
8
});
9

10
formatDistance(1000);                       // "½ mi"
11
formatDuration(3600);                       // "1 h 00 m"
12
formatDistance(1000, { type: 'metric' });   // "1 km": the argument wins, key by key

The Display units example switches the global units, and a route’s labels and a summary printed with these functions change together.