Collection Operations

Collection operations in the expression language provide powerful mechanisms for testing membership and filtering based on sets of values. This chapter provides a comprehensive overview of collection operations, their syntax, capabilities, and best practices.

in Operator

The in operator is the primary collection operation, used to test whether a value is present in a given set of values. Its counterpart, NOT IN, tests for the absence of a value in the set.

Basic Syntax

field in (value1, value2, ...)
field NOT in (value1, value2, ...)

Value Types and Type Handling

The in operator supports multiple value types within the same list:

1. String Values

   status in ("active", "pending", "completed")

2. Numeric Values

   • Integers and floating-point numbers are supported
   • All numbers are internally handled as float64

   priority in (1, 2.5, 3.14)

3. Mixed Value Types

   value in ("test", 42, "hello", 3.14)

Syntax Flexibility

1. Optional Commas Both formats are valid:

   status in ("active", "pending", "completed")
   status in ("active" "pending" "completed")

2. Single Value Lists

   category in ("books")

3. Empty Lists

   value in ()  // Always evaluates to false
   value NOT in ()  // Always evaluates to true

Edge Cases and Error Handling

1. Invalid Syntax

   // Missing opening parenthesis - Error
   status in "active", "pending")
   
   // Invalid number format - Error
   priority in (1, 2.5.5, 3)
   
   // Unexpected tokens - Error
   status in ("test", ==, "value")

2. Type Mismatches

   • The in operator performs strict type checking
   • No automatic type conversion between strings and numbers

   // This will not match even if status contains "42"
   status in (42)

Best Practices

1. List Organization

   // Preferred: Use commas for better readability
   status in ("active", "pending", "completed")
   
   // Avoid: Space-separated values can be less clear
   status in ("active" "pending" "completed")

2. Value Ordering

   // Preferred: Organize similar values together
   type in ("error", "warning", "critical", 404, 500, 503)

3. Type Consistency

   // Preferred: Use consistent types when possible
   priority in (1, 2, 3, 4, 5)
   status in ("active", "pending", "completed")
   
   // Avoid mixing types unless necessary
   value in ("high", 1, "low", 2)

4. List Length

   // Consider breaking very long lists into logical groups
   // Instead of:
   status in ("pending", "active", "paused", "cancelled", "expired", "deleted", "archived")
   
   // Use:
   (status in ("pending", "active", "paused") OR 
    status in ("cancelled", "expired", "deleted", "archived"))

Implementation Details

The in operator is implemented with the following characteristics:

1. Value Parsing

   • String values are stored as-is
   • Numeric values are parsed as float64
   • Invalid number formats trigger parsing errors

2. List Evaluation

   • Values are compared using strict equality
   • Type checking is performed during comparison
   • Empty lists are handled as special cases

3. Performance Considerations

   • Lists are evaluated linearly
   • Consider list size impact on performance
   • Very large lists might benefit from alternative approaches

Common Use Cases

1. Status Checking

   status in ("active", "pending")

2. Error Code Filtering

   code in (404, 500, 503)

3. Category Matching

   category in ("books", "electronics", "clothing")

4. Permission Validation

   role in ("admin", "moderator", "editor")

Integration with Other Features

1. With Logical Operators

   status in ("active", "pending") AND priority > 3

2. With Parentheses

   (status in ("active", "pending") OR priority in (1, 2)) AND category == "urgent"

3. With NOT Operator

   status NOT in ("deleted", "archived")