TDateTimeFormatter protocol

Each TDateTimeFormatter instance has a localizable name for use with the locale mechanism. You can use the date and time formatter from the current locale to format time in a meaningful format. The TLocale class provides identifiers for a default time format, a full date format, an abbreviated date format, and a numeric date format. See "Predefined locale items" on page 265 for more information.

This sample code shows how to format the current time using the full date formatter from the current locale:

  // Get the correct date formatter from the current locale.
  TLocale currentLocale = TLocale::GetCurrentLocale();
  TLocaleItem<TDateTimeFormatter> item;
  TDeleterFor<TDateTimeFormatter> dateFormatter = 
              item.CopyItem( TLocale::kFullDateFormatID, currentLocale );
  
  // Get the current time.
  TSeconds currentTime;
  TDateTimeClock().Now( currentTime );
  
  // Use the formatter.
  TStandardText formattedDate;
  TFormatResult result;
  
  dateFormatter->Format( TFormattableTime(currentTime), formattedDate, result );

• Using military, or 24-hour, time
• Specifying midnight as hour 0
• Abbreviating years--for example, 99 instead of 1999
• Flexible scanning--having more than one date or time formatting pattern to map against a scanned text string
• Using different number formatters to format the numeric portions of the date and time

TGregorianDateTimeFormatter is a pattern-based formatter. This type of formatter uses a specific pattern, encapsulated by a TDateTimePattern instance, as a template for formatting and scanning. A pattern-based formatter also supports flexible scanning. You can specify more than one TDateTimePattern instance for use during scanning, and the formatter returns the pattern that produces the best results.

TDateTimePattern derives from TParameterFormatter (see "Using TParameterFormatter" on page 219). You create a TDateTimePattern the same way you create a TParameterFormatter:

1. Create a text template and attach it to the TDateTimePattern with the SetTemplate function.
   
2. Use the SetDateTimeFieldFormat function to identify each variable range, setting each range to a particular date or time field type, and attaching a formatter.
   
3. Use the pattern by attaching it to the formatter with the TPatternBasedDateTimeFormatter::AdoptPattern member function.
   

This mechanism lets you individually set the formatter for each field; typically this will be a number formatter. You might also use a TChoiceFormatter to provide text-number mappings--for example, mapping the kMonthInYear field to the month names.

NOTE In a future release, the system will provide an editor for creating and modifying date and time patterns.

You can also use the TAlternateTextMatch mechanism to extend the scanning function. For example, you might want to scan either the hyphen or the slash as a date separator.

The following sample code shows how to create a pattern-based date formatter and attach an alternate text match:

  TGregorianDateTimeFormatter dateFormatter;
  TDateTimePattern* datePattern = new TDateTimePattern;
  TPositionalNumberFormatter dateNumberFormatter;
  TFormattableTime date;
  TScanResult dateScanResult;
  TAlternateTextMatch dateAlternateTextMatch;
  
  // Create the template for the pattern; for example, 1/1/1999
  TStandardText textTemplate("<month>/<day>/<year>");
  dateFormatter.SetTemplate(textTemplate);
  
  // Define the fields and attach formatters.
  datePattern->SetDateTimeFieldFormat(TTextRange(TTextOffset(0),TTextOffset(7)),
                                      0, kMonthInYear, dateNumberFormatter);
  datePattern->SetDateTimeFieldFormat(TTextRange(TTextOffset(8),TTextOffset(13)),
                                      0, kDayInMonth, dateNumberFormatter);
  datePattern->SetDateTimeFieldFormat(TTextRange(TTextOffset(14),TTextOffset(20)),
                                      0, kYearInEra, dateNumberFormatter);
  
  // Attach the pattern to the date formatter.
  dateFormatter->AdoptPattern(datePattern);
  
  // Add an alternate text match so that the pattern 1-1-1999 scans in.
  dateAlternateTextMatch.AddAlternateText(TStandardText("-"));
  dateFormatter.SetTextMatch(TTextRange(TTextOffset(7),TTextOffset(8)),
                              dateAlternateTextMatch);
  dateFormatter.SetTextMatch(TTextRange(TTextOffset(13),TTextOffset(14)),
                              dateAlternateTextMatch);
  
  // Perform the scanning operation.
  TStandardText scanText("1-1-1999");
  dateFormatter.Scan(scanText,TTextRange::GetMaximumRange(),date,dateScanResult);

Each TCalendar instance has a localizable name for use with the locale mechanism. When you need the current TCalendar instance, you can get it from the current locale using the identifier TLocale::kCalendarID.

Calendar fields

This table lists the TCalendar fields, along with the values that appear in the U. S. Gregorian calendar.

	Field	Minimum value	Lower maximum value	Upper maximum value	Value for date 12:12:12 p.m. January 1, 1999 A.D.
	kEra	0 (B.C.)	1 (A.D.)	1	1
	kYearInEra	1	5,000,000	5,000,000	1999
	kMonthInYear	1 (January)	12 (December)	12	1
	kDayInMonth	1	28	31	1
	kHourInDay	0	23	23	12
	kMinuteInHour	0	59	59	12
	kSecondInMinute	0	59	59	12
	kHalfDayInDay	0 (A.M.)	1 (P.M.)	1	1
	kHourInHalfDay	0	11	11	0
	kWeekInYear	1	53	54	1
	kDayInWeek	0 (Sunday)	6 (Saturday)	6	5 (Friday)
	kDayInYear	1	365	366	1

Changing calendar fields

• Setting--Specifying a specific value for an individual field. TCalendar adjusts the minimum number of fields necessary to produce valid results.
• Rolling--Incrementing or decrementing a field without changing the value of any other field. For example, incrementing the month field in the date Dec. 30, 1989, by one produces the date Jan. 30, 1989. TCalendar adjusts other fields when necessary to produce a valid result. For example, incrementing the month field in the date Jan. 30, 1989, by one produces the invalid date Feb. 30, 1989; TCalendar adjusts the value in the invalid field to the closest valid date, producing Feb. 28, 1989.
• Shifting--Incrementing or decrementing a field, adjusting the values of other fields as appropriate, and keeping them within their range. This function produces a wrap-around effect. For example, incrementing the month field in the date Dec. 30, 1989, by one produces the date Jan. 30, 1990.

	Operation	Result (Current date: 6-26-1999)
	SetField(kMonthInYear,1)	1-26-1999
	SetField(kMonthInYear,13)	1-26-1999
	RollField(kMonthInYear,1)	7-26-1999
	RollField(kMonthInYear,7)	1-26-1999
	ShiftField(kMonthInYear, 1)	7-26-1999
	ShiftField(kMonthInYear,7)	1-26-2000

Time zones

Each TTimeZone instance can have a localizable name that can be used with the locale mechanism. When you need the current TTimeZone instance, you can get it from the current locale using the identifier TLocale::kTimeZoneID.

The TTimeZone class does not support using a single TTimeZone instance to represent standard and daylight savings time for the same zone. Daylight savings time for a region can be represented by a second TTimeZone instance. For example, you might have two TTimeZone instances for the Pacific time zone, one for Pacific Standard Time and one for Pacific Daylight Time.