Railo tip: using timezones in date/time functions

At the Railo team, we wanted to schedule regular meetings with the team. Normally, you would just pick a date and time, and you're done. But that's not so easy with the Railo team, since we live all around the world. Our main developer Michael therefor created a "tea(m) time" page where we can see what time it currently is for all the team members. At second glance, it suddenly struck me that I never saw this kind of timezone usage before:

#LSDateFormat(now(), "long", getLocale(), tz)#

where tz is a timezone string like "Australia/Perth". So I looked it up in both the Railo wiki and the ACF documentation, to find out that I just hit another hidden gem in Railo!

What this timezone attribute can do, is for example show you the current time in any timezone of the world:

<cfoutput>
<em>What time is it in:</em><br />
<table>
<tr><td>New York:</td>
<td align="right">#timeformat(now(), "medium", "America/New_York")#</td></tr>
<tr><td>Moscow:</td>
<td align="right">#timeformat(now(), "medium", "Europe/Moscow")#</td></tr>
<tr><td>Amsterdam:</td>
<td align="right">#timeformat(now(), "medium", "Europe/Amsterdam")#</td></tr>
<tr><td>Timbuktu:</td>
<td align="right">#timeformat(now(), "medium", "Africa/Timbuktu")#</td></tr>
</table>
</cfoutput>

This code will output the following (at 23:35 local Dutch time):

example output of the previous code

Not only does this work with lsDateFormat, but also with: (retrieved from the Railo wiki)

CreateDate CreateDate(year,month,day[,timezone]) docs
CreateDateTime CreateDateTime(year,month,day,hour,minute,second [,millis] [,timezone]) docs
CreateTime CreateTime(hour,minute,second [,millis] [,timezone]) docs
DateFormat DateFormat(object [,mask] [,timezone]) docs
Day Day(date[,timezone]) docs
DayOfWeek DayOfWeek(date[,timezone]) docs
DayOfYear DayOfYear(date[,timezone]) docs
DaysInMonth DaysInMonth(date[,timezone]) docs
DaysInYear DaysInYear(date[,timezone]) docs
FirstDayOfMonth FirstDayOfMonth(date[,timezone]) docs
Hour Hour(Date[,timezone]) docs
LSDateFormat LSDateFormat(date[,mask][,locale][,timezone]) docs
LSIsDate LSIsDate(string[,locale][,timezone]) docs
LSParseDateTime LSParseDateTime(dateString[,locale][,timezone]) docs
LSTimeFormat LSTimeFormat(time[,mask][,locale][,timezone]) docs
Minute Minute(date[,timezone]) docs
Month Month(Date[,timezone]) docs
ParseDateTime ParseDateTime(string1[,string2][,timezone]) docs
Quarter Quarter(date[,timezone]) docs
Second Second(date[,timezone]) docs
TimeFormat TimeFormat(time[,mask][,timezone]) docs
Week Week(date[,timezone]) docs
Year Year(date[,timezone]) docs

Just to be complete, here's a list with date/time functions without a timezone attribute:

CreateODBCDate CreateODBCDate(date) docs
CreateODBCDateTime CreateODBCDateTime(date) docs
CreateODBCTime CreateODBCTime(date) docs
CreateTimeSpan CreateTimeSpan(days,hours,minutes,seconds[,milliseconds]) docs
DateAdd DateAdd(datepart,number,date) docs
DateCompare DateCompare(date1,date2[,arg3]) docs
DateConvert DateConvert(conversion_type,date) docs
DateDiff DateDiff(datepart,date1,date2) docs
DatePart DatePart(datepart,date) docs
DayOfWeekAsString DayOfWeekAsString(day_of_week[,locale]) docs
GetHttpTimeString GetHttpTimeString([date_time_object]) docs
GetTickCount GetTickCount() docs
GetTimeZoneInfo GetTimeZoneInfo() docs
IsDate IsDate(string) docs
IsLeapYear IsLeapYear(year) docs
IsNumericDate IsNumericDate(number) docs
MonthAsString MonthAsString(monthnumber[,locale]) docs
Now Now() docs

What is also pretty cool, is the very long list of available timezones:

Etc/GMT+12, Etc/GMT+11, MIT, Pacific/Apia, Pacific/Midway, Pacific/Niue, Pacific/Pago_Pago, Pacific/Samoa, US/Samoa, America/Adak, America/Atka, Etc/GMT+10, HST, Pacific/Fakaofo, Pacific/Honolulu, Pacific/Johnston, Pacific/Rarotonga, Pacific/Tahiti, SystemV/HST10, US/Aleutian, US/Hawaii, Pacific/Marquesas, AST, America/Anchorage, America/Juneau, America/Nome, America/Yakutat, Etc/GMT+9, Pacific/Gambier, SystemV/YST9, SystemV/YST9YDT, US/Alaska, America/Dawson, America/Ensenada, America/Los_Angeles, America/Santa_Isabel, America/Tijuana, America/Vancouver, America/Whitehorse, Canada/Pacific, Canada/Yukon, Etc/GMT+8, Mexico/BajaNorte, PST, PST8PDT, Pacific/Pitcairn, SystemV/PST8, SystemV/PST8PDT, US/Pacific, US/Pacific-New, America/Boise, America/Cambridge_Bay, America/Chihuahua, America/Dawson_Creek, America/Denver, America/Edmonton, America/Hermosillo, America/Inuvik, America/Mazatlan, America/Ojinaga, America/Phoenix, America/Shiprock, America/Yellowknife, Canada/Mountain, Etc/GMT+7, MST, MST7MDT, Mexico/BajaSur, Navajo, PNT, SystemV/MST7, SystemV/MST7MDT, US/Arizona, US/Mountain, America/Bahia_Banderas, America/Belize, America/Cancun, America/Chicago, America/Costa_Rica, America/El_Salvador, America/Guatemala, America/Indiana/Knox, America/Indiana/Tell_City, America/Knox_IN, America/Managua, America/Matamoros, America/Menominee, America/Merida, America/Mexico_City, America/Monterrey, America/North_Dakota/Center, America/North_Dakota/New_Salem, America/Rainy_River, America/Rankin_Inlet, America/Regina, America/Swift_Current, America/Tegucigalpa, America/Winnipeg, CST, CST6CDT, Canada/Central, Canada/East-Saskatchewan, Canada/Saskatchewan, Chile/EasterIsland, Etc/GMT+6, Mexico/General, Pacific/Easter, Pacific/Galapagos, SystemV/CST6, SystemV/CST6CDT, US/Central, US/Indiana-Starke, America/Atikokan, America/Bogota, America/Cayman, America/Coral_Harbour, America/Detroit, America/Fort_Wayne, America/Grand_Turk, America/Guayaquil, America/Havana, America/Indiana/Indianapolis, America/Indiana/Marengo, America/Indiana/Petersburg, America/Indiana/Vevay, America/Indiana/Vincennes, America/Indiana/Winamac, America/Indianapolis, America/Iqaluit, America/Jamaica, America/Kentucky/Louisville, America/Kentucky/Monticello, America/Lima, America/Louisville, America/Montreal, America/Nassau, America/New_York, America/Nipigon, America/Panama, America/Pangnirtung, America/Port-au-Prince, America/Resolute, America/Thunder_Bay, America/Toronto, Canada/Eastern, Cuba, EST, EST5EDT, Etc/GMT+5, IET, Jamaica, SystemV/EST5, SystemV/EST5EDT, US/East-Indiana, US/Eastern, US/Michigan, America/Caracas, America/Anguilla, America/Antigua, America/Argentina/San_Luis, America/Aruba, America/Asuncion, America/Barbados, America/Blanc-Sablon, America/Boa_Vista, America/Campo_Grande, America/Cuiaba, America/Curacao, America/Dominica, America/Eirunepe, America/Glace_Bay, America/Goose_Bay, America/Grenada, America/Guadeloupe, America/Guyana, America/Halifax, America/La_Paz, America/Manaus, America/Marigot, America/Martinique, America/Moncton, America/Montserrat, America/Port_of_Spain, America/Porto_Acre, America/Porto_Velho, America/Puerto_Rico, America/Rio_Branco, America/Santiago, America/Santo_Domingo, America/St_Barthelemy, America/St_Kitts, America/St_Lucia, America/St_Thomas, America/St_Vincent, America/Thule, America/Tortola, America/Virgin, Antarctica/Palmer, Atlantic/Bermuda, Atlantic/Stanley, Brazil/Acre, Brazil/West, Canada/Atlantic, Chile/Continental, Etc/GMT+4, PRT, SystemV/AST4, SystemV/AST4ADT, America/St_Johns, CNT, Canada/Newfoundland, AGT, America/Araguaina, America/Argentina/Buenos_Aires, America/Argentina/Catamarca, America/Argentina/ComodRivadavia, America/Argentina/Cordoba, America/Argentina/Jujuy, America/Argentina/La_Rioja, America/Argentina/Mendoza, America/Argentina/Rio_Gallegos, America/Argentina/Salta, America/Argentina/San_Juan, America/Argentina/Tucuman, America/Argentina/Ushuaia, America/Bahia, America/Belem, America/Buenos_Aires, America/Catamarca, America/Cayenne, America/Cordoba, America/Fortaleza, America/Godthab, America/Jujuy, America/Maceio, America/Mendoza, America/Miquelon, America/Montevideo, America/Paramaribo, America/Recife, America/Rosario, America/Santarem, America/Sao_Paulo, Antarctica/Rothera, BET, Brazil/East, Etc/GMT+3, America/Noronha, Atlantic/South_Georgia, Brazil/DeNoronha, Etc/GMT+2, America/Scoresbysund, Atlantic/Azores, Atlantic/Cape_Verde, Etc/GMT+1, Africa/Abidjan, Africa/Accra, Africa/Bamako, Africa/Banjul, Africa/Bissau, Africa/Casablanca, Africa/Conakry, Africa/Dakar, Africa/El_Aaiun, Africa/Freetown, Africa/Lome, Africa/Monrovia, Africa/Nouakchott, Africa/Ouagadougou, Africa/Sao_Tome, Africa/Timbuktu, America/Danmarkshavn, Atlantic/Canary, Atlantic/Faeroe, Atlantic/Faroe, Atlantic/Madeira, Atlantic/Reykjavik, Atlantic/St_Helena, Eire, Etc/GMT, Etc/GMT+0, Etc/GMT-0, Etc/GMT0, Etc/Greenwich, Etc/UCT, Etc/UTC, Etc/Universal, Etc/Zulu, Europe/Belfast, Europe/Dublin, Europe/Guernsey, Europe/Isle_of_Man, Europe/Jersey, Europe/Lisbon, Europe/London, GB, GB-Eire, GMT, GMT0, Greenwich, Iceland, Portugal, UCT, UTC, Universal, WET, Zulu, Africa/Algiers, Africa/Bangui, Africa/Brazzaville, Africa/Ceuta, Africa/Douala, Africa/Kinshasa, Africa/Lagos, Africa/Libreville, Africa/Luanda, Africa/Malabo, Africa/Ndjamena, Africa/Niamey, Africa/Porto-Novo, Africa/Tunis, Africa/Windhoek, Arctic/Longyearbyen, Atlantic/Jan_Mayen, CET, ECT, Etc/GMT-1, Europe/Amsterdam, Europe/Andorra, Europe/Belgrade, Europe/Berlin, Europe/Bratislava, Europe/Brussels, Europe/Budapest, Europe/Copenhagen, Europe/Gibraltar, Europe/Ljubljana, Europe/Luxembourg, Europe/Madrid, Europe/Malta, Europe/Monaco, Europe/Oslo, Europe/Paris, Europe/Podgorica, Europe/Prague, Europe/Rome, Europe/San_Marino, Europe/Sarajevo, Europe/Skopje, Europe/Stockholm, Europe/Tirane, Europe/Vaduz, Europe/Vatican, Europe/Vienna, Europe/Warsaw, Europe/Zagreb, Europe/Zurich, MET, Poland, ART, Africa/Blantyre, Africa/Bujumbura, Africa/Cairo, Africa/Gaborone, Africa/Harare, Africa/Johannesburg, Africa/Kigali, Africa/Lubumbashi, Africa/Lusaka, Africa/Maputo, Africa/Maseru, Africa/Mbabane, Africa/Tripoli, Asia/Amman, Asia/Beirut, Asia/Damascus, Asia/Gaza, Asia/Istanbul, Asia/Jerusalem, Asia/Nicosia, Asia/Tel_Aviv, CAT, EET, Egypt, Etc/GMT-2, Europe/Athens, Europe/Bucharest, Europe/Chisinau, Europe/Helsinki, Europe/Istanbul, Europe/Kaliningrad, Europe/Kiev, Europe/Mariehamn, Europe/Minsk, Europe/Nicosia, Europe/Riga, Europe/Simferopol, Europe/Sofia, Europe/Tallinn, Europe/Tiraspol, Europe/Uzhgorod, Europe/Vilnius, Europe/Zaporozhye, Israel, Libya, Turkey, Africa/Addis_Ababa, Africa/Asmara, Africa/Asmera, Africa/Dar_es_Salaam, Africa/Djibouti, Africa/Kampala, Africa/Khartoum, Africa/Mogadishu, Africa/Nairobi, Antarctica/Syowa, Asia/Aden, Asia/Baghdad, Asia/Bahrain, Asia/Kuwait, Asia/Qatar, Asia/Riyadh, EAT, Etc/GMT-3, Europe/Moscow, Europe/Samara, Europe/Volgograd, Indian/Antananarivo, Indian/Comoro, Indian/Mayotte, W-SU, Asia/Riyadh87, Asia/Riyadh88, Asia/Riyadh89, Mideast/Riyadh87, Mideast/Riyadh88, Mideast/Riyadh89, Asia/Tehran, Iran, Asia/Baku, Asia/Dubai, Asia/Muscat, Asia/Tbilisi, Asia/Yerevan, Etc/GMT-4, Indian/Mahe, Indian/Mauritius, Indian/Reunion, NET, Asia/Kabul, Antarctica/Mawson, Asia/Aqtau, Asia/Aqtobe, Asia/Ashgabat, Asia/Ashkhabad, Asia/Dushanbe, Asia/Karachi, Asia/Oral, Asia/Samarkand, Asia/Tashkent, Asia/Yekaterinburg, Etc/GMT-5, Indian/Kerguelen, Indian/Maldives, PLT, Asia/Calcutta, Asia/Colombo, Asia/Kolkata, IST, Asia/Kathmandu, Asia/Katmandu, Antarctica/Vostok, Asia/Almaty, Asia/Bishkek, Asia/Dacca, Asia/Dhaka, Asia/Novokuznetsk, Asia/Novosibirsk, Asia/Omsk, Asia/Qyzylorda, Asia/Thimbu, Asia/Thimphu, BST, Etc/GMT-6, Indian/Chagos, Asia/Rangoon, Indian/Cocos, Antarctica/Davis, Asia/Bangkok, Asia/Ho_Chi_Minh, Asia/Hovd, Asia/Jakarta, Asia/Krasnoyarsk, Asia/Phnom_Penh, Asia/Pontianak, Asia/Saigon, Asia/Vientiane, Etc/GMT-7, Indian/Christmas, VST, Antarctica/Casey, Asia/Brunei, Asia/Choibalsan, Asia/Chongqing, Asia/Chungking, Asia/Harbin, Asia/Hong_Kong, Asia/Irkutsk, Asia/Kashgar, Asia/Kuala_Lumpur, Asia/Kuching, Asia/Macao, Asia/Macau, Asia/Makassar, Asia/Manila, Asia/Shanghai, Asia/Singapore, Asia/Taipei, Asia/Ujung_Pandang, Asia/Ulaanbaatar, Asia/Ulan_Bator, Asia/Urumqi, Australia/Perth, Australia/West, CTT, Etc/GMT-8, Hongkong, PRC, Singapore, Australia/Eucla, Asia/Dili, Asia/Jayapura, Asia/Pyongyang, Asia/Seoul, Asia/Tokyo, Asia/Yakutsk, Etc/GMT-9, JST, Japan, Pacific/Palau, ROK, ACT, Australia/Adelaide, Australia/Broken_Hill, Australia/Darwin, Australia/North, Australia/South, Australia/Yancowinna, AET, Antarctica/DumontDUrville, Asia/Sakhalin, Asia/Vladivostok, Australia/ACT, Australia/Brisbane, Australia/Canberra, Australia/Currie, Australia/Hobart, Australia/Lindeman, Australia/Melbourne, Australia/NSW, Australia/Queensland, Australia/Sydney, Australia/Tasmania, Australia/Victoria, Etc/GMT-10, Pacific/Chuuk, Pacific/Guam, Pacific/Port_Moresby, Pacific/Saipan, Pacific/Truk, Pacific/Yap, Australia/LHI, Australia/Lord_Howe, Antarctica/Macquarie, Asia/Anadyr, Asia/Kamchatka, Asia/Magadan, Etc/GMT-11, Pacific/Efate, Pacific/Guadalcanal, Pacific/Kosrae, Pacific/Noumea, Pacific/Pohnpei, Pacific/Ponape, SST, Pacific/Norfolk, Antarctica/McMurdo, Antarctica/South_Pole, Etc/GMT-12, Kwajalein, NST, NZ, Pacific/Auckland, Pacific/Fiji, Pacific/Funafuti, Pacific/Kwajalein, Pacific/Majuro, Pacific/Nauru, Pacific/Tarawa, Pacific/Wake, Pacific/Wallis, NZ-CHAT, Pacific/Chatham, Etc/GMT-13, Pacific/Enderbury, Pacific/Tongatapu, Etc/GMT-14, Pacific/Kiritimati

del.icio.us Digg StumbleUpon Facebook Technorati Fav reddit Google Bookmarks
| Viewed 5551 times
  1. Michael Offner

    #1 by Michael Offner - April 7, 2011 at 9:49 AM

    Why the second group take no Timezone, the first group convert a date to a string or a the opposite and the second does not.
    You can compare timezone usage with "locale" usage, a date object is independent of a specific "locale", so it is also independent of a specific timezone.
    a Date object only defines a time pass by since "1.1.1970 00:00:00 UTC" in milliseconds, this means for example new java.util.Date(30*1000) is "1.1.1970 00:00:30 UTC" or
    "1.1.1970 01:00:30 CET", the Date object is absolute, not relative to a timezone.
    when you convert a date object in something else, the timezone comes into play.
    Like you know, the "locale" argument always is optional, like the "timezone" attribute as well.
    this function call "DateFormat(date)" takes the "locale" and "timezone" definition from the environment, defined in admin or with help of the function "setLocale" and "setTimezone", with help of the function "getLocale" and "getTimezone" you can read the current setting.
    Perhaps you are asking, but what happens in this case:
    now: #now()#
    in this case the function "now" returns a date object, this date object is converted to a string before it is written to te response stream, for this railo use a specific pattern and the timezone defined in enviroment, but not the function "now" does this conversion, "now" just return a date object, because of that it has no timezone argument
  2. Michael Offner

    #2 by Michael Offner - April 7, 2011 at 10:11 AM

    a small addition:
    "datePart" also takes "timezone" as optional argument and "GetHttpTimeString" takes no timezone, because it always produce a GMT based format
  3. Paul Klinkenberg

    #3 by Paul Klinkenberg - April 7, 2011 at 11:40 AM

    Hi Micha,
    Thanks for the explanation! It makes the inner workings more clear :-)
    By the way, datePart() does not use the timezone argument in it's calculations yet. I guess that's why it was not in the documentation yet? I created an enhancement request for this: https://issues.jboss.org/browse/RAILO-1294
    But anyway, great work!
(will not be published)
Leave this field empty

disc-crystalline