Difference between revisions of "PascalTZ"

From Lazarus wiki
Jump to navigationJump to search
m
 
(5 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{LanguageBar}}
 +
 
=== About ===
 
=== About ===
PascalTZ stands for "Pascal Time Zone". It allows you to convert local times to [http://en.wikipedia.org/wiki/Gmt GMT]/[http://en.wikipedia.org/wiki/Utc UTC]/[http://en.wikipedia.org/wiki/Coordinated_Universal_Time Zulu] and across [http://en.wikipedia.org/wiki/Time_zone time zones] taking in account the different rules for this change on every time zone. PascalTZ uses the public database available at http://www.twinsun.com/tz/tz-link.htm to know how to change time for any past time (rules changed over the years) and it is almost 100% reliable for times in 20th and 21th century, and quite precise for prior times as some rules in 19th century and before were never properly documented. Time zone changes for the future times are not reliable as the rules can change sometimes suddenly like Venezuela 2007 change proposed a bunch of days before the change, or the 2009 Argentina ones.
 
  
The unit can:
+
PascalTZ stands for "Pascal Time Zone". It allows you to convert between local times in various [http://en.wikipedia.org/wiki/Time_zone time zones] and [http://en.wikipedia.org/wiki/Gmt GMT]/[http://en.wikipedia.org/wiki/Coordinated_Universal_Time UTC], taking into account historical changes to time zone rules. PascalTZ uses the [https://www.iana.org/time-zones Time Zone Database] (often called <tt>tz</tt> or <tt>zoneinfo</tt>) to determine how to correctly adjust time for various time zones. The correctness of time zone conversions in future relies on using an up to date database. Beware, time zone rules may be changed by governments around the world, sometimes with a very short notice.
  
* Convert a given time/date in local time to/from GMT time.
+
PascalTZ component can be used in pure FPC projects or installed as a design and runtime package in Lazarus IDE. It also comes with a testing framework, a collection of time zone conversion test vectors and test cases for internal functions.
* Convert a given time/date across two zone times.
 
* In the conversion process detect invalid times.
 
* Be updateable simply upgrading the [http://www.twinsun.com/tz/tz-link.htm TZ Database], actual tzdata*.tar.gz file now stored here: [ftp://munnari.oz.au/pub/ ftp://munnari.oz.au/pub/]
 
  
The download contains the component, an installation package and a demo application, that illustrates the features of the component along with some instrumentation for evaluating the component on a given system. The unit can also used in non Lazarus projects (plain FPC applications) as the unit does not require any user graphic interface but is included as a package for easy integration in applications.
+
More information can be found at [https://github.com/dezlov/PascalTZ GitHub:PascalTZ].
  
=== Author ===
+
=== Example ===
  
2009 - [[User:Joshy|Jose Mejuto]]
+
<syntaxhighlight lang=pascal>
 +
uses
 +
  SysUtils, DateUtils, uPascalTZ;
  
=== License ===
+
var
[http://svn.freepascal.org/svn/lazarus/trunk/COPYING.modifiedLGPL modified] [http://svn.freepascal.org/svn/lazarus/trunk/COPYING.LGPL LGPL] (same as the FPC RTL and the Lazarus LCL). You can contact the author if the modified LGPL doesn't work with your project licensing.
+
  PascalTZ: TPascalTZ;
 +
  DateTime: TDateTime;
  
=== Download ===
+
begin
The latest stable release can be found on [http://sourceforge.net/projects/lazarus-ccr/files/PascalTZ/ PascalTZ] at SourceForge's CCR.
+
  PascalTZ := TPascalTZ.Create;
  
=== API description ===
+
  // Load time zone database from "tzdata" directory
 +
  // Download from: https://www.iana.org/time-zones
 +
  PascalTZ.DatabasePath := 'tzdata';
  
The database is presented in different files so you can use one of them
+
  // Current local and UTC time
using "ParseDatabaseFromFile" or concatenate the interested ones in a single
+
  DateTime := Now;
file or stream. Once the database is loaded calling again "ParseDatabaseFromXXXX"
+
  WriteLn('Local time: ', DateTimeToStr(DateTime));
deletes the in memory parsed data.
+
  DateTime := LocalTimeToUniversal(DateTime);
 +
  WriteLn('UTC time: ', DateTimeToStr(DateTime));
  
* ProcessedLines
+
  // Convert current time to Paris time
   Amount of read lines in database.
+
   DateTime := PascalTZ.GMTToLocalTime(DateTime, 'Europe/Paris');
 +
  WriteLn('Time in Paris: ', DateTimeToStr(DateTime));
  
* DetectInvalidLocalTimes [True|False] (default true)
+
   // Convert Paris time to Chicago time
   When converting it will check if the given time is impossible (does not
+
   DateTime := PascalTZ.Convert(DateTime, 'Europe/Paris', 'America/Chicago');
   exists). This happends, in example, when a local time changes from 2:00
+
   WriteLn('Time in Chicago: ', DateTimeToStr(DateTime));
   to 3:00, if the time to be converted is 2:01 at the change date, that
 
  time does not exists as it is not linear.
 
  
* GetTimeZoneNames(const AZones: TStringList; const AOnlyGeoZones: Boolean=true);
+
   // Check if a time zone exists
   Returns a TStringList with the time zones available in the database. This
+
   WriteLn('Africa/Lagos exists? ', PascalTZ.TimeZoneExists('Africa/Lagos'));
   names must be used for local times to perform conversions. It is not a
+
   WriteLn('Australia/Darwin exists? ', PascalTZ.TimeZoneExists('Australia/Darwin'));
  country list, as many countries have several time zones. AOnlyGeoZones
 
   removes from the list the usual "GMT, BST, PST" from the list.
 
  
* GMTToLocalTime
+
   PascalTZ.Free;
   Converts a GMT/UTC/Zulu time to a time zone (AToZone). ATimeZoneSubFix
+
end.
  returns the subfix for that zone like "GMT, BST, ...".
+
</syntaxhighlight>
  
* LocalTimeToGMT
+
=== Authors ===
  Converts a local time at time zone "AFromZone" to GMT/UTC/Zulu time.
 
  
* TimeZoneToTimeZone
+
This library was originally published by [[User:Joshy|José Mejuto]] in 2009 and is maintained by [[User:dezlov|Denis Kozlov]] since 2015.
  Converts time across zones. Basically this performs a local time to
 
  GMT and GTM to the new local time.
 
  
* ParseDatabaseFromFile(const AFileName: String): Boolean;
+
=== License ===
  Reads the database from a file.
 
  
* ParseDatabaseFromStream(const AStream: TStream): Boolean;
+
[http://svn.freepascal.org/svn/lazarus/trunk/COPYING.modifiedLGPL Modified] [http://svn.freepascal.org/svn/lazarus/trunk/COPYING.LGPL LGPL] (same as the FPC RTL and the Lazarus LCL).
  Reads the database from a stream.
 
  
=== Change Log ===
+
=== Download ===
  
* Version 1.0 2009.11.10
+
[https://github.com/dezlov/PascalTZ/releases GitHub:PascalTZ releases]
  
=== Dependencies / System Requirements ===
+
=== Change Log ===
 
 
* [http://www.twinsun.com/tz/tz-link.htm TZ Database]
 
 
 
Status: ''Stable''
 
  
Issues: TDateTime in fpc seems to have problems for dates before 30 Dec 1899, so the time operations before such date could be wrong. If you need to operate with early dates you can derive a new class from TPascalTZ and expose the TTZDateTime to operate with.
+
* Version 1.0 (2009-11-10) [https://github.com/dezlov/PascalTZ/blob/v2.0/CHANGELOG.md]
 +
* Version 2.0 (2016-07-19) [https://github.com/dezlov/PascalTZ/blob/v2.0/CHANGELOG.md]
  
=== Installation ===
+
=== Bug Reports ===
  
* Just add the '''upascaltz''' to the uses clause of your project.
+
Bug reports and suggestions can be logged at [https://github.com/dezlov/PascalTZ/issues GitHub:PascalTZ issues].
* Load a database in a new instance of the class.
 
  
 
=== See also ===
 
=== See also ===
Since 2.6.2, FPC has the functions <code>LocalTimeToUniversal</code> and <code>UniversalTimeToLocal</code> in the ''dateutils'' unit to convert between local time and UTC time. These functions can be useful and an alternative for PascalTZ if you are not interested in historical/future date/times (i.e. the functions use current daylight saving time etc to convert to/from UTC time).
 
  
The functions do allow for specifying manual offsets against UTC, but then you would need to keep track of those offsets - which PascalTZ does for you.
+
Since 2.6.2, FPC has the functions <code>LocalTimeToUniversal</code> and <code>UniversalTimeToLocal</code> in the ''dateutils'' unit to convert between local time and UTC time. These functions can be useful and an alternative for PascalTZ if you are not interested in historical/future date/times (i.e. the functions use current daylight saving time etc to convert to/from UTC time). These functions do allow for specifying manual offsets against UTC, but then you would need to keep track of those offsets - which PascalTZ does for you.
  
 
[[Category:Components]]
 
[[Category:Components]]
 
[[Category:Lazarus-CCR]]
 
[[Category:Lazarus-CCR]]
[[Category:Lazarus]] {{^|Comment: This unit can be used in graphical Lazarus applications}}
+
[[Category:Lazarus]]
[[Category:FPC]] {{^|Comment: This unit can also be used in text based FPC applications}}
+
[[Category:FPC]]

Latest revision as of 20:17, 9 July 2020

English (en) русский (ru)

About

PascalTZ stands for "Pascal Time Zone". It allows you to convert between local times in various time zones and GMT/UTC, taking into account historical changes to time zone rules. PascalTZ uses the Time Zone Database (often called tz or zoneinfo) to determine how to correctly adjust time for various time zones. The correctness of time zone conversions in future relies on using an up to date database. Beware, time zone rules may be changed by governments around the world, sometimes with a very short notice.

PascalTZ component can be used in pure FPC projects or installed as a design and runtime package in Lazarus IDE. It also comes with a testing framework, a collection of time zone conversion test vectors and test cases for internal functions.

More information can be found at GitHub:PascalTZ.

Example

uses
  SysUtils, DateUtils, uPascalTZ;

var
  PascalTZ: TPascalTZ;
  DateTime: TDateTime;

begin
  PascalTZ := TPascalTZ.Create;

  // Load time zone database from "tzdata" directory
  // Download from: https://www.iana.org/time-zones
  PascalTZ.DatabasePath := 'tzdata';

  // Current local and UTC time
  DateTime := Now;
  WriteLn('Local time: ', DateTimeToStr(DateTime));
  DateTime := LocalTimeToUniversal(DateTime);
  WriteLn('UTC time: ', DateTimeToStr(DateTime));

  // Convert current time to Paris time
  DateTime := PascalTZ.GMTToLocalTime(DateTime, 'Europe/Paris');
  WriteLn('Time in Paris: ', DateTimeToStr(DateTime));

  // Convert Paris time to Chicago time
  DateTime := PascalTZ.Convert(DateTime, 'Europe/Paris', 'America/Chicago');
  WriteLn('Time in Chicago: ', DateTimeToStr(DateTime));

  // Check if a time zone exists
  WriteLn('Africa/Lagos exists? ', PascalTZ.TimeZoneExists('Africa/Lagos'));
  WriteLn('Australia/Darwin exists? ', PascalTZ.TimeZoneExists('Australia/Darwin'));

  PascalTZ.Free;
end.

Authors

This library was originally published by José Mejuto in 2009 and is maintained by Denis Kozlov since 2015.

License

Modified LGPL (same as the FPC RTL and the Lazarus LCL).

Download

GitHub:PascalTZ releases

Change Log

  • Version 1.0 (2009-11-10) [1]
  • Version 2.0 (2016-07-19) [2]

Bug Reports

Bug reports and suggestions can be logged at GitHub:PascalTZ issues.

See also

Since 2.6.2, FPC has the functions LocalTimeToUniversal and UniversalTimeToLocal in the dateutils unit to convert between local time and UTC time. These functions can be useful and an alternative for PascalTZ if you are not interested in historical/future date/times (i.e. the functions use current daylight saving time etc to convert to/from UTC time). These functions do allow for specifying manual offsets against UTC, but then you would need to keep track of those offsets - which PascalTZ does for you.