enumerateDates(startingAfter:matching:options:using:)

func enumerateDates(startingAfter start: Date, 
           matching comps: DateComponents, 
            options opts: NSCalendar.Options = [], 
              using block: (Date?, Bool, UnsafeMutablePointer<ObjCBool>) -> Void)

Discussion 議論

Executes a given block with dates that most closely match a given set of components after a given date, until the enumeration is stopped. 与えられたブロックを、ある与えられた日付の後で、ある与えられた一揃いの構成要素に最もぴったりと合致する日付とともに、列挙が停止されるまで、実行します。

Strict & Non-Strict Matching 厳密＆非厳密マッチ

If you specify a strict matching option (matchStrictly), this method searches as far as necessary looking for a match, up to a an implementation-defined limit. If an exact match is not possible, nil is passed to the date argument of the block, and the enumeration is stopped. Otherwise, this method searches as far as the next instance of the next highest calendar unit in the given NSDateComponents object. あなたが厳密マッチオプション（matchStrictly）を指定するならば、このメソッドは合致するものを見つけるのに必要なだけ、実装定義の限界に至るまで、検索します。厳密な合致が不可能ならば、nilがブロックのdate引数に渡されます、そして列挙は停止されます。そうでないならば、このメソッドはその与えられたNSDateComponentsオブジェクトの中で次に最も高いカレンダー単位の次のインスタンスまで検索します。

If you do not specify a strict matching option, you must specify one of the following options, or else an illegal argument exception will be thrown: あなたが厳密マッチオプションを指定しないならば、あなたは以下のオプションの１つを指定しなければなりません、さもなければ不正引数例外がスローされるでしょう：

matchPreviousTimePreservingSmallerUnits

If specified, and there is no matching time before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the previous existing value of the missing unit and preserves the lower units' values. もし指定されて、そして合致する時間がその与えられたNSDateComponentsオブジェクトで指定される次に最も高い単位の次のインスタンスの終わりの前にないならば、このメソッドはその見つからない単位の１つ前の存在する値を使います、そしてより低い単位の値を保全します。

matchNextTimePreservingSmallerUnits

If specified, and there is no matching time before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the next existing value of the missing unit and preserves the lower units' values. もし指定されて、そして合致する時間がその与えられたNSDateComponentsオブジェクトで指定される次に最も高い単位の次のインスタンスの終わりの前にないならば、このメソッドはその見つからない単位の次の存在する値を使います、そしてより低い単位の値を保全します。

matchNextTime

If specified, and there is no matching time before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the next existing value of the missing unit and does not preserve the lower units' values. もし指定されて、そして合致する時間がその与えられたNSDateComponentsオブジェクトで指定される次に最も高い単位の次のインスタンスの終わりの前にないならば、このメソッドはその見つからない単位の次の存在する値を使います、そしてより低い単位の値を保全しません。

For example, if the date "February 29th" does not exist for a particular year, a non-strict match would return "February 28th" of that year instead. 例えば、 "February 29th" が特定の年に存在しないならば、非厳密マッチは代わりにその年の "February 28th" を返すでしょう。

As another example, if the time "2:37AM" does not exist for a particular day, such as when advancing by an hour at the beginning of Daylight Savings Time, the following is true: 別の例として、時刻 "2:37AM" が特定の日に存在しないならば、例えば夏時間の始まりで１時間進める場合、以下は真です：

• If strict matching is specified, "2:37AM" on the following the next day is used. 厳密マッチが指定されるならば、続く翌日の "2:37AM" が使われます。

• If matchPreviousTimePreservingSmallerUnits is specified, "1:37AM" would be used instead, if that time exists. matchPreviousTimePreservingSmallerUnitsが指定されるならば、 "1:37AM" が代わりに使われるでしょう、もしその時刻が存在するならば。

• If matchNextTimePreservingSmallerUnits is specified, the date at the time "3:37AM" would be used instead, if that time exists. matchNextTimePreservingSmallerUnitsが指定されるならば、時刻 "3:37AM" での日付が代わりに使われるでしょう、もしその時刻が存在するならば。

• If matchNextTime is specified, the date at the time "3:00AM" would be used instead, if that time exists. matchNextTimeが指定されるならば、時刻 "3:00AM" での日付が代わりに使われるでしょう、もしその時刻が存在するならば。

Matching First or Last Occurrence 最初または最後の出現にマッチする

If you specify a "match first" option (matchFirst) and there are two or more matching times (that is, all components are the same) before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the first occurrence. あなたが "最初のものにマッチ" オプション（matchFirst）を指定するそして複数の合致する（すなわち、全ての構成要素が同じ）時間がNSDateComponentsオブジェクトで指定される次に最も高い単位の次のインスタンスの終わりの前にあるならば、このメソッドは最初の出現を使います。

If you specify a "match last" option (matchLast) and there are two or more matching times (that is, all components are the same) before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the last occurrence. あなたが "最後のものにマッチ" オプション（matchLast）を指定するそして複数の合致する（すなわち、全ての構成要素が同じ）時間がNSDateComponentsオブジェクトで指定される次に最も高い単位の次のインスタンスの終わりの前にあるならば、このメソッドは最後の出現を使います。

If neither "match first" or "match last" options are specified or both options are specified, this method behaves as if matchFirst was specified. "最初のものにマッチ" または "最後のものにマッチ" オプションがどちらも指定されないもしくは両方のオプションが指定されるならば、このメソッドはmatchFirst指定されたかのように振る舞います。

There is no option to return middle occurrences of more than two occurrences of a matching time, if such exist. ある合致する時間の２つより多い出現の真ん中の出現を、そのようなものがあっても、返すためのオプションはありません。

For example, when Daylight Savings Time ends, clocks are set back by one hour at 2:00AM, such that times between 1:00AM and 1:59AM occur twice that day. The matchFirst and matchLast search options return the first and last occurrence of these times. 例えば、夏時間が終わる時、時計は2:00AMに１時間戻して設定されます、それで1:00AM と 1:59AM の間の時間がその日に２度出現します。matchFirstとmatchLast検索オプションは、それらの時間の最初と最後の出現を返します。

Forward & Backward Search 前方＆後方検索

If you specify a backward search option (searchBackwards), this method will search for previous matches before the given date. This method will return the same results as if the search were made in the forward direction from the distant past, but with the results in reverse order starting with the match most recent to the given date. That is, when searching backwards for a particular hour with no specified minute or second value, the resulting time is not "59" minutes and "59" seconds for the matching hour. When enumerating dates that repeat a time, such as when the clock turns back to 1:00AM from 2:00AM when Daylight Savings Time ends, the "first" time is determined as if the search were performed in the forwards direction. あなたが後方検索オプション（searchBackwards）を指定するならば、このメソッドは与えられた日付より前の最初の合致を検索します。このメソッドは遠い過去から前方方向に検索がなされたのと同じ結果を返します、しかし逆順での結果で、最近の合致するもので始まって与えられた日付まで。すなわち、ある特定の時間に対する後方検索で、指定される分と秒がない場合、結果の時刻は、その合致する時間の "59" 分と "59" 秒ではありません。ある時刻を繰り返す日付を列挙する場合、例えば夏時間が終わる時に時計が 1:00AM に 2:00AM から戻る場合、"最初の" 時刻は、まるで検索が前方向に実行されたかのように決定されます。

For example, given a date with a time of "5:00AM" when searching for a minute component equal to 30, a forward search returns the time "5:30AM" and a backward search returns "4:30AM". 例えば、"5:00AM" の時刻をもつ日付が、30と等しい分の構成要素を検索する場合に与えられて、前方検索は時刻 "5:30AM" を返し、後方検索は "4:30AM" を返します。