Add implementation for getEra:... and getHour:... method in NSCalendar. Add documentation to all methods.

ChangeLog

@@ -1,3 +1,12 @@
+2022-04-06 Gregory John Casamento <greg.casamento@gmail.com>
+
+	* Headers/Foundation/NSCalendar.h: Add documentation.
+	* Source/NSCalendar.m: Implement getEra:... and getHour:...
+        methods based on Keysight/TestPlant changes
+	* Tests/base/NSCalendar/basic.m: Minor cleanup.
+	* Tests/base/NSCalendar/component-diff.m: Add tests for
+        methods implemented above.
+
 2022-03-07 Gregory John Casamento <greg.casamento@gmail.com>
 
         * Headers/Foundation/NSIndexPath.h: Add declarations for new

Headers/Foundation/NSCalendar.h

@@ -275,12 +275,29 @@ GS_EXPORT_CLASS
   void  *_dummy3;
 }
 
+/**
+ * Returns the current calendar.
+ */
 + (id) currentCalendar;
+
+/**
+ * Create a calendar with the given string as identifier.
+ */
 + (id) calendarWithIdentifier: (NSString *) string;
 
+/**
+ * Instantiate a calendar with the given string as identifier.
+ */
 - (id) initWithCalendarIdentifier: (NSString *) string;
+
+/**
+ * Returns the calendar identifier for the receiver.
+ */
 - (NSString *) calendarIdentifier;
 
+/**
+ * Returns the calendar units specified by unitFlags for the given date object.
+ */
 - (NSDateComponents *) components: (NSUInteger) unitFlags
                          fromDate: (NSDate *) date;
 /**
@@ -298,32 +315,94 @@ GS_EXPORT_CLASS
                          fromDate: (NSDate *) startingDate
                            toDate: (NSDate *) resultDate
                           options: (NSUInteger) opts;
+
+/**
+ * Returns a date object created by adding the NSDateComponents in comps to
+ * to object date with the options specified by opts.
+ */
 - (NSDate *) dateByAddingComponents: (NSDateComponents *) comps
                              toDate: (NSDate *) date
                             options: (NSUInteger) opts;
+
+/**
+ * Creates an NSDate from NSDateComponents in comps.
+ */
 - (NSDate *) dateFromComponents: (NSDateComponents *) comps;
 
+/**
+ * Returns the locale of the receiver.
+ */
 - (NSLocale *) locale;
+
+/**
+ * Sets the locale of the receiver.
+ */
 - (void)setLocale: (NSLocale *) locale;
+
+/**
+ * Returns the integer value of the first weekday (0-6).
+ */
 - (NSUInteger) firstWeekday;
+
+/**
+ * Set the integer first weekday of the week (0-6).
+ */
 - (void) setFirstWeekday: (NSUInteger) weekday;
+
+/**
+ * Returns the minimum number of days in the first week of the receiver.
+ */
 - (NSUInteger) minimumDaysInFirstWeek;
+
+/**
+ * Sets the minimum number of days in the first week of the receiver.
+ */
 - (void) setMinimumDaysInFirstWeek: (NSUInteger) mdw;
+
+/**
+ * Returns the NSTimeZone associated with the receiver.
+ */
 - (NSTimeZone *) timeZone;
+
+/**
+ * Sets tz as the current NSTimeZone of the receiver.
+ */
 - (void) setTimeZone: (NSTimeZone *) tz;
 
+/**
+ * Returns the maximum range of unit.
+ */
 - (NSRange) maximumRangeOfUnit: (NSCalendarUnit) unit;
+
+/**
+ * Returns the minimum range of unit.
+ */
 - (NSRange) minimumRangeofUnit: (NSCalendarUnit) unit;
+
+/**
+ * Returns the ordinality of unit smaller within the
+ * unit larger with the given date.
+ */
 - (NSUInteger) ordinalityOfUnit: (NSCalendarUnit) smaller
                          inUnit: (NSCalendarUnit) larger
                         forDate: (NSDate *) date;
+
+/**
+ * Returns the range of unit smaller in larger in date.
+ */
 - (NSRange) rangeOfUnit: (NSCalendarUnit) smaller
                  inUnit: (NSCalendarUnit) larger
                 forDate: (NSDate *) date;
 
 #if OS_API_VERSION(MAC_OS_X_VERSION_10_5, GS_API_LATEST)
+/**
+ * A calendar that tracks changes to the user's calendar.
+ */
 + (id) autoupdatingCurrentCalendar;
 
+/**
+ * Returns by referene the started time and duration of a given unit containing the given date.
+ */ 
 - (BOOL) rangeOfUnit: (NSCalendarUnit) unit
            startDate: (NSDate **) datep
             interval: (NSTimeInterval *)tip
@@ -331,24 +410,36 @@ GS_EXPORT_CLASS
 #endif
 
 #if OS_API_VERSION(MAC_OS_X_VERSION_10_9, GS_API_LATEST)
+/**
+ * Returns by reference the era, year, month, and day from the given date.
+ */
 - (void) getEra: (NSInteger *)eraValuePointer
            year: (NSInteger *)yearValuePointer
           month: (NSInteger *)monthValuePointer
             day: (NSInteger *)dayValuePointer
        fromDate: (NSDate *)date;
 
+/**
+ * Returns by reference the hour, minute, second, and nanosecond from the given date.
+ */
 - (void) getHour: (NSInteger *)hourValuePointer
           minute: (NSInteger *)minuteValuePointer
           second: (NSInteger *)secondValuePointer
       nanosecond: (NSInteger *)nanosecondValuePointer
         fromDate: (NSDate *)date;
 
+/**
+ * Returns by reference the era, year, week of year, and weekday from the given date.
+ */
 - (void) getEra: (NSInteger *)eraValuePointer 
 yearForWeekOfYear: (NSInteger *)yearValuePointer 
      weekOfYear: (NSInteger *)weekValuePointer 
         weekday: (NSInteger *)weekdayValuePointer 
        fromDate: (NSDate *)date;
 
+/**
+ * Returns the integer value of the specified unit from the given date.
+ */
 - (NSInteger) component: (NSCalendarUnit)unit 
                fromDate: (NSDate *)date;
 #endif

Tests/base/NSCalendar/basic.m

@@ -54,7 +54,6 @@ int main()
   PASS([testObj minimumDaysInFirstWeek] == 10,
     "-setMinimumDaysInFirstWeek: can set ten");
 
-
   END_SET("NSCalendar basic")
   return 0;
 }

Tests/base/NSCalendar/component-diff.m

@@ -3,6 +3,7 @@
 #import <Foundation/NSCalendar.h>
 #import <Foundation/NSTimeZone.h>
 #import <Foundation/NSLocale.h>
+#import <Foundation/NSDateFormatter.h>
 #include <stdio.h>
 
 #if	defined(GS_USE_ICU)
@@ -51,8 +52,40 @@ int main()
                   options: 0];
   PASS([comps month] == NSNotFound, "no month returned if not requested");
   PASS([comps day] == 33, "day difference without larger unit correct");
+
   
+  /* Test getEra:year:month:day:fromDate:
+   */
+  NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
+  [dateFormatter setDateFormat: @"d MMM yyyy HH:mm:ss Z"];
+  NSDate *date = [dateFormatter dateFromString:@"22 Nov 1969 08:15:00 Z"];
+
+  NSInteger era = 0;
+  NSInteger year = 0;
+  NSInteger month = 0;
+  NSInteger day = 0;
+  NSInteger hour = 0;
+  NSInteger min = 0;
+  NSInteger sec = 0;
+  NSInteger nano = 0;
   
+  [cal getEra:&era year:&year month:&month day:&day fromDate:date];
+
+  PASS(era == 1, "getEra:year:month:day:fromDate: returns correct era");
+  PASS(year == 1969, "getEra:year:month:day:fromDate: returns correct year");
+  PASS(month == 11, "getEra:year:month:day:fromDate: returns correct month");
+  PASS(day == 22, "getEra:year:month:day:fromDate: returns correct day");
+  
+  /* Test getHour:minute:second:nanosecond:fromDate:
+   */
+  [cal getHour:&hour minute:&min second:&sec nanosecond:&nano fromDate:date];
+
+  PASS(hour == 3, "getHour:minute:second:nanosecond:fromDate: returns correct hour");
+  PASS(min == 15, "getHour:minute:second:nanosecond:fromDate: returns correct minute");
+  PASS(sec == 0, "getHour:minute:second:nanosecond:fromDate: returns correct second");
+  PASS(nano == 0, "getHour:minute:second:nanosecond:fromDate: returns correct nanosecond");
+  
+  RELEASE(dateFormatter);
   RELEASE(cal);
   
   END_SET("NSCalendar date component differences")