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 5e4f37ea18db552c9b39b9bf0311b2375a5069ab Author: chaokunyang <[email protected]> AuthorDate: Mon Jan 26 17:28:15 2026 +0000 🔄 synced local 'docs/specification/' with remote 'docs/specification/' --- docs/specification/xlang_serialization_spec.md | 29 +++++++++++++++++++------- docs/specification/xlang_type_mapping.md | 2 +- 2 files changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/specification/xlang_serialization_spec.md b/docs/specification/xlang_serialization_spec.md index e02ee979c2..362d2784c4 100644 --- a/docs/specification/xlang_serialization_spec.md +++ b/docs/specification/xlang_serialization_spec.md @@ -69,9 +69,9 @@ This specification defines the Fory xlang binary format. The format is dynamic r - set: an unordered set of unique elements. - map: a map of key-value pairs. Mutable types such as `list/map/set/array` are not allowed as key of map. - duration: an absolute length of time, independent of any calendar/timezone, as a count of nanoseconds. -- timestamp: a point in time, independent of any calendar/timezone, as a count of nanoseconds. The count is relative - to an epoch at UTC midnight on January 1, 1970. -- local_date: a naive date without timezone. The count is days relative to an epoch at UTC midnight on Jan 1, 1970. +- timestamp: a point in time, independent of any calendar/timezone, encoded as seconds (int64) and nanoseconds + (uint32) since the epoch at UTC midnight on January 1, 1970. +- date: a naive date without timezone. The count is days relative to an epoch at UTC midnight on Jan 1, 1970. - decimal: exact decimal value represented as an integer value in two's complement. - binary: an variable-length array of bytes. - array: only allow 1d numeric components. Other arrays will be taken as List. The implementation should support the @@ -197,8 +197,8 @@ Named types (`NAMED_*`) do not embed a user ID; their names are carried in metad | 33 | NAMED_UNION | Union with embedded union type name/TypeDef | | 34 | NONE | Empty/unit type (no data) | | 35 | DURATION | Time duration (seconds + nanoseconds) | -| 36 | TIMESTAMP | Point in time (nanoseconds since epoch) | -| 37 | LOCAL_DATE | Date without timezone (days since epoch) | +| 36 | TIMESTAMP | Point in time (seconds + nanoseconds since epoch) | +| 37 | DATE | Date without timezone (days since epoch) | | 38 | DECIMAL | Arbitrary precision decimal | | 39 | BINARY | Raw binary data | | 40 | ARRAY | Generic array type | @@ -1220,6 +1220,21 @@ Enums are serialized as an unsigned var int. If the order of enum values change, the value users expect. In such cases, users must register enum serializer by make it write enum value as an enumerated string with unique hash disabled. +### timestamp + +Timestamp represents a point in time independent of any calendar/timezone. It is encoded as: + +- `seconds` (int64): seconds since Unix epoch (1970-01-01T00:00:00Z) +- `nanos` (uint32): nanosecond adjustment within the second + +On write, implementations must normalize negative timestamps so that `nanos` is always in `[0, 1_000_000_000)`. +This is a fixed-size 12-byte payload (8 bytes seconds + 4 bytes nanos). + +### date + +Date represents a date without timezone. It is encoded as an `int32` count of days since the Unix epoch +(1970-01-01). This is a fixed-size 4-byte payload. + ### decimal Not supported for now. @@ -1532,8 +1547,8 @@ This section provides a step-by-step guide for implementing Fory xlang serializa 6. **Temporal Types** - [ ] Duration (seconds + nanoseconds) - - [ ] Timestamp (nanoseconds since epoch) - - [ ] LocalDate (days since epoch) + - [ ] Timestamp (seconds + nanoseconds since epoch) + - [ ] Date (days since epoch) 7. **Reference Tracking** - [ ] Implement write-side object tracking (object → ref_id map) diff --git a/docs/specification/xlang_type_mapping.md b/docs/specification/xlang_type_mapping.md index 8a1b1c18b4..9390e56d6d 100644 --- a/docs/specification/xlang_type_mapping.md +++ b/docs/specification/xlang_type_mapping.md @@ -63,7 +63,7 @@ Note: | none | 32 | null | None | null | `std::monostate` | nil | `()` | | duration | 33 | Duration | timedelta | Number | duration | Duration | Duration | | timestamp | 34 | Instant | datetime | Number | std::chrono::nanoseconds | Time | DateTime | -| local_date | 35 | Date | datetime | Number | std::chrono::nanoseconds | Time | DateTime | +| date | 35 | Date | datetime | Number | fory::serialization::Date | Time | DateTime | | decimal | 36 | BigDecimal | Decimal | bigint | / | / | / | | binary | 37 | byte[] | bytes | / | `uint8_t[n]/vector<T>` | `[n]uint8/[]T` | `Vec<uint8_t>` | | array | 38 | array | np.ndarray | / | / | array/slice | Vec | --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
