PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSGregorianDate


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


Class Description


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 independent 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 between 1 and 12 that indicates the month.

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




Method Types


Constructors
NSGregorianDate
Retrieving date elements
dayOfCommonEra
dayOfMonth
dayOfWeek
dayOfYear
hourOfDay
microsecondOfSecond
minuteOfHour
monthOfYear
secondOfMinute
yearOfCommonEra
Adjusting a date
dateByAddingGregorianUnits
Computing date intervals
gregorianUnitsSinceDate
Comparing dates
equals
hashCode
isEqualToGregorianDate
Representing dates as Strings
toString
Getting the time zone
timeZone


Constructors



NSGregorianDate

public NSGregorianDate()

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

public NSGregorianDate(double seconds)

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. It sets the date's time zone to the default time zone.

public NSGregorianDate( double seconds, NSDate aDate)

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

public NSGregorianDate( double seconds, NSTimeZone aTimeZone)

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. It sets the date's time zone to aTimeZone.

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

Returns a Gregorian date initialized with the specified values for year, month, day, hour, minute, and second and the NSTimeZone object. 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.

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)

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.

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: gregorianUnitsSinceDate



dayOfCommonEra

public int dayOfCommonEra()

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, dayOfWeek, dayOfYear, hourOfDay, microsecondOfSecond, minuteOfHour, monthOfYear, secondOfMinute, yearOfCommonEra



dayOfMonth

public int dayOfMonth()

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

See Also: dayOfCommonEra, dayOfWeek, dayOfYear, hourOfDay, microsecondOfSecond, minuteOfHour, monthOfYear, secondOfMinute, yearOfCommonEra



dayOfWeek

public int dayOfWeek()

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

See Also: dayOfCommonEra, dayOfMonth, dayOfYear, hourOfDay, microsecondOfSecond, minuteOfHour, monthOfYear, secondOfMinute, yearOfCommonEra



dayOfYear

public int dayOfYear()

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

See Also: dayOfCommonEra, dayOfMonth, dayOfWeek, hourOfDay, microsecondOfSecond, minuteOfHour, monthOfYear, secondOfMinute, yearOfCommonEra



equals

public boolean equals(Object anObject)

Description forthcoming.

gregorianUnitsSinceDate

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

Computes the calendrical time difference between the receiver and date and returns it in years, months, days, hours, minutes, and seconds. 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: dateByAddingGregorianUnits



hashCode

public int hashCode()

Description forthcoming.

hourOfDay

public int hourOfDay()

Returns the hour value (0 through 23) of the receiver. 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: dayOfCommonEra, dayOfMonth, dayOfWeek, dayOfYear, microsecondOfSecond, minuteOfHour, monthOfYear, secondOfMinute, yearOfCommonEra



isEqualToGregorianDate

public boolean isEqualToGregorianDate(NSGregorianDate aGregorianDate)

Description forthcoming.

microsecondOfSecond

public int microsecondOfSecond()

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

See Also: dayOfCommonEra, dayOfMonth, dayOfWeek, dayOfYear, hourOfDay, minuteOfHour, monthOfYear, secondOfMinute, yearOfCommonEra



minuteOfHour

public int minuteOfHour()

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

See Also: dayOfCommonEra, dayOfMonth, dayOfWeek, dayOfYear, hourOfDay, microsecondOfSecond, monthOfYear, secondOfMinute, yearOfCommonEra



monthOfYear

public int monthOfYear()

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

See Also: dayOfCommonEra, dayOfMonth, dayOfWeek, dayOfYear, hourOfDay, microsecondOfSecond, minuteOfHour, secondOfMinute, yearOfCommonEra



secondOfMinute

public int secondOfMinute()

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

See Also: dayOfCommonEra, dayOfMonth, dayOfWeek, dayOfYear, hourOfDay, microsecondOfSecond, minuteOfHour, monthOfYear, yearOfCommonEra



timeZone

NSTimeZone timeZone()

Returns the time zone object associated with the receiver. 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

String toString()

Returns a string representation of the receiver.



yearOfCommonEra

public int 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).

See Also: dayOfCommonEra, dayOfMonth, dayOfWeek, dayOfYear, hourOfDay, microsecondOfSecond, minuteOfHour, monthOfYear, secondOfMinute




Table of Contents