Conversions between basic types

Table Of Contents

From date and time to timestamp
From timestamp to date and time
From local types to global type
From global type to local types
From one timezone to another timezone

From date and time to timestamp

In order to construct a PlainTimestamp from PlainDate and PlainTime, the class PlainDate offers various methods with prefix "at".

	PlainTimestamp dateAtMidnight = PlainDate.of(2014, 3, 12).atStartOfDay(); // 2014-03-12T00
	PlainTimestamp dateAt1145 = PlainDate.of(2014, 3, 12).atTime(11, 45); // 2014-03-12T11:45
	PlainTimestamp dateTime = PlainDate.of(2014, 3, 12).at(PlainTime.of(11, 45)); // 2014-03-12T11:45

From timestamp to date and time

In order to get a date or time from a PlainTimestamp just remember that latter one is a combination of PlainDate and PlainTime so a timestamp already contains date and time. You can use simple getters.

	PlainTimestamp tsp = PlainDate.of(2014, 3, 12).atTime(11, 45); // 2014-03-12T11:45
	PlainDate date = tsp.getCalendarDate();
	PlainTime time = tsp.getWallTime();

From local types to global type

Conversions from local types to global types always require a timezone or offset reference. While an offset reference is always simple, fixed and unique, a timezone encapsulates external context whose data are inferred from a repository like that one built-in the Java runtime environment and can change with time in an arbitrary manner. For example many regions of the world know winter time and summer time.

If you do not want to give any explicit offset or timezone but refer to the underlying system then you can just choose the system timezone this way:

	Moment utc = PlainDate.of(2014, 3, 12).atStartOfDay().inStdTimezone();

A typical and fixed zone offset for India is constructed using factory methods like ZonalOffset.ofHoursMinutes(AHEAD_OF_UTC, 5, 30). You can refer to a timezone containing regional data using an identifier object either as String or as TZID. For most standard timezones there are enums available implementing the TZID-interface to avoid typo-mistakes, for example ASIA.HONG_KONG.

Once you have such an offset or a timezone reference you can convert between PlainTimestamp and Moment. Offset-related conversions use methods with prefix "at". Timezone-related methods use the prefix "in".

	Moment dateAtGreenwich = 
		PlainDate.of(2014, 3, 12).atStartOfDay().atUTC();
	Moment dateAtIndiaOffset = 
		PlainDate.of(2014, 3, 12)
			.at(ZonalOffset.ofHoursMinutes(AHEAD_OF_UTC, 5, 30));
	Moment dateAtIndiaZone =
		PlainDate.of(2014, 3, 12)
			.inTimezone(ASIA.KOLKATA); // or: in(Timezone.of("Asia/Kolkata"))

Note that the last conversion uses the default transition strategy choosing the later defined offset if possible. That means if a local timestamp can happen twice during a summer-to-winter-time transition then the later one will be choosen. Another transition strategy can be explicitly given however. Following code will reject the conversion if a local timestamp is invalid during a winter-to-summer-time:

	Moment invalid =
		PlainDate.of(2014, 3, 30)
			.atTime(2, 30)
	// throws IllegalArgumentException
	// Invalid local timestamp due to timezone transition: 2014-03-30T02:30 [BERLIN]

From global type to local types

The reverse way does never require a specialized transition strategy because here the mapping is not ambivalent and well defined. So it is sufficient just to use arguments like String, ZonalOffset or TZID.

	Moment moment = Moment.UNIX_EPOCH;
	PlainTimestamp local = moment.toLocalTimestamp(); // in system timezone
	PlainTimestamp atOffset0530 = moment.toZonalTimestamp(ZonalOffset.ofHoursMinutes(AHEAD_OF_UTC, 5, 30));
	PlainTimestamp india1 = moment.toZonalTimestamp("Asia/Kolkata");
	PlainTimestamp india2 = moment.toZonalTimestamp(ASIA.KOLKATA); // equivalent to india1
	PlainTime indiaTime = moment.toZonalTimestamp(ASIA.KOLKATA).getWallTime();

From one timezone to another timezone

Local timestamps can be ported between different timezones using just a one-liner this way changing their local representation:

	PlainTimestamp japan = 
		PlainDate.of(2014, 3, 11).atTime(17, 45)
	System.out.println(japan); // output: 2014-03-12T01:45

If you instead want to know when the same local timestamp happens in different regions and how much is the time difference then you can just convert from the same local timestamp to different moments and measure the distance. In following example you see that the german timestamp having the same representation as the japan timestamp happens 8 hours later.

	PlainTimestamp tsp = 
		PlainDate.of(2014, 3, 11).atTime(17, 45);
	Moment germany = tsp.toZonalTimestamp(EUROPE.BERLIN);
	Moment japan = tsp.toZonalTimestamp(ASIA.TOKYO);
	long delta = germany.until(japan, TimeUnit.HOURS); // -8 hours