---

NSGregorianDateFormatter

Overview

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.”

With Mac OS X version 10.4 and later, NSGregorianDateFormatter has two modes of operation (or behaviors). By default, instances of NSGregorianDateFormatter have the same behavior as they did on Mac OS X versions 10.0 to 10.3. You can, however, configure instances (or set a default for all instances) to adopt a new behavior implemented for Mac OS X version 10.4. See Data Formatting for a full description of the old and new behaviors.

Tasks

Constructors

• NSGregorianDateFormatter

Getting Behavior

• allowsNaturalLanguage

Getting and Setting Attributes

• dateFormat

String Manipulation

• attributedStringForObjectValue
• isPartialStringValid
• objectValueForString
• replacementStringForString
• stringForObjectValue

Instance Methods

allowsNaturalLanguage

Returns true if the receiver attempts to process dates entered as a vernacular string (“today,” “day before yesterday,” and so on).

public boolean allowsNaturalLanguage()

Discussion

Returns false if the receiver does not do any natural-language processing of these date expressions.

attributedStringForObjectValue

Returns an NSAttributedString if the string for display should have some attributes.

public NSAttributedString attributedStringForObjectValue(Object anObject, NSDictionary attributes)

Discussion

For instance, you might want past dates to appear in red text. Invoke your implementation of stringForObjectValue to get the nonattributed string. Then create an NSAttributedString with it. The default attributes for text in the cell are passed in with attributes; use this NSDictionary to reset the attributes of the string when a change in value warrants it (for example, a negative value becomes positive). If an NSAttributedString cannot be created for anObject, an NSFormatter.FormattingException is thrown. For information on creating attributed strings, see the NSAttributedString class.

dateFormat

Returns the date format string used by the receiver.

public String dateFormat()

Discussion

See “The Calendar Format” for a list of the conversion specifiers permitted in date format strings.

isPartialStringValid

Since this method is invoked each time the user presses a key while the cell has the keyboard focus, it lets you verify the cell text as the user types it. partialString is the text currently in the cell.

public boolean isPartialStringValid(String partialString)

Discussion

Return true if partialString is acceptable and false if it is not. If you return false, the cell displays partialString minus the last character typed.

See Also

• replacementStringForString

objectValueForString

Returns an object you’ve created from aString.

public Object objectValueForString(String aString)

Discussion

If an object cannot be created from aString, an NSFormatter.ParsingException is thrown.

See Also

• stringForObjectValue

replacementStringForString

Checks whether aString is a valid string for the cell.

public String replacementStringForString(String aString)

Discussion

If it is, returns it unmodified. Otherwise, corrects it and returns the modified string. For example, you might convert all lowercase letters to uppercase or insert different separator characters in a date.

See Also

• isPartialStringValid

stringForObjectValue

Returns the string that textually represents the cell’s object for display and for editing.

public String stringForObjectValue(Object anObject)

Discussion

First tests the passed-in object to see if it’s of the correct class. If it isn’t, returns null; if it is of the right class, returns a properly formatted and, if necessary, localized string. If a string cannot be created for anObject, an NSFormatter.FormattingException is thrown.

See Also

• attributedStringForObjectValue
• objectValueForString

Constants

The following constants specify predefined date and time format styles.The format for these date and time styles is not exact because they depend on the locale, user preference settings, and the operating system version. Do not use these constants if you want an exact format.

Date and Time Format Styles

NSDateFormatterNoStyle

Specifies no style. Equal to kCFDateFormatterNoStyle. Available in Mac OS X version 10.4 and later.

NSDateFormatterShortStyle

Specifies a short style, typically numeric only, such as “11/23/37” or “3:30pm”. Equal to kCFDateFormatterShortStyle. Available in Mac OS X version 10.4 and later.

NSDateFormatterMediumStyle

Specifies a medium style, typically with abbreviated text, such as “Nov 23, 1937”. Equal to kCFDateFormatterMediumStyle. Available in Mac OS X version 10.4 and later.

NSDateFormatterLongStyle

Specifies a long style, typically with full text, such as “November 23, 1937” or “3:30:32pm”. Equal to kCFDateFormatterLongStyle. Available in Mac OS X version 10.4 and later.

NSDateFormatterFullStyle

Specifies a full style with complete details, such as “Tuesday, April 12, 1952 AD” or “3:30:42pm PST”. Equal to kCFDateFormatterFullStyle. Available in Mac OS X version 10.4 and later.

Date Formatter Behavior

NSDateFormatterBehaviorDefault

Specifies default formatting behavior.

NSDateFormatterBehavior10_0

Specifies formatting behavior equivalent to that in Mac OS X 10.0.

NSDateFormatterBehavior10_4

Specifies formatting behavior equivalent for Mac OS X 10.4.

---