This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit 4a1381d3a554b83a8b9fe2a703b5286a61920980 Author: chaokunyang <[email protected]> AuthorDate: Tue Apr 28 10:48:34 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/swift/basic-serialization.md | 8 ++-- docs/guide/swift/cross-language.md | 4 +- docs/guide/swift/custom-serializers.md | 2 +- docs/guide/swift/field-configuration.md | 70 ++++++++++++++++++++++++++++++--- docs/guide/swift/index.md | 4 +- docs/guide/swift/polymorphism.md | 6 +-- docs/guide/swift/references.md | 6 +-- docs/guide/swift/schema-evolution.md | 4 +- docs/guide/swift/troubleshooting.md | 6 +-- docs/guide/swift/type-registration.md | 2 +- 10 files changed, 85 insertions(+), 27 deletions(-) diff --git a/docs/guide/swift/basic-serialization.md b/docs/guide/swift/basic-serialization.md index 4d7283be5..7781f3c3c 100644 --- a/docs/guide/swift/basic-serialization.md +++ b/docs/guide/swift/basic-serialization.md @@ -23,19 +23,19 @@ This page covers object graph serialization and core API usage in Swift. ## Object Graph Serialization -Use `@ForyObject` on structs/classes/enums, register types, then serialize and deserialize. +Use `@ForyStruct`, `@ForyEnum`, or `@ForyUnion`, register types, then serialize and deserialize. ```swift import Foundation import Fory -@ForyObject +@ForyStruct struct Address: Equatable { var street: String = "" var zip: Int32 = 0 } -@ForyObject +@ForyStruct struct Person: Equatable { var id: Int64 = 0 var name: String = "" @@ -97,7 +97,7 @@ assert(fromBuffer == person) Use `Date` for timestamp values and `LocalDate` for day-only dates. `LocalDate` supports epoch-day and `Date` conversions through `fromEpochDay(_:)`, -`toEpochDay()`, `init(date:)`, and `toDate()`. +`toEpochDay()`, `init(utcDate:)`, and `toUTCDate()`. ### Collections diff --git a/docs/guide/swift/cross-language.md b/docs/guide/swift/cross-language.md index 202748d90..2c9f4c6fd 100644 --- a/docs/guide/swift/cross-language.md +++ b/docs/guide/swift/cross-language.md @@ -32,7 +32,7 @@ let fory = Fory(xlang: true, trackRef: false, compatible: true) ### ID-based registration ```swift -@ForyObject +@ForyStruct struct Order { var id: Int64 = 0 var amount: Double = 0 @@ -64,7 +64,7 @@ foryc schema.fdl --swift_out ./Sources/Generated Generated Swift code includes: -- `@ForyObject` models and `@ForyField(id: ...)` metadata +- `@ForyStruct`, `@ForyEnum`, `@ForyUnion`, and field/case metadata - Tagged union enums (associated-value enum cases) - `ForyRegistration.register(_:)` helpers with transitive import registration - `toBytes` / `fromBytes` helpers on generated types diff --git a/docs/guide/swift/custom-serializers.md b/docs/guide/swift/custom-serializers.md index dfe184a2b..b6723aae7 100644 --- a/docs/guide/swift/custom-serializers.md +++ b/docs/guide/swift/custom-serializers.md @@ -19,7 +19,7 @@ license: | limitations under the License. --- -For types that cannot or should not use `@ForyObject`, implement `Serializer` manually. +For types that cannot or should not use Fory model macros, implement `Serializer` manually. ## When to Use Custom Serializers diff --git a/docs/guide/swift/field-configuration.md b/docs/guide/swift/field-configuration.md index a44869dfd..fc6da8020 100644 --- a/docs/guide/swift/field-configuration.md +++ b/docs/guide/swift/field-configuration.md @@ -23,15 +23,18 @@ This page covers macro-level field configuration in Swift. ## Available Macro Attributes -- `@ForyObject` on struct/class/enum +- `@ForyStruct` on struct/class models +- `@ForyEnum` on C-style enum models +- `@ForyUnion` and `@ForyCase` on associated-value enum models - `@ForyField(encoding: ...)` on numeric fields +- `@ListField`, `@SetField`, and `@MapField` for nested collection field metadata ## `@ForyField(encoding:)` Use `@ForyField` to override integer encoding strategy. ```swift -@ForyObject +@ForyStruct struct Metrics: Equatable { @ForyField(encoding: .fixed) var u32Fixed: UInt32 = 0 @@ -54,7 +57,62 @@ struct Metrics: Equatable { Compile-time validation rejects unsupported combinations (for example, `Int32` with `.tagged`). -## `@ForyObject` Requirements +## Nested Collection Field Metadata + +Use `@ListField`, `@SetField`, and `@MapField` when a nested field needs type-specific +wire metadata, such as fixed or tagged integer encoding inside a container. + +```swift +@ForyStruct +struct NestedMetrics: Equatable { + @ListField(element: .encoding(.fixed)) + var values: [Int32?] = [] + + @SetField(element: .encoding(.fixed)) + var ids: Set<UInt32?> = [] + + @MapField(key: .encoding(.fixed), value: .encoding(.tagged)) + var byId: [Int32: UInt64] = [:] + + @MapField(value: .list(element: .encoding(.fixed))) + var groups: [String: [Int32?]] = [:] +} +``` + +Non-null `List` elements with fixed-width signed or unsigned integer metadata are +classified and encoded as the matching Fory primitive packed-array type. `Set` +fields stay classified as Fory sets, including fixed-width integer sets. + +When the Swift property type is an alias or otherwise needs a full hint, use +`@ForyField(type:)`: + +```swift +typealias MetricsMap = [String: [Int32?]] + +@ForyStruct +struct AliasMetrics: Equatable { + @ForyField(type: .map( + key: .string, + value: .list(.int32(nullable: true, encoding: .fixed)) + )) + var metrics: MetricsMap = [:] +} +``` + +Union payloads use the same DSL through `@ForyCase(payload:)`: + +```swift +@ForyUnion +enum Event: Equatable { + @ForyCase(id: 1) + case created(String) + + @ForyCase(id: 2, payload: .uint64(encoding: .fixed)) + case deleted(UInt64) +} +``` + +## Model Macro Requirements ### Struct and class fields @@ -64,10 +122,10 @@ Compile-time validation rejects unsupported combinations (for example, `Int32` w ### Class requirement -Classes annotated with `@ForyObject` must provide a `required init()` for default construction. +Classes annotated with `@ForyStruct` must provide a `required init()` for default construction. ```swift -@ForyObject +@ForyStruct final class Node { var value: Int32 = 0 var next: Node? = nil @@ -78,7 +136,7 @@ final class Node { ## Dynamic Any Fields in Macro Types -`@ForyObject` supports dynamic fields and nested containers: +Fory model macros support dynamic fields and nested containers: - `Any`, `AnyObject`, `any Serializer` - `AnyHashable` diff --git a/docs/guide/swift/index.md b/docs/guide/swift/index.md index 6914a1772..93334b489 100644 --- a/docs/guide/swift/index.md +++ b/docs/guide/swift/index.md @@ -24,7 +24,7 @@ Apache Fory Swift provides high-performance object graph serialization with stro ## Why Fory Swift? - Fast binary serialization for Swift value and reference types -- `@ForyObject` macro for zero-boilerplate model serialization +- `@ForyStruct`, `@ForyEnum`, and `@ForyUnion` macros for zero-boilerplate model serialization - Cross-language protocol compatibility (`xlang`) with Java, Rust, Go, Python, and more - Compatible mode for schema evolution across versions - Built-in support for dynamic values (`Any`, `AnyObject`, `any Serializer`, `AnyHashable`) @@ -67,7 +67,7 @@ targets: [ ```swift import Fory -@ForyObject +@ForyStruct struct User: Equatable { var name: String = "" var age: Int32 = 0 diff --git a/docs/guide/swift/polymorphism.md b/docs/guide/swift/polymorphism.md index f03d677c0..4a888640c 100644 --- a/docs/guide/swift/polymorphism.md +++ b/docs/guide/swift/polymorphism.md @@ -41,10 +41,10 @@ Equivalent overloads exist for: - `[Int32: Any]` - `[AnyHashable: Any]` -## Dynamic Fields in `@ForyObject` Types +## Dynamic Fields in Fory Model Types ```swift -@ForyObject +@ForyStruct struct DynamicHolder { var value: Any = ForyAnyNullValue() var list: [Any] = [] @@ -59,7 +59,7 @@ struct DynamicHolder { If dynamic values contain user-defined runtime types, register those concrete types. ```swift -@ForyObject +@ForyStruct struct Address { var street: String = "" var zip: Int32 = 0 diff --git a/docs/guide/swift/references.md b/docs/guide/swift/references.md index 726758519..fa4206ef6 100644 --- a/docs/guide/swift/references.md +++ b/docs/guide/swift/references.md @@ -34,7 +34,7 @@ When enabled, reference-trackable types preserve identity and cycles. ```swift import Fory -@ForyObject +@ForyStruct final class Animal { var name: String = "" @@ -45,7 +45,7 @@ final class Animal { } } -@ForyObject +@ForyStruct final class AnimalPair { var first: Animal? = nil var second: Animal? = nil @@ -79,7 +79,7 @@ Use `weak` on at least one edge in a cycle to avoid leaks. ```swift import Fory -@ForyObject +@ForyStruct final class Node { var value: Int32 = 0 weak var next: Node? = nil diff --git a/docs/guide/swift/schema-evolution.md b/docs/guide/swift/schema-evolution.md index 3ae00f086..be70d1214 100644 --- a/docs/guide/swift/schema-evolution.md +++ b/docs/guide/swift/schema-evolution.md @@ -32,14 +32,14 @@ let fory = Fory(xlang: true, trackRef: false, compatible: true) ```swift import Fory -@ForyObject +@ForyStruct struct PersonV1 { var name: String = "" var age: Int32 = 0 var address: String = "" } -@ForyObject +@ForyStruct struct PersonV2 { var name: String = "" var age: Int32 = 0 diff --git a/docs/guide/swift/troubleshooting.md b/docs/guide/swift/troubleshooting.md index f94b0d1ea..02f768ddd 100644 --- a/docs/guide/swift/troubleshooting.md +++ b/docs/guide/swift/troubleshooting.md @@ -59,15 +59,15 @@ Fix: ## Common Macro-time Errors -### `@ForyObject requires explicit types for stored properties` +### `@ForyStruct requires explicit types for stored properties` Add explicit type annotations to stored properties. -### `@ForyObject enum associated values cannot have default values` +### `Fory enum associated values cannot have default values` Remove default values from enum case associated values. -### `Set<...> with Any elements is not supported by @ForyObject yet` +### `Set<...> with Any elements is not supported by @ForyStruct yet` Use `[Any]` or a typed set instead. diff --git a/docs/guide/swift/type-registration.md b/docs/guide/swift/type-registration.md index 0e5228ce4..56297c10c 100644 --- a/docs/guide/swift/type-registration.md +++ b/docs/guide/swift/type-registration.md @@ -34,7 +34,7 @@ If a type is missing, deserialization fails with: Use a stable ID shared by serializer and deserializer peers. ```swift -@ForyObject +@ForyStruct struct User { var name: String = "" var age: Int32 = 0 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
