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