Java Time Zones

Java Time Zones extensions manages dates via Java built-in classes: GregorianCalndar, TimeZone, SimpleDateFormat, Locale.


Extension's functions:
===============
[CSE] means [Ctrl+Shift+Enter] i.e. an array formula.

* Date string functions
jtz_date_reformat
jtz_date_add
jtz_date_tz
jtz_date_tz_offset
jtz_date_is_dst
jtz_date_parse
jtz_date_split [CSE]

* Unix time (milliseconds) functions
jtz_unix_add
jtz_unix_now
jtz_unix_format
jtz_unix_is_dst
jtz_unix_split [CSE]
jtz_unix_tz_offset
jtz_unix_timer
jtz_unix_timer_split [CSE]

* Information functions
jtz_format_codes [CSE]
jtz_loc_ids [CSE]
jtz_tz_ids [CSE]
jtz_tz_loc
jtz_tz_info [CSE]
jtz_tz_by_raw_offset [CSE]

* Values in milliseconds
jtz_mls_hour
jtz_mls_minute
jtz_mls_second

* Date fields
jtz_f_year
jtz_f_month
jtz_f_day
jtz_f_hour
jtz_f_minute
jtz_f_second
jtz_f_millis
jtz_f_raw_offset
jtz_f_dst_offset
jtz_f_total_offset


About time zones
===========
* Greenwich Mean Time (GMT) is an absolute time reference and it doesn't change with the seasons. Each time zone has constant RAW offset from GMT. But some of them use additional offset called Daylight Saving Time (DST). Finally we can say that each time zone has TOTAL_OFFSET = RAW_OFFSET + DST_OFFSET. Some zones don't use DST i.e. DST_OFFSET = 0

* Unix time is defined as the number of milliseconds from "1970-01-01 00:00:00.000 GMT"

* A given Unix time have the same graphical representation in all time zones. On the other hand graphical representation of a "plain" date can vary depending on a time zone, e.g.
a Unix time:
"1319568508751"
in Poland means:
"2011-10-25 20:48:28.751 CEST"
but in Greece:
"2011-10-25 21:48:28.751 EEST"
So, last two dates describe the same point in time despite they have different graphical representation.


Priority and default values of parameters
============================
* A time zone can be read from a date using "z" format code or it can be given by "time zone ID" parameter. Remember, time zone in date format ("z" code) has higher priority than "time zone ID" i.e. if a date format contains "z" then "time zone ID" parameter is ignored.

* If date format doesn't contain "z" code and "time zone ID" parameter is skipped or it's empty then "GMT" time zone is used.

* If "locale ID" parameter is skipped or it's empty then a default locale of your Java Virtual Machine is used.

* Notice that time zone included in a date string e.g. (CET or CEST) carries more information that a time zone given by its ID e.g. "Europe/Warsaw". "Europe/Warsaw" time zone can be "CET" or "CEST". This is important during DST change. E.g. in year 2011 in "Europe/Warsaw" we disabled DST at:
"2011-10-30 03:00:00.000 CEST"
by pushing back clocks to:
"2011-10-30 02:00:00.000 CET"
Finally if we have only time zone ID like:
"Europe/Warsaw"
and any time between:
"2011-10-30 02:00:00.000" and
"2011-10-30 03:00:00.000"
we don't know if it is:
"CEST" or "CET"
Finally, use a time zone included in a date ("z" format code) wherever possible. If you have a date with a general time zone ID only, be careful because sometimes it is not strict.


Tutorial:
=======
* Get unix time
In: jtz_unix_now()
Out: 1319568508751

* But what does it mean in Poland?
In: jtz_unix_format(1319568508751; "yyyy-MM-dd HH:mm:ss.S z"; "Europe/Warsaw")
Out: 2011-10-25 20:48:28.751 CEST

* In Greece?
In: jtz_unix_format(1319568508751; "yyyy-MM-dd HH:mm:ss.S z"; "Europe/Athens")
Out: 2011-10-25 21:48:28.751 EEST

* How to read date format?
In: jtz_format_codes() [CSE]
Out: G | Era designator
...

Date format codes are case sensitive, "M" is for moth but "m" is for "minute".
Some codes can be repeated e.g. "MMM" gives short month name, "MMMM" gives long month name.

* Where can I find time zones IDs like "Europe/Warsaw"?
In: jtz_tz_ids() [CSE]
Out: ACT | CST | Central Standard Time (Northern Territory) | CST | Central Summer Time (Northern Territory)
...

where columns mean:
[1] time zone ID
[2] short RAW name
[3] long RAW name
[4] short DST name
[5] long DST name

You can search for particular time zone ID:
In: jtz_tz_ids(0; "en"; "Eur"; "Wars") [CSE]

where parameters are:
[1] if ( 1) then search is performed only in default locale,
if (== 1) then search is performed in ALL locales supported by Java
[2] output locale; Time zones IDs are the same in all locales but time zones
names can differ.
[3] search string
[4] search string

Requirements:

• LibreOffice