Class: NSCalendar

Inherits:
NSObject show all

Overview

Calendars encapsulate information about systems of reckoning time in which the beginning, length, and divisions of a year are defined. They provide information about the calendar and support for calendrical computations such as determining the range of a given calendrical unit and adding units to a given absolute time.

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Class Method Details

+ (Object) autoupdatingCurrentCalendar

Returns the current logical calendar for the current user. Settings you get from this calendar do change as the user’s settings change (contrast with currentCalendar).Note that if you cache values based on the calendar or related information those caches will of course not be automatically updated by the updating of the calendar object.

Returns:

  • (Object) —

    The current logical calendar for the current user.

+ (Object) currentCalendar

Returns the logical calendar for the current user. The returned calendar is formed from the settings for the current user’s chosen system locale overlaid with any custom settings the user has specified in System Preferences. Settings you get from this calendar do not change as System Preferences are changed, so that your operations are consistent (contrast with autoupdatingCurrentCalendar).

Returns:

  • (Object) —

    The logical calendar for the current user.

Instance Method Details

- (String) calendarIdentifier

Returns the identifier for the receiver.

Returns:

  • (String) —

    The identifier for the receiver. For valid identifiers, see NSLocale.

- (NSDateComponents) components(unitFlags, fromDate:date)

Returns a NSDateComponents object containing a given date decomposed into specified components. The Weekday ordinality, when requested, refers to the next larger (than Week) of the requested units. Some computations can take a relatively long time.The following example shows how to use this method to determine the current year, month, and day, using an existing calendar (gregorian):

Parameters:

  • unitFlags (Integer) —

    The components into which to decompose date—a bitwise OR of NSCalendarUnit constants.

  • date (NSDate) —

    The date for which to perform the calculation.

Returns:

  • (NSDateComponents) —

    An NSDateComponents object containing date decomposed into the components specified by unitFlags. Returns nil if date falls outside of the defined range of the receiver or if the computation cannot be performed

- (NSDateComponents) components(unitFlags, fromDate:startingDate, toDate:resultDate, options:opts)

Returns, as an NSDateComponents object using specified components, the difference between two supplied dates. The result is lossy if there is not a small enough unit requested to hold the full precision of the difference. Some operations can be ambiguous, and the behavior of the computation is calendar-specific, but generally larger components will be computed before smaller components; for example, in the Gregorian calendar a result might be 1 month and 5 days instead of, for example, 0 months and 35 days. The resulting component values may be negative if resultDate is before startDate.The following example shows how to get the approximate number of months and days between two dates using an existing calendar (gregorian): Note that some computations can take a relatively long time.

Parameters:

  • unitFlags (Integer) —

    Specifies the components for the returned NSDateComponents object—a bitwise OR of NSCalendarUnit constants.

  • startingDate (NSDate) —

    The start date for the calculation.

  • resultDate (NSDate) —

    The end date for the calculation.

  • opts (Integer) —

    Options for the calculation.If you specify a “wrap” option (NSWrapCalendarComponents), the specified components are incremented and wrap around to zero/one on overflow, but do not cause higher units to be incremented. When the wrap option is false, overflow in a unit carries into the higher units, as in typical addition.

Returns:

  • (NSDateComponents) —

    An NSDateComponents object whose components are specified by unitFlags and calculated from the difference between the resultDate and startDate using the options specified by opts. Returns nil if either date falls outside the defined range of the receiver or if the computation cannot be performed.

- (NSDate) dateByAddingComponents(comps, toDate:date, options:opts)

Returns a new NSDate object representing the absolute time calculated by adding given components to a given date. Some operations can be ambiguous, and the behavior of the computation is calendar-specific, but generally components are added in the order specified.The following example shows how to add 2 months and 3 days to the current date and time using an existing calendar (gregorian): Note that some computations can take a relatively long time.

Parameters:

  • comps (NSDateComponents) —

    The components to add to date.

  • date (NSDate) —

    The date to which comps are added.

  • opts (Integer) —

    Options for the calculation. See “NSDateComponents wrapping behavior” for possible values. Pass 0 to specify no options.If you specify no options (you pass 0), overflow in a unit carries into the higher units (as in typical addition).

Returns:

  • (NSDate) —

    A new NSDate object representing the absolute time calculated by adding to date the calendrical components specified by comps using the options specified by opts. Returns nil if date falls outside the defined range of the receiver or if the computation cannot be performed.

- (NSDate) dateFromComponents(comps)

Returns a new NSDate object representing the absolute time calculated from given components. When there are insufficient components provided to completely specify an absolute time, a calendar uses default values of its choice. When there is inconsistent information, a calendar may ignore some of the components parameters or the method may return nil. Unnecessary components are ignored (for example, Day takes precedence over Weekday and Weekday ordinals).The following example shows how to use this method to create a date object to represent 14:10:00 on 6 January 1965, for a given calendar (gregorian). Note that some computations can take a relatively long time to perform.

Parameters:

  • comps (NSDateComponents) —

    The components from which to calculate the returned date.

Returns:

  • (NSDate) —

    A new NSDate object representing the absolute time calculated from comps. Returns nil if the receiver cannot convert the components given in comps into an absolute time. The method also returns nil and for out-of-range values.

- (Integer) firstWeekday

Returns the index of the first weekday of the receiver.

Returns:

  • (Integer) —

    The index of the first weekday of the receiver.

- (Object) initWithCalendarIdentifier(string)

Initializes a newly-allocated NSCalendar object for the calendar specified by a given identifier.

Parameters:

  • string (String) —

    The identifier for the new calendar. For valid identifiers, see NSLocale.

Returns:

  • (Object) —

    The initialized calendar, or nil if the identifier is unknown (if, for example, it is either an unrecognized string or the calendar is not supported by the current version of the operating system).

- (NSLocale) locale

Returns the locale for the receiver.

Returns:

  • (NSLocale) —

    The locale for the receiver.

- (NSRange) maximumRangeOfUnit(unit)

The maximum range limits of the values that a given unit can take on in the receive As an example, in the Gregorian calendar the maximum range of values for the Day unit is 1-31.

Parameters:

  • unit (NSCalendarUnit) —

    The unit for which the maximum range is returned.

Returns:

  • (NSRange) —

    The maximum range limits of the values that the unit specified by unit can take on in the receiver.

- (Integer) minimumDaysInFirstWeek

Returns the minimum number of days in the first week of the receiver.

Returns:

  • (Integer) —

    The minimum number of days in the first week of the receiver

- (NSRange) minimumRangeOfUnit(unit)

Returns the minimum range limits of the values that a given unit can take on in the receiver. As an example, in the Gregorian calendar the minimum range of values for the Day unit is 1-28.

Parameters:

  • unit (NSCalendarUnit) —

    The unit for which the maximum range is returned.

Returns:

  • (NSRange) —

    The minimum range limits of the values that the unit specified by unit can take on in the receiver.

- (Integer) ordinalityOfUnit(smaller, inUnit:larger, forDate:date)

Returns, for a given absolute time, the ordinal number of a smaller calendar unit (such as a day) within a specified larger calendar unit (such as a week). The ordinality is in most cases not the same as the decomposed value of the unit. Typically return values are 1 and greater. For example, the time 00:45 is in the first hour of the day, and for units Hour and Day respectively, the result would be 1. An exception is the week-in-month calculation, which returns 0 for days before the first week in the month containing the date.Note that some computations can take a relatively long time.

Parameters:

  • smaller (NSCalendarUnit) —

    The smaller calendar unit

  • larger (NSCalendarUnit) —

    The larger calendar unit

  • date (NSDate) —

    The absolute time for which the calculation is performed

Returns:

  • (Integer) —

    The ordinal number of smaller within larger at the time specified by date. Returns NSNotFound if larger is not logically bigger than smaller in the calendar, or the given combination of units does not make sense (or is a computation which is undefined).

- (NSRange) rangeOfUnit(smaller, inUnit:larger, forDate:date)

Returns the range of absolute time values that a smaller calendar unit (such as a day) can take on in a larger calendar unit (such as a month) that includes a specified absolute time. You can use this method to calculate, for example, the range the Day unit can take on in the Month in which date lies.

Parameters:

  • smaller (NSCalendarUnit) —

    The smaller calendar unit.

  • larger (NSCalendarUnit) —

    The larger calendar unit.

  • date (NSDate) —

    The absolute time for which the calculation is performed.

Returns:

  • (NSRange) —

    The range of absolute time values smaller can take on in larger at the time specified by date. Returns NSNotFound if larger is not logically bigger than smaller in the calendar, or the given combination of units does not make sense (or is a computation which is undefined).

- (Boolean) rangeOfUnit(unit, startDate:datep, interval:tip, forDate:date)

Returns by reference the starting time and duration of a given calendar unit that contains a given date.

Parameters:

  • unit (NSCalendarUnit) —

    A calendar unit (see “Calendar Units” for possible values).

  • datep (Pointer) —

    Upon return, contains the starting time of the calendar unit unit that contains the date date

  • tip (NSTimeInterval) —

    Upon return, contains the duration of the calendar unit unit that contains the date date

  • date (NSDate) —

    A date.

Returns:

  • (Boolean) —

    YES if the starting time and duration of a unit could be calculated, otherwise NO.

- (Object) setFirstWeekday(weekday)

Sets the index of the first weekday for the receiver.

Parameters:

  • weekday (Integer) —

    The first weekday for the receiver.

Returns:

- (Object) setLocale(locale)

Sets the locale for the receiver.

Parameters:

  • locale (NSLocale) —

    The locale for the receiver.

Returns:

- (Object) setMinimumDaysInFirstWeek(mdw)

Sets the minimum number of days in the first week of the receiver.

Parameters:

  • mdw (Integer) —

    The minimum number of days in the first week of the receiver.

Returns:

- (Object) setTimeZone(tz)

Sets the time zone for the receiver.

Parameters:

  • tz (NSTimeZone) —

    The time zone for the receiver.

Returns:

- (NSTimeZone) timeZone

Returns the time zone for the receiver.

Returns:

  • (NSTimeZone) —

    The time zone for the receiver.