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 08039ca3bf17cbfe0c30ea401ed166ee9fd0fc57 Author: chaokunyang <[email protected]> AuthorDate: Wed Apr 22 15:13:29 2026 +0000 π synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/cpp/cross-language.md | 32 +++++++++++++----------- docs/guide/cpp/supported-types.md | 35 ++++++++++++++------------ docs/guide/csharp/cross-language.md | 2 ++ docs/guide/csharp/supported-types.md | 3 +++ docs/guide/java/cross-language.md | 2 ++ docs/guide/python/cross-language.md | 45 ++++++++++++++++++++++++++-------- docs/guide/rust/basic-serialization.md | 15 +++++++----- docs/guide/rust/cross-language.md | 26 ++++++++++++-------- docs/guide/xlang/serialization.md | 7 ++++++ 9 files changed, 111 insertions(+), 56 deletions(-) diff --git a/docs/guide/cpp/cross-language.md b/docs/guide/cpp/cross-language.md index 5632d45b2..b0f308b5b 100644 --- a/docs/guide/cpp/cross-language.md +++ b/docs/guide/cpp/cross-language.md @@ -137,15 +137,17 @@ print(f"Timestamp: {msg.timestamp}") ### Primitive Types -| C++ Type | Java Type | Python Type | Go Type | Rust Type | -| --------- | --------- | ----------- | --------- | --------- | -| `bool` | `boolean` | `bool` | `bool` | `bool` | -| `int8_t` | `byte` | `int` | `int8` | `i8` | -| `int16_t` | `short` | `int` | `int16` | `i16` | -| `int32_t` | `int` | `int` | `int32` | `i32` | -| `int64_t` | `long` | `int` | `int64` | `i64` | -| `float` | `float` | `float` | `float32` | `f32` | -| `double` | `double` | `float` | `float64` | `f64` | +| C++ Type | Java Type | Python Type | Go Type | Rust Type | +| ------------------ | ---------- | ----------------- | ------------------- | ---------- | +| `bool` | `boolean` | `bool` | `bool` | `bool` | +| `int8_t` | `byte` | `int` | `int8` | `i8` | +| `int16_t` | `short` | `int` | `int16` | `i16` | +| `int32_t` | `int` | `int` | `int32` | `i32` | +| `int64_t` | `long` | `int` | `int64` | `i64` | +| `float` | `float` | `float` | `float32` | `f32` | +| `double` | `double` | `float` | `float64` | `f64` | +| `fory::float16_t` | `Float16` | `pyfory.float16` | `float16.Float16` | `Float16` | +| `fory::bfloat16_t` | `BFloat16` | `pyfory.bfloat16` | `bfloat16.BFloat16` | `BFloat16` | ### String Types @@ -155,11 +157,13 @@ print(f"Timestamp: {msg.timestamp}") ### Collection Types -| C++ Type | Java Type | Python Type | Go Type | -| ---------------- | ---------- | ----------- | ---------------- | -| `std::vector<T>` | `List<T>` | `list` | `[]T` | -| `std::set<T>` | `Set<T>` | `set` | `map[T]struct{}` | -| `std::map<K,V>` | `Map<K,V>` | `dict` | `map[K]V` | +| C++ Type | Java Type | Python Type | Go Type | Rust Type | +| ------------------------------- | -------------- | --------------- | --------------------- | --------------- | +| `std::vector<T>` | `List<T>` | `list` | `[]T` | `Vec<T>` | +| `std::vector<fory::float16_t>` | `Float16List` | `float16array` | `[]float16.Float16` | `Vec<Float16>` | +| `std::vector<fory::bfloat16_t>` | `BFloat16List` | `bfloat16array` | `[]bfloat16.BFloat16` | `Vec<BFloat16>` | +| `std::set<T>` | `Set<T>` | `set` | `map[T]struct{}` | `HashSet<T>` | +| `std::map<K,V>` | `Map<K,V>` | `dict` | `map[K]V` | `HashMap<K,V>` | ### Temporal Types diff --git a/docs/guide/cpp/supported-types.md b/docs/guide/cpp/supported-types.md index ab191a9ad..c2ca398e0 100644 --- a/docs/guide/cpp/supported-types.md +++ b/docs/guide/cpp/supported-types.md @@ -25,22 +25,23 @@ This page documents all types supported by Fory C++ serialization. All C++ primitive types are supported with efficient binary encoding: -| Type | Size | Fory TypeId | Notes | -| ---------- | ------ | ----------- | --------------------- | -| `bool` | 1 byte | BOOL | True/false | -| `int8_t` | 1 byte | INT8 | Signed byte | -| `uint8_t` | 1 byte | INT8 | Unsigned byte | -| `int16_t` | 2 byte | INT16 | Signed short | -| `uint16_t` | 2 byte | INT16 | Unsigned short | -| `int32_t` | 4 byte | INT32 | Signed integer | -| `uint32_t` | 4 byte | INT32 | Unsigned integer | -| `int64_t` | 8 byte | INT64 | Signed long | -| `uint64_t` | 8 byte | INT64 | Unsigned long | -| `float` | 4 byte | FLOAT32 | IEEE 754 single | -| `double` | 8 byte | FLOAT64 | IEEE 754 double | -| `char` | 1 byte | INT8 | Character (as signed) | -| `char16_t` | 2 byte | INT16 | 16-bits characters | -| `char32_t` | 4 byte | INT32 | 32-bits characters | +| Type | Size | Fory TypeId | Notes | +| ------------------ | ------ | ----------- | --------------------- | +| `bool` | 1 byte | BOOL | True/false | +| `int8_t` | 1 byte | INT8 | Signed byte | +| `uint8_t` | 1 byte | INT8 | Unsigned byte | +| `int16_t` | 2 byte | INT16 | Signed short | +| `uint16_t` | 2 byte | INT16 | Unsigned short | +| `int32_t` | 4 byte | INT32 | Signed integer | +| `uint32_t` | 4 byte | INT32 | Unsigned integer | +| `int64_t` | 8 byte | INT64 | Signed long | +| `uint64_t` | 8 byte | INT64 | Unsigned long | +| `float` | 4 byte | FLOAT32 | IEEE 754 single | +| `double` | 8 byte | FLOAT64 | IEEE 754 double | +| `fory::bfloat16_t` | 2 byte | BFLOAT16 | IEEE 754 bfloat16 | +| `char` | 1 byte | INT8 | Character (as signed) | +| `char16_t` | 2 byte | INT16 | 16-bits characters | +| `char32_t` | 4 byte | INT32 | 32-bits characters | ```cpp int32_t value = 42; @@ -71,6 +72,8 @@ assert(text == decoded); `std::vector<T>` for any serializable element type: +`std::vector<fory::bfloat16_t>` is the dense array carrier for xlang `bfloat16_array`. + ```cpp std::vector<int32_t> numbers{1, 2, 3, 4, 5}; auto bytes = fory.serialize(numbers).value(); diff --git a/docs/guide/csharp/cross-language.md b/docs/guide/csharp/cross-language.md index 2b11ceb70..a1c8af945 100644 --- a/docs/guide/csharp/cross-language.md +++ b/docs/guide/csharp/cross-language.md @@ -93,6 +93,8 @@ value = fory.deserialize(payload_from_csharp) See [xlang guide](../xlang/index.md) for complete mapping. +For reduced-precision numeric payloads, use `Half` / `Half[]` or `List<Half>` for xlang `float16`, and `BFloat16` / `BFloat16[]` or `List<BFloat16>` for xlang `bfloat16`. + ## Best Practices 1. Keep type IDs stable and documented. diff --git a/docs/guide/csharp/supported-types.md b/docs/guide/csharp/supported-types.md index 0b6397788..e1a92ac0f 100644 --- a/docs/guide/csharp/supported-types.md +++ b/docs/guide/csharp/supported-types.md @@ -29,6 +29,7 @@ This page summarizes built-in and generated type support in Apache Foryβ’ C#. | `sbyte`, `short`, `int`, `long` | Supported | | `byte`, `ushort`, `uint`, `ulong` | Supported | | `float`, `double` | Supported | +| `Half`, `BFloat16` | Supported | | `string` | Supported | | `byte[]` | Supported | | Nullable primitives (for example `int?`) | Supported | @@ -36,6 +37,8 @@ This page summarizes built-in and generated type support in Apache Foryβ’ C#. ## Arrays - Primitive numeric arrays (`bool[]`, `int[]`, `ulong[]`, etc.) +- `Half[]`, `List<Half>` for `float16_array` +- `BFloat16[]`, `List<BFloat16>` for `bfloat16_array` - `byte[]` - General arrays (`T[]`) through collection serializers diff --git a/docs/guide/java/cross-language.md b/docs/guide/java/cross-language.md index f1dfd4eb6..6309d25a6 100644 --- a/docs/guide/java/cross-language.md +++ b/docs/guide/java/cross-language.md @@ -158,6 +158,8 @@ Not all Java types have equivalents in other languages. When using xlang mode: - Use **primitive types** (`int`, `long`, `double`, `String`) for maximum compatibility - Use **standard collections** (`List`, `Map`, `Set`) instead of language-specific ones +- Use **reduced-precision carriers** (`Float16`, `BFloat16`, `Float16List`, `BFloat16List`) for 16-bit float payloads +- Treat `Float16[]` and `BFloat16[]` as xlang `list` carriers; use `Float16List` and `BFloat16List` when the wire type must be `float16_array` or `bfloat16_array` - Avoid **Java-specific types** like `Optional`, `BigDecimal` (unless the target language supports them) - See [Type Mapping Guide](../../specification/xlang_type_mapping.md) for complete compatibility matrix diff --git a/docs/guide/python/cross-language.md b/docs/guide/python/cross-language.md index b5b96f5ca..61f6d1dab 100644 --- a/docs/guide/python/cross-language.md +++ b/docs/guide/python/cross-language.md @@ -109,18 +109,43 @@ class TypedData: double_value: pyfory.float64 # 64-bit float ``` +## Reduced-Precision Types + +`pyfory.serialization` exports Cython-only carrier types for xlang reduced-precision values: + +- `float16` and `float16array` +- `bfloat16` and `bfloat16array` + +These names are compiled into the `pyfory.serialization` extension and re-exported from `pyfory`. There is no pure-Python fallback module for them. + +The scalar wrappers behave like reduced-precision numeric value types. They support arithmetic and +ordering with Python numeric operands, and each operation quantizes the result back to the wrapper's +own format (`pyfory.float16` or `pyfory.bfloat16`). + +The array wrappers are value-oriented public APIs. Construct them from Python numeric values with +`pyfory.float16array([...])`, `pyfory.float16array.from_values([...])`, +`pyfory.bfloat16array([...])`, or `pyfory.bfloat16array.from_values([...])`. Use +`from_buffer(...)` and `to_buffer()` only when you already need packed little-endian `uint16` +storage and want the raw-buffer fast path. Both array carriers also implement the CPython buffer +protocol, so `memoryview(pyfory.float16array(...))` and `memoryview(pyfory.bfloat16array(...))` +expose the packed `uint16` storage directly. + ## Type Mapping -| Python | Java | Rust | Go | -| ---------------- | -------- | --------- | --------- | -| `str` | `String` | `String` | `string` | -| `int` | `long` | `i64` | `int64` | -| `pyfory.int32` | `int` | `i32` | `int32` | -| `pyfory.int64` | `long` | `i64` | `int64` | -| `float` | `double` | `f64` | `float64` | -| `pyfory.float32` | `float` | `f32` | `float32` | -| `list` | `List` | `Vec` | `[]T` | -| `dict` | `Map` | `HashMap` | `map[K]V` | +| Python | Java | Rust | Go | +| ---------------------- | -------------- | --------------- | --------------------- | +| `str` | `String` | `String` | `string` | +| `int` | `long` | `i64` | `int64` | +| `pyfory.int32` | `int` | `i32` | `int32` | +| `pyfory.int64` | `long` | `i64` | `int64` | +| `float` | `double` | `f64` | `float64` | +| `pyfory.float32` | `float` | `f32` | `float32` | +| `pyfory.float16` | `Float16` | `Float16` | `float16.Float16` | +| `pyfory.bfloat16` | `BFloat16` | `BFloat16` | `bfloat16.BFloat16` | +| `pyfory.float16array` | `Float16List` | `Vec<Float16>` | `[]float16.Float16` | +| `pyfory.bfloat16array` | `BFloat16List` | `Vec<BFloat16>` | `[]bfloat16.BFloat16` | +| `list` | `List` | `Vec` | `[]T` | +| `dict` | `Map` | `HashMap` | `map[K]V` | ## Differences from Python Native Mode diff --git a/docs/guide/rust/basic-serialization.md b/docs/guide/rust/basic-serialization.md index c12857a67..9ac5e5d5a 100644 --- a/docs/guide/rust/basic-serialization.md +++ b/docs/guide/rust/basic-serialization.md @@ -81,12 +81,13 @@ assert_eq!(person, decoded); ### Primitive Types -| Rust Type | Description | -| ------------------------- | --------------- | -| `bool` | Boolean | -| `i8`, `i16`, `i32`, `i64` | Signed integers | -| `f32`, `f64` | Floating point | -| `String` | UTF-8 string | +| Rust Type | Description | +| ------------------------- | --------------------------- | +| `bool` | Boolean | +| `i8`, `i16`, `i32`, `i64` | Signed integers | +| `f32`, `f64` | Floating point | +| `BFloat16` | 16-bit brain floating point | +| `String` | UTF-8 string | ### Collections @@ -102,6 +103,8 @@ assert_eq!(person, decoded); | `BinaryHeap<T>` | Binary heap | | `Option<T>` | Optional value | +`Vec<BFloat16>` is the dense xlang carrier for `bfloat16_array` payloads. + ### Smart Pointers | Rust Type | Description | diff --git a/docs/guide/rust/cross-language.md b/docs/guide/rust/cross-language.md index dac48ec6a..245f17542 100644 --- a/docs/guide/rust/cross-language.md +++ b/docs/guide/rust/cross-language.md @@ -133,16 +133,22 @@ See [xlang_type_mapping.md](../../specification/xlang_type_mapping.md) for compl ### Common Type Mappings -| Rust | Java | Python | -| -------------- | ------------ | ------------- | -| `i32` | `int` | `int32` | -| `i64` | `long` | `int64` | -| `f32` | `float` | `float32` | -| `f64` | `double` | `float64` | -| `String` | `String` | `str` | -| `Vec<T>` | `List<T>` | `List[T]` | -| `HashMap<K,V>` | `Map<K,V>` | `Dict[K,V]` | -| `Option<T>` | nullable `T` | `Optional[T]` | +| Rust | Java | Python | +| --------------- | -------------- | --------------- | +| `i32` | `int` | `int32` | +| `i64` | `long` | `int64` | +| `f32` | `float` | `float32` | +| `f64` | `double` | `float64` | +| `Float16` | `Float16` | `float16` | +| `BFloat16` | `BFloat16` | `bfloat16` | +| `String` | `String` | `str` | +| `Vec<T>` | `List<T>` | `List[T]` | +| `Vec<Float16>` | `Float16List` | `float16array` | +| `Vec<BFloat16>` | `BFloat16List` | `bfloat16array` | +| `[Float16; N]` | `Float16List` | `float16array` | +| `[BFloat16; N]` | `BFloat16List` | `bfloat16array` | +| `HashMap<K,V>` | `Map<K,V>` | `Dict[K,V]` | +| `Option<T>` | nullable `T` | `Optional[T]` | ## Best Practices diff --git a/docs/guide/xlang/serialization.md b/docs/guide/xlang/serialization.md index a646db6e5..17fbd5c5c 100644 --- a/docs/guide/xlang/serialization.md +++ b/docs/guide/xlang/serialization.md @@ -25,6 +25,13 @@ This page demonstrates cross-language serialization patterns with examples in al Common types can be serialized automatically without registration: primitive numeric types, string, binary, array, list, map, and more. +Reduced-precision floating-point values are also part of the built-in xlang type system: + +- `float16` and `float16_array` +- `bfloat16` and `bfloat16_array` + +Use the language-specific carrier types documented in the type mapping reference. Python exposes the Cython-only `float16`, `float16array`, `bfloat16`, and `bfloat16array` names from `pyfory.serialization`; the Python array carriers are constructed from Python numeric values, while `from_buffer(...)` is reserved for packed raw storage. Go uses the `float16` and `bfloat16` packages for scalar, slice, and array carriers; JavaScript uses `number` / `number[]` for `float16` and `BFloat16` / [...] + ### Java ```java --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
