PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSGregorianDateFormatter


Inherits from:
NSFormatter : NSObject
Package:
com.apple.yellow.foundation


Class Description


Instances of NSGregorianDateFormatter format the textual representation of cells that contain NSDates (including NSGregorianDates), and convert textual representations of dates and times into NSDates. You can express the representation of dates and times very flexibly: "Thu 22 Dec 1994" is just as acceptable as "12/22/94". With natural-language processing for dates enabled, users can also express dates colloquially, such as "today," "day after tomorrow," and "a month from today."

To use an NSGregorianDateFormatter, create an instance of it with NSGregorianDateFormatter. Then use NSCell's setFormatter method to associate the NSGregorianDateFormatter object with a cell. The value of a cell (NSCell) is represented by an object, typically an NSDate object in this case. When this value needs to be displayed or edited, the cell passes its object to the NSGregorianDateFormatter instance, which returns the formatted string. When the user enters a string, or when one is programmatically written in a cell (using setStringValue), the cell obtains the equivalent NSDate object from the NSGregorianDateFormatter.

NSControl provides delegation methods that permit you to validate cell contents and to handle errors in formatting. See the specification of the NSFormatter class for details.

When a cell with a NSGregorianDateFormatter is copied, the new cell retains the NSGregorianDateFormatter object instead of copying it. You remove an NSGregorianDateFormatter from a cell by specifying null as the argument of setFormatter.

Instances of NSGregorianDateFormatter are immutable.


The Calendar Format


You must specify a format whenever you create a NSGregorianDateFormatter. This format is a string that contains specifiers that are very similar to those used in the standard C library function strftime(). When NSGregorianDateFormatter converts a date to a string, it uses this format.

The date conversion specifiers cover a range of date conventions:


Specifier Description
%% a '%' character
%a abbreviated weekday name
%A full weekday name
%b abbreviated month name
%B full month name
%c shorthand for "%X %x", the locale format for date and time
%d day of the month as a decimal number (01-31)
%e same as %d but does not print the leading 0 for days 1 through 9
%F milliseconds as a decimal number (000-999)
%H hour based on a 24-hour clock as a decimal number (00-23)
%I hour based on a 12-hour clock as a decimal number (01-12)
%j day of the year as a decimal number (001-366)
%m month as a decimal number (01-12)
%M minute as a decimal number (00-59)
%p AM/PM designation for the locale
%S second as a decimal number (00-59)
%w weekday as a decimal number (0-6), where Sunday is 0
%x date using the date representation for the locale
%X time using the time representation for the locale
%y year without century (00-99)
%Y year with century (such as 1990)
%Z time zone name (such as Pacific Daylight Time)
%z time zone offset in hours and minutes from GMT (HHMM)




Method Types


Constructors
NSGregorianDateFormatter
Determining attributes
allowsNaturalLanguage
dateFormat
String manipulation
attributedStringForObjectValue
isPartialStringValid
objectValueForString
replacementStringForString
stringForObjectValue


Constructors



NSGregorianDateFormatter

public NSGregorianDateFormatter()

Description forthcoming.

public NSGregorianDateFormatter( String format, boolean naturalLanguageFlag)

Creates an NSGregorianDateFormatter instance that uses the date format in its conversions. See "The Calendar Format" for a list of conversion specifiers permitted in date format strings. Set naturalLanguageFlag to true if you want the NSGregorianDateFormatter to process dates entered as expressions in the vernacular (for example, "tomorrow"); NSGregorianDateFormatter attempts natural-language processing only after it fails to interpret an entered string according to format.




Instance Methods



allowsNaturalLanguage

public boolean allowsNaturalLanguage()

Returns true if the NSGregorianDateFormatter attempts to process dates entered as a vernacular string ("today," "day before yesterday," and so on). Returns false if the NSGregorianDateFormatter does not do any natural-language processing of these date expressions.



attributedStringForObjectValue

public NSAttributedString attributedStringForObjectValue( Object anObject, NSDictionary aDictionary)

Description forthcoming. Throws NSFormatter.FormattingException.

dateFormat

public String dateFormat()

Returns the date format string used by an NSGregorianDateFormatter object. See "The Calendar Format" for a list of the conversion specifiers permitted in date format strings.



isPartialStringValid

public boolean isPartialStringValid(String aString)

Description forthcoming.

objectValueForString

public Object objectValueForString(String aString)

Description forthcoming. Throws NSFormatter.ParsingException

replacementStringForString

public String replacementStringForString(String aString)

Description forthcoming.

stringForObjectValue

public String stringForObjectValue(Object anObject)

Description forthcoming. Throws NSFormatter.FormattingException


Table of Contents