net.rim.device.api.i18n
Class DateFormat

java.lang.Object
  |
  +--net.rim.device.api.i18n.Format
        |
        +--net.rim.device.api.i18n.DateFormat
Direct Known Subclasses:
SimpleDateFormat

public abstract class DateFormat
extends Format

Defines fundamental functionality for locale-independent formatting of date/time information.

Compatible with java.text.DateFormat from Java's standard edition.

Note: Time and date interpretation is consistent with Calendar objects. For example, the exact moment of "midnight" always belongs to the following day.


Field Summary
static int AM_PM_FIELD
          Useful constant for AM_PM field alignment.
static int DATE_DEFAULT
          Default date format style.
static int DATE_FIELD
          Useful constant for DATE field alignment.
static int DATE_FULL
          Full date style.
static int DATE_LONG
          Long date style.
static int DATE_MEDIUM
          Medium date style.
static int DATE_SHORT
          Short date style.
static int DATETIME_DEFAULT
          Default date-time format style.
static int DAY_OF_WEEK_FIELD
          Useful constant for DAY_OF_WEEK field alignment.
static int ERA_FIELD
          Useful constant for ERA field alignment.
static long GUID_DATE_FORMAT_CHANGED
          GUID for the global event sent when the default date format changes.
static int HOUR_FIELD
          Useful constant for HOUR field alignment.
static int HOUR_OF_DAY_FIELD
          Useful constant for HOUR_OF_DAY field alignment.
static int MILLISECOND_FIELD
          Useful constant for MILLISECOND field alignment.
static int MINUTE_FIELD
          Useful constant for MINUTE field alignment.
static int MONTH_FIELD
          Useful constant for MONTH field alignment.
static int SECOND_FIELD
          Useful constant for SECOND field alignment.
static int TIME_DEFAULT
          Default time format style.
static int TIME_FULL
          Full time style.
static int TIME_LONG
          Long time style.
static int TIME_MEDIUM
          Medium time style: typically, this style should be used by default.
static int TIME_SHORT
          Short time style.
static int TIMEZONE_FIELD
          Useful constant for TIMEZONE field alignment.
static int YEAR_FIELD
          Useful constant for YEAR field alignment.
 
Constructor Summary
protected DateFormat()
          Constructs new DateFormat instance.
 
Method Summary
abstract  StringBuffer format(Calendar date, StringBuffer toAppendTo_o, FieldPosition pos_io)
          Retrieves formatted string representation of calendar object.
 StringBuffer format(Object obj, StringBuffer toAppendTo_o, FieldPosition pos_io)
          Retrieves formatted string representation of object.
 String formatLocal(long date)
          Retrieves formatted representation of local date.
 StringBuffer formatLocal(StringBuffer sb, long date)
          Retrieves formatted representation of local date into string buffer.
static DateFormat getInstance(int style)
          Retrieves the date formatter for the given style and the default locale.
 
Methods inherited from class net.rim.device.api.i18n.Format
format, getFields
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

AM_PM_FIELD

public static final int AM_PM_FIELD
Useful constant for AM_PM field alignment. For example: at 11:05:17.170 PM the AM_PM is PM. Note: if the 24-hour format is used, am or pm is not displayed.

By default, equal to Calendar.AM_PM.


DATE_DEFAULT

public static final int DATE_DEFAULT
Default date format style. For example: Mar 08, 2006.

By default, set to DATE_MEDIUM; subclasses may override this.


DATE_FIELD

public static final int DATE_FIELD
Useful constant for DATE field alignment. For example, the first day in a month has the value 1.

By default, equal to Calendar.DAY_OF_MONTH.


DATE_FULL

public static final int DATE_FULL
Full date style. For example: Wednesday, March 08, 2006 CE

All date information should be present, including era and timezone.


DATE_LONG

public static final int DATE_LONG
Long date style.

For example: Wednesday, March 08, 2006.


DATE_MEDIUM

public static final int DATE_MEDIUM
Medium date style. For example: Mar 08, 2006.

Typically, this style should used by default.


DATE_SHORT

public static final int DATE_SHORT
Short date style. For example: 03.08.06.

A very abbreviated format; for example, may include only numbers for date, month, and year.


DATETIME_DEFAULT

public static final int DATETIME_DEFAULT
Default date-time format style. For example, Mar 08, 2006 or Jan. 24, 1975.

By default, set to (DATE_DEFAULT | TIME_DEFAULT); subclasses may override this.


DAY_OF_WEEK_FIELD

public static final int DAY_OF_WEEK_FIELD
Useful constant for DAY_OF_WEEK field alignment. Number values representing a day in a week: SUNDAY, MONDAY, TUESDAY, etc.

By default, equal to Calendar.DAY_OF_WEEK.


ERA_FIELD

public static final int ERA_FIELD
Useful constant for ERA field alignment. For example: CE or BCE.

By default, equal to CalendarExtensions#ERA.


GUID_DATE_FORMAT_CHANGED

public static final long GUID_DATE_FORMAT_CHANGED
GUID for the global event sent when the default date format changes.

HOUR_FIELD

public static final int HOUR_FIELD
Useful constant for HOUR field alignment. For example: at 12:05:17.170 PM the HOUR is 12.

By default, equal to Calendar.HOUR.


HOUR_OF_DAY_FIELD

public static final int HOUR_OF_DAY_FIELD
Useful constant for HOUR_OF_DAY field alignment. For example: at 11:05:17.170 PM the HOUR_OF_DAY is 23

By default, equal to Calendar.HOUR_OF_DAY.


MILLISECOND_FIELD

public static final int MILLISECOND_FIELD
Useful constant for MILLISECOND field alignment. For example: at 12:05:17.170 PM the MILLISECOND is 170.

By default, equal to Calendar.MILLISECOND.


MINUTE_FIELD

public static final int MINUTE_FIELD
Useful constant for MINUTE field alignment. For example: at 12:05:17.170 PM the MINUTE is 5.

By default, equal to Calendar.MINUTE.


MONTH_FIELD

public static final int MONTH_FIELD
Useful constant for MONTH field alignment. For example, the first month in a year, January, is represented by 0.

By default, equal to Calendar.MONTH.


SECOND_FIELD

public static final int SECOND_FIELD
Useful constant for SECOND field alignment. For example: at 12:05:17.170 PM the SECOND is 17.

By default, equal to Calendar.SECOND.


TIME_DEFAULT

public static final int TIME_DEFAULT
Default time format style.

By default, set to TIME_MEDIUM; subclasses may override this.


TIME_FULL

public static final int TIME_FULL
Full time style. For example: 2:10:20pm PST. Note: if the 24-hour format is used, am or pm is not displayed.

All time information should be present, including era and timezone.


TIME_LONG

public static final int TIME_LONG
Long time style. For example: 2:10:20pm. Note: if the 24-hour format is used, am or pm is not displayed.

TIME_MEDIUM

public static final int TIME_MEDIUM
Medium time style: typically, this style should be used by default. For example, Jan. 24, 1975.

TIME_SHORT

public static final int TIME_SHORT
Short time style. For example: 2:10pm. Note: if the 24-hour format is used, am or pm is not displayed.

A very abbreviated format; for example, time might not include anything except hour.


TIMEZONE_FIELD

public static final int TIMEZONE_FIELD
Useful constant for TIMEZONE field alignment.

By default, set to "90" (no equivalent in Calendar).


YEAR_FIELD

public static final int YEAR_FIELD
Useful constant for YEAR field alignment.

By default, equal to Calendar.YEAR.

Constructor Detail

DateFormat

protected DateFormat()
Constructs new DateFormat instance.
Method Detail

format

public abstract StringBuffer format(Calendar date,
                                    StringBuffer toAppendTo_o,
                                    FieldPosition pos_io)
Retrieves formatted string representation of calendar object.

Comparable to java.text.DateFormat.format in Java's standard edition.

Parameters:
date - Calendar object containing date to format.
toAppendTo_o - String buffer to hold the formatted results.
pos_io - If not null, this method should invoke Format.getFields() and set the begin/end for this field during formatting.
Returns:
String buffer containing formatted string representation of object.

format

public StringBuffer format(Object obj,
                           StringBuffer toAppendTo_o,
                           FieldPosition pos_io)
Retrieves formatted string representation of object.

Comparable to java.text.DateFormat.format in Java's standard edition.

Note: This method casts the provided object to a Calendar, and invokes format(Calendar,StringBuffer,FieldPosition).

Overrides:
format in class Format
Parameters:
obj - Object to format.
toAppendTo_o - String buffer to hold the formatted results.
pos_io - If not null, this method should invoke Format.getFields() and set the begin/end for this field during formatting.
Returns:
String buffer containing formatted string representation of object.

formatLocal

public final String formatLocal(long date)
Retrieves formatted representation of local date.

Parameters:
date - Date/time to format.
Returns:
Formatted date string.

formatLocal

public final StringBuffer formatLocal(StringBuffer sb,
                                      long date)
Retrieves formatted representation of local date into string buffer.

Parameters:
sb - String buffer to hold the formatted results.
date - Date/time to format.
Returns:
String buffer containing formatted representation of provided date.

getInstance

public static final DateFormat getInstance(int style)
Retrieves the date formatter for the given style and the default locale.
Parameters:
style - Date/time format style to use (one of DATE_FULL, DATE_LONG, DATE_MEDIUM, DATE_SHORT, DATE_DEFAULT, TIME_FULL, TIME_LONG, TIME_MEDIUM, TIME_SHORT, TIME_DEFAULT, DATETIME_DEFAULT).
Returns:
New SimpleDateFormat instance with the provided style.


Copyright 1999-2007 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.