Merge pull request #36 from orchetect/dev

Dev merge

Package.swift

@@ -22,6 +22,7 @@ let package = Package(
 
     dependencies: [
         // testing-only dependency
+        .package(url: "https://github.com/orchetect/XCTestUtils", from: "1.0.0"),
         .package(url: "https://github.com/orchetect/SegmentedProgress", from: "1.0.1")
     ],
 
@@ -32,7 +33,7 @@ let package = Package(
 
         .testTarget(
             name: "OTCoreTests",
-            dependencies: ["OTCore", "SegmentedProgress"])
+            dependencies: ["OTCore", "XCTestUtils", "SegmentedProgress"])
     ]
 
 )

Sources/OTCore/Abstractions/Clamped Property Wrapper.swift

@@ -0,0 +1,114 @@
+//
+//  Clamped Property Wrapper.swift
+//  OTCore • https://github.com/orchetect/OTCore
+//
+
+import Foundation
+
+/// **OTCore:**
+/// Property wrapper that clamps the wrapped value to a given range.
+@propertyWrapper
+public struct Clamped<Value> where Value : Comparable {
+
+    var min: Value?
+    var max: Value?
+    private var value: Value
+
+    public var wrappedValue: Value {
+        get {
+            value
+        }
+        set {
+            value = Self.clamping(newValue, min: min, max: max)
+        }
+    }
+
+    internal static func clamping(_ value: Value,
+                                  min: Value?,
+                                  max: Value?) -> Value {
+
+        if let min = min {
+            if let max = max {
+                return value.clamped(to: min...max)
+            } else {
+                return value.clamped(to: min...)
+            }
+        } else if let max = max {
+            return value.clamped(to: ...max)
+        } else {
+            return value
+        }
+
+    }
+
+    public init(wrappedValue defaultValue: Value,
+                to range: ClosedRange<Value>) {
+
+        let formRange = range.absoluteBounds
+
+        self.min = formRange.min
+        self.max = formRange.max
+
+        self.value = Self.clamping(defaultValue,
+                                   min: formRange.min,
+                                   max: formRange.max)
+
+    }
+
+    public init(wrappedValue defaultValue: Value,
+                to range: Range<Value>) where Value : Strideable {
+
+        let formRange = range.absoluteBounds
+
+        self.min = formRange.min
+        self.max = formRange.max
+
+        self.value = Self.clamping(defaultValue,
+                                   min: formRange.min,
+                                   max: formRange.max)
+
+    }
+
+    public init(wrappedValue defaultValue: Value,
+                to range: PartialRangeUpTo<Value>) where Value : Strideable {
+
+        let formRange = range.absoluteBounds
+
+        self.min = formRange.min
+        self.max = formRange.max
+
+        self.value = Self.clamping(defaultValue,
+                                   min: formRange.min,
+                                   max: formRange.max)
+
+    }
+
+    public init(wrappedValue defaultValue: Value,
+                to range: PartialRangeThrough<Value>) {
+
+        let formRange = range.absoluteBounds
+
+        self.min = formRange.min
+        self.max = formRange.max
+
+        self.value = Self.clamping(defaultValue,
+                                   min: formRange.min,
+                                   max: formRange.max)
+
+    }
+
+    public init(wrappedValue defaultValue: Value,
+                to range: PartialRangeFrom<Value>) {
+
+        let formRange = range.absoluteBounds
+
+        self.min = formRange.min
+        self.max = formRange.max
+
+        self.value = Self.clamping(defaultValue,
+                                   min: formRange.min,
+                                   max: formRange.max)
+
+    }
+
+}

Sources/OTCore/Abstractions/Collection Set-Like Methods.swift

@@ -31,9 +31,9 @@ extension Collection where Self: RangeReplaceableCollection,
 
     /// **OTCore:**
     /// Similar behavior to a Set, this will append the element to the end of the collection if it does not already exist in the collection.
-    @inlinable public mutating
-    func insert(_ element: Element,
-                position: CollectionPosition = .default) {
+    @inlinable @_disfavoredOverload
+    public mutating func insert(_ element: Element,
+                                position: CollectionPosition = .default) {
 
         if !contains(element) {
             switch position {
@@ -49,8 +49,9 @@ extension Collection where Self: RangeReplaceableCollection,
 
     /// **OTCore:**
     /// Similar behavior to a Set, if the element exists in the collection this will replace it at its current index with the new element. If it doesn't exist, it will either be replaced, reordered to the start, or reordered to the end of the collection based upon the `position` specified.
-    @inlinable public mutating func update(with newMember: Element,
-                                           position: CollectionPosition = .default) {
+    @inlinable @_disfavoredOverload
+    public mutating func update(with newMember: Element,
+                                position: CollectionPosition = .default) {
 
         if let index = firstIndex(of: newMember) {
             switch position {
@@ -76,15 +77,18 @@ extension Collection where Self: RangeReplaceableCollection,
 
     /// **OTCore:**
     /// Similar behavior to a Set, but removes all instances of the element.
-    @inlinable public mutating func removeAll(_ member: Element) {
+    @inlinable @_disfavoredOverload
+    public mutating func removeAll(_ member: Element) {
 
         removeAll(where: { $0 == member })
 
     }
 
     /// **OTCore:**
     /// Similar behavior to a Set, join two collections together and where elements are equal, retain the existing element.
-    @inlinable public func union<S>(_ other: S) -> Self where Element == S.Element, S : Sequence {
+    @inlinable @_disfavoredOverload
+    public func union<S>(_ other: S) -> Self
+    where Element == S.Element, S : Sequence {
 
         var newCollection = self
         other.forEach {
@@ -98,7 +102,9 @@ extension Collection where Self: RangeReplaceableCollection,
 
     /// **OTCore:**
     /// Similar behavior to a Set, join two collections together and where elements are equal, retain the existing element.
-    @inlinable public mutating func formUnion<S>(_ other: S) where Element == S.Element, S : Sequence {
+    @inlinable @_disfavoredOverload
+    public mutating func formUnion<S>(_ other: S)
+    where Element == S.Element, S : Sequence {
 
         other.forEach {
             if !contains($0) {
@@ -110,7 +116,9 @@ extension Collection where Self: RangeReplaceableCollection,
 
     /// **OTCore:**
     /// Similar behavior to a Set, join two collections together and where elements are equal, replace the existing element with the new element preserving the original index.
-    @inlinable public func union<S>(updating other: S) -> Self where Element == S.Element, S : Sequence {
+    @inlinable @_disfavoredOverload
+    public func union<S>(updating other: S) -> Self
+    where Element == S.Element, S : Sequence {
 
         var newCollection = self
         other.forEach {
@@ -122,7 +130,9 @@ extension Collection where Self: RangeReplaceableCollection,
 
     /// **OTCore:**
     /// Similar behavior to a Set, join two collections together and where elements are equal, replace the existing element with the new element preserving the original index.
-    @inlinable public mutating func formUnion<S>(updating other: S) where Element == S.Element, S : Sequence {
+    @inlinable @_disfavoredOverload
+    public mutating func formUnion<S>(updating other: S)
+    where Element == S.Element, S : Sequence {
 
         other.forEach {
             update(with: $0)

Sources/OTCore/Abstractions/DateComponents from String.swift

@@ -38,6 +38,7 @@ extension DateComponents {
     ///
     /// - "21Oct2020"
     /// - "2020Oct21"
+    @_disfavoredOverload
     public init?(string: String) {
 
         self.init()
@@ -205,6 +206,7 @@ extension String {
 
     /// **OTCore:**
     /// Attempts to parse Year, Month and Day components from an unformatted date string using simple heuristics.
+    @_disfavoredOverload
     public var dateComponents: DateComponents? {
 
         DateComponents(string: self)

Sources/OTCore/Abstractions/String Parsing.swift

@@ -9,6 +9,7 @@ extension String {
 
     /// **OTCore:**
     /// Returns true if the string is a valid email address.
+    @_disfavoredOverload
     public var isValidEmailAddress: Bool {
 
         // [email protected]

Sources/OTCore/Abstractions/String Title Case.swift

@@ -30,6 +30,7 @@ extension String {
     /// (English localization only at this time.)
     ///
     @available(macOS 10.11, *)
+    @_disfavoredOverload
     public var titleCased: String {
 
         var words =

Sources/OTCore/Abstractions/String Wrapped.swift

@@ -7,15 +7,17 @@ extension String {
 
     /// **OTCore:**
     /// Returns the string adding the passed `with` parameter as a prefix and suffix.
-    @inlinable public func wrapped(with prefixAndSuffix: String) -> String {
+    @inlinable @_disfavoredOverload
+    public func wrapped(with prefixAndSuffix: String) -> String {
 
         prefixAndSuffix + self + prefixAndSuffix
 
     }
 
     /// **OTCore:**
     /// Returns the string adding the passed `with` parameter as a prefix and suffix.
-    @inlinable public func wrapped(with prefixAndSuffix: StringWrappedEnclosingType) -> String {
+    @inlinable @_disfavoredOverload
+    public func wrapped(with prefixAndSuffix: StringWrappedEnclosingType) -> String {
 
         switch prefixAndSuffix {
         case .parentheses:      return "(" + self + ")"
@@ -32,13 +34,13 @@ extension String {
     /// Type describing a pair of enclosing brackets/braces or similar characters that are different for prefix and suffix.
     public enum StringWrappedEnclosingType {
 
-        /// ( ), aka parens
+        /// ( ) a.k.a. parens
         case parentheses
 
-        /// [ ], aka square brackets
+        /// [ ] a.k.a. square brackets
         case brackets
 
-        /// { }, aka curly braces
+        /// { } a.k.a. curly braces
         case braces
 
         /// < >
@@ -55,16 +57,29 @@ extension String {
     /// **OTCore:**
     /// Syntactic sugar. Returns the string wrapped with parentheses: `( )`.
     /// Same as `self.wrapped(with: .parentheses)`
-    @inlinable public var parens: Self {
+    @inlinable @_disfavoredOverload
+    public var parenthesized: Self {
 
         wrapped(with: .parentheses)
 
     }
 
+    /// **OTCore:**
+    /// Syntactic sugar. Returns the string wrapped with parentheses: `( )`.
+    /// Same as `self.wrapped(with: .parentheses)`
+    @inlinable @_disfavoredOverload
+    @available(*, unavailable, renamed: "parenthesized")
+    public var parens: Self {
+
+        parenthesized
+
+    }
+
     /// **OTCore:**
     /// Syntactic sugar. Returns the string wrapped with single quote marks: `' '`.
     /// Same as `self.wrapped(with: .singleQuotes)`
-    @inlinable public var singleQuoted: Self {
+    @inlinable @_disfavoredOverload
+    public var singleQuoted: Self {
 
         wrapped(with: .singleQuotes)
 
@@ -73,7 +88,8 @@ extension String {
     /// **OTCore:**
     /// Syntactic sugar. Returns the string wrapped with double quote marks: `" "`.
     /// Same as `self.wrapped(with: .quotes)`
-    @inlinable public var quoted: Self {
+    @inlinable @_disfavoredOverload
+    public var quoted: Self {
 
         wrapped(with: .quotes)