Array Lookup and Query Functions¶
Advanced array filtering functions using comparison operators. These provide alternatives to lambda-based .Filter() for common comparison patterns.
Comparison Query Functions¶
$FindEquals¶
Finds all elements in an array that equal a specific value.
Syntax:
Examples:
// Find all numbers equal to 5
numbers = [1, 5, 3, 5, 7];
result = $FindEquals(numbers, 5); // [5, 5]
// Find all people with age 30
people = [
{ "name": "Alice", "age": 30 },
{ "name": "Bob", "age": 25 },
{ "name": "Charlie", "age": 30 }
];
result = $FindEquals(people, "age", 30);
// [{ name: "Alice", age: 30 }, { name: "Charlie", age: 30 }]
$FindNotEquals¶
Finds all elements in an array that do not equal a specific value.
Syntax:
Example:
// Find all active users
users = [
{ "name": "Alice", "status": "active" },
{ "name": "Bob", "status": "inactive" },
{ "name": "Charlie", "status": "active" }
];
activeUsers = $FindNotEquals(users, "status", "inactive");
$FindGreaterThan¶
Finds all elements greater than a specific value.
Syntax:
Example:
// Find all prices above 100
prices = [50, 120, 80, 150, 90];
expensive = $FindGreaterThan(prices, 100); // [120, 150]
// Find all orders above threshold
orders = [
{ "id": 1, "total": 50 },
{ "id": 2, "total": 150 },
{ "id": 3, "total": 200 }
];
largeOrders = $FindGreaterThan(orders, "total", 100);
$FindGreaterThanOrEqual¶
Finds all elements greater than or equal to a specific value.
Syntax:
Example:
// Find passing grades (>= 60)
grades = [45, 60, 75, 55, 80];
passing = $FindGreaterThanOrEqual(grades, 60); // [60, 75, 80]
$FindLessThan¶
Finds all elements less than a specific value.
Syntax:
Example:
// Find low stock items
inventory = [
{ "product": "A", "quantity": 5 },
{ "product": "B", "quantity": 20 },
{ "product": "C", "quantity": 3 }
];
lowStock = $FindLessThan(inventory, "quantity", 10);
$FindLessThanOrEqual¶
Finds all elements less than or equal to a specific value.
Syntax:
Example:
// Find items within budget
items = [
{ "name": "Item A", "price": 50 },
{ "name": "Item B", "price": 75 },
{ "name": "Item C", "price": 30 }
];
affordable = $FindLessThanOrEqual(items, "price", 50);
Comparison with .Filter()¶
These lookup functions provide a more concise alternative to .Filter() for simple comparisons:
// Using $FindGreaterThan
result1 = $FindGreaterThan(numbers, 10);
// Equivalent using .Filter()
result2 = numbers.Filter((x) => x > 10);
// For property-based queries
result3 = $FindGreaterThan(people, "age", 30);
result4 = people.Filter((p) => p.age > 30);
When to use lookup functions:
- Simple value comparisons
- Property-based filtering without complex logic
- Clearer intent for basic queries
When to use .Filter():
- Complex conditions with multiple criteria
- Logic involving multiple properties
- Custom comparison logic
Common Patterns¶
Pattern 1: Multi-Criteria Filtering¶
// Find items in price range
products = [
{ "name": "A", "price": 50 },
{ "name": "B", "price": 150 }
];
// Between 50 and 100
affordable = $FindGreaterThanOrEqual(products, "price", 50);
inRange = $FindLessThanOrEqual(affordable, "price", 100);
Pattern 2: Exclude Specific Values¶
// Find all statuses except "pending"
orders = [
{ "id": 1, "status": "completed" },
{ "id": 2, "status": "pending" },
{ "id": 3, "status": "shipped" }
];
nonPending = $FindNotEquals(orders, "status", "pending");
Pattern 3: Threshold Alerts¶
// Find accounts below minimum balance
accounts = [
{ "id": 1, "balance": 50 },
{ "id": 2, "balance": 500 },
{ "id": 3, "balance": 25 }
];
lowBalance = $FindLessThan(accounts, "balance", 100);
$Log("Low balance alerts:", lowBalance.Length());
Best Practices¶
- Use for simple comparisons - These functions excel at single-criterion filtering
- Combine for ranges - Chain calls for min/max range queries
- Consider performance - For very large arrays with complex logic,
.Filter()may be more efficient - Property names - Use string literals for property names to avoid typos