| 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*/ |