If you spot a problem with this page, click here to create a Bugzilla issue.

Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using a local clone.

std.datetime.timezone


Category	Functions
Time zones	TimeZone UTC LocalTime PosixTimeZone WindowsTimeZone SimpleTimeZone
Utilities	clearTZEnvVar parseTZConversions setTZEnvVar TZConversions

License:

Boost License 1.0.

Authors:

Jonathan M Davis

Source std/datetime/timezone.d

abstract class TimeZone;

Represents a time zone. It is used with std.datetime.systime.SysTime to indicate the time zone of a std.datetime.systime.SysTime.

const nothrow @property @safe string name();

The name of the time zone. Exactly how the time zone name is formatted depends on the derived class. In the case of PosixTimeZone, it's the TZ Database name, whereas with WindowsTimeZone, it's the name that Windows chose to give the registry key for that time zone (typically the name that they give stdTime if the OS is in English). For other time zone types, what it is depends on how they're implemented.

const nothrow @property @safe string stdName();

Typically, the abbreviation (generally 3 or 4 letters) for the time zone when DST is not in effect (e.g. PST). It is not necessarily unique.

However, on Windows, it may be the unabbreviated name (e.g. Pacific Standard Time). Regardless, it is not the same as name.

const nothrow @property @safe string dstName();

Typically, the abbreviation (generally 3 or 4 letters) for the time zone when DST is in effect (e.g. PDT). It is not necessarily unique.

However, on Windows, it may be the unabbreviated name (e.g. Pacific Daylight Time). Regardless, it is not the same as name.

abstract const nothrow @property @safe bool hasDST();

Whether this time zone has Daylight Savings Time at any point in time. Note that for some time zone types it may not have DST for current dates but will still return true for hasDST because the time zone did at some point have DST.

abstract const nothrow @safe bool dstInEffect(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and returns whether DST is effect in this time zone at the given point in time.

Parameters:

long stdTime The UTC time that needs to be checked for DST in this time zone.

abstract const nothrow @safe long utcToTZ(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and converts it to this time zone's time.

Parameters:

long stdTime The UTC time that needs to be adjusted to this time zone's time.

abstract const nothrow @safe long tzToUTC(long adjTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in this time zone's time and converts it to UTC (i.e. std time).

Parameters:

long adjTime The time in this time zone that needs to be adjusted to UTC time.

const nothrow @safe Duration utcOffsetAt(long stdTime);

Returns what the offset from UTC is at the given std time. It includes the DST offset in effect at that time (if any).

Parameters:

long stdTime The UTC time for which to get the offset from UTC for this time zone.

protected immutable pure @safe this(string name, string stdName, string dstName);

Parameters:

string `name`	The name of the time zone.
string `stdName`	The abbreviation for the time zone during std time.
string `dstName`	The abbreviation for the time zone during DST.

class LocalTime: std.datetime.timezone.TimeZone;

A TimeZone which represents the current local time zone on the system running your program.

This uses the underlying C calls to adjust the time rather than using specific D code based off of system settings to calculate the time such as PosixTimeZone and WindowsTimeZone do. That also means that it will use whatever the current time zone is on the system, even if the system's time zone changes while the program is running.

static pure nothrow @trusted immutable(LocalTime) opCall();

LocalTime is a singleton class. LocalTime returns its only instance.

const nothrow @property @safe string name();

In principle, this is the name of the local time zone. However, this always returns the empty string. This is because time zones cannot be uniquely identified by the attributes given by the OS (such as the stdName and dstName), and neither Posix systems nor Windows systems provide an easy way to get the TZ Database name of the local time zone.

const nothrow @property @trusted string stdName();

Typically, the abbreviation (generally 3 or 4 letters) for the time zone when DST is not in effect (e.g. PST). It is not necessarily unique.

However, on Windows, it may be the unabbreviated name (e.g. Pacific Standard Time). Regardless, it is not the same as name.

This property is overridden because the local time of the system could change while the program is running and we need to determine it dynamically rather than it being fixed like it would be with most time zones.

const nothrow @property @trusted string dstName();

Typically, the abbreviation (generally 3 or 4 letters) for the time zone when DST is in effect (e.g. PDT). It is not necessarily unique.

However, on Windows, it may be the unabbreviated name (e.g. Pacific Daylight Time). Regardless, it is not the same as name.

const nothrow @property @trusted bool hasDST();

const nothrow @trusted bool dstInEffect(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and returns whether DST is in effect in this time zone at the given point in time.

Parameters:

long stdTime The UTC time that needs to be checked for DST in this time zone.

const nothrow @trusted long utcToTZ(long stdTime);

Returns hnsecs in the local time zone using the standard C function calls on Posix systems and the standard Windows system calls on Windows systems to adjust the time to the appropriate time zone from std time.

Parameters:

long stdTime The UTC time that needs to be adjusted to this time zone's time.

See Also:

TimeZone.utcToTZ

const nothrow @trusted long tzToUTC(long adjTime);

Returns std time using the standard C function calls on Posix systems and the standard Windows system calls on Windows systems to adjust the time to UTC from the appropriate time zone.

See Also:

TimeZone.tzToUTC

Parameters:

long adjTime The time in this time zone that needs to be adjusted to UTC time.

class UTC: std.datetime.timezone.TimeZone;

A TimeZone which represents UTC.

static pure nothrow @safe immutable(UTC) opCall();

UTC is a singleton class. UTC returns its only instance.

const nothrow @property @safe bool hasDST();

Always returns false.

const nothrow @safe bool dstInEffect(long stdTime);

Always returns false.

const nothrow @safe long utcToTZ(long stdTime);

Returns the given hnsecs without changing them at all.

Parameters:

long stdTime The UTC time that needs to be adjusted to this time zone's time.

See Also:

TimeZone.utcToTZ

const nothrow @safe long tzToUTC(long adjTime);

Returns the given hnsecs without changing them at all.

See Also:

TimeZone.tzToUTC

Parameters:

long adjTime The time in this time zone that needs to be adjusted to UTC time.

const nothrow @safe Duration utcOffsetAt(long stdTime);

Returns a core.time.Duration of 0.

Parameters:

long stdTime The UTC time for which to get the offset from UTC for this time zone.

class SimpleTimeZone: std.datetime.timezone.TimeZone;

Represents a time zone with an offset (in minutes, west is negative) from UTC but no DST.

It's primarily used as the time zone in the result of std.datetime.systime.SysTime's fromISOString, fromISOExtString, and fromSimpleString.

name and dstName are always the empty string since this time zone has no DST, and while it may be meant to represent a time zone which is in the TZ Database, obviously it's not likely to be following the exact rules of any of the time zones in the TZ Database, so it makes no sense to set it.

const nothrow @property @safe bool hasDST();

Always returns false.

const nothrow @safe bool dstInEffect(long stdTime);

Always returns false.

const nothrow @safe long utcToTZ(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and converts it to this time zone's time.

Parameters:

long stdTime The UTC time that needs to be adjusted to this time zone's time.

const nothrow @safe long tzToUTC(long adjTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in this time zone's time and converts it to UTC (i.e. std time).

Parameters:

long adjTime The time in this time zone that needs to be adjusted to UTC time.

const nothrow @safe Duration utcOffsetAt(long stdTime);

Returns utcOffset as a core.time.Duration.

Parameters:

long stdTime The UTC time for which to get the offset from UTC for this time zone.

immutable pure @safe this(Duration utcOffset, string stdName = "");

Parameters:

Duration `utcOffset`	This time zone's offset from UTC with west of UTC being negative (it is added to UTC to get the adjusted time).
string `stdName`	The `stdName` for this time zone.

const pure nothrow @property @safe Duration utcOffset();

The amount of time the offset from UTC is (negative is west of UTC, positive is east).

class PosixTimeZone: std.datetime.timezone.TimeZone;

Represents a time zone from a TZ Database time zone file. Files from the TZ Database are how Posix systems hold their time zone information. Unfortunately, Windows does not use the TZ Database. To use the TZ Database, use PosixTimeZone (which reads its information from the TZ Database files on disk) on Windows by providing the TZ Database files and telling PosixTimeZone.getTimeZone where the directory holding them is.

To get a PosixTimeZone, call PosixTimeZone.getTimeZone (which allows specifying the location the time zone files).

Note Unless your system's local time zone deals with leap seconds (which is highly unlikely), then the only way to get a time zone which takes leap seconds into account is to use PosixTimeZone with a time zone whose name starts with "right/". Those time zone files do include leap seconds, and PosixTimeZone will take them into account (though posix systems which use a "right/" time zone as their local time zone will not take leap seconds into account even though they're in the file).

const nothrow @property @safe bool hasDST();

const nothrow @safe bool dstInEffect(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and returns whether DST is in effect in this time zone at the given point in time.

Parameters:

long stdTime The UTC time that needs to be checked for DST in this time zone.

const nothrow @safe long utcToTZ(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and converts it to this time zone's time.

Parameters:

long stdTime The UTC time that needs to be adjusted to this time zone's time.

const nothrow @safe long tzToUTC(long adjTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in this time zone's time and converts it to UTC (i.e. std time).

Parameters:

long adjTime The time in this time zone that needs to be adjusted to UTC time.

enum string defaultTZDatabaseDir;

The default directory where the TZ Database files are stored. It's empty for Windows, since Windows doesn't have them. You can also use the TZDatabaseDir version to pass an arbitrary path at compile-time, rather than hard-coding it here. Android concatenates all time zone data into a single file called tzdata and stores it in the directory below.

static @trusted immutable(PosixTimeZone) getTimeZone(string name, string tzDatabaseDir = defaultTZDatabaseDir);

Returns a TimeZone with the give name per the TZ Database. The time zone information is fetched from the TZ Database time zone files in the given directory.

Parameters:

string `name`	The TZ Database name of the desired time zone
string `tzDatabaseDir`	The directory where the TZ Database files are located. Because these files are not located on Windows systems, provide them and give their location here to use PosixTimeZones.

Throws:

std.datetime.date.DateTimeException if the given time zone could not be found or FileException if the TZ Database file could not be opened.

Examples:

version (Posix)
{
    auto tz = PosixTimeZone.getTimeZone("America/Los_Angeles");

    writeln(tz.name); // "America/Los_Angeles"
    writeln(tz.stdName); // "PST"
    writeln(tz.dstName); // "PDT"
}

static @trusted string[] getInstalledTZNames(string subName = "", string tzDatabaseDir = defaultTZDatabaseDir);

Returns a list of the names of the time zones installed on the system.

Providing a sub-name narrows down the list of time zones (which can number in the thousands). For example, passing in "America" as the sub-name returns only the time zones which begin with "America".

Parameters:

string `subName`	The first part of the desired time zones.
string `tzDatabaseDir`	The directory where the TZ Database files are located.

Throws:

FileException if it fails to read from disk.

class WindowsTimeZone: std.datetime.timezone.TimeZone;

This class is Windows-Only.

Represents a time zone from the Windows registry. Unfortunately, Windows does not use the TZ Database. To use the TZ Database, use PosixTimeZone (which reads its information from the TZ Database files on disk) on Windows by providing the TZ Database files and telling PosixTimeZone.getTimeZone where the directory holding them is.

The TZ Database files and Windows' time zone information frequently do not match. Windows has many errors with regards to when DST switches occur (especially for historical dates). Also, the TZ Database files include far more time zones than Windows does. So, for accurate time zone information, use the TZ Database files with PosixTimeZone rather than WindowsTimeZone. However, because WindowsTimeZone uses Windows system calls to deal with the time, it's far more likely to match the behavior of other Windows programs. Be aware of the differences when selecting a method.

WindowsTimeZone does not exist on Posix systems.

To get a WindowsTimeZone, call WindowsTimeZone.getTimeZone.

See Also:

Home of the TZ Database files

const nothrow @property @safe bool hasDST();

const nothrow @safe bool dstInEffect(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and returns whether DST is in effect in this time zone at the given point in time.

Parameters:

long stdTime The UTC time that needs to be checked for DST in this time zone.

const nothrow @safe long utcToTZ(long stdTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in UTC time (i.e. std time) and converts it to this time zone's time.

Parameters:

long stdTime The UTC time that needs to be adjusted to this time zone's time.

const nothrow @safe long tzToUTC(long adjTime);

Takes the number of hnsecs (100 ns) since midnight, January 1st, 1 A.D. in this time zone's time and converts it to UTC (i.e. std time).

Parameters:

long adjTime The time in this time zone that needs to be adjusted to UTC time.

static @safe immutable(WindowsTimeZone) getTimeZone(string name);

Returns a TimeZone with the given name per the Windows time zone names. The time zone information is fetched from the Windows registry.

Parameters:

string name The TZ Database name of the desired time zone.

Throws:

std.datetime.date.DateTimeException if the given time zone could not be found.

Example

auto tz = WindowsTimeZone.getTimeZone("Pacific Standard Time");

static @safe string[] getInstalledTZNames();

Returns a list of the names of the time zones installed on the system. The list returned by WindowsTimeZone contains the Windows TZ names, not the TZ Database names. However, TimeZone.getinstalledTZNames will return the TZ Database names which are equivalent to the Windows TZ names.

nothrow @safe void setTZEnvVar(string tzDatabaseName);

This function is Posix-Only.

Sets the local time zone on Posix systems with the TZ Database name by setting the TZ environment variable.

Unfortunately, there is no way to do it on Windows using the TZ Database name, so this function only exists on Posix systems.

nothrow @safe void clearTZEnvVar();

This function is Posix-Only.

Clears the TZ environment variable.

struct TZConversions; pure @safe TZConversions parseTZConversions(string windowsZonesXMLText);

Provides the conversions between the IANA time zone database time zone names (which POSIX systems use) and the time zone names that Windows uses.

Windows uses a different set of time zone names than the IANA time zone database does, and how they correspond to one another changes over time (particularly when Microsoft updates Windows). windowsZones.xml provides the current conversions (which may or may not match up with what's on a particular Windows box depending on how up-to-date it is), and parseTZConversions reads in those conversions from windowsZones.xml so that a D program can use those conversions.

However, it should be noted that the time zone information on Windows is frequently less accurate than that in the IANA time zone database, and if someone really wants accurate time zone information, they should use the IANA time zone database files with PosixTimeZone on Windows rather than WindowsTimeZone, whereas WindowsTimeZone makes more sense when trying to match what Windows will think the time is in a specific time zone.

Also, the IANA time zone database has a lot more time zones than Windows does.

Parameters:

string windowsZonesXMLText The text from windowsZones.xml

Throws:

Exception if there is an error while parsing the given XML.

    // Parse the conversions from a local file.
    auto text = std.file.readText("path/to/windowsZones.xml");
    auto conversions = parseTZConversions(text);

    // Alternatively, grab the XML file from the web at runtime
    // and parse it so that it's guaranteed to be up-to-date, though
    // that has the downside that the code needs to worry about the
    // site being down or unicode.org changing the URL.
    auto url = "http://unicode.org/cldr/data/common/supplemental/windowsZones.xml";
    auto conversions2 = parseTZConversions(std.net.curl.get(url));

string[][string] toWindows;: The key is the Windows time zone name, and the value is a list of IANA TZ database names which are close (currently only ever one, but it allows for multiple in case it's ever necessary).
string[][string] fromWindows;: The key is the IANA time zone database name, and the value is a list of Windows time zone names which are close (usually only one, but it could be multiple).

Library Reference

std.datetime.timezone