Завершальні операції виводу
Конвеєр нічого не робить, доки не виконається завершальна операція. Вони виконують блокувальну нативну роботу поза кооперативним виконавцем Swift, є async і саме там викидаються помилки декодування, пікселів та кодування. Скасування завдання, що викликає операцію, зупиняє роботу й викидає CancellationError; конвеєр лишається чинним і може бути виконаний знову.
| Операція | Повертає | Для чого |
|---|---|---|
data() |
Output (data, info) |
Байти в пам’яті: тіло HTTP, стовпець бази даних. Потребує кодувальника. |
write(to:) |
OutputInfo |
Файл; записується через тимчасовий файл і перейменовується. |
writeChunks(chunkSize:_:) |
OutputInfo |
Потокова передача зі зворотним тиском. Потребує кодувальника. |
raw(_:premultiplied:background:) |
RawImage |
Пікселі без кодування (Необроблені пікселі). Кодувальника не має бути обрано. |
metadata() |
ImageMetadata |
Заголовок джерела (Перевірка). |
OutputInfo містить format, width, height, byteCount і, для PDF, pdf (pageCount, pageWidth, pageHeight).
let image = try Hokusai(url: URL(fileURLWithPath: "scene.png")).resize(width: 400)
// data(): bytes and facts about them. An encoder must be selected.let output = try await image.webp(quality: 80).data()print("data():", output.info.format.rawValue, output.info.width, "×", output.info.height, output.info.byteCount, "bytes")
// write(to:) infers the encoder from the extension only when none is selected...let inferred = try await image.write(to: URL(fileURLWithPath: "inferred.webp"))print("inferred:", inferred.format.rawValue)// ...an explicit encoder always wins, whatever the extension says.let explicit = try await image.png().write(to: URL(fileURLWithPath: "really-png.jpg"))print("explicit:", explicit.format.rawValue, "written to a .jpg name")
// writeChunks(): bounded, backpressured output for streaming.var chunks = 0, total = 0let streamed = try await image.jpeg().writeChunks(chunkSize: 4096) { chunk in chunks += 1; total += chunk.count}print("writeChunks:", chunks, "chunks,", total, "bytes, info says", streamed.byteCount)
// outputFormat is known before evaluation, e.g. to set a Content-Type first.print("outputFormat:", try image.avif().outputFormat?.rawValue ?? "none", "—", image.outputFormat?.rawValue ?? "none (no encoder)")
// Mistakes are typed errors.do { _ = try await image.data() } catch { print("no encoder →", error) }do { _ = try await image.write(to: URL(fileURLWithPath: "out.xyz")) } catch { print("unknown extension →", error) }Як читати результати
Section titled “Як читати результати”data()вивів формат, розмір і кількість байтів, які створив.write(to:)визначає кодувальник за розширенням лише тоді, коли ви жодного не обрали (inferred.webpзаписано як WebP). Явно обраний кодувальник завжди перемагає:png()з іменем.jpgзаписує дані PNG уreally-png.jpg, тож розширення добирайте самі.writeChunksдоставив 9 660 байтів трьома шматками не більше ніж по 4 096 байтів, іOutputInfo.byteCountзбігся. У передачі тримається щонайбільшеchunkSize × 4байтів закодованого виводу, тож повільний споживач сповільнює кодування замість того, щоб збільшувати пам’ять.chunkSize—1…67 108 864(типово 64 КіБ). TIFF не можна записувати лише вперед, тож його спершу кодують у пам’яті, а потім передають шматками. Якщоconsumeвикидає помилку, кодування зупиняється й ця помилка викидається; після збою чи скасування споживач отримав часткову передачу й мусить її відкинути.outputFormatвідомий до виконання (avif, аnil, коли кодувальника не обрано), тож сервер може встановитиContent-Typeдо першого байта.
Гарантії файлового виводу
Section titled “Гарантії файлового виводу”write(to:) пише у тимчасовий файл (.name.hokusai-…) у каталозі призначення й перейменовує його поверх призначення лише по завершенні запису, тож невдалий чи скасований запис залишає наявний файл точно таким, яким він був, і ніколи не лишає пів-зображення. Замінений файл зберігає права доступу; символічне посилання лишається посиланням, а замінюється його ціль. Призначення, що є файлом, який читає конвеєр (зокрема через символічне посилання), відхиляється з invalidOption («output URL») до будь-якого запису: запишіть в інший файл і замініть оригінал самі. Призначення, яке не вдається відкрити чи записати, викидає HokusaiError.io з операцією .write і причиною від системи.
Помилки
Section titled “Помилки”| Ситуація | Результат |
|---|---|
data() чи writeChunks без кодувальника |
invalidOption(name: "output format", …"call jpeg(), png(), webp(), avif(), pdf(), or encode(using:) before data()") |
write(to:) з невідомим розширенням і без кодувальника |
invalidOption(name: "output URL", …"use a supported image extension or select an encoder") |
write(to:) з іменем .svg |
unsupported: SVG — це формат входу, а не кодувальник |
raw з обраним кодувальником |
invalidOption(name: "raw", …): для закодованого зображення використовуйте data() |
Вивід понад RuntimeConfiguration.maxOutputPixels |
resource (outputPixels), до обчислення будь-якого пікселя |
Де стоїть кодувальник
Section titled “Де стоїть кодувальник”Кодувальник — це конфігурація завершальної операції, а не операція над зображенням: jpeg(quality: 70).resize(width: 300) і resize(width: 300).jpeg(quality: 70) дають байт-у-байт однаковий вивід, а вибір другого кодувальника замінює перший (Порядок операцій).