From 012a475cc03cfa0c20ab15f2ae9bfb821a30bec2 Mon Sep 17 00:00:00 2001 From: Sindre Sorhus Date: Mon, 12 Jul 2021 14:24:20 +0200 Subject: [PATCH] Minor documentation tweaks --- .../Defaults/Defaults+AnySerializable.swift | 22 ++++++----- readme.md | 39 +++++++++++-------- 2 files changed, 35 insertions(+), 26 deletions(-) diff --git a/Sources/Defaults/Defaults+AnySerializable.swift b/Sources/Defaults/Defaults+AnySerializable.swift index addb667..5842970 100644 --- a/Sources/Defaults/Defaults+AnySerializable.swift +++ b/Sources/Defaults/Defaults+AnySerializable.swift @@ -3,18 +3,22 @@ import Foundation extension Defaults { /** - Type-erased wrappers for `Defaults.Serializable` values. - It can be used when the user wants to create an `Any` value that conforms to `Defaults.Serializable`. - It will have an internal property `value` which` should always be a UserDefaults natively supported type. + Type-erased wrapper for `Defaults.Serializable` values. - `get` will deserialize internal value to the type that user explicit in the function parameter. + It can be useful when you need to create an `Any` value that conforms to `Defaults.Serializable`. + + It will have an internal property `value` which should always be a `UserDefaults` natively supported type. + + `get` will deserialize the internal value to the type that user specify in the function parameter. ``` let any = Defaults.Key("independentAnyKey", default: 121_314) - print(Defaults[any].get(Int.self)) //=> 121_314 + + print(Defaults[any].get(Int.self)) + //=> 121_314 ``` - - Note: the only way to assign a non-serializable value is using `ExpressibleByArrayLiteral` or `ExpressibleByDictionaryLiteral` to assign a type that is not UserDefaults natively supported type. + - Note: The only way to assign a non-serializable value is using `ExpressibleByArrayLiteral` or `ExpressibleByDictionaryLiteral` to assign a type that is not a `UserDefaults` natively supported type. ``` private enum mime: String, Defaults.Serializable { @@ -25,7 +29,7 @@ extension Defaults { let any = Defaults.Key("independentAnyKey", default: [mime.JSON]) ``` */ - public struct AnySerializable: Defaults.Serializable { + public struct AnySerializable: Serializable { var value: Any public static let bridge = AnyBridge() @@ -99,7 +103,7 @@ extension Defaults.AnySerializable: Hashable { } extension Defaults.AnySerializable: Equatable { - public static func == (lhs: Defaults.AnySerializable, rhs: Defaults.AnySerializable) -> Bool { + public static func == (lhs: Self, rhs: Self) -> Bool { switch (lhs.value, rhs.value) { case let (lhs as Data, rhs as Data): return lhs == rhs @@ -188,7 +192,7 @@ extension Defaults.AnySerializable: ExpressibleByDictionaryLiteral { } extension Defaults.AnySerializable: _DefaultsOptionalType { - /// Since nil cannot assign to `Any`, we use `Void` instead of `nil`. + // Since `nil` cannot be assigned to `Any`, we use `Void` instead of `nil`. public var isNil: Bool { value is Void } } diff --git a/readme.md b/readme.md index b6aa877..97e53e7 100644 --- a/readme.md +++ b/readme.md @@ -434,11 +434,11 @@ Defaults.AnySerializable(_ value: Value) Type: `class` -Type-erased wrappers for `Defaults.Serializable` values. +Type-erased wrapper for `Defaults.Serializable` values. -- `get() -> Value?`: Retrieve the value which type is `Value` from the UserDefaults. -- `get(_: Value.Type) -> Value?`: Specific the `Value` that you want to retrieve, this will be useful in some ambiguous cases. -- `set(_ newValue: Value)`: Set newValue into `Defaults.AnySerializable`. +- `get() -> Value?`: Retrieve the value which type is `Value` from UserDefaults. +- `get(_: Value.Type) -> Value?`: Specify the `Value` you want to retrieve. This can be useful in some ambiguous cases. +- `set(_ newValue: Value)`: Set a new value for `Defaults.AnySerializable`. #### `Defaults.reset(keys…)` @@ -678,18 +678,17 @@ Defaults[.dictionaryUser]["user"]?.name //=> "Hello" ### Dynamic value -There might be situations where you want to use `[String: Any]` directly. -But `Defaults` need its value to conform to `Defaults.Serializable`, so here is a class `Defaults.AnySerializable` to overcome this limitation. +There might be situations where you want to use `[String: Any]` directly, but `Defaults` need its values to conform to `Defaults.Serializable`. The type-eraser `Defaults.AnySerializable` helps overcome this limitation. -`Defaults.AnySerializable` only available for `Value` which conforms to `Defaults.Serializable`. +`Defaults.AnySerializable` is only available for values that conform to `Defaults.Serializable`. -Warn: The type erasure should only be used when there's no other way to handle it because it has much worse performance. It should only be used in wrapped types. For example, wrapped in `Array`, `Set` or `Dictionary`. +Warning: The type-eraser should only be used when there's no other way to handle it because it has much worse performance. It should only be used in wrapped types. For example, wrapped in `Array`, `Set` or `Dictionary`. #### Primitive type -`Defaults.AnySerializable` conforms to `ExpressibleByStringLiteral`, `ExpressibleByIntegerLiteral`, `ExpressibleByFloatLiteral`, `ExpressibleByBooleanLiteral`, `ExpressibleByNilLiteral`, `ExpressibleByArrayLiteral` and `ExpressibleByDictionaryLiteral`. +`Defaults.AnySerializable` conforms to `ExpressibleByStringLiteral`, `ExpressibleByIntegerLiteral`, `ExpressibleByFloatLiteral`, `ExpressibleByBooleanLiteral`, `ExpressibleByNilLiteral`, `ExpressibleByArrayLiteral`, and `ExpressibleByDictionaryLiteral`. -So it can assign directly with these primitive types. +Which means you can assign these primitive types directly: ```swift let any = Defaults.Key("anyKey", default: 1) @@ -698,9 +697,9 @@ Defaults[any] = "🦄" #### Other types -##### Using `get`, `set` +##### Using `get` and `set` -For other types, you will have to assign it like this. +For other types, you will have to assign it like this: ```swift enum mime: String, Defaults.Serializable { @@ -711,18 +710,23 @@ enum mime: String, Defaults.Serializable { let any = Defaults.Key("anyKey", default: [Defaults.AnySerializable(mime.JSON)]) if let mimeType: mime = Defaults[any].get() { - print(mimeType.rawValue) //=> "application/json" + print(mimeType.rawValue) + //=> "application/json" } + Defaults[any].set(mime.STREAM) + if let mimeType: mime = Defaults[any].get() { - print(mimeType.rawValue) //=> "application/octet-stream" + print(mimeType.rawValue) + //=> "application/octet-stream" } ``` -#### Wrapped in `Array`, `Set`, `Dictionary` +#### Wrapped in `Array`, `Set`, or `Dictionary` -`Defaults.AnySerializable` also support the above types wrapped in `Array`, `Set`, `Dictionary` -Here is the example for `[String: Defaults.AnySerializable]`. +`Defaults.AnySerializable` also support the above types wrapped in `Array`, `Set`, `Dictionary`. + +Here is the example for `[String: Defaults.AnySerializable]`: ```swift extension Defaults.Keys { @@ -744,6 +748,7 @@ if let value: String = Defaults[.magic]["unicorn"]?.get() { Defaults[.magic]["number"] = 3 Defaults[.magic]["boolean"] = true Defaults[.magic]["enum"] = Defaults.AnySerializable(mime.JSON) + if let mimeType: mime = Defaults[.magic]["enum"]?.get() { print(mimeType.rawValue) //=> "application/json"