Class DateRngFmt

Create a new date range formatter instance. The date range formatter is immutable once it is created, but can format as many different date ranges as needed with the same options. Create different date range formatter instances for different purposes and then keep them cached for use later if you have more than one range to format.

The options may contain any of the following properties:

locale - locale to use when formatting the date/times in the range. If the locale is not specified, then the default locale of the app or web page will be used.
calendar - the type of calendar to use for this format. The value should be a sting containing the name of the calendar. Currently, the supported types are "gregorian", "julian", "arabic", "hebrew", or "chinese". If the calendar is not specified, then the default calendar for the locale is used. When the calendar type is specified, then the format method must be called with an instance of the appropriate date type. (eg. Gregorian calendar means that the format method must be called with a GregDate instance.)
timezone - time zone to use when formatting times. This may be a time zone instance or a time zone specifier string in RFC 822 format. If not specified, the default time zone for the locale is used.
length - Specify the length of the format to use as a string. The length is the approximate size of the formatted string.
- short - use a short representation of the time. This is the most compact format possible for the locale.
- medium - use a medium length representation of the time. This is a slightly longer format.
- long - use a long representation of the time. This is a fully specified format, but some of the textual components may still be abbreviated. (eg. "Tue" instead of "Tuesday")
- full - use a full representation of the time. This is a fully specified format where all the textual components are spelled out completely.
eg. The "short" format for an en_US range may be "MM/yy - MM/yy", whereas the long format might be "MMM, yyyy - MMM, yyyy". In the long format, the month name is textual instead of numeric and is longer, the year is 4 digits instead of 2, and the format contains slightly more spaces and formatting characters.
Note that the length parameter does not specify which components are to be formatted. The components that are formatted depend on the length of time in the range.
clock - specify that formatted times should use a 12 or 24 hour clock if the format happens to include times. Valid values are "12" and "24".
In some locales, both clocks are used. For example, in en_US, the general populace uses a 12 hour clock with am/pm, but in the US military or in nautical or aeronautical or scientific writing, it is more common to use a 24 hour clock. This property allows you to construct a formatter that overrides the default for the locale.
If this property is not specified, the default is to use the most widely used convention for the locale.
onLoad - a callback function to call when the date range format object is fully loaded. When the onLoad option is given, the DateRngFmt object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.

Defined in: DateRngFmt.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	DateRngFmt(options)

Method Summary
Method Attributes	Method Name and Description
	format(startDateLike, endDateLike) Format a date/time range according to the settings of the current formatter.
	getCalendar() Return the name of the calendar used to format date/times for this formatter instance.
	getClock() Return the clock option set in the constructor.
	getLength() Return the length used to format date/times in this formatter.
	getLocale() Return the locale used with this formatter instance.
	getTimeZone() Return the time zone used to format date/times for this formatter instance.

Class Detail

DateRngFmt(options)

Parameters:
{Object} options: options governing the way this date range formatter instance works

Method Detail

{string} format(startDateLike, endDateLike)

Format a date/time range according to the settings of the current formatter. The range is specified as being from the "start" date until the "end" date.

The template that the date/time range uses depends on the length of time between the dates, on the premise that a long date range which is too specific is not useful. For example, when giving the dates of the 100 Years War, in most situations it would be more appropriate to format the range as "1337 - 1453" than to format it as "10:37am November 9, 1337 - 4:37pm July 17, 1453", as the latter format is much too specific given the length of time that the range represents. If a very specific, but long, date range really is needed, the caller should format two specific dates separately and put them together as you might with other normal strings.

The format used for a date range contains the following date components, where the order of those components is rearranged and the component values are translated according to each locale:

within 3 days: the times of day, dates, months, and years
within 730 days (2 years): the dates, months, and years
within 3650 days (10 years): the months and years
longer than 10 years: the years only

In general, if any of the date components share a value between the start and end date, that component is only given once. For example, if the range is from November 15, 2011 to November 26, 2011, the start and end dates both share the same month and year. The range would then be formatted as "November 15-26, 2011".

If you want to format a length of time instead of a particular range of time (for example, the length of an event rather than the specific start time and end time of that event), then use a duration formatter instance (DurationFmt) instead. The formatRange method will make sure that each component of the date/time is within the normal range for that component. For example, the minutes will always be between 0 and 59, no matter what is specified in the date to format, because that is the normal range for minutes. A duration format will allow the number of minutes to exceed 59. For example, if you were displaying the length of a movie that is 198 minutes long, the minutes component of a duration could be 198.

Parameters:
{IDate|Date|number|string} startDateLike: the starting date/time of the range. The date may be given as an ilib IDate object, a javascript intrinsic Date object, a unix time, or a date string parsable by the javscript Date.
{IDate|Date|number|string} endDateLike: the ending date/time of the range. The date may be given as an ilib IDate object, a javascript intrinsic Date object, a unix time, or a date string parsable by the javscript Date.

Throws:
: "Wrong calendar type" when the start or end dates are not the same calendar type as the formatter itself

Returns:: {string} a date range formatted for the locale

{string} getCalendar()

Return the name of the calendar used to format date/times for this formatter instance.

Returns:: {string} the name of the calendar used by this formatter

{string} getClock()

Return the clock option set in the constructor. If the clock option was not given, the default from the locale is returned instead.

Returns:: {string} "12" or "24" depending on whether this formatter uses the 12-hour or 24-hour clock

{string} getLength()

Return the length used to format date/times in this formatter. This is either the value of the length option to the constructor, or the default value.

Returns:: {string} the length of formats this formatter returns

{Locale} getLocale()

Return the locale used with this formatter instance.

Returns:: {Locale} the Locale instance for this formatter

{TimeZone} getTimeZone()

Return the time zone used to format date/times for this formatter instance.

Returns:: {TimeZone} a string naming the time zone

Classes

Class DateRngFmt