Merge branch 'release/5.1.0'

.travis.yml

@@ -1,5 +1,5 @@
 language: objective-c
-osx_image: xcode9.3
+osx_image: xcode10.1
 
 env:
   global:

Configs/SwiftDate.plist

@@ -15,7 +15,7 @@
 	<key>CFBundlePackageType</key>
 	<string>FMWK</string>
 	<key>CFBundleShortVersionString</key>
-	<string>5.0.11</string>
+	<string>5.1.0</string>
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>

Documentation/3.Manipulate_Date.md

@@ -19,8 +19,9 @@
 - [3.8 - Generate Related Dates (`nextYear, nextWeeekday, startOfMonth, startOfWeek, prevMonth`...)](3.Manipulate_Date.md#relateddates)
 - [3.9 - Date at start/end of time component](3.Manipulate_Date.md#startendcomponent)
 - [3.10 - Enumerate Dates](3.Manipulate_Date.md#enumeratedates)
-- [3.11 - Random Dates](3.Manipulate_Date.md#randomdates)
-- [3.12 - Sort Dates](3.Manipulate_Date.md#sort)
+- [3.11 - Enumerate Dates for Weekday in Range](3.Manipulate_Date.md#enumerateweekdays)
+- [3.12 - Random Dates](3.Manipulate_Date.md#randomdates)
+- [3.13 - Sort Dates](3.Manipulate_Date.md#sort)
 
 Dates can be manipulated as you need by using classic math operators and readable time units.
 
@@ -382,9 +383,47 @@ let dates = DateInRegion.enumerateDates(from: fromDate, to: toDate, increment: i
 
 [^ Top](#index)
 
+<a name="enumerateweekdays"/>
+
+## 3.12 - Enumerate Dates for Weekday in Range
+The following function allows you to enumerate all dates of a particular weekdays which are in a determinated date range.
+Both `Date` and `DateInRegion` implements this static function:
+
+```swift
+public static func datesForWeekday(_ weekday: WeekDay, from startDate: Date, to endDate: Date, region: Region = SwiftDate.defaultRegion) -> [Date]
+```
+
+Another shortcut method allows you to get weekdays in a particular month of a year:
+
+```swift
+public static func datesForWeekday(_ weekday: WeekDay, inMonth month: Int, ofYear year: Int, region: Region = SwiftDate.defaultRegion) -> [Date]
+```
+
+Examples:
+
+```swift
+// Get all mondays in Jan 2019
+let mondaysInJan2019 = Date.datesForWeekday(.monday, inMonth: 1, ofYear: 2019)
+
+// You will get 4 results
+// - 2019-01-07T00:00:00Z
+// - 2019-01-14T00:00:00Z
+// - 2019-01-21T00:00:00Z
+// - 2019-01-28T00:00:00Z
+
+// Get all fridays between May 27, 2019 and June 8, 2019
+let fromDate = Date(year: 2019, month: 5, day: 27, hour: 0, minute: 0)
+let toDate = Date(year: 2019, month: 6, day: 8, hour: 0, minute: 0)
+let fridaysInJunePartial = Date.datesForWeekday(.friday, from: fromDate, to: toDate, region: Region.UTC)
+
+// You will get 2 results:
+// - 2019-05-31T00:00:00Z
+// - 2019-06-07T00:00:00Z
+```
+
 <a name="randomdates"/>
 
-## 3.11 - Random Dates
+## 3.12 - Random Dates
 SwiftDate exposes a set of functions to generate a random date or array of random dates in a bounds.
 There are several functions to perform this operation:
 
@@ -417,7 +456,7 @@ let aDate = DateInRegion.randomDate(withinDaysBeforeToday: 7, region: rome)
 
 <a name="sort"/>
 
-## 3.12 - Sort Dates
+## 3.13 - Sort Dates
 Two conveniences function allows you to sort an array of dates by newest or oldest. Naming is pretty simple:
 
 - `sortedByOldest()`: sort dates by the oldest

Documentation/Index.md

@@ -49,8 +49,9 @@ The following documentation explore all the major features of the library. If yo
 - [3.8 - Generate Related Dates (`nextYear, nextWeeekday, startOfMonth, startOfWeek, prevMonth`...)](3.Manipulate_Date.md#relateddates)
 - [3.9 - Date at start/end of time component](3.Manipulate_Date.md#startendcomponent)
 - [3.10 - Enumerate Dates](3.Manipulate_Date.md#enumeratedates)
-- [3.11 - Random Dates](3.Manipulate_Date.md#randomdates)
-- [3.12 - Sort Dates](3.Manipulate_Date.md#sort)
+- [3.11 - Enumerate Dates for Weekday in Range](3.Manipulate_Date.md#enumerateweekdays)
+- [3.12 - Random Dates](3.Manipulate_Date.md#randomdates)
+- [3.13 - Sort Dates](3.Manipulate_Date.md#sort)
 
 ### [4 - Compare Dates](4.Compare_Dates.md)
 

README.md

@@ -1,31 +1,20 @@
 <p align="center" >
-<img src="Documentation/SwiftDate.png" width=506px alt="SwiftDate" title="SwiftDate">
+<img src="Documentation/SwiftDateArt.png" width=476px alt="SwiftDate" title="SwiftDate">
 </p>
 
-<p align="center" >★★ <b>Star me to follow the project! </b> ★★<br>
-Created and maintaned by <b>Daniele Margutti</b> - <a href="http://www.danielemargutti.com">www.danielemargutti.com</a>
-</p>
-
-![](https://img.shields.io/cocoapods/dt/SwiftDate.svg)
-![](https://img.shields.io/badge/coverage-90%25-green.svg)
-![](https://img.shields.io/cocoapods/p/SwiftDate.svg)
 ![](https://img.shields.io/cocoapods/v/SwiftDate.svg)
+![](https://img.shields.io/cocoapods/p/SwiftDate.svg)
+![](https://img.shields.io/badge/coverage-90%25-green.svg)
 ![](https://img.shields.io/badge/carthage-compatible-brightgreen.svg)
 [](https://img.shields.io/travis/malcommac/SwiftDate.svg)
 
-## What's SwiftDate?
+<p align="center" >★★ <b>Star me to follow the project! </b> ★★<br>
+Created and maintaned by <b>Daniele Margutti</b> - <a href="http://www.danielemargutti.com">www.danielemargutti.com</a>
+</p>
 
 SwiftDate is the **definitive toolchain to manipulate and display dates and time zones** on all Apple platform and even on Linux and Swift Server Side frameworks like Vapor or Kitura.
 
-★★ Over [3M of downloads](https://cocoapods.org/pods/SwiftDate) on CocoaPods ★★
-
-### Help SwiftDate Development
-
-<a href="https://www.patreon.com/danielemargutti"><img src="Documentation/support_patreon_button.png" width=160px alt="SwiftDate" title="SwiftDate"></a>
-</p>
-
-If you are using SwiftDate or any other my libraries please [consider support further development](https://www.patreon.com/danielemargutti) and mainteniance becoming a patreon.
-It's fast and easy, a way to **help opensource software development**.
+Over [3M of downloads](https://cocoapods.org/pods/SwiftDate) on CocoaPods
 
 ### Features Highlights
 From simple date manipulation to complex business logic SwiftDate maybe the right choice for your next project.
@@ -44,24 +33,20 @@ From simple date manipulation to complex business logic SwiftDate maybe the righ
 
 and of course...
 
-- **IT'S TESTED!**. As 5.0.0 the project has 90% of code coverage (want help us? write some unit tests and make a PR)
+- **IT'S TESTED!**. As 5.x the project has 90% of code coverage (want help us? write some unit tests and make a PR)
 - **IT'S FULLY DOCUMENTED!**, [both with a complete guide](/Documentation/Index.md) and with Jazzy!
 - **WE LOVE PLAYGROUND!** [Check out](/Playgrounds/SwiftDate.playground) our interative playground!
 
 
 ## Start with SwiftDate
 
-- Current Version: **5.0.4** 
-- Last Update: **July 18, 2018**
-- Code Coverage: **~90%**
-
 The entire library is fully documented both via XCode method inspector and a complete markdown documentation you can found below.
 
-- → **[Read the Documentation](/Documentation/Index.md)** (updated as 5.0.4)
+- → **[Full Documentation](/Documentation/Index.md)**
 - → **[Requirements, Install, License & More](/Documentation/0.Informations.md)**
 - → **[Upgrading from SwiftDate 4](/Documentation/10.Upgrading_SwiftDate4.md)**
 
-## Explore SwiftDate
+### Explore SwiftDate
 
 From simple date manipulation to complex business logic SwiftDate maybe the right choice for your next project.
 
@@ -206,6 +191,9 @@ let increment2 = DateComponents.create {
 // generate dates in range by incrementing +1h,30m,10s each new date
 let dates = DateInRegion.enumerateDates(from: fromDate2, to: toDate2, increment: increment2)
 
+// Get all mondays in Jan 2019
+let mondaysInJan2019 = Date.datesForWeekday(.monday, inMonth: 1, ofYear: 2019)
+
 // Altering time components
 let _ = dateA.dateBySet(hour: 10, min: 0, secs: 0)
 

Sources/SwiftDate/Date/Date+Compare.swift

@@ -21,7 +21,7 @@ public extension Date {
 	///   - precision: The precision of the comparison (default is 5 minutes, or 300 seconds).
 	/// - Returns: A boolean; true if close by, false otherwise.
 	public func compareCloseTo(_ refDate: Date, precision: TimeInterval = 300) -> Bool {
-		return (abs(self.timeIntervalSince(refDate)) < precision)
+		return (abs(timeIntervalSince(refDate)) < precision)
 	}
 
 	// MARK: - Extendend Compare
@@ -31,7 +31,7 @@ public extension Date {
 	/// - Parameter compareType: comparison type.
 	/// - Returns: `true` if comparison succeded, `false` otherwise
 	public func compare(_ compareType: DateComparisonType) -> Bool {
-		return self.inDefaultRegion().compare(compareType)
+		return inDefaultRegion().compare(compareType)
 	}
 
 	/// Returns a ComparisonResult value that indicates the ordering of two given dates based on
@@ -41,7 +41,7 @@ public extension Date {
 	/// - parameter granularity: The smallest unit that must, along with all larger units be less for the given dates
 	/// - returns: `ComparisonResult`
 	func compare(toDate refDate: Date, granularity: Calendar.Component) -> ComparisonResult {
-		return self.inDefaultRegion().compare(toDate: refDate.inDefaultRegion(), granularity: granularity)
+		return inDefaultRegion().compare(toDate: refDate.inDefaultRegion(), granularity: granularity)
 	}
 
 	/// Compares whether the receiver is before/before equal `date` based on their components down to a given unit granularity.
@@ -52,7 +52,7 @@ public extension Date {
 	///   - granularity: smallest unit that must, along with all larger units, be less for the given dates
 	/// - Returns: Boolean
 	public func isBeforeDate(_ refDate: Date, orEqual: Bool = false, granularity: Calendar.Component) -> Bool {
-		return self.inDefaultRegion().isBeforeDate(refDate.inDefaultRegion(), orEqual: orEqual, granularity: granularity)
+		return inDefaultRegion().isBeforeDate(refDate.inDefaultRegion(), orEqual: orEqual, granularity: granularity)
 	}
 
 	/// Compares whether the receiver is after `date` based on their components down to a given unit granularity.
@@ -63,7 +63,7 @@ public extension Date {
 	///   - granularity: Smallest unit that must, along with all larger units, be greater for the given dates.
 	/// - Returns: Boolean
 	public func isAfterDate(_ refDate: Date, orEqual: Bool = false, granularity: Calendar.Component) -> Bool {
-		return self.inDefaultRegion().isAfterDate(refDate.inDefaultRegion(), orEqual: orEqual, granularity: granularity)
+		return inDefaultRegion().isAfterDate(refDate.inDefaultRegion(), orEqual: orEqual, granularity: granularity)
 	}
 
 	/// Return true if receiver data is contained in the range specified by two dates.
@@ -75,9 +75,9 @@ public extension Date {
 	///   - granularity: smallest unit that must, along with all larger units, be greater for the given dates.
 	/// - Returns: Boolean
 	public func isInRange(date startDate: Date, and endDate: Date, orEqual: Bool = false, granularity: Calendar.Component = .nanosecond) -> Bool {
-		return self.inDefaultRegion().isInRange(date: startDate.inDefaultRegion(), and: endDate.inDefaultRegion(), granularity: granularity)
+        return self.inDefaultRegion().isInRange(date: startDate.inDefaultRegion(), and: endDate.inDefaultRegion(), orEqual: orEqual, granularity: granularity)
 	}
-	
+
 	/// Compares equality of two given dates based on their components down to a given unit
 	/// granularity.
 	///
@@ -87,7 +87,7 @@ public extension Date {
 	///
 	/// - returns: `true` if the dates are the same down to the given granularity, otherwise `false`
 	public func isInside(date: Date, granularity: Calendar.Component) -> Bool {
-		return (self.compare(toDate: date, granularity: granularity) == .orderedSame)
+		return (compare(toDate: date, granularity: granularity) == .orderedSame)
 	}
 
 	// MARK: - Date Earlier/Later
@@ -97,15 +97,15 @@ public extension Date {
 	/// - Parameter date: The date to compare to self
 	/// - Returns: The date that is earlier
 	public func earlierDate(_ date: Date) -> Date {
-		return (self.timeIntervalSince1970 <= date.timeIntervalSince1970) ? self : date
+		return (timeIntervalSince1970 <= date.timeIntervalSince1970) ? self : date
 	}
 
 	/// Return the later of two dates, between self and a given date.
 	///
 	/// - Parameter date: The date to compare to self
 	/// - Returns: The date that is later
 	public func laterDate(_ date: Date) -> Date {
-		return (self.timeIntervalSince1970 >= date.timeIntervalSince1970) ? self : date
+		return (timeIntervalSince1970 >= date.timeIntervalSince1970) ? self : date
 	}
 
 }

Sources/SwiftDate/Date/Date+Components.swift

@@ -12,25 +12,25 @@ public extension Date {
 
 	/// Indicates whether the month is a leap month.
 	public var isLeapMonth: Bool {
-		return self.inDefaultRegion().isLeapMonth
+		return inDefaultRegion().isLeapMonth
 	}
 
 	/// Indicates whether the year is a leap year.
 	public var isLeapYear: Bool {
-		return self.inDefaultRegion().isLeapYear
+		return inDefaultRegion().isLeapYear
 	}
 
 	/// Julian day is the continuous count of days since the beginning of
 	/// the Julian Period used primarily by astronomers.
 	public var julianDay: Double {
-		return self.inDefaultRegion().julianDay
+		return inDefaultRegion().julianDay
 	}
 
 	/// The Modified Julian Date (MJD) was introduced by the Smithsonian Astrophysical Observatory
 	/// in 1957 to record the orbit of Sputnik via an IBM 704 (36-bit machine)
 	/// and using only 18 bits until August 7, 2576.
 	public var modifiedJulianDay: Double {
-		return self.inDefaultRegion().modifiedJulianDay
+		return inDefaultRegion().modifiedJulianDay
 	}
 
 	/// Return elapsed time expressed in given components since the current receiver and a reference date.
@@ -40,6 +40,6 @@ public extension Date {
 	///   - component: time unit to extract.
 	/// - Returns: value
 	public func getInterval(toDate: Date?, component: Calendar.Component) -> Int64 {
-		return self.inDefaultRegion().getInterval(toDate: toDate?.inDefaultRegion(), component: component)
+		return inDefaultRegion().getInterval(toDate: toDate?.inDefaultRegion(), component: component)
 	}
 }

Sources/SwiftDate/Date/Date+Create.swift

@@ -74,15 +74,15 @@ public extension Date {
 	/// - Parameter style: rounding mode.
 	/// - Returns: rounded date
 	public func dateRoundedAt(at style: RoundDateMode) -> Date {
-		return self.inDefaultRegion().dateRoundedAt(style).date
+		return inDefaultRegion().dateRoundedAt(style).date
 	}
 
 	/// Returns a new DateInRegion that is initialized at the start of a specified unit of time.
 	///
 	/// - Parameter unit: time unit value.
 	/// - Returns: instance at the beginning of the time unit; `self` if fails.
 	public func dateAtStartOf(_ unit: Calendar.Component) -> Date {
-		return self.inDefaultRegion().dateAtStartOf(unit).date
+		return inDefaultRegion().dateAtStartOf(unit).date
 	}
 
 	/// Return a new DateInRegion that is initialized at the start of the specified components
@@ -102,7 +102,7 @@ public extension Date {
 	///
 	/// - returns: A new Moment instance.
 	public func dateAtEndOf(_ unit: Calendar.Component) -> Date {
-		return self.inDefaultRegion().dateAtEndOf(unit).date
+		return inDefaultRegion().dateAtEndOf(unit).date
 	}
 
 	/// Return a new DateInRegion that is initialized at the end of the specified components
@@ -170,7 +170,7 @@ public extension Date {
 	/// - Parameter type: related date to obtain.
 	/// - Returns: instance of the related date.
 	public func dateAt(_ type: DateRelatedType) -> Date {
-		return self.inDefaultRegion().dateAt(type).date
+		return inDefaultRegion().dateAt(type).date
 	}
 
 	/// Create a new date at now and extract the related date using passed rule type.
@@ -181,4 +181,37 @@ public extension Date {
 		return Date().dateAt(type)
 	}
 
+	/// Return the dates for a specific weekday inside given month of specified year.
+	/// Ie. get me all the saturdays of Feb 2018.
+	/// NOTE: Values are returned in order.
+	///
+	/// - Parameters:
+	///   - weekday: weekday target.
+	///   - month: month target.
+	///   - year: year target.
+	///   - region: region target, omit to use `SwiftDate.defaultRegion`
+	/// - Returns: Ordered list of the dates for given weekday into given month.
+	public static func datesForWeekday(_ weekday: WeekDay, inMonth month: Int, ofYear year: Int,
+									   region: Region = SwiftDate.defaultRegion) -> [Date] {
+		let fromDate = DateInRegion(Date(year: year, month: month, day: 1, hour: 0, minute: 0), region: region)
+		let toDate = fromDate.dateAt(.endOfMonth)
+		return DateInRegion.datesForWeekday(weekday, from: fromDate, to: toDate, region: region).map { $0.date }
+	}
+
+	/// Return the dates for a specific weekday inside a specified date range.
+	/// NOTE: Values are returned in order.
+	///
+	/// - Parameters:
+	///   - weekday: weekday target.
+	///   - startDate: from date of the range.
+	///   - endDate: to date of the range.
+	///   - region: region target, omit to use `SwiftDate.defaultRegion`
+	/// - Returns: Ordered list of the dates for given weekday in passed range.
+	public static func datesForWeekday(_ weekday: WeekDay, from startDate: Date, to endDate: Date,
+									   region: Region = SwiftDate.defaultRegion) -> [Date] {
+		let fromDate = DateInRegion(startDate, region: region)
+		let toDate = DateInRegion(endDate, region: region)
+		return DateInRegion.datesForWeekday(weekday, from: fromDate, to: toDate, region: region).map { $0.date }
+	}
+
 }

Sources/SwiftDate/Date/Date+Math.swift

@@ -34,7 +34,3 @@ public func - (lhs: Date, rhs: DateComponents) -> Date {
 public func + (lhs: Date, rhs: TimeInterval) -> Date {
 	return lhs.addingTimeInterval(rhs)
 }
-
-public func - (lhs: Date, rhs: TimeInterval) -> Date {
-	return lhs.addingTimeInterval(-rhs)
-}

Sources/SwiftDate/Date/Date.swift

@@ -51,7 +51,7 @@ extension Date: DateRepresentable {
 
 	/// Extract the date components.
 	public var dateComponents: DateComponents {
-		return self.region.calendar.dateComponents(DateComponents.allComponentsSet, from: self)
+		return region.calendar.dateComponents(DateComponents.allComponentsSet, from: self)
 	}
 
 	/// Initialize a new date object from string expressed in given region.