Керуємо виводом: CustomStringConvertible

1. Для людини й для налагодження

Коли ви робите перші кроки в програмуванні, print() здається магією: «я передав значення — і воно якось саме вивелося». І зазвичай це правда: Swift намагається показати щось корисне. Але щойно ваш struct стає трохи складнішим, звичайний вивід перетворюється на «кашу з полів», у якій уже важко зрозуміти, що саме відбувається і де саме сховалася помилка.

Є дві різні потреби. Перша — показати значення людині, тобто користувачеві або вам самим, так, щоб воно читалося як нормальна фраза, а не як дамп памʼяті. Друга — вивести діагностичну інформацію: більше деталей, щоб під час налагодження не грати в детектива з лупою.

Swift підтримує обидві потреби через два протоколи: CustomStringConvertible і CustomDebugStringConvertible.

Протоколи простими словами: вимоги до типу

Слово «протокол» звучить так, ніби зараз почнуться «контракти, абстракції й архітектура на 40 сторінок», але сьогодні нам це не потрібно. Досить короткого, прикладного розуміння — саме такого, якого вистачає для виводу.

Протокол у Swift — це список вимог до типу. Тобто: «якщо ти хочеш відповідати цьому протоколу, то маєш мати ось такі властивості або методи». Протокол сам по собі не зберігає дані й не створює обʼєкти. Він лише описує, що в типу обовʼязково має бути.

Найважливіший момент для новачка: протокол — це не «магія», а домовленість. Як у спортзалі: якщо на тренажері написано «для ніг», ви все одно можете намагатися качати там біцепс… але це буде дивно й незручно. Протоколи — це написи «для чого цей тип призначений» і «чого від нього очікують».

2. Оголошуємо відповідність протоколу: struct X: SomeProtocol

Синтаксис відповідності протоколу простий: після імені типу ставлять двокрапку й назву протоколу. Це читається майже як звичайна фраза: «структура Book відповідає протоколу CustomStringConvertible».

Важливо: щойно ви написали : CustomStringConvertible, компілятор починає перевіряти: «а ви точно реалізували те, що обіцяли?» Якщо ви забули потрібну властивість або помилилися типом, Swift не стане мовчки терпіти. Він одразу видасть помилку компіляції.

У цьому й перевага протоколів: вони роблять договір перевірюваним.

Ось мінімальна заготовка:

struct Book: CustomStringConvertible {
    var title: String
    var description: String { title }
}

Тут протокол вимагає description: String. Отже, ми маємо дати обчислювану властивість description і повернути рядок.

3. CustomStringConvertible: зрозумілий для людини description

Коли ви пишете print(something), Swift має якось перетворити something на рядок. У стандартній бібліотеці це повʼязано з кількома механізмами, і один із найважливіших — саме CustomStringConvertible.

Що вимагає протокол

CustomStringConvertible вимагає лише одного:

var description: String { get }

Тобто обчислювану властивість лише для читання. Це ідеально відповідає тому, що ви знаєте про обчислювані властивості: це відповідь на запитання, а не нове сховище.

Приклад: виводимо книгу красиво

Продовжимо розвивати нашу модель для навчального застосунку «бібліотека». Поки що без файлів, без мережі, без великих архітектур — лише типи й акуратний вивід.

struct Book: CustomStringConvertible {
    var id: Int
    var title: String
    var author: String

    var description: String {
        "\"\(title)\" — \(author)"
    }

    let b = Book(id: 1, title: "Dune", author: "Frank Herbert")
    print(b) // "Dune" — Frank Herbert

Зверніть увагу на маленьку, але важливу річ: ми друкуємо b, а не b.description. print сам зрозуміє, що треба взяти description, тому що тип узяв на себе цей контракт.

Чому це зручно в struct

У struct ми постійно виводимо значення, щоб перевіряти логіку. І поки застосунок ще маленький, print() — це наш міні-налагоджувач. Якщо вивід неприємно читати, ви починаєте рідше себе перевіряти, а потім ловите баги вже пізно (і починаєте підозрювати кота, що він підміняє вам індекси масиву вночі).

Правило: description має бути детермінованим

«Детермінований» означає: одні й ті самі дані → один і той самий рядок. Якщо ви почнете додавати туди випадкові числа, поточну дату або «ха-ха, сьогодні вівторок», ви самі зламаєте собі налагодження: журнал перестане бути порівнюваним.

Інтерполяція рядків: чому "\(book)" працює

Ми вже активно використовуємо інтерполяцію рядків: "\(x)". Важливо розуміти, що це не просто склейка, а механізм, який теж намагається отримати рядкове представлення значення.

Щойно ви визначили description, ваш тип починає «красиво жити» одразу в кількох місцях — і в print(), і в інтерполяції.

Мініприклад:

let msg = "Взяли книгу: \(b)"
print(msg) // Взяли книгу: "Dune" — Frank Herbert

Звʼязок з обчислюваними властивостями: description обчислюється

Дуже важливо побачити звʼязок: description і debugDescription — це обчислювані властивості. Тобто вони не зберігають рядки, а обчислюють їх щоразу.

Це добре з двох причин. По-перше, рядок ніколи не застаріє: якщо ви змінили title, то description під час наступного читання покаже вже нове значення. По-друге, ви не плодите зайвий стан. Це той самий принцип, що й в обчислюваних властивостях на кшталт area у прямокутника: не зберігати те, що можна надійно порахувати.

Невеликий приклад зі зміною:

var book = Book(id: 2, title: "Untitled", author: "Unknown", isAvailable: false)
print(book) // "Untitled" — Unknown

book.title = "Clean Code"
print(book) // "Clean Code" — Unknown

Рядок змінюється сам, тому що це обчислення.

Не робіть description занадто розумним

Дуже хочеться зробити description суперрозумним: форматувати, відмінювати слова, підставляти емодзі, враховувати локаль, малювати ASCII-арт. Проблема в тому, що тоді description перетворюється на приховану функцію, яка робить купу роботи під час кожного print().

Практичне правило для новачка: description і debugDescription мають бути короткими й передбачуваними. Якщо вам потрібна дія, наприклад складна генерація звіту, краще зробити окремий метод, наприклад makeReport() — так у коді буде видно, що це не просто поле, а окрема операція.

4. CustomDebugStringConvertible: діагностичний debugDescription

Іноді красивої фрази недостатньо. Наприклад, ви хочете побачити id, прапорці, службові поля. Для цього існує CustomDebugStringConvertible.

Приблизно так само, як у житті: «покажіть паспорт» — детально, а «як до вас звертатися?» — коротко. І так, іноді ваш struct поводиться як людина: під час налагодження теж хоче предʼявити документи.

Що вимагає протокол

CustomDebugStringConvertible вимагає:

var debugDescription: String { get }

Ідея та сама: обчислювана властивість, яка повертає рядок.

print vs debugPrint

У Swift є дві функції, які новачкам часто здаються однаковими:

• print(...) — вивід для людини
• debugPrint(...) — вивід для налагодження

Якщо тип реалізує CustomDebugStringConvertible, то debugPrint використовуватиме debugDescription.

description і debugDescription: різниця за змістом

Коли ви вперше бачите дві схожі властивості, хочеться запитати: «а хіба не можна залишити одну?» Можна, але стане гірше. Краще розділити відповідальність.

Головна ідея: description — «візитівка», debugDescription — «техпаспорт».

Практика: робимо і description, і debugDescription

Зробімо так, щоб книга красиво виводилася для користувача, але в налагодженні ми бачили більше деталей.

struct Book: CustomStringConvertible, CustomDebugStringConvertible {
    var id: Int
    var title: String
    var author: String
    var isAvailable: Bool

    var description: String {
        "\"\(title)\" — \(author)"
    }

    var debugDescription: String {
        "Книга(id: \(id), назва: \(title), автор: \(author), доступність: \(isAvailable))"
    }
}

let b = Book(id: 1, title: "Dune", author: "Frank Herbert", isAvailable: true)
print(b)      // "Dune" — Frank Herbert
debugPrint(b) // Книга(id: 1, назва: Dune, автор: Frank Herbert, доступність: true)

Це дуже практичний підхід: користувацьке повідомлення коротке, а діагностичне — максимально корисне.

Історична довідка: від Printable до CustomStringConvertible

Раніше в Swift були протоколи Printable і DebugPrintable, але потім їх перейменували на зрозуміліші CustomStringConvertible і CustomDebugStringConvertible.

Сенс перейменування доволі людяний: слово «Printable» звучить так, ніби це про принтер, який закінчує чорнило рівно перед дедлайном. А «convertible» підкреслює ідею: ми подаємо значення як рядок.

5. Приватність і політика виводу

Коли ви керуєте description, у вас зʼявляється влада. А влада — це відповідальність.

Якщо у вашому типі є чутливі дані — пароль, токен, код відновлення, — то друкувати їх у description за замовчуванням — погана ідея. Навіть якщо ви зараз пишете навчальний проєкт, звичка виводити секрети в логи потім боляче відгукнеться в реальній розробці.

Зробімо мініприклад: читабельний вивід без секрету.

struct Password: CustomStringConvertible, CustomDebugStringConvertible {
    var value: String

    var description: String { "Password(****)" }
    var debugDescription: String { "Пароль(довжина: \(value.count))" }
}

let p = Password(value: "qwerty123")
print(p)      // Password(****)
debugPrint(p) // Пароль(довжина: 9)

Тут ми не розкриваємо значення, але залишаємо корисну діагностику — довжину.

6. Вбудовуємо в LibraryCLI: виводимо каталог

Зберемо невеликий фрагмент, схожий на те, що ми справді робитимемо в консольній бібліотеці: виводимо список книг і хочемо, щоб кожен рядок був зрозумілим.

struct Library {
    var books: [Book]

    func printCatalog() {
        for book in books {
            print(book) // використовує description
        }
    }
}

let lib = Library(books: [
    Book(id: 1, title: "Dune", author: "Frank Herbert", isAvailable: true),
    Book(id: 2, title: "Clean Code", author: "Robert C. Martin", isAvailable: false)
])

lib.printCatalog()
// "Dune" — Frank Herbert
// "Clean Code" — Robert C. Martin

У цей момент printCatalog() стає дуже читабельним: він виводить книги, і ми справді бачимо книги, а не внутрішній устрій структури.

7. Чому це контракт: компілятор перевіряє

Якщо ви оголосили відповідність протоколу, але забули потрібну властивість, Swift не дасть скомпілювати код. Це важлива дисципліна: ви не можете майже відповідати контракту.

Уявімо, що ви написали:

struct Book: CustomStringConvertible {
    var title: String
    // забули description
}

Компілятор скаже приблизно: «тип не відповідає протоколу». І це чудово: помилка ловиться одразу, а не перетворюється на «чому print виводить не те».

8. Типові помилки

Помилка №1: рекурсивний description через self.
Найпоширеніший сценарій — написати "\(self)" всередині description. Це виглядає красиво, але логічно означає: щоб отримати рядок, знову отримай рядок. Так ви потрапляєте в нескінченну рекурсію. Правильний підхід — будувати рядок із конкретних збережених властивостей: id, name, title тощо.

Помилка №2: плутати description і debugDescription та робити їх однаковими «про всяк випадок».
Якщо обидві властивості друкують одне й те саме, ви втрачаєте сенс розділення. У результаті або користувач бачить занадто багато технічних деталей, або налагодження виходить занадто бідним. Корисна звичка: description — коротко й по суті, debugDescription — з контекстом (id, прапорці, службові поля).

Помилка №3: друкувати секрети й персональні дані.
Новачки часто вставляють у description усе підряд, включно з паролями, токенами або приватними полями. Навіть у навчальному проєкті варто тренувати правильну політику виводу: секрети маскуємо, а в debug-виводі даємо безпечні характеристики, наприклад довжину рядка, а не вміст.

Помилка №4: робити description недетермінованим.
Якщо description залежить від випадкових чисел або поточного часу, ваші журнали перестають бути порівнюваними, а налагодження — відтворюваним. Особливо неприємно це в моменти, коли ви намагаєтеся зрозуміти, чому одна й та сама дія іноді дає різний результат. Для виводу обирайте стабільні дані самого екземпляра.

Помилка №5: перетворювати обчислюваний description на важку операцію.
Якщо всередині description ви починаєте робити складні обчислення, великі цикли або звернення до зовнішніх ресурсів, то звичайний print(book) несподівано стає дорогою операцією. Це дуже підступна проблема: ви думаєте, що просто друкуєте значення, а насправді запускаєте мініалгоритм. Тримайте description коротким, а складну генерацію тексту виносьте в окремі методи.