(avro) branch branch-1.11 updated: AVRO-3939: [Rust] Add documentation about the new schemata equality comparator to the README.md

[mg...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

mgrigorov pushed a commit to branch branch-1.11
in repository https://gitbox.apache.org/repos/asf/avro.git


The following commit(s) were added to refs/heads/branch-1.11 by this push:
     new 8fb03c245 AVRO-3939: [Rust] Add documentation about the new schemata equality comparator to the README.md
8fb03c245 is described below

commit 8fb03c2455f21845cb53410c46277fb9efb0ebaa
Author: Martin Tzvetanov Grigorov <mg...@apache.org>
AuthorDate: Fri Mar 1 14:23:11 2024 +0200

    AVRO-3939: [Rust] Add documentation about the new schemata equality comparator to the README.md
    
    Signed-off-by: Martin Tzvetanov Grigorov <mg...@apache.org>
    (cherry picked from commit f3f644e2bf17838b4499d4ccba2e88436f704fb4)
---
 lang/rust/avro/README.md  | 40 ++++++++++++++++++++++++++++++++++++++++
 lang/rust/avro/src/lib.rs | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/lang/rust/avro/README.md b/lang/rust/avro/README.md
index 3108e515d..3a48806b7 100644
--- a/lang/rust/avro/README.md
+++ b/lang/rust/avro/README.md
@@ -686,6 +686,46 @@ Similar logic could be applied to the schema namespace, enum symbols and field n
 If the application parses schemas before setting a validator, the default validator will be
 registered and used!
 
+### Custom schema equality comparators
+
+The library provides two implementations of schema equality comparators:
+1. `SpecificationEq` - a comparator that serializes the schemas to their
+canonical forms (i.e. JSON) and compares them as strings. It is the only implementation
+until apache_avro 0.16.0.
+See the [Avro specification](https://avro.apache.org/docs/1.11.1/specification/#parsing-canonical-form-for-schemas)
+for more information!
+2. `StructFieldEq` - a comparator that compares the schemas structurally.
+It is faster than the `SpecificationEq` because it returns `false` as soon as a difference
+is found and is recommended for use!
+It is the default comparator since apache_avro 0.17.0.
+
+To use a custom comparator, you need to implement the `SchemataEq` trait and set it using the
+`set_schemata_equality_comparator` function:
+
+```rust
+use apache_avro::{AvroResult, Schema};
+use apache_avro::schema::Namespace;
+use apache_avro::schema_equality::{SchemataEq, set_schemata_equality_comparator};
+
+#[derive(Debug)]
+struct MyCustomSchemataEq;
+
+impl SchemataEq for MyCustomSchemataEq {
+    fn compare(&self, schema_one: &Schema, schema_two: &Schema) -> bool {
+        todo!()
+    }
+}
+
+// don't parse any schema before registering the custom comparator !
+
+set_schemata_equality_comparator(Box::new(MyCustomSchemataEq));
+
+// ... use the library
+```
+**Note**: the library allows to set a comparator only once per the application lifetime!
+If the application parses schemas before setting a comparator, the default comparator will be
+registered and used!
+
 <!-- cargo-rdme end -->
 
 ## Minimal supported Rust version
diff --git a/lang/rust/avro/src/lib.rs b/lang/rust/avro/src/lib.rs
index bd4b6b663..d84c76b07 100644
--- a/lang/rust/avro/src/lib.rs
+++ b/lang/rust/avro/src/lib.rs
@@ -799,6 +799,46 @@
 //! If the application parses schemas before setting a validator, the default validator will be
 //! registered and used!
 //!
+//! ## Custom schema equality comparators
+//!
+//! The library provides two implementations of schema equality comparators:
+//! 1. `SpecificationEq` - a comparator that serializes the schemas to their
+//! canonical forms (i.e. JSON) and compares them as strings. It is the only implementation
+//! until apache_avro 0.16.0.
+//! See the [Avro specification](https://avro.apache.org/docs/1.11.1/specification/#parsing-canonical-form-for-schemas)
+//! for more information!
+//! 2. `StructFieldEq` - a comparator that compares the schemas structurally.
+//! It is faster than the `SpecificationEq` because it returns `false` as soon as a difference
+//! is found and is recommended for use!
+//! It is the default comparator since apache_avro 0.17.0.
+//!
+//! To use a custom comparator, you need to implement the `SchemataEq` trait and set it using the
+//! `set_schemata_equality_comparator` function:
+//!
+//! ```rust
+//! use apache_avro::{AvroResult, Schema};
+//! use apache_avro::schema::Namespace;
+//! use apache_avro::schema_equality::{SchemataEq, set_schemata_equality_comparator};
+//!
+//! #[derive(Debug)]
+//! struct MyCustomSchemataEq;
+//!
+//! impl SchemataEq for MyCustomSchemataEq {
+//!     fn compare(&self, schema_one: &Schema, schema_two: &Schema) -> bool {
+//!         todo!()
+//!     }
+//! }
+//!
+//! // don't parse any schema before registering the custom comparator !
+//!
+//! set_schemata_equality_comparator(Box::new(MyCustomSchemataEq));
+//!
+//! // ... use the library
+//! ```
+//! **Note**: the library allows to set a comparator only once per the application lifetime!
+//! If the application parses schemas before setting a comparator, the default comparator will be
+//! registered and used!
+//!
 
 mod bigdecimal;
 mod codec;