Difference between revisions of "PascalTZ"

From Free Pascal wiki
Jump to navigationJump to search
(remark about built in functions in 2.6.2+. Categories as this unit works for both Laz & FPC)
m
Line 84: Line 84:
 
[[Category:Components]]
 
[[Category:Components]]
 
[[Category:Lazarus-CCR]]
 
[[Category:Lazarus-CCR]]
[[Category:Lazarus]] <--! This unit can be used in graphical Lazarus applications -->
+
[[Category:Lazarus]] {{^|Comment: This unit can be used in graphical Lazarus applications}}
[[Category:FPC]] <--! This unit can also be used in text based FPC applications -->
+
[[Category:FPC]] {{^|Comment: This unit can also be used in text based FPC applications}}

Revision as of 16:35, 12 December 2013

About

PascalTZ stands for "Pascal Time Zone". It allows you to convert local times to GMT/UTC/Zulu and across 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:

  • Convert a given time/date in local time to/from GMT time.
  • Convert a given time/date across two zone times.
  • In the conversion process detect invalid times.
  • Be updateable simply upgrading the TZ Database, actual tzdata*.tar.gz file now stored here: 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.

Author

2009 - Jose Mejuto

License

modified 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.

Download

The latest stable release can be found on PascalTZ at SourceForge's CCR.

API description

The database is presented in different files so you can use one of them using "ParseDatabaseFromFile" or concatenate the interested ones in a single file or stream. Once the database is loaded calling again "ParseDatabaseFromXXXX" deletes the in memory parsed data.

  • ProcessedLines
 Amount of read lines in database.
  • DetectInvalidLocalTimes [True|False] (default true)
 When converting it will check if the given time is impossible (does not
 exists). This happends, in example, when a local time changes from 2:00
 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);
 Returns a TStringList with the time zones available in the database. This
 names must be used for local times to perform conversions. It is not a
 country list, as many countries have several time zones. AOnlyGeoZones
 removes from the list the usual "GMT, BST, PST" from the list.
  • GMTToLocalTime
 Converts a GMT/UTC/Zulu time to a time zone (AToZone). ATimeZoneSubFix
 returns the subfix for that zone like "GMT, BST, ...".
  • LocalTimeToGMT
 Converts a local time at time zone "AFromZone" to GMT/UTC/Zulu time.
  • TimeZoneToTimeZone
 Converts time across zones. Basically this performs a local time to
 GMT and GTM to the new local time.
  • ParseDatabaseFromFile(const AFileName: String): Boolean;
 Reads the database from a file.
  • ParseDatabaseFromStream(const AStream: TStream): Boolean;
 Reads the database from a stream.

Change Log

  • Version 1.0 2009.11.10

Dependencies / System Requirements

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.

Installation

  • Just add the upascaltz to the uses clause of your project.
  • Load a database in a new instance of the class.

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).

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. English (en) русский (ru)
English (en) русский (ru)