Posts tagged "calendar"

Formatting with alternate calendars in Flex

This article was originally written in English. Text in other languages was provided by machine translation.

Dates can be formatted in various calendars in the Flex SDK. Let’s explore how it works.

Flex SDK lets you format a given date in “alternate calendars” besides the Gregorian calendar. The industry convention refers all non-Gregorian calendars as alternate calendars. To use an alternate calendar, it requires a little bit of care in your Flex application.

Types of calendars

Before we dive into the alternate calendar usages in the Flex SDK, let’s take a brief look at a couple of calen­dars of the world so that you get familiar with what this calendar talk is about. Please be aware, I can only describe the basic usages of some common alternate calendars. There are complexities behind each of the calendars and I may not be explicitly state them. Investigate fur­ther before you actually use them.

Gregorian calendar

This is the calendar most systems provide as the standard. You probably know this calendar already but here are some of the characteristics: There are always twelve months in a year and each month has 28 to 31 days. The numbers of days in each of the months are fixed (30 or 31 days) except for the second month (February), which includes 28 (non-leap years) or 29 days (leap years). The number of days in a year is fixed (365 or 366 days).

Islamic calendar (Hijri calendar)

Islamic calendar is one of the lunar calendars.  There are always twelve months in a year. Each month has ei­ther 29 or 30 days. Beginning of a month is determined by observing the moon phase (Islamic religious calendar). Because of this nature, it is not very possible to predict the dates with the Islamic religious calendar. For the sake of convenience, there is the variant of the calendar, Islamic civil calendar, which determines the dates through some pure mathematical calculation. Islamic civil calendar may not be accurate for religious events. Number of days in a year is 354 or 355 days. Hence, the Islamic calendar year and the Gregorian calendar year are not synchronized.

Japanese calendar

Japanese calendar is very similar with the Gregorian calendar. The difference is the era part and the year. The Gregorian calendar has been using the same era name for the past 2,000 years (AD; Anno Domini). There is also BC (Before Christ) era but BC years are not by supported by pretty much all calendar apps. On the other hand, Japanese calendar era name changes when there is new emperor. Therefore, every ten to a couple of ten years, there are new eras. *1

*1 Before the 1868, the era name changes were more frequent, an era lasted only as low as two years. But just like the BC in Gregorian, there is not much demand to be able to deal with the older eras in today’s calendar applica­tions.

There are much more types of calendars in the world but I hope you got some ideas how calendars can vary.

How to use the alternate calendars in Flex SDK

Now let’s look at the usage of alternate calendars. How do you use calendar other than the Gregorian in the Flex SDK? The an­swer is to use the locale ID.

The locale ID can optionally contain calendar tag. For example:

Locale ID Meaning
ar-SA Arabic used in Saudi Arabia
ar-SA@calendar=islamic Arabic used in Saudi Arabia. Islamic calendar
en-US@calendar=islamic English used in the U.S. Islamic calendar.

When you need to format a date in an alternate calendar, the calendar tag can be appended to the locale ID. Here is an example:

import spark.formatters.DateTimeFormatter;
private function calendarDemo():void
{
    var d:Date = new Date(2011, 9, 15);
    var dtf:DateTimeFormatter = new DateTimeFormatter();
    dtf.dateStyle = "long";
    dtf.timeStyle = "none";
 
    dtf.setStyle("locale", "en-US");
    trace("(1) " + dtf.format(d));
 
    dtf.setStyle("locale", "ar-SA");
    trace("(2) " + dtf.format(d));
 
    dtf.setStyle("locale", "ja-JP");
    trace("(3) " + dtf.format(d));
 
    dtf.setStyle("locale", "en-US@calendar=islamic");
    trace("(4) " + dtf.format(d));
 
    dtf.setStyle("locale", "ar-SA@calendar=islamic");
    trace("(5) " + dtf.format(d));
 
    dtf.setStyle("locale", "en-US@calendar=japanese");
    trace("(6) " + dtf.format(d));
 
    dtf.setStyle("locale", "ja-JP@calendar=japanese");
    trace("(7) " + dtf.format(d));
}

Here is the result you might get.

Please note that the result may vary depending on the run-time platforms.

Limitations you should be aware of

There are couples of limitations in the current Flash Player and Flex SDK for alternate calendar support.

  1. The Date class can handle only Gregorian dates.
  2. The Spark DateTimeFormatter class can format a Date object but parsing feature (translating a formatted Gregorian or non-Gregorian date string into a Date object) is not available. English Gregorian date string can be parsed through the Date class constructor in some degree.
  3. The availability of alternate calendar support and its behavior is platform dependent. Please check the plat­form if the alternate calendar support is important for your application.

If you would like to know more about alternate calendars, the calendar entries on Wikipedia is a good source.