From 0aa209b6ea45f3d01c7f9f507d0e152795b699dc Mon Sep 17 00:00:00 2001 From: Tpt Date: Sat, 6 Mar 2021 11:13:51 +0100 Subject: [PATCH] Improves Graph and Dataset documentation --- lib/src/model/dataset.rs | 57 +++++++++++++++++++++++++++++----------- lib/src/model/graph.rs | 34 ++++++++++++++++++++---- 2 files changed, 71 insertions(+), 20 deletions(-) diff --git a/lib/src/model/dataset.rs b/lib/src/model/dataset.rs index b51ad5a3..27b617cb 100644 --- a/lib/src/model/dataset.rs +++ b/lib/src/model/dataset.rs @@ -464,7 +464,7 @@ impl Dataset { /// let file = " .\n".as_bytes(); /// /// let mut store = Dataset::new(); - /// store.load(file, DatasetFormat::NQuads,None)?; + /// store.load(file, DatasetFormat::NQuads, None)?; /// /// let mut buffer = Vec::new(); /// store.dump(&mut buffer, DatasetFormat::NQuads)?; @@ -558,7 +558,31 @@ impl Dataset { /// Applies on the dataset the canonicalization process described in /// [Canonical Forms for Isomorphic and Equivalent RDF Graphs: Algorithms for Leaning and Labelling Blank Nodes, Aidan Hogan, 2017](http://aidanhogan.com/docs/rdf-canonicalisation.pdf) /// - /// Warning: This implementation worst-case complexity is in O(b!) with b the number of blank nodes in the input graphs. + /// Usage example ([Dataset isomorphim](https://www.w3.org/TR/rdf11-concepts/#dfn-dataset-isomorphism)): + /// ``` + /// use oxigraph::io::DatasetFormat; + /// use oxigraph::model::Dataset; + /// + /// let file = "GRAPH _:a1 { [ ] . }".as_bytes(); + /// + /// let mut dataset1 = Dataset::new(); + /// dataset1.load(file, DatasetFormat::TriG, None)?; + /// let mut dataset2 = Dataset::new(); + /// dataset2.load(file, DatasetFormat::TriG, None)?; + /// + /// assert_ne!(dataset1, dataset2); + /// dataset1.canonicalize(); + /// dataset2.canonicalize(); + /// assert_eq!(dataset1, dataset2); + /// # Result::<_,Box>::Ok(()) + /// ``` + /// + /// Warning 1: Blank node ids depends on the current shape of the graph. Adding a new quad might change the ids of a lot of blank nodes. + /// Hence, this canonization might not be suitable for diffs. + /// + /// Warning 2: The canonicalization algorithm is not stable and canonical blank node Ids might change between Oxigraph version. + /// + /// Warning 3: This implementation worst-case complexity is in *O(b!)* with b the number of blank nodes in the input dataset. pub fn canonicalize(&mut self) { let bnodes = self.blank_nodes(); let (hash, partition) = @@ -1122,15 +1146,15 @@ impl<'a> GraphView<'a> { /// Usage example: /// ``` /// use oxigraph::io::GraphFormat; - /// use oxigraph::model::Graph; + /// use oxigraph::model::*; /// - /// let file = " .\n".as_bytes(); - /// - /// let mut store = Graph::new(); - /// store.load(file, GraphFormat::NTriples,None)?; + /// let mut dataset = Dataset::new(); + /// let ex = NamedNodeRef::new("http://example.com")?; + /// dataset.insert(QuadRef::new(ex, ex, ex, ex)); /// + /// let file = " .\n".as_bytes(); /// let mut buffer = Vec::new(); - /// store.dump(&mut buffer, GraphFormat::NTriples)?; + /// dataset.graph(ex).dump(&mut buffer, GraphFormat::NTriples)?; /// assert_eq!(file, buffer.as_slice()); /// # Result::<_,Box>::Ok(()) /// ``` @@ -1281,13 +1305,14 @@ impl<'a> GraphViewMut<'a> { /// use oxigraph::model::*; /// use oxigraph::io::GraphFormat; /// - /// let mut graph = Graph::new(); + /// let mut dataset = Dataset::new(); + /// let mut graph = dataset.graph_mut(NamedNodeRef::new("http://example.com")?); /// /// // insertion /// let file = b" ."; /// graph.load(file.as_ref(), GraphFormat::NTriples, None)?; /// - /// // we inspect the store contents + /// // we inspect the dataset contents /// let ex = NamedNodeRef::new("http://example.com")?; /// assert!(graph.contains(TripleRef::new(ex, ex, ex))); /// # Result::<_,Box>::Ok(()) @@ -1425,15 +1450,17 @@ impl<'a> GraphViewMut<'a> { /// Usage example: /// ``` /// use oxigraph::io::GraphFormat; - /// use oxigraph::model::Graph; + /// use oxigraph::model::*; /// - /// let file = " .\n".as_bytes(); + /// let mut dataset = Dataset::new(); + /// let mut graph = dataset.graph_mut(NamedNodeRef::new("http://example.com")?); /// - /// let mut store = Graph::new(); - /// store.load(file, GraphFormat::NTriples,None)?; + /// let ex = NamedNodeRef::new("http://example.com")?; + /// graph.insert(TripleRef::new(ex, ex, ex)); /// + /// let file = " .\n".as_bytes(); /// let mut buffer = Vec::new(); - /// store.dump(&mut buffer, GraphFormat::NTriples)?; + /// graph.dump(&mut buffer, GraphFormat::NTriples)?; /// assert_eq!(file, buffer.as_slice()); /// # Result::<_,Box>::Ok(()) /// ``` diff --git a/lib/src/model/graph.rs b/lib/src/model/graph.rs index b40f6582..9b25042e 100644 --- a/lib/src/model/graph.rs +++ b/lib/src/model/graph.rs @@ -187,7 +187,7 @@ impl Graph { /// let file = b" ."; /// graph.load(file.as_ref(), GraphFormat::NTriples, None)?; /// - /// // we inspect the store contents + /// // we inspect the graph contents /// let ex = NamedNodeRef::new("http://example.com")?; /// assert!(graph.contains(TripleRef::new(ex, ex, ex))); /// # Result::<_,Box>::Ok(()) @@ -216,11 +216,11 @@ impl Graph { /// /// let file = " .\n".as_bytes(); /// - /// let mut store = Graph::new(); - /// store.load(file, GraphFormat::NTriples,None)?; + /// let mut graph = Graph::new(); + /// graph.load(file, GraphFormat::NTriples, None)?; /// /// let mut buffer = Vec::new(); - /// store.dump(&mut buffer, GraphFormat::NTriples)?; + /// graph.dump(&mut buffer, GraphFormat::NTriples)?; /// assert_eq!(file, buffer.as_slice()); /// # Result::<_,Box>::Ok(()) /// ``` @@ -230,8 +230,32 @@ impl Graph { /// Applies on the graph the canonicalization process described in /// [Canonical Forms for Isomorphic and Equivalent RDF Graphs: Algorithms for Leaning and Labelling Blank Nodes, Aidan Hogan, 2017](http://aidanhogan.com/docs/rdf-canonicalisation.pdf) + /// + /// Usage example ([Graph isomorphim](https://www.w3.org/TR/rdf11-concepts/#dfn-graph-isomorphism)): + /// ``` + /// use oxigraph::io::GraphFormat; + /// use oxigraph::model::Graph; + /// + /// let file = " [ ] .".as_bytes(); + /// + /// let mut graph1 = Graph::new(); + /// graph1.load(file, GraphFormat::Turtle, None)?; + /// let mut graph2 = Graph::new(); + /// graph2.load(file, GraphFormat::Turtle, None)?; + /// + /// assert_ne!(graph1, graph2); + /// graph1.canonicalize(); + /// graph2.canonicalize(); + /// assert_eq!(graph1, graph2); + /// # Result::<_,Box>::Ok(()) + /// ``` + /// + /// Warning 1: Blank node ids depends on the current shape of the graph. Adding a new triple might change the ids of a lot of blank nodes. + /// Hence, this canonization might not be suitable for diffs. + /// + /// Warning 2: The canonicalization algorithm is not stable and canonical blank node Ids might change between Oxigraph version. /// - /// Warning: This implementation worst-case complexity is in O(b!) with b the number of blank nodes in the input graphs. + /// Warning 3: This implementation worst-case complexity is in *O(b!)* with b the number of blank nodes in the input graph. pub fn canonicalize(&mut self) { self.dataset.canonicalize() }