mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-23 00:41:02 +00:00
Documented the class.
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@15537 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-Macdonald
parent
737d9b20cd
commit
50139c4bc0
1 changed files with 270 additions and 56 deletions
|
|
@ -274,6 +274,11 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
|
||||
@class NSGDate;
|
||||
|
||||
/**
|
||||
* An [NSDate] subclass which understands about timezones and provides
|
||||
* methods for dealing with date and time information by calendar and
|
||||
* with hours minutes and seconds.
|
||||
*/
|
||||
@implementation NSCalendarDate
|
||||
|
||||
+ (void) initialize
|
||||
|
|
@ -307,7 +312,8 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
}
|
||||
|
||||
/**
|
||||
* Getting an NSCalendar Date
|
||||
* Return an NSCalendarDate for the current date and time using the
|
||||
* default timezone.
|
||||
*/
|
||||
+ (id) calendarDate
|
||||
{
|
||||
|
|
@ -316,6 +322,11 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
return AUTORELEASE(d);
|
||||
}
|
||||
|
||||
/**
|
||||
* Return an NSCalendarDate generated from the supplied description
|
||||
* using the format specified for parsing that string.<br />
|
||||
* Calls -initWithString:calendarFormat: to create the date.
|
||||
*/
|
||||
+ (id) dateWithString: (NSString *)description
|
||||
calendarFormat: (NSString *)format
|
||||
{
|
||||
|
|
@ -324,6 +335,12 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
return AUTORELEASE(d);
|
||||
}
|
||||
|
||||
/**
|
||||
* Return an NSCalendarDate generated from the supplied description
|
||||
* using the format specified for parsing that string and interpreting
|
||||
* it according to the dictionary specified.<br />
|
||||
* Calls -initWithString:calendarFormat:locale: to create the date.
|
||||
*/
|
||||
+ (id) dateWithString: (NSString *)description
|
||||
calendarFormat: (NSString *)format
|
||||
locale: (NSDictionary *)dictionary
|
||||
|
|
@ -334,6 +351,10 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
return AUTORELEASE(d);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates and returns an NSCalendarDate from the specified values
|
||||
* by calling -initWithYear:month:day:hour:minute:second:timeZone:
|
||||
*/
|
||||
+ (id) dateWithYear: (int)year
|
||||
month: (unsigned int)month
|
||||
day: (unsigned int)day
|
||||
|
|
@ -352,6 +373,10 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
return AUTORELEASE(d);
|
||||
}
|
||||
|
||||
/**
|
||||
* Creates and returns a new NSCalendarDate object by taking the
|
||||
* value of the receiver and adding the interval in seconds specified.
|
||||
*/
|
||||
- (id) addTimeInterval: (NSTimeInterval)seconds
|
||||
{
|
||||
id newObj = [[self class] dateWithTimeIntervalSinceReferenceDate:
|
||||
|
|
@ -396,8 +421,10 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
[super dealloc];
|
||||
}
|
||||
|
||||
/*
|
||||
* Initializing an NSCalendar Date
|
||||
/**
|
||||
* Initializes an NSCalendarDate using the specified description and the
|
||||
* default calendar format and locale.<br />
|
||||
* Calls -initWithString:calendarFormat:locale:
|
||||
*/
|
||||
- (id) initWithString: (NSString *)description
|
||||
{
|
||||
|
|
@ -407,6 +434,11 @@ GSBreakTime(NSTimeInterval when, int *year, int *month, int *day,
|
|||
locale: nil];
|
||||
}
|
||||
|
||||
/**
|
||||
* Initializes an NSCalendarDate using the specified description and format
|
||||
* string interpreted in the default locale.<br />
|
||||
* Calls -initWithString:calendarFormat:locale:
|
||||
*/
|
||||
- (id) initWithString: (NSString *)description
|
||||
calendarFormat: (NSString *)format
|
||||
{
|
||||
|
|
@ -458,6 +490,88 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
#define hads 32
|
||||
#define hadw 64
|
||||
|
||||
/**
|
||||
* Initializes an NSCalendarDate using the specified description and format
|
||||
* string interpreted in the given locale.<br />
|
||||
* Format specifiers are -
|
||||
* <list>
|
||||
* <item>
|
||||
* %% literal % character
|
||||
* </item>
|
||||
* <item>
|
||||
* %a abbreviated weekday name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %A full weekday name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %b abbreviated month name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %B full month name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %c same as '%X %x'
|
||||
* </item>
|
||||
* <item>
|
||||
* %d day of month as decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %e same as %d without leading zero (you get a leading space instead)
|
||||
* </item>
|
||||
* <item>
|
||||
* %F milliseconds as a decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %H hour as a decimal number using 24-hour clock
|
||||
* </item>
|
||||
* <item>
|
||||
* %I hour as a decimal number using 12-hour clock
|
||||
* </item>
|
||||
* <item>
|
||||
* %j day of year as a decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %m month as decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %M minute as decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %p 'am' or 'pm'
|
||||
* </item>
|
||||
* <item>
|
||||
* %S second as decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %U week of the current year as decimal number (Sunday first day)
|
||||
* </item>
|
||||
* <item>
|
||||
* %W week of the current year as decimal number (Monday first day)
|
||||
* </item>
|
||||
* <item>
|
||||
* %w day of the week as decimal number (Sunday = 0)
|
||||
* </item>
|
||||
* <item>
|
||||
* %x date with date representation for locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %X time with time representation for locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %y year as a decimal number without century
|
||||
* </item>
|
||||
* <item>
|
||||
* %Y year as a decimal number with century
|
||||
* </item>
|
||||
* <item>
|
||||
* %z time zone offset in hours and minutes from GMT (HHMM)
|
||||
* </item>
|
||||
* <item>
|
||||
* %Z time zone abbreviation
|
||||
* </item>
|
||||
* </list>
|
||||
*/
|
||||
- (id) initWithString: (NSString *)description
|
||||
calendarFormat: (NSString *)fmt
|
||||
locale: (NSDictionary *)locale
|
||||
|
|
@ -623,33 +737,6 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
// -Long day and month names depend on a non-alpha character after the
|
||||
// last digit to work.
|
||||
//
|
||||
// The strftime specifiers as used by OpenStep + %U.
|
||||
//
|
||||
// %% literal % character
|
||||
// %a abbreviated weekday name according to locale
|
||||
// %A full weekday name according to locale
|
||||
// %b abbreviated month name according to locale
|
||||
// %B full month name according to locale
|
||||
// %c same as '%X %x'
|
||||
// %d day of month as decimal number
|
||||
// %e same as %d without leading zero (you get a leading space instead)
|
||||
// %F milliseconds as a decimal number
|
||||
// %H hour as a decimal number using 24-hour clock
|
||||
// %I hour as a decimal number using 12-hour clock
|
||||
// %j day of year as a decimal number
|
||||
// %m month as decimal number
|
||||
// %M minute as decimal number
|
||||
// %p 'am' or 'pm'
|
||||
// %S second as decimal number
|
||||
// %U week of the current year as decimal number (Sunday first day)
|
||||
// %W week of the current year as decimal number (Monday first day)
|
||||
// %w day of the week as decimal number (Sunday = 0)
|
||||
// %x date with date representation for locale
|
||||
// %X time with time representation for locale
|
||||
// %y year as a decimal number without century
|
||||
// %Y year as a decimal number with century
|
||||
// %z time zone offset in hours and minutes from GMT (HHMM)
|
||||
// %Z time zone abbreviation
|
||||
|
||||
while (formatIdx < formatLen)
|
||||
{
|
||||
|
|
@ -1231,6 +1318,10 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return self;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the day number (ie number of days since the start of) in the
|
||||
* 'common' era of the receiving date. The era starts at 1 A.D.
|
||||
*/
|
||||
- (int) dayOfCommonEra
|
||||
{
|
||||
NSTimeInterval when;
|
||||
|
|
@ -1239,6 +1330,9 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return dayOfCommonEra(when);
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the month (1 to 31) of the receiving date.
|
||||
*/
|
||||
- (int) dayOfMonth
|
||||
{
|
||||
int m, d, y;
|
||||
|
|
@ -1250,6 +1344,18 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return d;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the day of the week (0 to 6) of the receiving date.
|
||||
* <list>
|
||||
* <item>0 is sunday</item>
|
||||
* <item>1 is monday</item>
|
||||
* <item>2 is tuesday</item>
|
||||
* <item>3 is wednesday</item>
|
||||
* <item>4 is thursday</item>
|
||||
* <item>5 is friday</item>
|
||||
* <item>6 is saturday</item>
|
||||
* </list>
|
||||
*/
|
||||
- (int) dayOfWeek
|
||||
{
|
||||
int d;
|
||||
|
|
@ -1268,6 +1374,9 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return d;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the day of the year (1 to 366) of the receiving date.
|
||||
*/
|
||||
- (int) dayOfYear
|
||||
{
|
||||
int m, d, y, days, i;
|
||||
|
|
@ -1282,6 +1391,9 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return days;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the hour of the day (0 to 23) of the receiving date.
|
||||
*/
|
||||
- (int) hourOfDay
|
||||
{
|
||||
int h;
|
||||
|
|
@ -1304,6 +1416,9 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return h;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the minute of the hour (0 to 59) of the receiving date.
|
||||
*/
|
||||
- (int) minuteOfHour
|
||||
{
|
||||
int h, m;
|
||||
|
|
@ -1325,6 +1440,9 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return m;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the month of the year (1 to 12) of the receiving date.
|
||||
*/
|
||||
- (int) monthOfYear
|
||||
{
|
||||
int m, d, y;
|
||||
|
|
@ -1336,6 +1454,9 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return m;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the second of the minute (0 to 59) of the receiving date.
|
||||
*/
|
||||
- (int) secondOfMinute
|
||||
{
|
||||
int h, m, s;
|
||||
|
|
@ -1360,6 +1481,10 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return s;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the year of the 'common' era of the receiving date.
|
||||
* The era starts at 1 A.D.
|
||||
*/
|
||||
- (int) yearOfCommonEra
|
||||
{
|
||||
int m, d, y;
|
||||
|
|
@ -1397,12 +1522,90 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return [self descriptionWithCalendarFormat: _calendar_format locale: nil];
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a string representation of the receiver using the specified
|
||||
* format string.<br />
|
||||
* Calls -descriptionWithCalendarFormat:locale: with a nil locale.
|
||||
*/
|
||||
- (NSString*) descriptionWithCalendarFormat: (NSString *)format
|
||||
{
|
||||
return [self descriptionWithCalendarFormat: format locale: nil];
|
||||
}
|
||||
|
||||
#define UNIX_REFERENCE_INTERVAL -978307200.0
|
||||
/**
|
||||
* Returns a string representation of the receiver using the specified
|
||||
* format string and locale dictionary.<br />
|
||||
* Format specifiers are -
|
||||
* <list>
|
||||
* <item>
|
||||
* %a abbreviated weekday name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %A full weekday name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %b abbreviated month name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %B full month name according to locale
|
||||
* </item>
|
||||
* <item>
|
||||
* %d day of month as decimal number (leading zero)
|
||||
* </item>
|
||||
* <item>
|
||||
* %e day of month as decimal number (leading space)
|
||||
* </item>
|
||||
* <item>
|
||||
* %F milliseconds (000 to 999)
|
||||
* </item>
|
||||
* <item>
|
||||
* %H hour as a decimal number using 24-hour clock
|
||||
* </item>
|
||||
* <item>
|
||||
* %I hour as a decimal number using 12-hour clock
|
||||
* </item>
|
||||
* <item>
|
||||
* %j day of year as a decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %m month as decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %M minute as decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %p 'am' or 'pm'
|
||||
* </item>
|
||||
* <item>
|
||||
* %S second as decimal number
|
||||
* </item>
|
||||
* <item>
|
||||
* %U week of the current year as decimal number (Sunday first day)
|
||||
* </item>
|
||||
* <item>
|
||||
* %W week of the current year as decimal number (Monday first day)
|
||||
* </item>
|
||||
* <item>
|
||||
* %w day of the week as decimal number (Sunday = 0)
|
||||
* </item>
|
||||
* <item>
|
||||
* %y year as a decimal number without century
|
||||
* </item>
|
||||
* <item>
|
||||
* %Y year as a decimal number with century
|
||||
* </item>
|
||||
* <item>
|
||||
* %z time zone offset (HHMM)
|
||||
* </item>
|
||||
* <item>
|
||||
* %Z time zone
|
||||
* </item>
|
||||
* <item>
|
||||
* %% literal % character
|
||||
* </item>
|
||||
* </list>
|
||||
*/
|
||||
- (NSString*) descriptionWithCalendarFormat: (NSString*)format
|
||||
locale: (NSDictionary*)locale
|
||||
{
|
||||
|
|
@ -1432,30 +1635,6 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
&yd, &md, &dom, &hd, &mnd, &sd, &mil);
|
||||
nhd = hd;
|
||||
|
||||
// The strftime specifiers
|
||||
// %a abbreviated weekday name according to locale
|
||||
// %A full weekday name according to locale
|
||||
// %b abbreviated month name according to locale
|
||||
// %B full month name according to locale
|
||||
// %d day of month as decimal number (leading zero)
|
||||
// %e day of month as decimal number (leading space)
|
||||
// %F milliseconds (000 to 999)
|
||||
// %H hour as a decimal number using 24-hour clock
|
||||
// %I hour as a decimal number using 12-hour clock
|
||||
// %j day of year as a decimal number
|
||||
// %m month as decimal number
|
||||
// %M minute as decimal number
|
||||
// %p 'am' or 'pm'
|
||||
// %S second as decimal number
|
||||
// %U week of the current year as decimal number (Sunday first day)
|
||||
// %W week of the current year as decimal number (Monday first day)
|
||||
// %w day of the week as decimal number (Sunday = 0)
|
||||
// %y year as a decimal number without century
|
||||
// %Y year as a decimal number with century
|
||||
// %z time zone offset (HHMM)
|
||||
// %Z time zone
|
||||
// %% literal % character
|
||||
|
||||
// Find the order of date elements
|
||||
// and translate format string into printf ready string
|
||||
j = 0;
|
||||
|
|
@ -1697,34 +1876,54 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return newDate;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a description of the receiver using its normal format but with
|
||||
* the specified locale dictionary.<br />
|
||||
* Calls -descriptionWithCalendarFormat:locale: to do this.
|
||||
*/
|
||||
- (NSString*) descriptionWithLocale: (NSDictionary *)locale
|
||||
{
|
||||
return [self descriptionWithCalendarFormat: _calendar_format locale: locale];
|
||||
}
|
||||
|
||||
// Getting and Setting Calendar Formats
|
||||
/**
|
||||
* Returns the format string associated with the receiver.<br />
|
||||
* See -descriptionWithCalendarFormat:locale: for details.
|
||||
*/
|
||||
- (NSString*) calendarFormat
|
||||
{
|
||||
return _calendar_format;
|
||||
}
|
||||
|
||||
/**
|
||||
* Sets the format string associated with the receiver.<br />
|
||||
* See -descriptionWithCalendarFormat:locale: for details.
|
||||
*/
|
||||
- (void) setCalendarFormat: (NSString *)format
|
||||
{
|
||||
RELEASE(_calendar_format);
|
||||
_calendar_format = [format copyWithZone: [self zone]];
|
||||
}
|
||||
|
||||
// Getting and Setting Time Zones
|
||||
/**
|
||||
* Sets the time zone associated with the receiver.
|
||||
*/
|
||||
- (void) setTimeZone: (NSTimeZone *)aTimeZone
|
||||
{
|
||||
ASSIGN(_time_zone, aTimeZone);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the time zone associated with the receiver.
|
||||
*/
|
||||
- (NSTimeZone*) timeZone
|
||||
{
|
||||
return _time_zone;
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the time zone detail associated with the receiver.
|
||||
*/
|
||||
- (NSTimeZoneDetail*) timeZoneDetail
|
||||
{
|
||||
NSTimeZoneDetail *detail = [_time_zone timeZoneDetailForDate: self];
|
||||
|
|
@ -1744,16 +1943,27 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
|
||||
@implementation NSCalendarDate (GregorianDate)
|
||||
|
||||
/**
|
||||
* Returns the number of the last day of the month in the specified year.
|
||||
*/
|
||||
- (int) lastDayOfGregorianMonth: (int)month year: (int)year
|
||||
{
|
||||
return lastDayOfGregorianMonth(month, year);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the number of days since the start of the era for the specified
|
||||
* day, month, and year.
|
||||
*/
|
||||
- (int) absoluteGregorianDay: (int)day month: (int)month year: (int)year
|
||||
{
|
||||
return absoluteGregorianDay(day, month, year);
|
||||
}
|
||||
|
||||
/**
|
||||
* Given a day number since the start of the era, returns the dat as a
|
||||
* day, month, and year.
|
||||
*/
|
||||
- (void) gregorianDateFromAbsolute: (int)d
|
||||
day: (int *)day
|
||||
month: (int *)month
|
||||
|
|
@ -1928,6 +2138,10 @@ static inline int getDigits(const char *from, char *to, int limit)
|
|||
return AUTORELEASE(c);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the number of years, months, days, hours, minutes, and seconds
|
||||
* between the receiver and the given date.
|
||||
*/
|
||||
- (void) years: (int*)years
|
||||
months: (int*)months
|
||||
days: (int*)days
|
||||
|
|
|
|||
Loading…
Reference in a new issue