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 d6530868412e639374ac1e74ed596eca4078eea2 Author: chaokunyang <[email protected]> AuthorDate: Fri May 8 06:43:55 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/dart/cross-language.md | 5 +++-- docs/guide/dart/index.md | 4 ++-- docs/guide/dart/supported-types.md | 11 ++++++----- docs/guide/java/advanced-features.md | 7 +++---- docs/guide/javascript/supported-types.md | 26 +++++++++++++------------- docs/guide/xlang/serialization.md | 2 +- 6 files changed, 28 insertions(+), 27 deletions(-) diff --git a/docs/guide/dart/cross-language.md b/docs/guide/dart/cross-language.md index 077a771dbb..1918d9468c 100644 --- a/docs/guide/dart/cross-language.md +++ b/docs/guide/dart/cross-language.md @@ -161,7 +161,7 @@ Fory matches fields by name or by stable field ID. For robust cross-language int 1. Use the same type identity on every side (same numeric ID or same `namespace + typeName`). 2. Assign stable `@ForyField(id: ...)` values to all fields before shipping the first payload. 3. Keep field names consistent or rely on IDs, since Dart typically uses `lowerCamelCase` while Go uses `PascalCase` for exported fields and C# often uses `PascalCase` properties. -4. Use explicit numeric field metadata: `@ForyField(type: Int32Type())` in Dart for Java `int`, Go `int32`, and C# `int`; `double` in Dart for 64-bit floats; `Float32` for 32-bit; `Int64` / `Uint64` for full-range 64-bit values. +4. Use explicit numeric field metadata: `@ForyField(type: Int32Type())` in Dart for Java `int`, Go `int32`, and C# `int`; `double` in Dart for 64-bit floats; `double` plus `Float16Type` or `Bfloat16Type` for 16-bit floats; `Float32` for 32-bit; `Int64` / `Uint64` for full-range 64-bit values. 5. Use `Timestamp`, `LocalDate`, and `Duration` for temporal fields rather than raw `DateTime`. 6. Validate real round trips across all languages before shipping. @@ -173,7 +173,8 @@ Because Dart `int` is not itself a promise about the exact xlang wire width, pre - `@ForyField(type: Uint32Type())` for xlang `uint32` - `@ForyField(type: Int8Type())` / `@ForyField(type: Int16Type())` / `@ForyField(type: Uint8Type())` / `@ForyField(type: Uint16Type())` for narrower integer widths - `Int64` and `Uint64` for full-range 64-bit values on web -- `Float16`, `Bfloat16`, and `Float32` for reduced-width floating point +- `double` fields annotated with `Float16Type` or `Bfloat16Type` for 16-bit + floating-point scalars, and `Float32` for single-precision values - `Float16List` and `Bfloat16List` for 16-bit floating-point array payloads - `Timestamp`, `LocalDate`, and `Duration` for explicit temporal semantics diff --git a/docs/guide/dart/index.md b/docs/guide/dart/index.md index 34e1da64eb..c7458389ca 100644 --- a/docs/guide/dart/index.md +++ b/docs/guide/dart/index.md @@ -118,8 +118,8 @@ dart run build_runner build --delete-conflicting-outputs - `@ForyStruct()` — marks a class for code generation - `@ForyField(...)` — per-field options and canonical `type:` overrides - `@ListField(...)`, `@SetField(...)`, `@MapField(...)` — container sugar for nested `type:` trees -- Exact-value wrappers: `Int64`, `Uint64`, `Float16`, `Bfloat16`, `Float32` -- Float wrappers: `Float16`, `Bfloat16`, `Float32` +- Exact-value wrappers: `Int64`, `Uint64`, `Float32` +- Reduced-precision scalar fields: `double` with `Float16Type` or `Bfloat16Type` - 16-bit float arrays: `Float16List`, `Bfloat16List` - Time types: `LocalDate`, `Timestamp`, `Duration` diff --git a/docs/guide/dart/supported-types.md b/docs/guide/dart/supported-types.md index 186de6938d..12f2e30980 100644 --- a/docs/guide/dart/supported-types.md +++ b/docs/guide/dart/supported-types.md @@ -76,14 +76,15 @@ field metadata or explicit `Buffer` APIs when native VM payloads must preserve unsigned 64-bit identity across dynamic boundaries. Dart web uses wrapper classes, so web root `Uint64` values keep `varuint64` metadata. -## Floating-Point Wrappers +## Floating-Point Types -Dart `double` maps to 64-bit float. If the peer uses reduced-precision -floating-point values, use an explicit wrapper: +Dart `double` maps to 64-bit float by default. If the peer uses +reduced-precision floating-point values, keep the Dart field as `double` and +mark the exact wire type with field metadata: - `Float32` — 32-bit float (matches Java `float`, C# `float`, Go `float32`) -- `Float16` — half-precision, for specialized numeric payloads -- `Bfloat16` — brain floating point, useful when interoperating with ML-oriented payloads +- `@ForyField(type: Float16Type()) double value` — half-precision scalar +- `@ForyField(type: Bfloat16Type()) double value` — bfloat16 scalar For contiguous 16-bit floating-point arrays, use `Float16List` and `Bfloat16List` rather than `Uint16List` when the schema is `array<float16>` diff --git a/docs/guide/java/advanced-features.md b/docs/guide/java/advanced-features.md index 8661f87558..99b57b5624 100644 --- a/docs/guide/java/advanced-features.md +++ b/docs/guide/java/advanced-features.md @@ -93,7 +93,7 @@ public interface MemoryAllocator { * The implementation must grow the buffer in-place by modifying * the existing buffer instance. */ - MemoryBuffer grow(MemoryBuffer buffer, int newCapacity); + void grow(MemoryBuffer buffer, int newCapacity); } ``` @@ -111,9 +111,9 @@ MemoryAllocator customAllocator = new MemoryAllocator() { } @Override - public MemoryBuffer grow(MemoryBuffer buffer, int newCapacity) { + public void grow(MemoryBuffer buffer, int newCapacity) { if (newCapacity <= buffer.size()) { - return buffer; + return; } // Custom growth strategy - add 100% extra capacity @@ -121,7 +121,6 @@ MemoryAllocator customAllocator = new MemoryAllocator() { byte[] data = new byte[newSize]; buffer.copyToUnsafe(0, data, Platform.BYTE_ARRAY_OFFSET, buffer.size()); buffer.initHeapBuffer(data, 0, data.length); - return buffer; } }; diff --git a/docs/guide/javascript/supported-types.md b/docs/guide/javascript/supported-types.md index a932a35b3c..4c1d1564bc 100644 --- a/docs/guide/javascript/supported-types.md +++ b/docs/guide/javascript/supported-types.md @@ -23,18 +23,18 @@ This page lists the JavaScript and TypeScript types supported by Fory, and expla ## Primitive and Scalar Types -| JavaScript value | Fory schema | Notes | -| --------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| `boolean` | `Type.bool()` | | -| `number` | `Type.int8()` / `Type.int16()` / `Type.int32()` / `Type.float32()` / `Type.float64()` | Pick the width that matches the peer language | -| `bigint` | `Type.int64()` / `Type.uint64()` | Use `bigint` for 64-bit integers | -| `string` | `Type.string()` | | -| `Uint8Array` | `Type.binary()` | Binary blob | -| `Date` | `Type.timestamp()` | Serializes/deserializes as `Date` | -| `Date` | `Type.date()` | Date without time; deserializes as `Date` | -| duration (ms) | `Type.duration()` | Exposed as a numeric millisecond value in JavaScript | -| `number` | `Type.float16()` | Half-precision float | -| `BFloat16` / `number` | `Type.bfloat16()` | Deserializes to `BFloat16` | +| JavaScript value | Fory schema | Notes | +| ---------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| `boolean` | `Type.bool()` | | +| `number` | `Type.int8()` / `Type.int16()` / `Type.int32()` / `Type.float32()` / `Type.float64()` | Pick the width that matches the peer language | +| `bigint` | `Type.int64()` / `Type.uint64()` | Use `bigint` for 64-bit integers | +| `string` | `Type.string()` | | +| `Uint8Array` | `Type.binary()` | Binary blob | +| `Date` | `Type.timestamp()` | Serializes/deserializes as `Date` | +| `Date` | `Type.date()` | Date without time; deserializes as `Date` | +| duration (ms) | `Type.duration()` | Exposed as a numeric millisecond value in JavaScript | +| `number` | `Type.float16()` | Half-precision float | +| `number` | `Type.bfloat16()` | Brain floating point | ## Integer Types @@ -97,7 +97,7 @@ Type.int64Array(); // BigInt64Array Type.float32Array(); // Float32Array Type.float64Array(); // Float64Array Type.float16Array(); // number[] -Type.bfloat16Array(); // BFloat16[] +Type.bfloat16Array(); // BFloat16Array ``` Use `Type.list(elementType)` for non-numeric, struct, nullable-element, or ref-tracked ordered collections. diff --git a/docs/guide/xlang/serialization.md b/docs/guide/xlang/serialization.md index bee4783697..aca6d3c250 100644 --- a/docs/guide/xlang/serialization.md +++ b/docs/guide/xlang/serialization.md @@ -30,7 +30,7 @@ Reduced-precision floating-point values are also part of the built-in xlang type - `float16` and `array<float16>` - `bfloat16` and `array<bfloat16>` -Use the language-specific carrier types documented in the type mapping reference. Python uses `pyfory.Float16` and `pyfory.BFloat16` as annotation markers only; scalar values are native Python `float`, and dense reduced-precision arrays use `pyfory.Float16Array` and `pyfory.BFloat16Array`. Go uses the `float16` and `bfloat16` packages for scalar, slice, and array carriers; JavaScript uses `number` for scalar `float16`, `BFloat16` / `number` for scalar `bfloat16`, and dense array carriers [...] +Use the language-specific carrier types documented in the type mapping reference. Python uses `pyfory.Float16` and `pyfory.BFloat16` as annotation markers only; scalar values are native Python `float`, and dense reduced-precision arrays use `pyfory.Float16Array` and `pyfory.BFloat16Array`. Go uses the `float16` and `bfloat16` packages for scalar, slice, and array carriers; JavaScript uses `number` for scalar `float16` and `bfloat16`, and dense array carriers `BoolArray`, `Float16Array`, [...] When `compatible=true`, a direct struct/class field can evolve between `list<T>` and `array<T>` for dense bool/numeric `T`. Integer list element encodings in the same signedness and width domain match the corresponding dense array element domain. This applies only to the immediate matched field schema. It does not apply to nested collection, map, array, union, or generic positions. If a peer `list<T>` payload declares nullable or ref-tracked elements, reading it into a local `array<T>` f [...] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
