A date or time specified in terms of units (such as year, month, day, hour, minute) to be evaluated in a calendar system and time zone.
`DateComponents` encapsulates the components of a date in an extendable, structured manner.
It is used to specify a date by providing the temporal components that make up a date and time in a particular calendar: hour, minutes, seconds, day, month, year, and so on. It can also be used to specify a duration of time, for example, 5 hours and 16 minutes. A `DateComponents` is not required to define all the component fields.
When a new instance of `DateComponents` is created, the date components are set to `nil`.
Members (47)
method · iOS 8.0+
isValidDate
TypeScript
isValidDateIn(calendar: Calendar): boolean
Swift declaration
func isValidDate(in calendar: Calendar) -> Bool
Indicates whether the current combination of properties represents a date which exists in the specified calendar.
This method is not appropriate for use on `DateComponents` values which are specifying relative quantities of calendar components.
Except for some trivial cases (e.g., 'seconds' should be 0 - 59 in any calendar), this method is not necessarily cheap.
If the time zone property is set in the `DateComponents`, it is used.
get · iOS 8.0+
isValidDate
TypeScript
get isValidDate(): boolean
Swift declaration
var isValidDate: Bool { get }
Indicates whether the current combination of properties represents a date which exists in the current calendar.
This method is not appropriate for use on `DateComponents` values which are specifying relative quantities of calendar components.
Except for some trivial cases (e.g., 'seconds' should be 0 - 59 in any calendar), this method is not necessarily cheap.
If the time zone property is set in the `DateComponents`, it is used.
The calendar property must be set, or the result is always `false`.
get · iOS 8.0+
nanosecond
TypeScript
get nanosecond(): (number) | null
Swift declaration
var nanosecond: Int? { get set }
A nanosecond or count of nanoseconds.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
nanosecond
TypeScript
set nanosecond(value: (number) | null)
Swift declaration
var nanosecond: Int? { get set }
A nanosecond or count of nanoseconds.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
weekOfYear
TypeScript
get weekOfYear(): (number) | null
Swift declaration
var weekOfYear: Int? { get set }
A week of the year or count of the weeks of the year.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
weekOfYear
TypeScript
set weekOfYear(value: (number) | null)
Swift declaration
var weekOfYear: Int? { get set }
A week of the year or count of the weeks of the year.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
description
TypeScript
get description(): string
Swift declaration
var description: String { get }
A textual representation of this instance.
Calling this property directly is discouraged. Instead, convert an
instance of any type to a string by using the `String(describing:)`
initializer. This initializer works with any type, and uses the custom
`description` property for types that conform to
`CustomStringConvertible`:
struct Point: CustomStringConvertible {
let x: Int, y: Int
var description: String {
return "(\(x), \(y))"
}
}
let p = Point(x: 21, y: 30)
let s = String(describing: p)
print(s)
// Prints "(21, 30)"
The conversion of `p` to a string in the assignment to `s` uses the
`Point` type's `description` property.
get · iOS 8.0+
isLeapMonth
TypeScript
get isLeapMonth(): (boolean) | null
Swift declaration
var isLeapMonth: Bool? { get set }
Set to true if these components represent a leap month.
set · iOS 8.0+
isLeapMonth
TypeScript
set isLeapMonth(value: (boolean) | null)
Swift declaration
var isLeapMonth: Bool? { get set }
Set to true if these components represent a leap month.
get · iOS 8.0+
weekOfMonth
TypeScript
get weekOfMonth(): (number) | null
Swift declaration
var weekOfMonth: Int? { get set }
A week of the month or a count of weeks of the month.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
weekOfMonth
TypeScript
set weekOfMonth(value: (number) | null)
Swift declaration
var weekOfMonth: Int? { get set }
A week of the month or a count of weeks of the month.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
customMirror
TypeScript
get customMirror(): SDKHandle
Swift declaration
var customMirror: Mirror { get }
The custom mirror for this instance.
If this type has value semantics, the mirror should be unaffected by
subsequent mutations of the instance.
get · iOS 26.0+
isRepeatedDay
TypeScript
get isRepeatedDay(): (boolean) | null
Swift declaration
var isRepeatedDay: Bool? { get set }
Set to true if these components represent a repeated day.
set · iOS 26.0+
isRepeatedDay
TypeScript
set isRepeatedDay(value: (boolean) | null)
Swift declaration
var isRepeatedDay: Bool? { get set }
Set to true if these components represent a repeated day.
get · iOS 8.0+
weekdayOrdinal
TypeScript
get weekdayOrdinal(): (number) | null
Swift declaration
var weekdayOrdinal: Int? { get set }
A weekday ordinal or count of weekday ordinals.
Weekday ordinal units represent the position of the weekday within the next larger calendar unit, such as the month. For example, 2 is the weekday ordinal unit for the second Friday of the month.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
weekdayOrdinal
TypeScript
set weekdayOrdinal(value: (number) | null)
Swift declaration
var weekdayOrdinal: Int? { get set }
A weekday ordinal or count of weekday ordinals.
Weekday ordinal units represent the position of the weekday within the next larger calendar unit, such as the month. For example, 2 is the weekday ordinal unit for the second Friday of the month.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
debugDescription
TypeScript
get debugDescription(): string
Swift declaration
var debugDescription: String { get }
A textual representation of this instance, suitable for debugging.
Calling this property directly is discouraged. Instead, convert an
instance of any type to a string by using the `String(reflecting:)`
initializer. This initializer works with any type, and uses the custom
`debugDescription` property for types that conform to
`CustomDebugStringConvertible`:
struct Point: CustomDebugStringConvertible {
let x: Int, y: Int
var debugDescription: String {
return "(\(x), \(y))"
}
}
let p = Point(x: 21, y: 30)
let s = String(reflecting: p)
print(s)
// Prints "(21, 30)"
The conversion of `p` to a string in the assignment to `s` uses the
`Point` type's `debugDescription` property.
get · iOS 8.0+
yearForWeekOfYear
TypeScript
get yearForWeekOfYear(): (number) | null
Swift declaration
var yearForWeekOfYear: Int? { get set }
The year corresponding to a week-counting week.
The Gregorian calendar defines a week to have 7 days, and a year to have 365 days, or 366 in a leap year. However, neither 365 or 366 divide evenly into a 7 day week, so it is often the case that the last week of a year ends on a day in the next year, and the first week of a year begins in the preceding year. To reconcile this, ISO 8601 defines a week-numbering year, consisting of either 52 or 53 full weeks (364 or 371 days), such that the first week of a year is designated to be the week containing the first Thursday of the year.
You can use the yearForWeekOfYear property with the weekOfYear and weekday properties to get the date corresponding to a particular weekday of a given week of a year. For example, the 6th day of the 53rd week of the year 2005 (ISO 2005-W53-6) corresponds to Sat 1 January 2005 on the Gregorian calendar.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
yearForWeekOfYear
TypeScript
set yearForWeekOfYear(value: (number) | null)
Swift declaration
var yearForWeekOfYear: Int? { get set }
The year corresponding to a week-counting week.
The Gregorian calendar defines a week to have 7 days, and a year to have 365 days, or 366 in a leap year. However, neither 365 or 366 divide evenly into a 7 day week, so it is often the case that the last week of a year ends on a day in the next year, and the first week of a year begins in the preceding year. To reconcile this, ISO 8601 defines a week-numbering year, consisting of either 52 or 53 full weeks (364 or 371 days), such that the first week of a year is designated to be the week containing the first Thursday of the year.
You can use the yearForWeekOfYear property with the weekOfYear and weekday properties to get the date corresponding to a particular weekday of a given week of a year. For example, the 6th day of the 53rd week of the year 2005 (ISO 2005-W53-6) corresponds to Sat 1 January 2005 on the Gregorian calendar.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
day
TypeScript
get day(): (number) | null
Swift declaration
var day: Int? { get set }
A day or count of days.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
day
TypeScript
set day(value: (number) | null)
Swift declaration
var day: Int? { get set }
A day or count of days.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
era
TypeScript
get era(): (number) | null
Swift declaration
var era: Int? { get set }
An era or count of eras.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
era
TypeScript
set era(value: (number) | null)
Swift declaration
var era: Int? { get set }
An era or count of eras.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
date
TypeScript
get date(): (globalThis.Date) | null
Swift declaration
var date: Date? { get }
The date calculated from the current components using the stored calendar.
get · iOS 8.0+
hour
TypeScript
get hour(): (number) | null
Swift declaration
var hour: Int? { get set }
An hour or count of hours.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
hour
TypeScript
set hour(value: (number) | null)
Swift declaration
var hour: Int? { get set }
An hour or count of hours.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
year
TypeScript
get year(): (number) | null
Swift declaration
var year: Int? { get set }
A year or count of years.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
year
TypeScript
set year(value: (number) | null)
Swift declaration
var year: Int? { get set }
A year or count of years.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
month
TypeScript
get month(): (number) | null
Swift declaration
var month: Int? { get set }
A month or count of months.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
month
TypeScript
set month(value: (number) | null)
Swift declaration
var month: Int? { get set }
A month or count of months.
- note: This value is interpreted in the context of the calendar in which it is used.
Returns the value of one of the properties, using an enumeration value instead of a property name.
The calendar, timeZone, isLeapMonth, and isRepeatedDay property values cannot be retrieved by this method.
get · iOS 8.0+
minute
TypeScript
get minute(): (number) | null
Swift declaration
var minute: Int? { get set }
A minute or count of minutes.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
minute
TypeScript
set minute(value: (number) | null)
Swift declaration
var minute: Int? { get set }
A minute or count of minutes.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
second
TypeScript
get second(): (number) | null
Swift declaration
var second: Int? { get set }
A second or count of seconds.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
second
TypeScript
set second(value: (number) | null)
Swift declaration
var second: Int? { get set }
A second or count of seconds.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
quarter
TypeScript
get quarter(): (number) | null
Swift declaration
var quarter: Int? { get set }
A quarter or count of quarters.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
quarter
TypeScript
set quarter(value: (number) | null)
Swift declaration
var quarter: Int? { get set }
A quarter or count of quarters.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 8.0+
weekday
TypeScript
get weekday(): (number) | null
Swift declaration
var weekday: Int? { get set }
A weekday or count of weekdays.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
weekday
TypeScript
set weekday(value: (number) | null)
Swift declaration
var weekday: Int? { get set }
A weekday or count of weekdays.
- note: This value is interpreted in the context of the calendar in which it is used.
Initializes a date components value, optionally specifying values for its fields.
get · iOS 8.0+
calendar
TypeScript
get calendar(): (Calendar) | null
Swift declaration
var calendar: Calendar? { get set }
The calendar used to interpret the other values in this structure.
- note: API which uses `DateComponents` may have different behavior if this value is `nil`. For example, assuming the current calendar or ignoring certain values.
set · iOS 8.0+
calendar
TypeScript
set calendar(value: (Calendar) | null)
Swift declaration
var calendar: Calendar? { get set }
The calendar used to interpret the other values in this structure.
- note: API which uses `DateComponents` may have different behavior if this value is `nil`. For example, assuming the current calendar or ignoring certain values.
mutating func setValue(_ value: Int?, for component: Calendar.Component)
Set the value of one of the properties, using an enumeration value instead of a property name.
The calendar, timeZone, isLeapMonth, and isRepeatedDay properties cannot be set by this method.
get · iOS 8.0+
timeZone
TypeScript
get timeZone(): (TimeZone) | null
Swift declaration
var timeZone: TimeZone? { get set }
A time zone.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 8.0+
timeZone
TypeScript
set timeZone(value: (TimeZone) | null)
Swift declaration
var timeZone: TimeZone? { get set }
A time zone.
- note: This value is interpreted in the context of the calendar in which it is used.
get · iOS 18.0+
dayOfYear
TypeScript
get dayOfYear(): (number) | null
Swift declaration
var dayOfYear: Int? { get set }
A day of the year.
For example, in the Gregorian calendar, can go from 1 to 365 or 1 to 366 in leap years.
- note: This value is interpreted in the context of the calendar in which it is used.
set · iOS 18.0+
dayOfYear
TypeScript
set dayOfYear(value: (number) | null)
Swift declaration
var dayOfYear: Int? { get set }
A day of the year.
For example, in the Gregorian calendar, can go from 1 to 365 or 1 to 366 in leap years.
- note: This value is interpreted in the context of the calendar in which it is used.
Skipped declarations
3 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
DateComponents.formatted(_:)
This declaration needs Swift generic type arguments. (no canonical witness for F)
DateComponents.init(_:strategy:)
This declaration needs Swift generic type arguments. (no canonical witness for T.ParseInput)
DateComponents.init(_:strategy:)
This declaration needs Swift generic type arguments. (no canonical witness for T)
