0
# Comparison Operations
1

2
Comprehensive set of comparison operators for filtering and conditional operations in JMESPath expressions. Includes equality, inequality, and numeric comparisons with proper type handling.
3

4
## Capabilities
5

6
### Base Comparator
7

8
Abstract base class for all comparison operators, providing the fundamental structure and interface.
9

10
```java { .api }
11
public abstract class Comparator implements JmesPathExpression {
12
    /**
13
     * Creates a comparator with left and right expressions
14
     * @param lhsExpr Left-hand side expression
15
     * @param rhsExpr Right-hand side expression
16
     */
17
    public Comparator(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
18
    
19
    /**
20
     * Gets the left-hand side expression
21
     * @return The LHS expression
22
     */
23
    public JmesPathExpression getLhsExpr();
24
    
25
    /**
26
     * Gets the right-hand side expression
27
     * @return The RHS expression
28
     */
29
    public JmesPathExpression getRhsExpr();
30
    
31
    /**
32
     * Determines if the left and right values match according to this comparator
33
     * @param lhs Left-hand side JsonNode value
34
     * @param rhs Right-hand side JsonNode value
35
     * @return true if the comparison succeeds, false otherwise
36
     */
37
    public abstract boolean matches(JsonNode lhs, JsonNode rhs);
38
    
39
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
40
        throws InvalidTypeException;
41
}
42
```
43

44
### Equality Comparison
45

46
Tests for equality between two JSON values using deep comparison semantics.
47

48
```java { .api }
49
public class OpEquals extends Comparator {
50
    /**
51
     * Creates an equality comparison operator
52
     * @param lhsExpr Left-hand side expression
53
     * @param rhsExpr Right-hand side expression
54
     */
55
    public OpEquals(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
56
    
57
    /**
58
     * Tests if two JsonNode values are equal
59
     * @param lhs Left-hand side value
60
     * @param rhs Right-hand side value
61
     * @return true if values are equal, false otherwise
62
     */
63
    public boolean matches(JsonNode lhs, JsonNode rhs);
64
}
65
```
66

67
**Usage Example:**
68

69
```java
70
// Create equality comparison: field == "value"
71
OpEquals equalityCheck = new OpEquals(
72
    new JmesPathField("status"),
73
    new JmesPathLiteral("active")
74
);
75
```
76

77
### Inequality Comparison
78

79
Tests for inequality between two JSON values.
80

81
```java { .api }
82
public class OpNotEquals extends Comparator {
83
    /**
84
     * Creates an inequality comparison operator
85
     * @param lhsExpr Left-hand side expression
86
     * @param rhsExpr Right-hand side expression
87
     */
88
    public OpNotEquals(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
89
    
90
    /**
91
     * Tests if two JsonNode values are not equal
92
     * @param lhs Left-hand side value
93
     * @param rhs Right-hand side value
94
     * @return true if values are not equal, false otherwise
95
     */
96
    public boolean matches(JsonNode lhs, JsonNode rhs);
97
}
98
```
99

100
**Usage Example:**
101

102
```java
103
// Create inequality comparison: field != "value"
104
OpNotEquals inequalityCheck = new OpNotEquals(
105
    new JmesPathField("type"),
106
    new JmesPathLiteral("deprecated")
107
);
108
```
109

110
### Numeric Comparator Base
111

112
Abstract base class for numeric comparisons that handles type conversion and validation.
113

114
```java { .api }
115
public abstract class NumericComparator extends Comparator {
116
    /**
117
     * Creates a numeric comparator with left and right expressions
118
     * @param lhsExpr Left-hand side expression
119
     * @param rhsExpr Right-hand side expression
120
     */
121
    public NumericComparator(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
122
    
123
    /**
124
     * Compares JsonNode values as numbers, handling type conversion
125
     * @param lhs Left-hand side JsonNode value
126
     * @param rhs Right-hand side JsonNode value
127
     * @return true if numeric comparison succeeds, false otherwise
128
     */
129
    public final boolean matches(JsonNode lhs, JsonNode rhs);
130
    
131
    /**
132
     * Performs the actual numeric comparison on BigDecimal values
133
     * @param lhs Left-hand side BigDecimal value
134
     * @param rhs Right-hand side BigDecimal value
135
     * @return true if comparison succeeds, false otherwise
136
     */
137
    public abstract boolean matches(BigDecimal lhs, BigDecimal rhs);
138
}
139
```
140

141
### Less Than Comparison
142

143
Compares two numeric values for less-than relationship.
144

145
```java { .api }
146
public class OpLessThan extends NumericComparator {
147
    /**
148
     * Creates a less-than comparison operator
149
     * @param lhsExpr Left-hand side expression
150
     * @param rhsExpr Right-hand side expression
151
     */
152
    public OpLessThan(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
153
    
154
    /**
155
     * Tests if left value is less than right value
156
     * @param lhs Left-hand side BigDecimal value
157
     * @param rhs Right-hand side BigDecimal value
158
     * @return true if lhs < rhs, false otherwise
159
     */
160
    public boolean matches(BigDecimal lhs, BigDecimal rhs);
161
}
162
```
163

164
**Usage Example:**
165

166
```java
167
// Create less-than comparison: age < 30
168
OpLessThan lessThanCheck = new OpLessThan(
169
    new JmesPathField("age"),
170
    new JmesPathLiteral(mapper.valueToTree(30))
171
);
172
```
173

174
### Less Than or Equal Comparison
175

176
Compares two numeric values for less-than-or-equal relationship.
177

178
```java { .api }
179
public class OpLessThanOrEqualTo extends NumericComparator {
180
    /**
181
     * Creates a less-than-or-equal comparison operator
182
     * @param lhsExpr Left-hand side expression
183
     * @param rhsExpr Right-hand side expression
184
     */
185
    public OpLessThanOrEqualTo(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
186
    
187
    /**
188
     * Tests if left value is less than or equal to right value
189
     * @param lhs Left-hand side BigDecimal value
190
     * @param rhs Right-hand side BigDecimal value
191
     * @return true if lhs <= rhs, false otherwise
192
     */
193
    public boolean matches(BigDecimal lhs, BigDecimal rhs);
194
}
195
```
196

197
### Greater Than Comparison
198

199
Compares two numeric values for greater-than relationship.
200

201
```java { .api }
202
public class OpGreaterThan extends NumericComparator {
203
    /**
204
     * Creates a greater-than comparison operator
205
     * @param lhsExpr Left-hand side expression
206
     * @param rhsExpr Right-hand side expression
207
     */
208
    public OpGreaterThan(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
209
    
210
    /**
211
     * Tests if left value is greater than right value
212
     * @param lhs Left-hand side BigDecimal value
213
     * @param rhs Right-hand side BigDecimal value
214
     * @return true if lhs > rhs, false otherwise
215
     */
216
    public boolean matches(BigDecimal lhs, BigDecimal rhs);
217
}
218
```
219

220
### Greater Than or Equal Comparison
221

222
Compares two numeric values for greater-than-or-equal relationship.
223

224
```java { .api }
225
public class OpGreaterThanOrEqualTo extends NumericComparator {
226
    /**
227
     * Creates a greater-than-or-equal comparison operator
228
     * @param lhsExpr Left-hand side expression
229
     * @param rhsExpr Right-hand side expression
230
     */
231
    public OpGreaterThanOrEqualTo(JmesPathExpression lhsExpr, JmesPathExpression rhsExpr);
232
    
233
    /**
234
     * Tests if left value is greater than or equal to right value
235
     * @param lhs Left-hand side BigDecimal value
236
     * @param rhs Right-hand side BigDecimal value
237
     * @return true if lhs >= rhs, false otherwise
238
     */
239
    public boolean matches(BigDecimal lhs, BigDecimal rhs);
240
}
241
```
242

243
## Usage Examples
244

245
### Filter with Comparison
246

247
```java
248
// Filter array: users[?age > 18]
249
JmesPathFilter adultFilter = new JmesPathFilter(
250
    new JmesPathField("users"),           // Array to filter
251
    new JmesPathIdentity(),               // Project identity (whole element)
252
    new OpGreaterThan(                    // Comparison condition
253
        new JmesPathField("age"),
254
        new JmesPathLiteral(mapper.valueToTree(18))
255
    )
256
);
257
```
258

259
### Complex Filtering
260

261
```java
262
// Multiple conditions: items[?price < 100 && category != "deprecated"]
263
JmesPathFilter complexFilter = new JmesPathFilter(
264
    new JmesPathField("items"),
265
    new JmesPathIdentity(),
266
    new JmesPathAndExpression(            // AND logical operation
267
        new OpLessThan(
268
            new JmesPathField("price"),
269
            new JmesPathLiteral(mapper.valueToTree(100))
270
        ),
271
        new OpNotEquals(
272
            new JmesPathField("category"),
273
            new JmesPathLiteral("deprecated")
274
        )
275
    )
276
);
277
```
278

279
## Type Definitions
280

281
### Import Dependencies
282

283
```java { .api }
284
import java.math.BigDecimal;
285
import com.fasterxml.jackson.databind.JsonNode;
286
```
287

288
The numeric comparators use `BigDecimal` for precise numeric comparisons and support various JSON numeric types including integers and floating-point numbers.