Merge pull request #142 from rdfjs/fix/equals

Rigorously define equals method on Term and Quad

Author: elf-pavlik

index.html

@@ -131,7 +131,7 @@ <h3><dfn>Term</dfn> interface</h3>
     interface Term {
       attribute string termType;
       attribute string value;
-      boolean equals(Term other);
+      boolean equals(optional Term? other);
     };
     </pre>
 
@@ -148,8 +148,18 @@ <h3><dfn>Term</dfn> interface</h3>
       <dfn>value</dfn> is refined by each interface which extends Term.
     </p>
     <p>
-      <dfn>equals()</dfn> returns <code>true</code> if and only if <code>other</code> has the same
-      <code>termType</code> and the same contents (as defined by concrete subclasses).
+      <dfn>equals()</dfn> returns <code>true</code>
+      when called with parameter <code>other</code>
+      on an object <code>term</code> if all of the conditions below hold:
+    </p>
+    <ul>
+      <li><code>other</code> is <em>neither</em> <code>null</code> nor <code>undefined</code>;</li>
+      <li><code>term.termType</code> is the same string as <code>other.termType</code>;</li>
+      <li><code>other</code> follows the additional constraints of the specific <code>Term</code> interface implemented by <code>term</code>
+        (e.g., <a>NamedNode</a>, <a>Literal</a>, …);</li>
+    </ul>
+    <p>
+      otherwise, it returns <code>false</code>.
     </p>
   </section>
 
@@ -160,7 +170,7 @@ <h3><dfn>NamedNode</dfn> interface</h3>
     interface NamedNode : Term {
       attribute string termType;
       attribute string value;
-      boolean equals(Term other);
+      boolean equals(optional Term? other);
     };
     </pre>
 
@@ -171,8 +181,10 @@ <h3><dfn>NamedNode</dfn> interface</h3>
       <dfn>value</dfn> the IRI of the named node (example: <code>"http://example.org/resource"</code>).
     </p>
     <p>
-      <dfn>equals()</dfn> returns <code>true</code> if and only if <code>other</code> has
-      <code>termType</code> <code>"NamedNode"</code> and the same <code></code>value</code>.
+      <dfn>equals()</dfn> returns <code>true</code> if
+      all general <a>Term.equals</a> conditions hold
+      and <code>term.value</code> is the same string as <code>other.value</code>;
+      otherwise, it returns <code>false</code>.
     </p>
   </section>
 
@@ -183,7 +195,7 @@ <h3><dfn>BlankNode</dfn> interface</h3>
     interface BlankNode : Term {
       attribute string termType;
       attribute string value;
-      boolean equals(Term other);
+      boolean equals(optional Term? other);
     };
     </pre>
 
@@ -196,8 +208,10 @@ <h3><dfn>BlankNode</dfn> interface</h3>
       sourced from RDF/XML, do not change the blank node name (example: <code>"blank3"</code>)
     </p>
     <p>
-      <dfn>equals()</dfn> returns <code>true</code> if and only if <code>other</code> has
-      <code>termType</code> <code>"BlankNode"</code> and the same <code>value</code>.
+      <dfn>equals()</dfn> returns <code>true</code> if
+      all general <a>Term.equals</a> conditions hold
+      and <code>term.value</code> is the same string as <code>other.value</code>;
+      otherwise, it returns <code>false</code>.
     </p>
   </section>
 
@@ -210,7 +224,7 @@ <h3><dfn>Literal</dfn> interface</h3>
       attribute string value;
       attribute string language;
       attribute NamedNode datatype;
-      boolean equals(Term other);
+      boolean equals(optional Term? other);
     };
     </pre>
 
@@ -235,9 +249,12 @@ <h3><dfn>Literal</dfn> interface</h3>
       <code>"http://www.w3.org/2001/XMLSchema#string"</code>.
     </p>
     <p>
-      <dfn>equals()</dfn> returns <code>true</code> if and only if <code>other</code> has
-      <code>termType</code> <code>"Literal"</code> and the same <code>value</code>,
-      <code>language</code>, and <code>datatype</code>.
+      <dfn>equals()</dfn> returns <code>true</code> if
+      all general <a>Term.equals</a> conditions hold,
+      <code>term.value</code> is the same string as <code>other.value</code>,
+      <code>term.language</code> is the same string as <code>other.language</code>, and
+      <code>term.datatype.equals(other.datatype)</code> evaluates to <code>true</code>;
+      otherwise, it returns <code>false</code>.
     </p>
   </section>
 
@@ -248,7 +265,7 @@ <h3><dfn>Variable</dfn> interface</h3>
     interface Variable : Term {
       attribute string termType;
       attribute string value;
-      boolean equals(Term other);
+      boolean equals(optional Term? other);
     };
     </pre>
 
@@ -260,8 +277,10 @@ <h3><dfn>Variable</dfn> interface</h3>
       <code>"a"</code>).
     </p>
     <p>
-      <dfn>equals()</dfn> returns <code>true</code> if and only if <code>other</code> has
-      <code>termType</code> <code>"Variable"</code> and the same <code>value</code>.
+      <dfn>equals()</dfn> returns <code>true</code> if
+      all general <a>Term.equals</a> conditions hold
+      and <code>term.value</code> is the same string as <code>other.value</code>;
+      otherwise, it returns <code>false</code>.
     </p>
   </section>
 
@@ -272,7 +291,7 @@ <h3><dfn>DefaultGraph</dfn> interface</h3>
     interface DefaultGraph : Term {
       attribute string termType;
       attribute string value;
-      boolean equals(Term other);
+      boolean equals(optional Term? other);
     };
     </pre>
 
@@ -287,8 +306,9 @@ <h3><dfn>DefaultGraph</dfn> interface</h3>
       <dfn>value</dfn> contains an empty string as constant value.
     </p>
     <p>
-      <dfn>equals()</dfn> returns <code>true</code> if and only if <code>other</code> has
-      <code>termType</code> <code>"DefaultGraph"</code>.
+      <dfn>equals()</dfn> returns <code>true</code> if
+      all general <a>Term.equals</a> conditions hold;
+      otherwise, it returns <code>false</code>.
     </p>
   </section>
 
@@ -301,7 +321,7 @@ <h3><dfn>Quad</dfn> interface</h3>
       attribute Term predicate;
       attribute Term object;
       attribute Term graph;
-      boolean equals(Quad other);
+      boolean equals(optional Quad? other);
     };
     </pre>
 
@@ -325,8 +345,20 @@ <h3><dfn>Quad</dfn> interface</h3>
       <code>Triple</code> MUST be represented as <code>Quad</code> with <code>graph</code> set to a <code>DefaultGraph</code>
     </p>
     <p>
-      <dfn>equals()</dfn> returns <code>true</code> if and only if the argument is a) of the same
-      type b) has all components equal.
+      <dfn>equals()</dfn> returns <code>true</code>
+      when called with parameter <code>other</code>
+      on an object <code>quad</code> if
+      all of the conditions below hold:
+    </p>
+    <ul>
+      <li><code>other</code> is <em>neither</em> <code>null</code> nor <code>undefined</code>;</li>
+      <li><code>quad.subject.equals(other.subject)</code> evaluates to <code>true</code>;</li>
+      <li><code>quad.predicate.equals(other.predicate)</code> evaluates to <code>true</code>;</li>
+      <li><code>quad.object.equals(other.object)</code> evaluates to a <code>true</code>;</li>
+      <li><code>quad.graph.equals(other.graph)</code> evaluates to a <code>true</code>;</li>
+    </ul>
+    <p>
+      otherwise, it returns <code>false</code>.
     </p>
   </section>