0
# Built-in Functions
1

2
Extensible function system with built-in implementations for common operations. Functions provide powerful data transformation and query capabilities within JMESPath expressions.
3

4
## Capabilities
5

6
### Function Base Class
7

8
Abstract base class for all function implementations, providing the foundation for the extensible function system.
9

10
```java { .api }
11
public abstract class JmesPathFunction implements JmesPathExpression {
12
    /**
13
     * Creates a function with the specified argument expressions
14
     * @param expressions List of argument expressions
15
     */
16
    public JmesPathFunction(List<JmesPathExpression> expressions);
17
    
18
    /**
19
     * Gets the list of argument expressions
20
     * @return List of JmesPathExpression arguments
21
     */
22
    public List<JmesPathExpression> getExpressions();
23
    
24
    /**
25
     * Evaluates the function with the provided evaluated arguments
26
     * @param evaluatedArgs List of JsonNode values from evaluated arguments
27
     * @return JsonNode result of the function evaluation
28
     */
29
    public abstract JsonNode evaluate(List<JsonNode> evaluatedArgs);
30
    
31
    public <Input, Output> Output accept(JmesPathVisitor<Input, Output> visitor, Input input) 
32
        throws InvalidTypeException;
33
}
34
```
35

36
### Length Function
37

38
Determines the length of arrays, objects, or strings. Essential for size-based filtering and validation.
39

40
```java { .api }
41
public class JmesPathLengthFunction extends JmesPathFunction {
42
    /**
43
     * Creates a length function with variable arguments
44
     * @param expressions Variable number of argument expressions
45
     */
46
    public JmesPathLengthFunction(JmesPathExpression... expressions);
47
    
48
    /**
49
     * Creates a length function with a list of arguments
50
     * @param arguments List of argument expressions
51
     */
52
    public JmesPathLengthFunction(List<JmesPathExpression> arguments);
53
    
54
    /**
55
     * Evaluates the length of the provided argument
56
     * @param evaluatedArgs List containing a single JsonNode argument
57
     * @return IntNode containing the length value
58
     * @throws InvalidTypeException If argument is not string, array, or object
59
     */
60
    public JsonNode evaluate(List<JsonNode> evaluatedArgs) throws InvalidTypeException;
61
}
62
```
63

64
**Supported Types:**
65
- **String**: Returns character count
66
- **Array**: Returns element count
67
- **Object**: Returns property count
68
- **Other types**: Throws `InvalidTypeException`
69

70
**Usage Examples:**
71

72
```java
73
// Get length of an array: length(items)
74
JmesPathLengthFunction arrayLength = new JmesPathLengthFunction(
75
    new JmesPathField("items")
76
);
77

78
// Get length of a string field: length(name)
79
JmesPathLengthFunction stringLength = new JmesPathLengthFunction(
80
    new JmesPathField("name")
81
);
82

83
// Use in filter: items[?length(tags) > 2]
84
JmesPathFilter lengthFilter = new JmesPathFilter(
85
    new JmesPathField("items"),
86
    new JmesPathIdentity(),
87
    new OpGreaterThan(
88
        new JmesPathLengthFunction(new JmesPathField("tags")),
89
        new JmesPathLiteral(mapper.valueToTree(2))
90
    )
91
);
92
```
93

94
### Contains Function
95

96
Checks if an array contains a specific value or if a string contains a substring.
97

98
```java { .api }
99
public class JmesPathContainsFunction extends JmesPathFunction {
100
    /**
101
     * Creates a contains function with variable arguments
102
     * @param expressions Variable number of argument expressions (subject, search)
103
     */
104
    public JmesPathContainsFunction(JmesPathExpression... expressions);
105
    
106
    /**
107
     * Creates a contains function with a list of arguments
108
     * @param expressions List of argument expressions (subject, search)
109
     */
110
    public JmesPathContainsFunction(List<JmesPathExpression> expressions);
111
    
112
    /**
113
     * Evaluates whether the subject contains the search value
114
     * @param evaluatedArgs List containing subject and search JsonNode values
115
     * @return BooleanNode.TRUE if subject contains search, BooleanNode.FALSE otherwise
116
     * @throws InvalidTypeException If subject is not string or array
117
     */
118
    public JsonNode evaluate(List<JsonNode> evaluatedArgs);
119
}
120
```
121

122
**Behavior:**
123
- **Array subject**: Returns true if any array element equals the search value (deep equality)
124
- **String subject**: Returns true if the string contains the search substring
125
- **Other types**: Throws `InvalidTypeException`
126

127
**Usage Examples:**
128

129
```java
130
// Check if array contains value: contains(categories, 'electronics')
131
JmesPathContainsFunction arrayContains = new JmesPathContainsFunction(
132
    new JmesPathField("categories"),
133
    new JmesPathLiteral("electronics")
134
);
135

136
// Check if string contains substring: contains(description, 'sale')
137
JmesPathContainsFunction stringContains = new JmesPathContainsFunction(
138
    new JmesPathField("description"),
139
    new JmesPathLiteral("sale")
140
);
141

142
// Use in filter: products[?contains(tags, 'featured')]
143
JmesPathFilter containsFilter = new JmesPathFilter(
144
    new JmesPathField("products"),
145
    new JmesPathIdentity(),
146
    new JmesPathContainsFunction(
147
        new JmesPathField("tags"),
148
        new JmesPathLiteral("featured")
149
    )
150
);
151
```
152

153
### Complex Function Usage
154

155
Functions can be combined with other expressions for sophisticated queries:
156

157
```java
158
// Complex query: items[?length(name) > 5 && contains(categories, 'tech')]
159
JmesPathFilter complexQuery = new JmesPathFilter(
160
    new JmesPathField("items"),
161
    new JmesPathIdentity(),
162
    new JmesPathAndExpression(
163
        new OpGreaterThan(
164
            new JmesPathLengthFunction(new JmesPathField("name")),
165
            new JmesPathLiteral(mapper.valueToTree(5))
166
        ),
167
        new JmesPathContainsFunction(
168
            new JmesPathField("categories"),
169
            new JmesPathLiteral("tech")
170
        )
171
    )
172
);
173
```
174

175
### Function Chaining
176

177
Functions can be used within projections and sub-expressions:
178

179
```java
180
// Project with function: items[*].length(tags)
181
JmesPathProjection functionProjection = new JmesPathProjection(
182
    new JmesPathField("items"),
183
    new JmesPathLengthFunction(new JmesPathField("tags"))
184
);
185

186
// Nested function calls: length(items[?contains(name, 'pro')])
187
JmesPathLengthFunction nestedFunction = new JmesPathLengthFunction(
188
    new JmesPathFilter(
189
        new JmesPathField("items"),
190
        new JmesPathIdentity(),
191
        new JmesPathContainsFunction(
192
            new JmesPathField("name"),
193
            new JmesPathLiteral("pro")
194
        )
195
    )
196
);
197
```
198

199
## Custom Function Implementation
200

201
To implement custom functions, extend the `JmesPathFunction` base class:
202

203
```java
204
public class CustomFunction extends JmesPathFunction {
205
    public CustomFunction(List<JmesPathExpression> expressions) {
206
        super(expressions);
207
    }
208
    
209
    @Override
210
    public JsonNode evaluate(List<JsonNode> evaluatedArgs) {
211
        // Custom function logic here
212
        // Validate arguments and return JsonNode result
213
        // Throw InvalidTypeException for type mismatches
214
    }
215
}
216
```
217

218
## Type Definitions
219

220
### Exception Handling
221

222
```java { .api }
223
public class InvalidTypeException extends RuntimeException {
224
    // Thrown when function arguments have incompatible types
225
}
226
```
227

228
### Jackson Dependencies
229

230
```java { .api }
231
import com.fasterxml.jackson.databind.JsonNode;
232
import com.fasterxml.jackson.databind.node.BooleanNode;
233
import com.fasterxml.jackson.databind.node.IntNode;
234
```
235

236
Functions work with Jackson's `JsonNode` system for type-safe JSON processing and return appropriate node types based on their operations.