ADC Home > Reference Library > Reference > Legacy Documents > Cocoa > Foundation Reference for Java (Legacy) >

Next Page > Hide TOC

Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

NSGregorianDate

Inherits from
Implements
Package
com.apple.cocoa.foundation
Companion guides

Overview

NSGregorianDate is a public subclass of NSDate that represents concrete date objects and performs date computations based on the Gregorian calendar. These objects associate a time interval with a time zone and are especially suited for representing and manipulating dates according to western calendrical systems. NSGregorianDates are immutable objects.

An NSGregorianDate object stores a date as the number of seconds relative to the absolute reference date (the first instance of 1 January 2001, GMT). Use the associated time zone to change how the NSGregorianDate object prints its time interval. The time zone does not change how the time interval is stored. Because the value is stored independently of the time zone, you can accurately compare NSGregorianDates with any other NSDate objects or use them to create other NSDate objects. It also means that you can track a date across different time zones; that is, you can create a new NSGregorianDate object with a different time zone to see how the particular date is represented in that time zone.

To retrieve conventional elements of an NSGregorianDate object, use the ...Of... methods. For example, dayOfWeek returns a number that indicates the day of the week (0 is Sunday). The monthOfYear method returns a number from 1 through 12 that indicates the month.

To format a date as a string or to parse a date from a string, use an NSGregorianDateFormatter.

Tasks

Constructors

Retrieving Date Elements

Adjusting a Date

Computing Date Intervals

Comparing Dates

Representing Dates as Strings

Getting the Time Zone

Constructors

NSGregorianDate

public NSGregorianDate()

Discussion

Creates a new Gregorian date initialized to the current date and time.

public NSGregorianDate(double seconds)

Discussion

Creates a new Gregorian date initialized to the absolute reference date (the first instant of 1 January 2001, GMT) plus seconds, which may be positive or negative. This constructor sets the date’s time zone to the default time zone.

public NSGregorianDate(double seconds, NSDate aDate)

Discussion

Creates a new Gregorian date initialized to aDate plus seconds, which may be positive or negative. This constructor sets the date’s time zone to the default time zone.

public NSGregorianDate(double seconds, NSTimeZone aTimeZone)

Discussion

Creates a new Gregorian date initialized to the absolute reference date (the first instant of 1 January 2001, GMT) plus seconds, which may be positive or negative. This constructor sets the date’s time zone to aTimeZone.

public NSGregorianDate(int year, int month, int day, int hour, int minute, int second, NSTimeZone aTimeZone)

Discussion

Creates a new Gregorian date with the specified values for year, month, day, hour, minute, second, and time zone, aTimeZone. The year value must include the century (for example, 1995 instead of 95). The other values are the standard ones: 1 through 12 for months, 1 through 31 for days, 0 through 23 for hours, and 0 through 59 for both minutes and seconds.

On days when daylight savings “falls back,” there are two 1:30 AMs. If you use this method there is no way to create the second 1:30 AM. Instead, you should create the first and then use dateByAddingGregorianUnits to add an hour.

The following code fragment shows a Gregorian date created for 4 July 1994, 9 PM, eastern standard time:

NSGregorianDate fireworks = new NSGregorianDate(1994, 7, 4, 21,  0, 0,
        new NSTimeZone("EST", true));

Instance Methods

dateByAddingGregorianUnits

public NSGregorianDate dateByAddingGregorianUnits(int year, int month, int day, int hour, int minute, int second)

Discussion

Returns a Gregorian date that is updated with the year, month, day, hour, minute, and second offsets specified as arguments. The offsets can be positive (future) or negative (past).

This method preserves “clock time” across changes in daylight savings time zones and leap years. For example, adding one month to a Gregorian date with a time of 12 noon correctly maintains time at 12 noon. One thing to be aware of is if you add one day to 2:30 AM on the day before daylight savings “springs ahead,” it will actually result in 1:30 AM on the next day (which is one day, or 24 hours, later).

Note that the arguments are applied in a left-to-right order: year first, then month, then day, and so on. So, adding one month, four days to 27 April results in 31 May, not 1 June.

The following code fragment shows a Gregorian date created with a date a week later than an existing Gregorian date:

NSCalendarDate now = new NSGregorianDate();
NSCalendarDate nextWeek =
    now.dateByAddingGregorianUnits(0, 0, 7, 0, 0, 0);
See Also

dayOfCommonEra

public int dayOfCommonEra()

Discussion

Returns the number of days since the beginning of the Common Era. The base year of the Common Era is 1 C.E. (which is the same as 1 A.D.).

See Also

dayOfMonth

Returns a number that indicates the day of the month (1 through 31) of the receiver.

public int dayOfMonth()

See Also

dayOfWeek

Returns a number that indicates the day of the week (0 through 6) of the receiver; 0 indicates Sunday.

public int dayOfWeek()

See Also

dayOfYear

Returns a number that indicates the day of the year (1 through 366) of the receiver.

public int dayOfYear()

See Also

equals

Returns true if anObject is an instance of NSGregorianDate and satisfies isEqualToGregorianDate.

public boolean equals(Object anObject)

Discussion

Returns false otherwise.

gregorianUnitsSinceDate

Computes the calendrical time difference between the receiver and date and returns it in years, months, days, hours, minutes, and seconds.

public void gregorianUnitsSinceDate(NSGregorianDate date, NSGregorianDate.IntRef years, NSGregorianDate.IntRef months, NSGregorianDate.IntRef days, NSGregorianDate.IntRef hours, NSGregorianDate.IntRef minutes, NSGregorianDate.IntRef seconds)

Discussion

NSGregorianDate.IntRef is a local class that contains a single element: the integer value.

You can choose any representation you wish for the time difference by passing null for the arguments you want to ignore. For example, the following code fragment computes the difference in months, days, and years between two dates:

NSGregorianDate momsBDay =
    new NSGregorianDate(1936, 1, 8, 7, 30, 0, new NSTimeZone("EST",  true));
NSGregorianDate dateOfBirth =
    new NSGregorianDate(1965, 12, 7, 17, 25, 0, new NSTimeZone("EST",  true));
 
NSGregorianDate.IntRef years = new NSGregorianDate.IntRef();
NSGregorianDate.IntRef months = new NSGregorianDate.IntRef();
NSGregorianDate.IntRef days = new NSGregorianDate.IntRef();
 
dateOfBirth.gregorianUnitsSinceDate(momsBDay, years, months, days,
    null, null, null)

This message returns 29 years, 10 months, and 29 days. If you want to express the years in terms of months, you pass null for the years argument:

dateOfBirth.gregorianUnitsSinceDate(momsBDay, null, months, days,
    null, null, null);

This message returns 358 months and 29 days.

See Also

hashCode

Returns a hash value for the receiver.

public int hashCode()

Discussion

The hash value is the integer value of the time interval returned from timeIntervalSinceReferenceDate (NSDate).

hourOfDay

Returns the hour value (0 through 23) of the receiver.

public int hourOfDay()

Discussion

On daylight savings “fall back” days, a value of 1 is returned for two consecutive hours, but with a different time zone (the first in daylight savings time and the second in standard time).

See Also

isEqualToGregorianDate

Returns true if the receiver and aGregorianDate represent the same date and have the same time zone set.

public boolean isEqualToGregorianDate(NSGregorianDate aGregorianDate)

Discussion

Returns false otherwise.

microsecondOfSecond

Returns the microseconds value (0 through 999,999) of the receiver.

public int microsecondOfSecond()

See Also

minuteOfHour

Returns the minutes value (0 through 59) of the receiver.

public int minuteOfHour()

See Also

monthOfYear

Returns a number that indicates the month of the year (1 through 12) of the receiver.

public int monthOfYear()

See Also

secondOfMinute

Returns the seconds value (0 through 59) of the receiver.

public int secondOfMinute()

See Also

timeZone

Returns the time zone object associated with the receiver.

NSTimeZone timeZone()

Discussion

You can explicitly set the time zone to an NSTimeZone object using a constructor that takes an NSTimeZone object as an argument. If you do not specify a time zone for an object at initialization time, NSGregorianDate uses the default time zone for the locale.

toString

Returns a string representation of the receiver.

String toString()

yearOfCommonEra

Returns a number that indicates the year, including the century, of the receiver (for example, 1995). The base year of the Common Era is 1 C.E. (which is the same as 1 A.D.).

public int yearOfCommonEra()

See Also


Next Page > Hide TOC

© 1997, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.