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
The following commit(s) were added to refs/heads/main by this push:
new 5365279679 π synced local 'docs/guide/' with remote 'docs/guide/'
5365279679 is described below
commit 53652796796ccdefcf0d0859b6bec4bed699a789
Author: chaokunyang <[email protected]>
AuthorDate: Thu Jan 29 12:37:21 2026 +0000
π synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/cpp/cross-language.md | 2 +-
docs/guide/cpp/custom-serializers.md | 26 +++---
docs/guide/cpp/field-configuration.md | 80 ++++++++---------
docs/guide/cpp/row-format.md | 156 +++++++++++++++++-----------------
4 files changed, 132 insertions(+), 132 deletions(-)
diff --git a/docs/guide/cpp/cross-language.md b/docs/guide/cpp/cross-language.md
index e443b2ff50..d0845e32e2 100644
--- a/docs/guide/cpp/cross-language.md
+++ b/docs/guide/cpp/cross-language.md
@@ -74,7 +74,7 @@ int main() {
auto result = fory.serialize(msg);
if (result.ok()) {
auto bytes = std::move(result).value();
- // Write to file, send over network, etc.
+ // write to file, send over network, etc.
std::ofstream file("message.bin", std::ios::binary);
file.write(reinterpret_cast<const char*>(bytes.data()), bytes.size());
}
diff --git a/docs/guide/cpp/custom-serializers.md
b/docs/guide/cpp/custom-serializers.md
index c17ed0358c..4a1a1ece30 100644
--- a/docs/guide/cpp/custom-serializers.md
+++ b/docs/guide/cpp/custom-serializers.md
@@ -69,12 +69,12 @@ struct Serializer<MyExt> {
write_data(value, ctx);
}
- // Write only the data (no type info)
+ // write only the data (no type info)
static void write_data(const MyExt &value, WriteContext &ctx) {
Serializer<int32_t>::write_data(value.id, ctx);
}
- // Write data with generics support
+ // write data with generics support
static void write_data_generic(const MyExt &value, WriteContext &ctx,
bool has_generics) {
(void)has_generics;
@@ -202,7 +202,7 @@ struct Serializer<CustomType> {
}
static void write_data(const CustomType &value, WriteContext &ctx) {
- // Write value as varint for compact encoding
+ // write value as varint for compact encoding
Serializer<int32_t>::write_data(value.value, ctx);
// Delegate string serialization to built-in serializer
Serializer<std::string>::write_data(value.name, ctx);
@@ -289,9 +289,9 @@ ctx.write_int8(value);
ctx.write_uint16(value);
// Variable-length integers (compact encoding)
-ctx.write_varuint32(value); // Unsigned varint
+ctx.write_var_uint32(value); // Unsigned varint
ctx.write_varint32(value); // Signed zigzag varint
-ctx.write_varuint64(value); // Unsigned varint
+ctx.write_var_uint64(value); // Unsigned varint
ctx.write_varint64(value); // Signed zigzag varint
// Tagged integers (for mixed-size encoding)
@@ -302,9 +302,9 @@ ctx.write_tagged_int64(value);
ctx.write_bytes(data_ptr, length);
// Access underlying buffer for advanced operations
-ctx.buffer().WriteInt32(value);
-ctx.buffer().WriteFloat(value);
-ctx.buffer().WriteDouble(value);
+ctx.buffer().write_int32(value);
+ctx.buffer().write_float(value);
+ctx.buffer().write_double(value);
```
## ReadContext Methods
@@ -317,9 +317,9 @@ uint8_t u8 = ctx.read_uint8(ctx.error());
int8_t i8 = ctx.read_int8(ctx.error());
// Variable-length integers
-uint32_t u32 = ctx.read_varuint32(ctx.error());
+uint32_t u32 = ctx.read_var_uint32(ctx.error());
int32_t i32 = ctx.read_varint32(ctx.error());
-uint64_t u64 = ctx.read_varuint64(ctx.error());
+uint64_t u64 = ctx.read_var_uint64(ctx.error());
int64_t i64 = ctx.read_varint64(ctx.error());
// Check for errors after read operations
@@ -328,9 +328,9 @@ if (ctx.has_error()) {
}
// Access underlying buffer for advanced operations
-int32_t value = ctx.buffer().ReadInt32(ctx.error());
-float f = ctx.buffer().ReadFloat(ctx.error());
-double d = ctx.buffer().ReadDouble(ctx.error());
+int32_t value = ctx.buffer().read_int32(ctx.error());
+float f = ctx.buffer().read_float(ctx.error());
+double d = ctx.buffer().read_double(ctx.error());
```
## Delegating to Built-in Serializers
diff --git a/docs/guide/cpp/field-configuration.md
b/docs/guide/cpp/field-configuration.md
index 0f78e1ad3c..899a52f6f8 100644
--- a/docs/guide/cpp/field-configuration.md
+++ b/docs/guide/cpp/field-configuration.md
@@ -145,7 +145,7 @@ FORY_STRUCT(Graph, name, left, right);
Controls whether type info is written for polymorphic smart pointer fields:
- `fory::dynamic<true>`: Force type info to be written (enable runtime subtype
support)
-- `fory::dynamic<false>`: Skip type info (use declared type directly, no
dynamic dispatch)
+- `fory::dynamic<false>`: skip type info (use declared type directly, no
dynamic dispatch)
By default, Fory auto-detects polymorphism via `std::is_polymorphic<T>`. Use
this tag to override:
@@ -351,7 +351,7 @@ fory::F(0) // Create with field ID 0
.varint() // Use variable-length encoding
.fixed() // Use fixed-size encoding
.tagged() // Use tagged encoding
- .dynamic(false) // Skip type info (no dynamic dispatch)
+ .dynamic(false) // skip type info (no dynamic dispatch)
.dynamic(true) // Force type info (enable dynamic dispatch)
.compress(false) // Disable compression
```
@@ -389,40 +389,40 @@ using namespace fory::serialization;
// Define struct with unsigned integer fields
struct MetricsData {
// Counters - often small values, use varint for space efficiency
- uint32_t requestCount;
- uint64_t bytesSent;
+ uint32_t request_count;
+ uint64_t bytes_sent;
// IDs - uniformly distributed, use fixed for consistent performance
- uint32_t userId;
- uint64_t sessionId;
+ uint32_t user_id;
+ uint64_t session_id;
// Timestamps - use tagged encoding for mixed value ranges
- uint64_t createdAt;
+ uint64_t created_at;
// Nullable fields
- std::optional<uint32_t> errorCount;
- std::optional<uint64_t> lastAccessTime;
+ std::optional<uint32_t> error_count;
+ std::optional<uint64_t> last_access_time;
};
-FORY_STRUCT(MetricsData, requestCount, bytesSent, userId, sessionId,
- createdAt, errorCount, lastAccessTime);
+FORY_STRUCT(MetricsData, request_count, bytes_sent, user_id, session_id,
+ created_at, error_count, last_access_time);
// Configure field encoding
FORY_FIELD_CONFIG(MetricsData,
// Small counters - varint saves space
- (requestCount, fory::F(0).varint()),
- (bytesSent, fory::F(1).varint()),
+ (request_count, fory::F(0).varint()),
+ (bytes_sent, fory::F(1).varint()),
// IDs - fixed for consistent performance
- (userId, fory::F(2).fixed()),
- (sessionId, fory::F(3).fixed()),
+ (user_id, fory::F(2).fixed()),
+ (session_id, fory::F(3).fixed()),
// Timestamp - tagged encoding
- (createdAt, fory::F(4).tagged()),
+ (created_at, fory::F(4).tagged()),
// Nullable fields
- (errorCount, fory::F(5).nullable().varint()),
- (lastAccessTime, fory::F(6).nullable().tagged())
+ (error_count, fory::F(5).nullable().varint()),
+ (last_access_time, fory::F(6).nullable().tagged())
);
int main() {
@@ -430,13 +430,13 @@ int main() {
fory.register_struct<MetricsData>(100);
MetricsData data{
- .requestCount = 42,
- .bytesSent = 1024,
- .userId = 12345678,
- .sessionId = 9876543210,
- .createdAt = 1704067200000000000ULL, // 2024-01-01 in nanoseconds
- .errorCount = 3,
- .lastAccessTime = std::nullopt
+ .request_count = 42,
+ .bytes_sent = 1024,
+ .user_id = 12345678,
+ .session_id = 9876543210,
+ .created_at = 1704067200000000000ULL, // 2024-01-01 in nanoseconds
+ .error_count = 3,
+ .last_access_time = std::nullopt
};
auto bytes = fory.serialize(data).value();
@@ -458,24 +458,24 @@ When serializing data to be read by other languages, use
`FORY_FIELD_CONFIG` to
// - Long (u64): VAR_UINT64 (varint), UINT64 (fixed), or TAGGED_UINT64
struct JavaCompatible {
- uint8_t byteField; // Maps to Java Byte
- uint16_t shortField; // Maps to Java Short
- uint32_t intVarField; // Maps to Java Integer with varint
- uint32_t intFixedField; // Maps to Java Integer with fixed
- uint64_t longVarField; // Maps to Java Long with varint
- uint64_t longTagged; // Maps to Java Long with tagged
+ uint8_t byte_field; // Maps to Java Byte
+ uint16_t short_field; // Maps to Java Short
+ uint32_t int_var_field; // Maps to Java Integer with varint
+ uint32_t int_fixed_field; // Maps to Java Integer with fixed
+ uint64_t long_var_field; // Maps to Java Long with varint
+ uint64_t long_tagged; // Maps to Java Long with tagged
};
-FORY_STRUCT(JavaCompatible, byteField, shortField, intVarField,
- intFixedField, longVarField, longTagged);
+FORY_STRUCT(JavaCompatible, byte_field, short_field, int_var_field,
+ int_fixed_field, long_var_field, long_tagged);
FORY_FIELD_CONFIG(JavaCompatible,
- (byteField, fory::F(0)), // UINT8 (auto)
- (shortField, fory::F(1)), // UINT16 (auto)
- (intVarField, fory::F(2).varint()), // VAR_UINT32
- (intFixedField, fory::F(3).fixed()), // UINT32
- (longVarField, fory::F(4).varint()), // VAR_UINT64
- (longTagged, fory::F(5).tagged()) // TAGGED_UINT64
+ (byte_field, fory::F(0)), // UINT8 (auto)
+ (short_field, fory::F(1)), // UINT16 (auto)
+ (int_var_field, fory::F(2).varint()), // VAR_UINT32
+ (int_fixed_field, fory::F(3).fixed()), // UINT32
+ (long_var_field, fory::F(4).varint()), // VAR_UINT64
+ (long_tagged, fory::F(5).tagged()) // TAGGED_UINT64
);
```
@@ -516,7 +516,7 @@ FORY_FIELD_CONFIG(DataV2,
| `.nullable()` | Mark field as nullable | Smart
pointers, primitives |
| `.ref()` | Enable reference tracking |
`std::shared_ptr`, `fory::serialization::SharedWeak` |
| `.dynamic(true)` | Force type info to be written (dynamic dispatch) | Smart
pointers |
-| `.dynamic(false)` | Skip type info (use declared type directly) | Smart
pointers |
+| `.dynamic(false)` | skip type info (use declared type directly) | Smart
pointers |
| `.varint()` | Use variable-length encoding |
`uint32_t`, `uint64_t` |
| `.fixed()` | Use fixed-size encoding |
`uint32_t`, `uint64_t` |
| `.tagged()` | Use tagged hybrid encoding |
`uint64_t` only |
diff --git a/docs/guide/cpp/row-format.md b/docs/guide/cpp/row-format.md
index 8c410b7e30..0ae72f6cb9 100644
--- a/docs/guide/cpp/row-format.md
+++ b/docs/guide/cpp/row-format.md
@@ -26,7 +26,7 @@ This page covers the row-based serialization format for
high-performance, cache-
Apache Foryβ’ Row Format is a binary format optimized for:
- **Random Access**: Read any field without deserializing the entire object
-- **Zero-Copy**: Direct memory access without data copying
+- **Zero-copy**: Direct memory access without data copying
- **Cache-Friendly**: Contiguous memory layout for CPU cache efficiency
- **Columnar Conversion**: Easy conversion to Apache Arrow format
- **Partial Serialization**: Serialize only needed fields
@@ -62,17 +62,17 @@ int main() {
// Create encoder
RowEncoder<Person> encoder;
- // Encode a person
+ // encode a person
Person person{1, "Alice", 95.5f};
- encoder.Encode(person);
+ encoder.encode(person);
- // Get the encoded row
- auto row = encoder.GetWriter().ToRow();
+ // get the encoded row
+ auto row = encoder.get_writer().to_row();
// Random access to fields
- int32_t id = row->GetInt32(0);
- std::string name = row->GetString(1);
- float score = row->GetFloat(2);
+ int32_t id = row->get_int32(0);
+ std::string name = row->get_string(1);
+ float score = row->get_float(2);
assert(id == 1);
assert(name == "Alice");
@@ -101,15 +101,15 @@ struct Point {
RowEncoder<Point> encoder;
// Access schema (for inspection)
-const Schema& schema = encoder.GetSchema();
+const Schema& schema = encoder.get_schema();
std::cout << "Fields: " << schema.field_names().size() << std::endl;
-// Encode value
+// encode value
Point p{1.0, 2.0};
-encoder.Encode(p);
+encoder.encode(p);
-// Get result as Row
-auto row = encoder.GetWriter().ToRow();
+// get result as Row
+auto row = encoder.get_writer().to_row();
```
### Nested Structs
@@ -127,18 +127,18 @@ struct Person {
FORY_STRUCT(Person, name, address);
};
-// Encode nested struct
+// encode nested struct
RowEncoder<Person> encoder;
Person person{"Alice", {"New York", "USA"}};
-encoder.Encode(person);
+encoder.encode(person);
-auto row = encoder.GetWriter().ToRow();
-std::string name = row->GetString(0);
+auto row = encoder.get_writer().to_row();
+std::string name = row->get_string(0);
// Access nested struct
-auto address_row = row->GetStruct(1);
-std::string city = address_row->GetString(0);
-std::string country = address_row->GetString(1);
+auto address_row = row->get_struct(1);
+std::string city = address_row->get_string(0);
+std::string country = address_row->get_string(1);
```
### Arrays / Lists
@@ -152,33 +152,33 @@ struct Record {
RowEncoder<Record> encoder;
Record record{{1, 2, 3, 4, 5}, "test"};
-encoder.Encode(record);
+encoder.encode(record);
-auto row = encoder.GetWriter().ToRow();
-auto array = row->GetArray(0);
+auto row = encoder.get_writer().to_row();
+auto array = row->get_array(0);
int count = array->num_elements();
for (int i = 0; i < count; i++) {
- int32_t value = array->GetInt32(i);
+ int32_t value = array->get_int32(i);
}
```
### Encoding Arrays Directly
```cpp
-// Encode a vector directly (not inside a struct)
+// encode a vector directly (not inside a struct)
std::vector<Person> people{
{"Alice", {"NYC", "USA"}},
{"Bob", {"London", "UK"}}
};
RowEncoder<decltype(people)> encoder;
-encoder.Encode(people);
+encoder.encode(people);
-// Get array data
-auto array = encoder.GetWriter().CopyToArrayData();
-auto first_person = array->GetStruct(0);
-std::string first_name = first_person->GetString(0);
+// get array data
+auto array = encoder.get_writer().copy_to_array_data();
+auto first_person = array->get_struct(0);
+std::string first_name = first_person->get_string(0);
```
## Row Data Access
@@ -191,32 +191,32 @@ The `Row` class provides random access to struct fields:
class Row {
public:
// Null check
- bool IsNullAt(int i) const;
+ bool is_null_at(int i) const;
// Primitive getters
- bool GetBoolean(int i) const;
- int8_t GetInt8(int i) const;
- int16_t GetInt16(int i) const;
- int32_t GetInt32(int i) const;
- int64_t GetInt64(int i) const;
- float GetFloat(int i) const;
- double GetDouble(int i) const;
+ bool get_boolean(int i) const;
+ int8_t get_int8(int i) const;
+ int16_t get_int16(int i) const;
+ int32_t get_int32(int i) const;
+ int64_t get_int64(int i) const;
+ float get_float(int i) const;
+ double get_double(int i) const;
// String/binary getter
- std::string GetString(int i) const;
- std::vector<uint8_t> GetBinary(int i) const;
+ std::string get_string(int i) const;
+ std::vector<uint8_t> get_binary(int i) const;
// Nested types
- std::shared_ptr<Row> GetStruct(int i) const;
- std::shared_ptr<ArrayData> GetArray(int i) const;
- std::shared_ptr<MapData> GetMap(int i) const;
+ std::shared_ptr<Row> get_struct(int i) const;
+ std::shared_ptr<ArrayData> get_array(int i) const;
+ std::shared_ptr<MapData> get_map(int i) const;
// Metadata
int num_fields() const;
SchemaPtr schema() const;
// Debug
- std::string ToString() const;
+ std::string to_string() const;
};
```
@@ -228,22 +228,22 @@ The `ArrayData` class provides access to list/array
elements:
class ArrayData {
public:
// Null check
- bool IsNullAt(int i) const;
+ bool is_null_at(int i) const;
// Element count
int num_elements() const;
// Primitive getters (same as Row)
- int32_t GetInt32(int i) const;
+ int32_t get_int32(int i) const;
// ... other primitives
// String getter
- std::string GetString(int i) const;
+ std::string get_string(int i) const;
// Nested types
- std::shared_ptr<Row> GetStruct(int i) const;
- std::shared_ptr<ArrayData> GetArray(int i) const;
- std::shared_ptr<MapData> GetMap(int i) const;
+ std::shared_ptr<Row> get_struct(int i) const;
+ std::shared_ptr<ArrayData> get_array(int i) const;
+ std::shared_ptr<MapData> get_map(int i) const;
// Type info
ListTypePtr type() const;
@@ -358,15 +358,15 @@ auto my_schema = schema({
// Create writer
RowWriter writer(my_schema);
-writer.Reset();
+writer.reset();
-// Write fields
-writer.Write(0, 42); // x = 42
-writer.Write(1, 3.14); // y = 3.14
-writer.WriteString(2, "test"); // name = "test"
+// write fields
+writer.write(0, 42); // x = 42
+writer.write(1, 3.14); // y = 3.14
+writer.write_string(2, "test"); // name = "test"
-// Get result
-auto row = writer.ToRow();
+// get result
+auto row = writer.to_row();
```
### ArrayWriter
@@ -379,26 +379,26 @@ auto array_type = list(int32());
// Create writer
ArrayWriter writer(array_type);
-writer.Reset(5); // 5 elements
+writer.reset(5); // 5 elements
-// Write elements
+// write elements
for (int i = 0; i < 5; i++) {
- writer.Write(i, i * 10);
+ writer.write(i, i * 10);
}
-// Get result
-auto array = writer.CopyToArrayData();
+// get result
+auto array = writer.copy_to_array_data();
```
### Null Values
```cpp
// Set null at specific index
-writer.SetNullAt(2); // Field 2 is null
+writer.set_null_at(2); // Field 2 is null
// Check null when reading
-if (!row->IsNullAt(2)) {
- std::string value = row->GetString(2);
+if (!row->is_null_at(2)) {
+ std::string value = row->get_string(2);
}
```
@@ -443,10 +443,10 @@ if (!row->IsNullAt(2)) {
```cpp
RowEncoder<Person> encoder;
-// Encode multiple records
+// encode multiple records
for (const auto& person : people) {
- encoder.Encode(person);
- auto row = encoder.GetWriter().ToRow();
+ encoder.encode(person);
+ auto row = encoder.get_writer().to_row();
// Process row...
}
```
@@ -454,9 +454,9 @@ for (const auto& person : people) {
### 2. Pre-allocate Buffer
```cpp
-// Get buffer reference for pre-allocation
-auto& buffer = encoder.GetWriter().buffer();
-buffer->Reserve(expected_size);
+// get buffer reference for pre-allocation
+auto& buffer = encoder.get_writer().buffer();
+buffer->reserve(expected_size);
```
### 3. Batch Processing
@@ -466,26 +466,26 @@ buffer->Reserve(expected_size);
std::vector<Person> batch;
batch.reserve(BATCH_SIZE);
-while (hasMore()) {
+while (has_more()) {
batch.clear();
- fillBatch(batch);
+ fill_batch(batch);
for (const auto& person : batch) {
- encoder.Encode(person);
- process(encoder.GetWriter().ToRow());
+ encoder.encode(person);
+ process(encoder.get_writer().to_row());
}
}
```
-### 4. Zero-Copy Reading
+### 4. Zero-copy Reading
```cpp
// Point to existing buffer (zero-copy)
Row row(schema);
-row.PointTo(buffer, offset, size);
+row.point_to(buffer, offset, size);
// Access fields directly from buffer
-int32_t id = row.GetInt32(0);
+int32_t id = row.get_int32(0);
```
## Supported Types Summary
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
