Menu

- Learn
- Documentation
  - Language Reference
  - Library Reference
  - Command-line Reference
  - Feature Overview
  - Articles
- Downloads
- Packages
- Community
  - Blog
  - Orgs using D
  - Twitter
  - Forums
  - IRC
  - Community Discord
  - Wiki
  - GitHub
  - Issues
  - Get involved
  - Contributors
  - Foundation
  - Security Team
  - Donate
  - Sponsors
- Resources
  - Tour
  - Books
  - Tutorials
  - Tools
  - Editors
  - IDEs
  - run.dlang.io
  - Visual D
  - Acknowledgments
  - D Style
  - Glossary
  - Sitemap

Search
Report a bug
If you spot a problem with this page, click here to create a Bugzilla issue.
Improve this page
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.
    See Also:
    Wikipedia entry on TZ Database
    List of Time Zones
  const nothrow @property scope @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 scope @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 scope @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 scope @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 scope @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 scope @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.
    See Also:
    Wikipedia entry on TZ Database
    List of Time Zones
  const nothrow @property scope @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 scope @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.
    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 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.
  const nothrow scope @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 scope @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 scope @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 scope @safe bool `dstInEffect`(long `stdTime`);
    Always returns false.
  const nothrow scope @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 scope @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 scope @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 scope @safe bool `dstInEffect`(long `stdTime`);
    Always returns false.
  const nothrow scope @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 scope @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 scope @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).

  See Also:
  Home of the TZ Database files
  Wikipedia entry on TZ Database
  List of Time Zones
  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.
  const nothrow scope @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 scope @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 scope @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.
    See Also:
    Wikipedia entry on TZ Database
    List of Time Zones
    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 @safe 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 scope @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.
  const nothrow scope @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 scope @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 scope @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.
    See Also:
    Wikipedia entry on TZ Database
    List of Time Zones
    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).

Copyright © 1999-2023 by the D Language Foundation | Page generated by Ddoc on Sat Jul 15 12:04:01 2023