Skip to content

Commit fc0328b

Browse files
paulinevospaulinevos
committed
Document MongoDB extension type comparisons
Adds an entry to MongoDB extension docs describing how MongoDB types are compared using PHP comparison operators. The types differ in complexity and therefore have various methods of being compared for equality and sorting.
1 parent 89b92b4 commit fc0328b

File tree

2 files changed

+175
-0
lines changed

2 files changed

+175
-0
lines changed

‎reference/mongodb/mongodb.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
&reference.mongodb.mongodb.driver.session;
1515
&reference.mongodb.mongodb.driver.clientencryption;
1616
&reference.mongodb.mongodb.driver.serverapi;
17+
&reference.mongodb.mongodb.driver.comparison;
1718

1819
&reference.mongodb.mongodb.driver.writeconcern;
1920
&reference.mongodb.mongodb.driver.readpreference;

‎reference/mongodb/mongodb/driver/comparison.xml‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- $Revision$ -->
3+
4+
<refentry xml:id="mongodb-driver-object.comparison" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<refnamediv>
6+
<refname>MongoDB type comparison</refname>
7+
<refpurpose>Compares two instances of various types specific to the MongoDB driver</refpurpose>
8+
</refnamediv>
9+
10+
<refsect1 role="description">
11+
&reftitle.description;
12+
<para>
13+
This section describes the comparison of various types specific to the MongoDB driver using the standard comparison
14+
operators (e.g. <code>&lt;</code>, <code>&gt;</code>, <code>==</code>, etc.). The comparison of two instances of a
15+
given type is based on the properties of that type, and may not be consistent across all types.
16+
17+
For example, `MongoDB\BSON\Binary` comparison is based on the length of its data, while `MongoDB\BSON\Int64`
18+
comparison is based on its integer value. Certain types, such as `MongoDB\Driver\WriteConcern`, are considered to
19+
have an arbitrary sort order and are only compared for equality. In such cases, two instances are considered equal
20+
if all of their properties are equal, and not equal otherwise (where $a will always be considered greater than $b,
21+
regardless of its properties).
22+
23+
If comparison between instances of two different types is attempted, then a fallback object comparison is performed
24+
based on the size of the instances.
25+
</para>
26+
</refsect1>
27+
28+
<refsect1 role="description">
29+
<title>Comparison properties per type</title>
30+
<para>
31+
The following table lists the properties used when comparing two instances of the same type,
32+
in the order they are evaluated. Types marked as equality-only do not support a meaningful sort
33+
order: the left-hand operand is always considered greater than the right-hand operand when the
34+
instances are not equal, regardless of their actual property values.
35+
</para>
36+
<table>
37+
<title>Properties used for comparison per type</title>
38+
<tgroup cols="3">
39+
<thead>
40+
<row>
41+
<entry>Type</entry>
42+
<entry>Properties used for comparison (in order)</entry>
43+
<entry>Equality only</entry>
44+
</row>
45+
</thead>
46+
<tbody>
47+
<row>
48+
<entry><classname>MongoDB\BSON\Binary</classname></entry>
49+
<entry>data length, type, data</entry>
50+
<entry>&false;</entry>
51+
</row>
52+
<row>
53+
<entry><classname>MongoDB\BSON\DBPointer</classname></entry>
54+
<entry>ref, id</entry>
55+
<entry>&false;</entry>
56+
</row>
57+
<row>
58+
<entry><classname>MongoDB\BSON\Document</classname></entry>
59+
<entry>raw BSON bytes</entry>
60+
<entry>&false;</entry>
61+
</row>
62+
<row>
63+
<entry><classname>MongoDB\BSON\Int64</classname></entry>
64+
<entry>integer value</entry>
65+
<entry>&false;</entry>
66+
</row>
67+
<row>
68+
<entry><classname>MongoDB\BSON\Javascript</classname></entry>
69+
<entry>code (scope is not considered)</entry>
70+
<entry>&false;</entry>
71+
</row>
72+
<row>
73+
<entry><classname>MongoDB\BSON\MaxKey</classname></entry>
74+
<entry>(none; all instances are equal)</entry>
75+
<entry>&true;</entry>
76+
</row>
77+
<row>
78+
<entry><classname>MongoDB\BSON\MinKey</classname></entry>
79+
<entry>(none; all instances are equal)</entry>
80+
<entry>&true;</entry>
81+
</row>
82+
<row>
83+
<entry><classname>MongoDB\BSON\ObjectId</classname></entry>
84+
<entry>OID bytes</entry>
85+
<entry>&false;</entry>
86+
</row>
87+
<row>
88+
<entry><classname>MongoDB\BSON\PackedArray</classname></entry>
89+
<entry>raw BSON bytes</entry>
90+
<entry>&false;</entry>
91+
</row>
92+
<row>
93+
<entry><classname>MongoDB\BSON\Regex</classname></entry>
94+
<entry>pattern, flags</entry>
95+
<entry>&false;</entry>
96+
</row>
97+
<row>
98+
<entry><classname>MongoDB\BSON\Symbol</classname></entry>
99+
<entry>value</entry>
100+
<entry>&false;</entry>
101+
</row>
102+
<row>
103+
<entry><classname>MongoDB\BSON\Timestamp</classname></entry>
104+
<entry>timestamp, increment</entry>
105+
<entry>&false;</entry>
106+
</row>
107+
<row>
108+
<entry><classname>MongoDB\BSON\Undefined</classname></entry>
109+
<entry>(none; all instances are equal)</entry>
110+
<entry>&true;</entry>
111+
</row>
112+
<row>
113+
<entry><classname>MongoDB\BSON\UTCDateTime</classname></entry>
114+
<entry>milliseconds since Unix epoch</entry>
115+
<entry>&false;</entry>
116+
</row>
117+
<row>
118+
<entry><classname>MongoDB\Driver\ReadConcern</classname></entry>
119+
<entry>level</entry>
120+
<entry>&false;</entry>
121+
</row>
122+
<row>
123+
<entry><classname>MongoDB\Driver\ReadPreference</classname></entry>
124+
<entry>mode, tag sets, maxStalenessSeconds</entry>
125+
<entry>&true;</entry>
126+
</row>
127+
<row>
128+
<entry><classname>MongoDB\Driver\WriteConcern</classname></entry>
129+
<entry>w, journal</entry>
130+
<entry>&true;</entry>
131+
</row>
132+
</tbody>
133+
</tgroup>
134+
</table>
135+
</refsect1>
136+
137+
<refsect1 role="examples">
138+
&reftitle.examples;
139+
<example>
140+
<title>MongoDB type comparison examples</title>
141+
<programlisting role="php">
142+
<![CDATA[
143+
<?php
144+
145+
var_dump(new ReadConcern(ReadConcern::MAJORITY) == new ReadConcern(ReadConcern::MAJORITY));
146+
// Order determined by string comparison of levels
147+
var_dump(new ReadConcern(ReadConcern::AVAILABLE) < new ReadConcern(ReadConcern::MAJORITY));
148+
149+
// Order is arbitrary; left-hand value will always be considered greater. Only equality checks are meaningful.
150+
var_dump(new WriteConcern("majority") < new ReadConcern("default"));
151+
var_dump(new WriteConcern("default") < new ReadConcern("majority"));
152+
153+
// Order is determined by data length
154+
var_dump(new Binary("foo", 1) < new Binary("foobar", 1));
155+
156+
// Order is determined by object size
157+
var_dump(new BSON\Binary("foo", 1) < new BSON\Int(1));
158+
159+
?>
160+
]]>
161+
</programlisting>
162+
&example.outputs;
163+
<screen>
164+
<![CDATA[
165+
bool true
166+
bool false
167+
bool false
168+
bool false
169+
bool true
170+
bool false
171+
]]>
172+
</screen>
173+
</example>
174+
</refsect1>

0 commit comments

Comments
 (0)