Swift Property Wrappers

Если вы использовали SwiftUI, то наверняка обращали внимание на такие ключевые слова, как @ObservedObject, @EnvironmentObject, @FetchRequest и так далее. Property Wrappers (далее «обёртки свойств») — новая возможность языка Swift 5.1. Эта статья поможет вам понять, откуда же взялись все конструкции с @, как использовать их в SwiftUI и в своих проектах.

Автор перевода: Евгений Заволжанский, разработчик FunCorp.

Прим.пер.: К моменту подготовки перевода часть исходного кода оригинальной статьи потеряла свою актуальность из-за изменений в языке, поэтому некоторые примеры кода намеренно заменены.

Обёртки свойств впервые были представлены на форумах Swift ещё в марте 2019 года, за несколько месяцев до объявления SwiftUI. В своём первоначальном предложении Дуглас Грегор ( Douglas Gregor), член команды Swift Core, описал эту конструкцию (тогда она называлась property delegates) как «доступное пользователю обобщение функциональности, в настоящее время предоставляемой такой языковой конструкцией, как, например, lazy».

Если свойство объявлено с ключевым словом lazy, это значит, что оно будет инициализировано при первом обращении к нему. Например, отложенную инициализацию свойства можно было бы реализовать с помощью закрытого свойства, доступ к которому осуществляется через вычисляемое свойство. Но с помощью ключевого слова lazy это сделать гораздо легче.

struct Structure {     // Отложенная инициализация свойства с помощью lazy     lazy var deferred = …      // Аналогичная реализация с помощью закрытого и вычисляемого свойства     private var _deferred: Type?     var deferred: Type {         get {             if let value = _deferred { return value }             let initialValue = …             _deferred = initialValue             return initialValue         }          set {             _deferred = newValue         }     } }

В SE-0258: Property Wrapper отлично объясняется дизайн и реализация обёрток свойств. Поэтому, вместо того чтобы пытаться улучшить описание в официальной документации, рассмотрим несколько примеров, которые можно реализовать с помощью обёрток свойств:

• ограничение значений свойств;
• преобразование значений при изменении свойств;
• изменение семантики равенства и сравнения свойств;
• логирование доступа к свойству. 

Ограничение значений свойств

SE-0258: Property Wrapper даёт несколько практических примеров, включая @Clamping, @Copying, @Atomic, @ThreadSpecific, @Box, @UserDefault. Рассмотрим обёртку @Clamping, которая позволяет ограничить максимальное или минимальное значение свойства.

@propertyWrapper struct Clamping<Value: Comparable> {     var value: Value     let range: ClosedRange<Value>      init(initialValue value: Value, _ range: ClosedRange<Value>) {         precondition(range.contains(value))         self.value = value         self.range = range     }      var wrappedValue: Value {         get { value }         set { value = min(max(range.lowerBound, newValue), range.upperBound) }     } }

@Clamping можно использовать, например, для моделирования кислотности раствора, величина которой может принимать значение от 0 до 14.

struct Solution {     @Clamping(0...14) var pH: Double = 7.0 }  let carbonicAcid = Solution(pH: 4.68)

Попытка установить значение pH, выходящее за диапазон от (0...14), приведёт к тому, что свойство примет значение, ближайшее к минимуму или максимуму интервала.

let superDuperAcid = Solution(pH: -1) superDuperAcid.pH // 0

Обёртки свойств могут использоваться при реализации других обёрток свойств. Например, обёртка @UnitInterval ограничивает значение свойства интервалом (0...1), используя @Clamping(0...1):

@propertyWrapper struct UnitInterval<Value: FloatingPoint> {     @Clamping(0...1)     var wrappedValue: Value = .zero      init(initialValue value: Value) {         self.wrappedValue = value     } }

Похожие идеи

• @Positive / @NonNegative указывает, что значение может быть либо положительным, либо отрицательным числом.
• @NonZero указывает, что значение свойства не может быть равно 0.
• @Validated или @Whitelisted / @Blacklisted ограничивает значение свойства определёнными значениями.

Преобразование значений при изменении свойств

Валидация значений текстовых полей — постоянная головная боль разработчиков приложений. Существует очень много вещей, которые нужно отслеживать: от банальностей типа кодировки до злонамеренных попыток ввести код через текстовое поле. Рассмотрим применение обёртки свойства для удаления пробелов, которые ввёл пользователь в начале и в конце строки.

import Foundation  let url = URL(string: " https://habrahabr.ru") // nil  let date = ISO8601DateFormatter().date(from: " 2019-06-24") // nil  let words = " Hello, world!".components(separatedBy: .whitespaces) words.count // 3

Foundation предлагает метод trimmingCharacters(in:), с помощью которого можно удалить пробелы в начале и в конце строки. Можно вызывать этот метод всегда, когда нужно гарантировать правильность ввода, но это не очень удобно. Для этого можно использовать обёртку свойства.

import Foundation  @propertyWrapper struct Trimmed {     private(set) var value: String = ""      var wrappedValue: String {         get { return value }         set { value = newValue.trimmingCharacters(in: .whitespacesAndNewlines) }     }      init(initialValue: String) {         self.wrappedValue = initialValue     } }

struct Post {     @Trimmed var title: String     @Trimmed var body: String }  let quine = Post(title: "  Swift Property Wrappers  ", body: "…") quine.title // "Swift Property Wrappers" — без пробелов в начале и в конце  quine.title = "      @propertyWrapper     " // "@propertyWrapper"

Похожие идеи

• @Transformed  применяет ICU-преобразование к введённой строке.
• @Rounded / @Truncated округляет или урезает значение строки.

Изменение семантики равенства и сравнения свойств

В Swift две строки равны, если они канонично эквивалентны, т.е. содержат одинаковые символы. Но допустим, мы хотим, чтобы строковые свойства были равны без учёта регистра символов, которые они содержат.

@CaseInsensitive реализует оболочку для свойств, имеющих тип String или SubString.

import Foundation  @propertyWrapper struct CaseInsensitive<Value: StringProtocol> {     var wrappedValue: Value }  extension CaseInsensitive: Comparable {     private func compare(_ other: CaseInsensitive) -> ComparisonResult {         wrappedValue.caseInsensitiveCompare(other.wrappedValue)     }      static func == (lhs: CaseInsensitive, rhs: CaseInsensitive) -> Bool {         lhs.compare(rhs) == .orderedSame     }      static func < (lhs: CaseInsensitive, rhs: CaseInsensitive) -> Bool {         lhs.compare(rhs) == .orderedAscending     }      static func > (lhs: CaseInsensitive, rhs: CaseInsensitive) -> Bool {         lhs.compare(rhs) == .orderedDescending     } }

let hello: String = "hello" let HELLO: String = "HELLO"  hello == HELLO // false CaseInsensitive(wrappedValue: hello) == CaseInsensitive(wrappedValue: HELLO) // true

Похожие идеи

• @Approximate для приблизительного сравнения свойств, имеющих тип Double или Float.
• @Ranked для свойств, значения которых имеют порядок (например, ранг игральных карт).

Логирование доступа к свойству

@Versioned позволит перехватывать присвоенные значения и запоминать, когда они были установлены.

import Foundation  @propertyWrapper struct Versioned<Value> {     private var value: Value     private(set) var timestampedValues: [(Date, Value)] = []      var wrappedValue: Value {         get { value }          set {             defer { timestampedValues.append((Date(), value)) }             value = newValue         }     }      init(initialValue value: Value) {         self.wrappedValue = value     } }

Класс ExpenseReport позволяет сохранить временные метки состояний обработки отчёта о расходах.

class ExpenseReport {     enum State { case submitted, received, approved, denied }      @Versioned var state: State = .submitted }

Но пример выше демонстрирует серьёзное ограничение в текущей реализации обёрток свойств, которое вытекает из ограничения Swift: свойства не могут генерировать исключения. Если бы мы хотели добавить в @Versioned ограничение для предотвращения изменения значения на .approved после того, как оно приняло значения .denied, то наилучший вариант — fatalError(), который плохо подходит для реальных приложений.

class ExpenseReport {     @Versioned var state: State = .submitted {         willSet {             if newValue == .approved,                 $state.timestampedValues.map { $0.1 }.contains(.denied)             {                 fatalError("Ошибка")             }         }     } }  var tripExpenses = ExpenseReport() tripExpenses.state = .denied tripExpenses.state = .approved // Fatal error: «ошибка» и краш приложения.

Похожие идеи

• @Audited для логирования доступа к свойству.
• @UserDefault для инкапсулирования механизма чтения и сохранения данных в UserDefaults.

Ограничения

Свойства не могут генерировать исключения

Как уже было сказано, обёртки свойств могут использовать лишь несколько методов обработки недопустимых значений:

• игнорировать их;
• завершить работу приложения при помощи fatalError().

Свойства, имеющие обёртку, не могут быть помечены атрибутом `typealias`

Пример @UnitInterval выше, свойство которого ограничено интервалом (0...1), не может быть объявлен как

typealias UnitInterval = Clamping(0...1)

Ограничение на использование композиции из нескольких обёрток свойств

Композиция обёрток свойств — не коммутативная операция: на поведение будет влиять порядок объявления. Рассмотрим пример, в котором свойство slug, представляющее собой url поста в блоге, нормализуется. В этом случае результат нормализации будет различаться в зависимости от того, когда пробелы будут заменены тире, до или после удаления пробелов. Поэтому на данный момент композиция из нескольких обёрток свойств не поддерживается.

@propertyWrapper struct Dasherized {     private(set) var value: String = ""      var wrappedValue: String {         get { value }         set { value = newValue.replacingOccurrences(of: " ", with: "-") }     }      init(initialValue: String) {         self.wrappedValue = initialValue     } }  struct Post {     …     @Dasherized @Trimmed var slug: String // error: multiple property wrappers are not supported }

Однако это ограничение можно обойти, если использовать вложенные обёртки свойств.

@propertyWrapper struct TrimmedAndDasherized {     @Dasherized     private(set) var value: String = ""      var wrappedValue: String {         get { value }         set { value = newValue.trimmingCharacters(in: .whitespacesAndNewlines) }     }      init(initialValue: String) {         self.wrappedValue = initialValue     } }  struct Post {     …     @TrimmedAndDasherized var slug: String }

Другие ограничения обёрток свойств

• Нельзя использовать внутри протокола.
• Экземпляр свойства с обёрткой не может быть объявлен в enum.
• Свойство с обёрткой, объявленное внутри класса, не может быть переопределено другим свойством.
• Свойство с обёрткой не может быть lazy, @NSCopying, @NSManaged, weak или unowned.
• Свойство с обёрткой  должно быть единственным в рамках своего определения (т.е. нельзя @Lazy var (x, y) = /* ... */ ).
• У свойства с обёрткой  нельзя определить getter и setter.
• Типы у свойства wrappedValue и у переменной wrappedValue в init(wrappedValue:) должны иметь тот же уровень доступа, что и тип обёртки свойства.
• Тип свойство projectedValue должен иметь тот же уровень доступа, что и тип обёртки свойства.
• init() должен иметь тот же уровень доступа, что и тип обёртки свойства.

Давайте подытожим. Обёртки свойств в Swift предоставляют авторам библиотек доступ к высокоуровневому поведению, ранее зарезервированному для языковых функций. Их потенциал для улучшения читаемости и уменьшения сложности кода огромен, и мы только поверхностно рассмотрели возможности этого инструмента.

Используете ли вы обёртки свойств в своих проектах? Пишите в комментариях!