9.2 Converting dates to chart time

The dates used on the chart depend on the user-configurable time zone. For example, the default setting is GMT+2 with daylight savings on the USA schedule (so that fx markets always open at midnight on Monday).

The chart's time zone is provided via the context data which is available via the data parameter for all functions. For example:

// Get base offset in minutes, and daylight savings mode
var offsetMinutes = data.context.timezone.offset;
var dstMode = data.context.timezone.dstMode; 

The dstMode is one of the values from the UDI.DST enumeration: 0 = no daylight savings, 1 = USA schedule, 2 = European schedule, 3 = Australian schedule

You can convert from the user's chart time to UTC using UDI.convertChartDateToUTC(). This returns an adjusted date as a number of milliseconds, which you can then convert to a Date() object if necessary. For example:

// Convert a value from data.barData.date[] to UTC
var currentBarDate = data.barData.date[0];
var currentAsUTC = UDI.convertChartDateToUTC(currentBarDate);
// Convert to Javascript date object, and output
var dateobj = new Date(currentAsUTC);
console.log("As UTC, bar date is " + dateobj.toISOString());

You can convert in the opposite direction, from UTC to chart time, using UDI.convertUTCToChartDate(). For example:

// Get current date from computer clock (as UTC milliseconds)
var currentDateFromComputerClock = (new Date()).valueOf();
// Convert to chart time 
var currentAsChartTime = UDI.convertUTCToChartDate(currentDateFromComputerClock);

You can also convert UTC to and from other time zones. For example, you can convert UTC to US east coast time, or vice versa.

To do this conversion, you provide a timezone structure, like the one which is included in the UDI's context data. This consists of an offset, in minutes, and a dstMode. For example, the definition of New York time is:

// Base of UTC-5, moving to UTC-4 on the USA daylight savings schedule 
{
	offset: -300,
	dstMode: UDI.DST.USA	// = 1
}

You can then convert from UTC to a different zone using UDI.convertUTCToZone(). For example, converting a date from UTC to US east coast. What this will do is to return the UTC number of milliseconds minus either 300 minutes or 240 minutes depending on whether the USA was in daylight savings at the date you supply:

var usec = UDI.convertUTCToZone(someDate, {offset: -300, dstMode: 1});

Similarly, you can convert from another zone to UTC using UDI.convertZoneToUTC(). This adds either 300 minutes or 240 minutes to the number of milliseconds you supply. For example:

// Convert the example above back to UTC
var utc = UDI.convertZoneToUTC(usec, {offset: -300, dstMode: 1});