gcc/testsuite/objc-obj-c++-shared/GNUStep/Foundation/NSDate.h

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