1 /* Interface for NSDate for GNUStep
2 Copyright (C) 1994, 1996, 1999 Free Software Foundation, Inc.
3
4 This file is part of the GNUstep Base Library.
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Lesser General Public
8 License as published by the Free Software Foundation; either
9 version 2 of the License, or (at your option) any later version.
10
11 This library is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 Library General Public License for more details.
15
16 You should have received a copy of the GNU Lesser General Public
17 License along with this library; if not, write to the Free
18 Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
19 Boston, MA 02111 USA.
20 */
21
22 #ifndef __NSDate_h_GNUSTEP_BASE_INCLUDE
23 #define __NSDate_h_GNUSTEP_BASE_INCLUDE
24 #import "../GNUstepBase/GSVersionMacros.h"
25
26 #import "NSObjCRuntime.h"
27
28 #if defined(__cplusplus)
29 extern "C" {
30 #endif
31
32 GS_EXPORT NSString * const NSSystemClockDidChangeNotification;
33
34 /**
35 * Time interval difference between two dates, in seconds.
36 */
37 typedef double NSTimeInterval;
38
39 /**
40 * Time interval between the unix standard reference date of 1 January 1970
41 * and the OpenStep reference date of 1 January 2001<br />
42 * This number comes from:<br />
43 * (((31 years * 365 days) + 8 days for leap years) = total number of days<br />
44 * 24 hours * 60 minutes * 60 seconds)<br />
45 * This ignores leap-seconds.
46 */
47 GS_EXPORT const NSTimeInterval NSTimeIntervalSince1970;
48
49 #import "NSObject.h"
50
51 @class NSArray;
52 @class NSCalendarDate;
53 @class NSData;
54 @class NSDictionary;
55 @class NSString;
56 @class NSTimeZone;
57 @class NSTimeZoneDetail;
58
59 @interface NSDate : NSObject <NSCoding,NSCopying>
60 {
61 }
62
63 /** Returns an autoreleased instance with the current date/time.
64 */
65 + (id) date;
66
67 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
68 /** Returns an autoreleased instance representing the date and time given
69 * by string. The value of string may be a 'natural' specification as
70 * specified by the preferences in the user defaults database, allowing
71 * phrases like 'last tuesday'
72 */
73 + (id) dateWithNaturalLanguageString: (NSString*)string;
74
75 /**
76 * <p>Returns an autoreleased instance representing the date and time given
77 * by string. The value of string may be a 'natural' specification as
78 * specified by the preferences in the user defaults database, allowing
79 * phrases like 'last tuesday'
80 * </p>
81 * The locale contains keys such as -
82 * <deflist>
83 * <term>NSDateTimeOrdering</term>
84 * <desc>Controls the use of ambiguous numbers. This is done as a
85 * sequence of the letters D(ay), M(onth), Y(ear), and H(our).
86 * YMDH means that the first number encountered is assumed to be a
87 * year, the second a month, the third a day, and the last an hour.
88 * </desc>
89 * <term>NSEarlierTimeDesignations</term>
90 * <desc>An array of strings for times in the past.<br />
91 * Defaults are <em>ago</em>, <em>last</em>, <em>past</em>, <em>prior</em>
92 * </desc>
93 * <term>NSHourNameDesignations</term>
94 * <desc>An array of arrays of strings identifying the time of day.
95 * Each array has an hour as its first value, and one or more words
96 * as subsequent values.<br />
97 * Defaults are: (0, midnight), (10, morning), (12, noon, lunch),
98 * (14, afternoon), (19, dinner).
99 * </desc>
100 * <term>NSLaterTimeDesignations</term>
101 * <desc>An array of strings for times in the future.<br />
102 * Default is <em>next</em>
103 * </desc>
104 * <term>NSNextDayDesignations</term>
105 * <desc>The day after today. Default is <em>tomorrow.</em>
106 * </desc>
107 * <term>NSNextNextDayDesignations</term>
108 * <desc>The day after tomorrow. Default is <em>nextday.</em>
109 * </desc>
110 * <term>NSPriorDayDesignations</term>
111 * <desc>The day before today. Default is <em>yesterday.</em>
112 * </desc>
113 * <term>NSThisDayDesignations</term>
114 * <desc>Identifies the current day. Default is <em>today.</em>
115 * </desc>
116 * <term>NSYearMonthWeekDesignations</term>
117 * <desc>An array giving the word for year, month, and week.<br />
118 * Defaults are <em>year</em>, <em>month</em> and <em>week</em>.
119 * </desc>
120 * </deflist>
121 */
122 + (id) dateWithNaturalLanguageString: (NSString*)string
123 locale: (NSDictionary*)locale;
124 #endif
125
126 /** Returns an autoreleased instance with the date and time value given
127 * by the string using the ISO standard format YYYY-MM-DD HH:MM:SS +/-HHHMM
128 * (all the fields of which must be present).
129 */
130 + (id) dateWithString: (NSString*)description;
131
132 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6,GS_API_LATEST)
133 /** Returns an autoreleased NSDate instance whose value is offset from
134 * that of the given date by the specified interval in seconds.
135 */
136 + (id) dateWithTimeInterval: (NSTimeInterval)seconds sinceDate: (NSDate*)date;
137 #endif
138
139 /** Returns an autoreleased instance with the offset from the unix system
140 * reference date of 1 January 1970, GMT.
141 */
142 + (id) dateWithTimeIntervalSince1970: (NSTimeInterval)seconds;
143
144 /** Returns an autoreleased instance with the offset from the current
145 * date/time given by seconds (which may be fractional).
146 */
147 + (id) dateWithTimeIntervalSinceNow: (NSTimeInterval)seconds;
148
149 /** Returns an autoreleased instance with the offset from the OpenStep
150 * reference date of 1 January 2001, GMT.
151 */
152 + (id) dateWithTimeIntervalSinceReferenceDate: (NSTimeInterval)seconds;
153
154 /** Returns an autoreleased instance with the date/time set in the far
155 * past.
156 */
157 + (id) distantPast;
158
159 /** Returns an autoreleased instance with the date/time set in the far
160 * future.
161 */
162 + (id) distantFuture;
163
164 /** Returns the time interval between the reference date and the current
165 * time.
166 */
167 + (NSTimeInterval) timeIntervalSinceReferenceDate;
168
169 /** Returns an autorelease date instance formed by adding the specified
170 * time interval in seconds to the receiver's time interval.
171 */
172 - (id) addTimeInterval: (NSTimeInterval)seconds;
173
174 /** Returns the time interval between the receivers value and the
175 * OpenStep reference date of 1 Jan 2001 GMT.
176 */
177 - (NSComparisonResult) compare: (NSDate*)otherDate;
178
179 #if OS_API_VERSION(MAC_OS_X_VERSION_10_6,GS_API_LATEST)
180 /** Returns an autoreleased NSDate instance whose value is offset from
181 * that of the receiver by the specified interval.
182 */
183 - (id) dateByAddingTimeInterval: (NSTimeInterval)ti;
184 #endif
185
186 /** Returns an autoreleased instance of the [NSCalendarDate] class whose
187 * date/time value is the same as that of the receiver, and which uses
188 * the formatString and timeZone specified.
189 */
190 - (NSCalendarDate*) dateWithCalendarFormat: (NSString*)formatString
191 timeZone: (NSTimeZone*)timeZone;
192
193 /** Returns a string representation of the receiver formatted according
194 * to the default format string, time zone, and locale.
195 */
196 - (NSString*) description;
197
198 /** Returns a string representation of the receiver formatted according
199 * to the specified format string, time zone, and locale.
200 */
201 - (NSString*) descriptionWithCalendarFormat: (NSString*)format
202 timeZone: (NSTimeZone*)aTimeZone
203 locale: (NSDictionary*)l;
204
205 /** Returns a string representation of the receiver formatted according
206 * to the default format string and time zone, but using the given locale.
207 */
208 - (NSString*) descriptionWithLocale: (id)locale;
209
210 /** Returns the earlier of the receiver and otherDate.<br />
211 * If the two represent identical date/time values, returns the receiver.
212 */
213 - (NSDate*) earlierDate: (NSDate*)otherDate;
214
215 /** Returns an instance initialised with the current date/time.
216 */
217 - (id) init;
218
219 /** Returns an instance with the date and time value given
220 * by the string using the ISO standard format YYYY-MM-DD HH:MM:SS +/-HHHMM
221 * (all the fields of which must be present).
222 */
223 - (id) initWithString: (NSString*)description;
224
225 /** Returns an instance with the given offset from anotherDate.
226 */
227 - (id) initWithTimeInterval: (NSTimeInterval)secsToBeAdded
228 sinceDate: (NSDate*)anotherDate;
229
230 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
231 /** Returns an instance with the offset from the unix system
232 * reference date of 1 January 1970, GMT.
233 */
234 - (id) initWithTimeIntervalSince1970: (NSTimeInterval)seconds;
235 #endif
236
237 /** Returns an instance with the offset from the current date/time.
238 */
239 - (id) initWithTimeIntervalSinceNow: (NSTimeInterval)secsToBeAdded;
240
241 /** <init />
242 * Returns an instance with the given offset from the OpenStep
243 * reference date of 1 January 2001, GMT.
244 */
245 - (id) initWithTimeIntervalSinceReferenceDate: (NSTimeInterval)secs;
246
247 /** Returns NO if other is not a date, otherwise returns the result of
248 * calling the -isEqualtoDate: method.
249 */
250 - (BOOL) isEqual: (id)other;
251
252 /** Returns whether the receiver is exactly equal to other, to the limit
253 * of the NSTimeInterval precision.<br />
254 * This is the behavior of the current MacOS-X system, not that of the
255 * OpenStep specification (which counted two dates within a second of
256 * each other as being equal).<br />
257 * The old behavior meant that two dates equal to a third date were not
258 * necessarily equal to each other (confusing), and meant that there was
259 * no reasonable way to use a date as a dictionary key or store dates
260 * in a set.
261 */
262 - (BOOL) isEqualToDate: (NSDate*)other;
263
264 /** Returns the earlier of the receiver and otherDate.<br />
265 * If the two represent identical date/time values, returns the receiver.
266 */
267 - (NSDate*) laterDate: (NSDate*)otherDate;
268
269 /** Returns the time interval between the receivers value and the
270 * unix system reference date of 1 January 1970, GMT.
271 */
272 - (NSTimeInterval) timeIntervalSince1970;
273
274 /** Returns the time interval between the receivers value and that of the
275 * otherDate argument. If otherDate is earlier than the receiver, the
276 * returned value will be positive, if it is later it will be negative.<br />
277 * For current (2011) OSX compatibility, this method returns NaN if otherDate
278 * is nil ... do not write code depending on that behavior.
279 */
280 - (NSTimeInterval) timeIntervalSinceDate: (NSDate*)otherDate;
281
282 /** Returns the time interval between the receivers value and the
283 * current date/time. If the receiver represents a date/time in
284 * the past this will be negative, if it is in the future the
285 * returned value will be positive.
286 */
287 - (NSTimeInterval) timeIntervalSinceNow;
288
289 /** Returns the time interval between the receivers value and the
290 * OpenStep reference date of 1 Jan 2001 GMT.
291 */
292 - (NSTimeInterval) timeIntervalSinceReferenceDate;
293
294 @end
295
296 #if defined(__cplusplus)
297 }
298 #endif
299
300 #endif /* __NSDate_h_GNUSTEP_BASE_INCLUDE*/