.. _expression_functions:

Expression Functions
================================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

Content Chimera provides a comprehensive set of functions that can be used in expressions for data transformation and analysis. These functions are grouped into several categories for different types of operations:

Choosing the right function
-----------------------------------------

Different functions serve different purposes. Here's a quick guide for common scenarios:

* For text manipulation, use the :ref:`Text Processing Functions <text_processing>` like ``text_transform``, ``regex``, or ``xpath``.
* For numerical calculations, use the :ref:`Mathematical Functions <mathematical>` like ``avg``, ``sum``, or basic arithmetic operations.
* For conditional logic, use the :ref:`Logical Functions <logical>` like ``if``, ``case``, or boolean operations.
* For value lookups, use the :ref:`Mapping Functions <mapping>` like ``map``.

Comparison of function types
---------------------------------

This is a brief comparison of the function categories available:

+---------------------+------------------+------------------+----------------------+
|                     | Primary Use      | Examples         | Common Use Cases     |
+=====================+==================+==================+======================+
| :ref:`Text Processing <text_processing>` | Manipulating and | text_transform,  | Cleaning HTML,       |
|                     | extracting text  | regex, xpath     | extracting patterns  |
+---------------------+------------------+------------------+----------------------+
| **Mathematical**    | Numerical        | avg, sum, min,   | Aggregating values,  |
|                     | calculations     | max, +, -, /     | calculating metrics  |
+---------------------+------------------+------------------+----------------------+
| **Logical**         | Conditional      | if, case, and,   | Decision making,     |
|                     | operations       | or, not          | branching logic      |
+---------------------+------------------+------------------+----------------------+
| **Mapping**         | Value lookups    | map              | Normalizing values,  |
|                     |                  |                  | categorization       |
+---------------------+------------------+------------------+----------------------+

.. _text_processing:

Text Processing Functions
-------------------------

text_transform
^^^^^^^^^^^^^^
Transforms HTML text by cleaning it up, removing unnecessary attributes and tags.

**Parameters:**

* text (required): The HTML text to transform
* transformer_id (optional): Specific transformer ID to use

**Returns:** Transformed text with HTML cleaned up

**Example:**

.. code-block:: VB.net

   text_transform("<p style='color: red'>Hello</p>")
   // Returns: <p>Hello</p>

**Special considerations:**
When no specific transformer is provided, a generic transformer is used. This function is useful for cleaning up HTML content before display or analysis.

xpath
^^^^^
Extracts values from HTML using XPath queries.

**Parameters:**

* html (required): The HTML to parse
* xpath_query (required): XPath query to execute

**Returns:** Comma-separated list of matching node values

**Example:**

.. code-block:: VB.net

   xpath("<div><p>Hello</p><p>World</p></div>", "//p")
   // Returns: Hello,World

**Special considerations:**
Uses PHP's DOMDocument and DOMXPath for parsing. Internal errors during HTML parsing are suppressed.

regex / regexall
^^^^^^^^^^^^^^^^
Pattern matching with optional capture groups.

**Parameters:**

* string (required): Text to search in
* pattern (required): Regular expression pattern

**Returns:** 

* For regex: First capture group match or true/false if no capture group
* For regexall: All capture group matches concatenated or true/false if no capture group

**Example:**

.. code-block:: VB.net

   regex("hello123world", "/\\d+/")
   // Returns: true, since there is a match but no capture group (in parentheses)

   regex("hello123world", "/hello(\\d+)world/")
   // Returns: 123

**Special considerations:**
Make sure to properly escape regular expression patterns (including with a leading and trailing slahs). The regex function returns only the first match, while regexall returns all matches.

substring
^^^^^^^^^
Extracts a portion of a string.

**Parameters:**

* string (required): Source string
* start (required): Starting position
* length (required): Number of characters to extract

**Returns:** Extracted substring

**Example:**

.. code-block:: VB.net

   substring("hello world", 0, 5)
   // Returns: hello

char_count
^^^^^^^^^^
Counts characters in a string.

**Parameters:**

* string (required): Text to count

**Returns:** Number of characters

**Example:**

.. code-block:: VB.net

   char_count("hello")
   // Returns: 5

**Special considerations:**
Uses PHP's mb_strlen function to properly handle multi-byte characters.

word_count
^^^^^^^^^^
Counts words in a string.

**Parameters:**

* string (required): Text to count

**Returns:** Number of words

**Example:**

.. code-block:: VB.net

   word_count("hello world")
   // Returns: 2

**Special considerations:**
Uses a custom implementation (Utilities::mb_str_word_count) to handle multi-byte characters.

trim
^^^^
Removes whitespace from string edges.

**Parameters:**

* string (required): Text to trim

**Returns:** Trimmed string

**Example:**

.. code-block:: VB.net

   trim("  hello  ")
   // Returns: hello

starts_with / starts_with_any
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Checks if string starts with pattern(s).

**Parameters:**

* string (required): Text to check
* pattern(s) (required): Single pattern or comma-separated patterns for _any variant

**Returns:** Boolean true/false

**Example:**

.. code-block:: VB.net

   starts_with("hello world", "hello")
   // Returns: true

   starts_with_any("hello world", "hi,hello,hey")
   // Returns: true

contains / contains_any
^^^^^^^^^^^^^^^^^^^^^^^
Checks if string contains pattern(s).

**Parameters:**

* string (required): Text to check
* pattern(s) (required): Single pattern or comma-separated patterns for _any variant

**Returns:** Boolean true/false

**Example:**

.. code-block:: VB.net

   contains("hello world", "world")
   // Returns: true

   contains_any("hello world", "earth,world,mars")
   // Returns: true

concat
^^^^^^
Concatenates multiple strings.

**Parameters:**

* strings (required): Two or more strings to concatenate

**Returns:** Concatenated string

**Example:**

.. code-block:: VB.net

   concat("hello", " ", "world")
   // Returns: hello world

parse_url
^^^^^^^^^
Parses URL components.

**Parameters:**

* url (required): URL to parse
* component (required): Component to extract (host, scheme, path, query, or fragment)

**Returns:** Requested URL component or error message

**Example:**

.. code-block:: VB.net

   parse_url("https://example.com/path?q=1", "host")
   // Returns: example.com

**Special considerations:**
Returns error messages if URL parsing fails or if the requested component doesn't exist in the URL.

.. _mathematical:

Mathematical Functions
----------------------

avg / avg_zn
^^^^^^^^^^^^^
Calculates average of values.

**Parameters:**

* values (required): Numbers to average

**Returns:** 

* avg: Average excluding null/empty values
* avg_zn: Average including null/empty values as zero

**Example:**

.. code-block:: VB.net

   avg(1, 2, null, 3)
   // Returns: 2

   avg_zn(1, 2, null, 3)
   // Returns: 1.5

**Special considerations:**
avg ignores null and empty values completely, while avg_zn counts them as zero in the calculation.

sum
^^^
Sums numeric values.

**Parameters:**

* values (required): Numbers to sum

**Returns:** Sum of values

**Example:**

.. code-block:: VB.net

   sum(1, 2, 3)
   // Returns: 6

**Special considerations:**
Null and empty values are ignored in the calculation.

min
^^^
Returns minimum value.

**Parameters:**

* values (required): Numbers to compare

**Returns:** Minimum value

**Example:**

.. code-block:: VB.net

   min(1, 2, 3)
   // Returns: 1

max
^^^
Returns maximum value.

**Parameters:**

* values (required): Numbers to compare

**Returns:** Maximum value

**Example:**

.. code-block:: VB.net

   max(1, 2, 3)
   // Returns: 3

round
^^^^^
Rounds a number.

**Parameters:**

* number (required): Number to round

**Returns:** Rounded integer

**Example:**

.. code-block:: VB.net

   round(1.6)
   // Returns: 2

**Special considerations:**
Returns null if the input is null or empty.

Arithmetic Operations
^^^^^^^^^^^^^^^^^^^^^
Basic arithmetic operations: divide (/), add (+), subtract (-), multiply (*).

**Parameters:**

* number1 (required): First number
* number2 (required): Second number

**Returns:** Result of arithmetic operation

**Special considerations:**
Division by zero will raise an error.

**Example:**

.. code-block:: VB.net

   10 / 2
   // Returns: 5

   3 + 4
   // Returns: 7

   5 - 2
   // Returns: 3

   6 * 2
   // Returns: 12

counta
^^^^^^
Counts non-empty values.

**Parameters:**

* values (required): Values to count

**Returns:** Count of non-empty values

**Example:**

.. code-block:: VB.net

   counta(1, null, "", 3)
   // Returns: 2

.. _logical:

Logical Functions
-----------------

if
^^
Conditional execution.

**Parameters:**

* condition (required): Boolean condition
* true_value (required): Value if condition is true
* false_value (optional): Value if condition is false (null if omitted)

**Returns:** Selected value based on condition

**Example:**

.. code-block:: VB.net

   if(5 > 3, "yes", "no")
   // Returns: yes

ifnull / isnull
^^^^^^^^^^^^^^^
Null value handling.

**Parameters:**

For ifnull:

* test_value (required): Value to test
* if_null_value (required): Value to return if test_value is null
* if_not_null_value (optional): Value to return if test_value is not null

For isnull:

* value (required): Value to test

**Returns:**

* ifnull: Selected value based on null test
* isnull: Boolean indicating if value is null

**Example:**

.. code-block:: VB.net

   ifnull(null, "was null", "not null")
   // Returns: was null

   isnull(null)
   // Returns: true

case
^^^^
Multiple condition handling.

**Parameters:**

* condition1, value1, condition2, value2, ..., default_value

**Returns:** First value whose condition is true, or default_value if no conditions are true

**Example:**

.. code-block:: VB.net

   case(x > 10, "high", x > 5, "medium", "low")

and
^^^
Logical AND operation.

**Parameters:**

* conditions (required): Two or more conditions

**Returns:** true if all conditions are true, false otherwise

**Example:**

.. code-block:: VB.net

   and(5 > 3, 2 < 4)
   // Returns: true

or
^^
Logical OR operation.

**Parameters:**

* conditions (required): Two or more conditions

**Returns:** true if any condition is true, false otherwise

**Example:**

.. code-block:: VB.net

   or(5 < 3, 2 < 4)
   // Returns: true

not
^^^
Logical NOT operation.

**Parameters:**

* condition (required): Condition to negate

**Returns:** Opposite of the condition's boolean value

**Example:**

.. code-block:: VB.net

   not(5 < 3)
   // Returns: true

Special Constants
^^^^^^^^^^^^^^^^^
Special constant values for logical operations:

* true: Boolean true value
* false: Boolean false value
* null: Null value
* now: Current date and time

**Example:**

.. code-block:: VB.net

   if(true, "always", "never")
   // Returns: always

.. _mapping:

Mapping Functions
-----------------

map
^^^
Looks up values in defined mappings.

**Parameters:**

* map_name (required): Name of the mapping to use
* lookup_value (required): Value to look up in the mapping

**Returns:** Mapped value or null if not found

**Special considerations:**

* Map must be defined and valid for the current extent
* Returns null if the map is not valid for the current extent

**Example:**

.. code-block:: VB.net

   map("content_type_map", "article")
   // Returns: mapped value for "article" in content_type_map