### XML Test File Format (qt3tests)

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Example of a test file in the qt3tests catalog format, using XML to define test cases for XPath functions.

```xml
<test-set name="fn-abs">
  <description>Tests for the fn:abs function</description>
  <test-case name="fn-abs-1">
    <description>Test abs with positive integer</description>
    <test>abs(10)</test>
    <result>
      <assert-eq>10</assert-eq>
    </result>
  </test-case>
  <test-case name="fn-abs-2">
    <test>abs(-10)</test>
    <result>
      <assert-eq>10</assert-eq>
    </result>
  </test-case>
</test-set>
```

--------------------------------

### Noir Floating-Point Addition

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Example of performing double-precision floating-point addition in Noir by delegating to the noir_IEEE754 library. Input and output are represented as u64 bit patterns.

```noir
use ieee754::{float64_from_bits, float64_to_bits, add_float64, ...};

fn numeric_add_double(a: u64, b: u64) -> u64 {
    let fa = float64_from_bits(a);
    let fb = float64_from_bits(b);
    float64_to_bits(add_float64(fa, fb))
}
```

--------------------------------

### Rust Stub Function Example

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Example of a stub function generated for an unimplemented XPath function. These stubs assert false and will cause tests to fail until the function is implemented.

```rust
/// Stub for fn:concat - NOT YET IMPLEMENTED
pub fn stub_fnconcat() -> bool {
    assert(false, "fn:concat is not yet implemented");
    false
}
```

--------------------------------

### Project Structure Overview

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Illustrates the directory layout and key files within the noir_XPath project, including main library packages, test directories, and utility scripts.

```tree
noir_XPath/
├── Nargo.toml                          # Workspace configuration
├── ARCHITECTURE.md                     # This file
├── IMPLEMENTATION_PLAN.md              # Phased implementation plan
├── README.md                           # User documentation
├── CONTRIBUTING.md                     # Development guidelines
│
├── xpath/                              # Main library package
│   ├── Nargo.toml
│   └── src/
│       ├── lib.nr                      # Module exports
│       ├── numeric.nr                  # Numeric functions & operators
│       ├── boolean.nr                  # Boolean functions & operators
│       ├── datetime.nr                 # DateTime functions
│       ├── comparison.nr               # Comparison operators
│       └── types.nr                    # Type definitions & conversions
│       # 🔮 Future: string.nr, hash.nr
│
├── xpath_unit_tests/                   # Manual unit tests
│   ├── Nargo.toml
│   └── src/
│       ├── main.nr
│       ├── numeric_tests.nr
│       ├── datetime_tests.nr
│       └── boolean_tests.nr
│
├── test_packages/                      # Auto-generated test packages
│   ├── xpath_test_fn_abs/             # Tests for fn:abs
│   │   ├── Nargo.toml
│   │   └── src/
│   │       ├── main.nr
│   │       └── chunk_*.nr
│   ├── xpath_test_op_numeric_add/     # Tests for op:numeric-add
│   └── ...
│
└── scripts/
    ├── generate_tests.py               # Test generator from qt3tests
    ├── run_tests.py                    # Local test runner
    └── regenerate_tests.sh             # Regenerate all test packages
```

--------------------------------

### List All Discoverable XPath Functions

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Use the `--list-all` option to list all functions, both implemented and unimplemented, that the script can discover.

```bash
python generate_tests.py --list-all
```

--------------------------------

### Run Unconstrained Benchmark

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Executes the unconstrained benchmark and appends results to the default JSON ledger. Use this to gather performance data.

```bash
python3 scripts/benchmark_unconstrained.py
```

--------------------------------

### Display Benchmark Summary

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Shows the most recent ledger entry without re-running the benchmark. Useful for quickly checking the latest results.

```bash
python3 scripts/benchmark_unconstrained.py --summary
```

--------------------------------

### Run Benchmark to Custom Output

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Directs benchmark results to a specified JSON ledger file. Allows for custom result storage.

```bash
python3 scripts/benchmark_unconstrained.py --output /tmp/my_bench.json
```

--------------------------------

### Generate Specific XPath Tests

Source: https://github.com/jeswr/noir_xpath/blob/main/TESTING.md

Use this command to generate qt3tests for a specific XPath function. Ensure you are in the 'scripts' directory.

```bash
cd scripts
python generate_tests.py --functions "fn:timezone-from-dateTime"
```

--------------------------------

### List Implemented XPath Functions

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Use the `--list-functions` option to display a list of XPath functions that have implemented tests.

```bash
python generate_tests.py --list-functions
```

--------------------------------

### Generate All Noir XPath Tests

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Run the script to generate test packages for all XPath functions. This is the default behavior.

```bash
python generate_tests.py
```

--------------------------------

### Run Noir Tests for Main Library Only

Source: https://github.com/jeswr/noir_xpath/blob/main/TESTING.md

Executes tests specifically for the main 'xpath' package. Use this to isolate testing to the core library.

```bash
nargo test --package xpath
```

--------------------------------

### Regenerate All XPath Tests

Source: https://github.com/jeswr/noir_xpath/blob/main/TESTING.md

Execute this command to regenerate all available qt3tests. This is useful for updating tests after code changes. Ensure you are in the 'scripts' directory.

```bash
cd scripts
python generate_tests.py
```

--------------------------------

### Generate Specific Noir Tests from QT3 Tests

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Generate Noir tests for specific XPath functions from the W3C QT3 test suite. This allows for targeted test generation.

```bash
cd scripts
python generate_tests.py --functions "fn:abs,op:numeric-add"
```

--------------------------------

### Comparison Module Functions

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Provides generic comparison utilities for different types.

```APIDOC
## Comparison Module (`comparison.nr`)

Generic comparison utilities:

```noir
// Value comparison for numeric types
fn value_equal<T>(a: T, b: T) -> bool where T: Eq
fn value_less_than<T>(a: T, b: T) -> bool where T: Ord
fn value_greater_than<T>(a: T, b: T) -> bool where T: Ord
```

> **🔮 Future**: String collation comparisons (depends on string module)
```

--------------------------------

### Skip Cloning qt3tests Repository

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Employ the `--skip-clone` flag to prevent the script from cloning or updating the qt3tests repository if it already exists locally.

```bash
python generate_tests.py --skip-clone
```

--------------------------------

### Specify Custom Output Directory

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Set a custom directory for generated test packages using the `--output-dir` option.

```bash
python generate_tests.py --output-dir ../custom_tests
```

--------------------------------

### Implement Integer Addition

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements integer addition using i128. This is a P0 priority function.

```noir
numeric_add_int
```

--------------------------------

### Implement Float Ceiling

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the ceiling function for floating-point numbers. This is a P1 priority function.

```noir
ceil_float
```

--------------------------------

### Implement Logical AND Operation

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the logical AND operation for boolean values. This is a P0 priority function.

```noir
logical_and
```

--------------------------------

### Generate Noir Tests from W3C qt3tests

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Python script to generate Noir test code from W3C qt3tests XML files. It maps XPath functions to Noir implementations and parses test cases.

```python
#!/usr/bin/env python3
"""
Generate Noir test code from W3C qt3tests test suite.
"""

import xml.etree.ElementTree as ET
from pathlib import Path
import os

QT3_NAMESPACE = "{http://www.w3.org/2010/09/qt-fots-catalog}"

# Map XPath functions to Noir implementations
FUNCTION_MAP = {
    "fn:abs": ("xpath::numeric::abs", "numeric"),
    "fn:string-length": ("xpath::string::string_length", "string"),
    # ... etc
}

# Functions to include (current scope)
SPARQL_FUNCTIONS = [
    # Numeric
    "fn:abs", "fn:round", "fn:ceiling", "fn:floor",
    "op:numeric-add", "op:numeric-subtract",
    "op:numeric-multiply", "op:numeric-divide",
    "op:numeric-equal", "op:numeric-less-than", "op:numeric-greater-than",
    # DateTime
    "fn:year-from-dateTime", "fn:month-from-dateTime", "fn:day-from-dateTime",
    "fn:hours-from-dateTime", "fn:minutes-from-dateTime", "fn:seconds-from-dateTime",
    "op:dateTime-equal", "op:dateTime-less-than", "op:dateTime-greater-than",
    # Boolean
    "fn:not", "op:boolean-equal",
]

def parse_test_set(xml_path: Path) -> list:
    """Parse a qt3tests test set XML file."""
    tree = ET.parse(xml_path)
    root = tree.getroot()
    
    tests = []
    for test_case in root.findall(f".//{QT3_NAMESPACE}test-case"):
        test = {
            "name": test_case.get("name"),
            "test": test_case.find(f"{QT3_NAMESPACE}test").text,
            "result": parse_result(test_case.find(f"{QT3_NAMESPACE}result")),
        }
        tests.append(test)
    return tests

def generate_noir_test(test: dict, func_name: str) -> str:
    """Generate Noir test function from qt3tests test case."""
    # ... implementation
    pass

def main():
    # Clone/update qt3tests repo
    # Parse catalog.xml
    # For each function in SPARQL_FUNCTIONS:
    #   Parse relevant test files
    #   Generate Noir test package
    #   Split into chunks of ~100 tests
    pass

```

--------------------------------

### Noir Safe Division with Option

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Illustrates safe division in Noir, returning an Option<i128> to handle potential division by zero errors. None is returned if the divisor is zero.

```noir
// Division may fail on zero divisor
fn numeric_divide_safe(a: i128, b: i128) -> Option<i128> {
    if b == 0 {
        Option::none()
    } else {
        Option::some(a / b)
    }
}
```

--------------------------------

### Implement Integer Equality Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the equality comparison for integers. This is a P0 priority function.

```noir
numeric_equal_int
```

--------------------------------

### Implement Integer Division

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements integer division. This is a P0 priority function.

```noir
numeric_divide_int
```

--------------------------------

### Implement Float Floor

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the floor function for floating-point numbers. This is a P1 priority function.

```noir
floor_float
```

--------------------------------

### Implement Integer Less Than Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the less than comparison for integers. This is a P0 priority function.

```noir
numeric_less_than_int
```

--------------------------------

### Implement Float64 Addition

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements addition for 64-bit floating-point numbers using the ieee754 library. This is a P0 priority function.

```noir
numeric_add_double
```

--------------------------------

### Run Noir Unit Tests Only

Source: https://github.com/jeswr/noir_xpath/blob/main/TESTING.md

Executes tests from the 'xpath_unit_tests' package. This focuses on additional comprehensive tests.

```bash
nargo test --package xpath_unit_tests
```

--------------------------------

### Implement Integer Floor

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the floor function for integers, which acts as an identity function. This is a P0 priority function.

```noir
floor_int
```

--------------------------------

### Implement Integer Ceiling

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the ceiling function for integers, which acts as an identity function. This is a P0 priority function.

```noir
ceil_int
```

--------------------------------

### Implement Float Division

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements division for floating-point numbers. This is a P0 priority function.

```noir
numeric_divide_float
```

--------------------------------

### Implement Boolean Less Than Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the less than comparison for boolean values. This is a P1 priority function.

```noir
boolean_less_than
```

--------------------------------

### Implement Boolean Equality Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the equality comparison for boolean values. This is a P0 priority function.

```noir
boolean_equal
```

--------------------------------

### Implement Float Equality Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the equality comparison for floating-point numbers. This is a P0 priority function.

```noir
numeric_equal_float
```

--------------------------------

### Add noir_XPath Dependency to Nargo.toml

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Add this dependency to your Nargo.toml file to include the noir_XPath library in your project. Ensure you specify the correct git repository, tag, and directory.

```toml
[dependencies]
xpath = { git = "https://github.com/jeswr/noir_XPath", tag = "v0.1.0", directory = "xpath" }
```

--------------------------------

### Implement Float Subtraction

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements subtraction for floating-point numbers. This is a P0 priority function.

```noir
numeric_subtract_float
```

--------------------------------

### Run All Noir Tests

Source: https://github.com/jeswr/noir_xpath/blob/main/TESTING.md

Executes all tests across all workspace members. This is the most comprehensive test run.

```bash
nargo test
```

--------------------------------

### Implement Float Less Than Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the less than comparison for floating-point numbers. This is a P0 priority function.

```noir
numeric_less_than_float
```

--------------------------------

### Implement Integer Subtraction

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements integer subtraction. This is a P0 priority function.

```noir
numeric_subtract_int
```

--------------------------------

### Implement Logical OR Operation

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the logical OR operation for boolean values. This is a P0 priority function.

```noir
logical_or
```

--------------------------------

### Implement Integer Modulo

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the modulo operation for integers. This is a P1 priority function.

```noir
numeric_mod_int
```

--------------------------------

### Generate Noir XPath Tests for Specific Functions

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Generate tests only for a specified comma-separated list of XPath functions using the `--functions` option.

```bash
python generate_tests.py --functions "fn:abs,op:numeric-add"
```

--------------------------------

### Implement Float32 Addition

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements addition for 32-bit floating-point numbers using the ieee754 library. This is a P0 priority function.

```noir
numeric_add_float
```

--------------------------------

### String Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Offers functions for string length, prefix, suffix, and substring checks. Note: Functions creating new strings are not exported.

```APIDOC
## String Operations

### Description
Provides functions to check string properties like length, starting/ending substrings, and containment. Functions that require string manipulation or creation (e.g., concatenation, slicing, case conversion) are not exported due to runtime limitations.

### Functions
- `string_length<const N: u32>(s: str<N>) -> u32`: Returns the length of the string `s`.
- `starts_with<const N: u32, const M: u32>(s: str<N>, prefix: str<M>) -> bool`: Returns true if `s` starts with `prefix`.
- `ends_with<const N: u32, const M: u32>(s: str<N>, suffix: str<M>) -> bool`: Returns true if `s` ends with `suffix`.
- `contains<const N: u32, const M: u32>(s: str<N>, substring: str<M>) -> bool`: Returns true if `s` contains `substring`.
```

--------------------------------

### DateTime Construction and Extraction in Noir

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Handles DateTime values stored as UTC microseconds. Provides functions for constructing datetimes from components or epoch microseconds, and for extracting individual components.

```noir
// Constants for time calculations
global MICROSECONDS_PER_SECOND: Field = 1_000_000;
global MICROSECONDS_PER_MINUTE: Field = 60_000_000;
global MICROSECONDS_PER_HOUR: Field = 3_600_000_000;
global MICROSECONDS_PER_DAY: Field = 86_400_000_000;

// Construction
fn datetime_from_components(
    year: i32, month: u8, day: u8,
    hour: u8, minute: u8, second: u8, microsecond: u32
) -> XsdDateTime

fn datetime_from_epoch_microseconds(micros: Field) -> XsdDateTime

// Component extraction (computed from epoch_microseconds)
fn year_from_datetime(dt: XsdDateTime) -> i32
fn month_from_datetime(dt: XsdDateTime) -> u8
fn day_from_datetime(dt: XsdDateTime) -> u8
fn hours_from_datetime(dt: XsdDateTime) -> u8
fn minutes_from_datetime(dt: XsdDateTime) -> u8
fn seconds_from_datetime(dt: XsdDateTime) -> u8  // Integer seconds
fn microseconds_from_datetime(dt: XsdDateTime) -> u32
```

--------------------------------

### Boolean Logic and Comparisons in Noir

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Implements logical operators (NOT, AND, OR) and comparison functions for boolean types. Supports equality, less than, and greater than comparisons.

```noir
// Logical operators
fn fn_not(a: bool) -> bool
fn logical_and(a: bool, b: bool) -> bool
fn logical_or(a: bool, b: bool) -> bool

// Comparison
fn boolean_equal(a: bool, b: bool) -> bool
fn boolean_less_than(a: bool, b: bool) -> bool    // false < true
fn boolean_greater_than(a: bool, b: bool) -> bool
```

--------------------------------

### DateTime Module Functions

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Handles DateTime operations, including construction, component extraction, and comparison.

```APIDOC
## DateTime Module (`datetime.nr`)

All DateTime values stored as UTC microseconds since epoch in a single `Field`.
Component extraction computes values on-demand via division/modulo.

```noir
// Constants for time calculations
global MICROSECONDS_PER_SECOND: Field = 1_000_000;
global MICROSECONDS_PER_MINUTE: Field = 60_000_000;
global MICROSECONDS_PER_HOUR: Field = 3_600_000_000;
global MICROSECONDS_PER_DAY: Field = 86_400_000_000;

// Construction
fn datetime_from_components(
    year: i32, month: u8, day: u8,
    hour: u8, minute: u8, second: u8, microsecond: u32
) -> XsdDateTime

fn datetime_from_epoch_microseconds(micros: Field) -> XsdDateTime

// Component extraction (computed from epoch_microseconds)
fn year_from_datetime(dt: XsdDateTime) -> i32
fn month_from_datetime(dt: XsdDateTime) -> u8
fn day_from_datetime(dt: XsdDateTime) -> u8
fn hours_from_datetime(dt: XsdDateTime) -> u8
fn minutes_from_datetime(dt: XsdDateTime) -> u8
fn seconds_from_datetime(dt: XsdDateTime) -> u8  // Integer seconds
fn microseconds_from_datetime(dt: XsdDateTime) -> u32

// Comparison (efficient single-field comparisons)
fn datetime_equal(a: XsdDateTime, b: XsdDateTime) -> bool {
    a.epoch_microseconds == b.epoch_microseconds
}

fn datetime_less_than(a: XsdDateTime, b: XsdDateTime) -> bool {
    a.epoch_microseconds as u64 < b.epoch_microseconds as u64
}

fn datetime_greater_than(a: XsdDateTime, b: XsdDateTime) -> bool {
    a.epoch_microseconds as u64 > b.epoch_microseconds as u64
}
```

> **Note**: The XPath `fn:seconds-from-dateTime` returns a decimal including fractional seconds. Since decimals are deferred, we provide integer seconds + separate microseconds accessor.
```

--------------------------------

### Noir String Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Utilize string functions like length, starts_with, ends_with, and contains. Note that functions creating new strings are not exported due to Noir's runtime limitations.

```noir
use dep::xpath({
    string_length,
    starts_with,
    ends_with,
    contains,
});

fn example() {
    let s: str<11> = "Hello World";
    
    // These functions work correctly (return boolean/numeric values):
    assert(string_length::<11>(s) == 11);
    assert(starts_with::<11, 5>(s, "Hello"));
    assert(ends_with::<11, 5>(s, "World"));
    assert(contains::<11, 5>(s, "lo Wo"));
}
```

--------------------------------

### Numeric Operations (Integer)

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Supports basic arithmetic operations for integers, including addition, multiplication, modulo, absolute value, min, and max.

```APIDOC
## Numeric Operations (Integer)

### Description
Provides essential arithmetic operations for integer types.

### Functions
- `numeric_add_int(a: i64, b: i64) -> i64`: Adds two integers.
- `numeric_multiply_int(a: i64, b: i64) -> i64`: Multiplies two integers.
- `numeric_mod_int(a: i64, b: i64) -> i64`: Computes the remainder of integer division.
- `abs_int(a: i64) -> i64`: Returns the absolute value of an integer.
- `min_int(a: i64, b: i64) -> i64`: Returns the minimum of two integers.
- `max_int(a: i64, b: i64) -> i64`: Returns the maximum of two integers.
```

--------------------------------

### Implement Integer Multiplication

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements integer multiplication. This is a P0 priority function.

```noir
numeric_multiply_int
```

--------------------------------

### DateTime Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Enables creation, extraction of components, comparison, and timezone handling for date and time values.

```APIDOC
## DateTime Operations

### Description
Functions for creating, manipulating, and querying date and time values, including timezone information.

### Types
- `XsdDateTime`: Represents a date and time value.

### Functions
- `datetime_from_components(year: u32, month: u32, day: u32, hour: u32, minute: u32, second: u32, microsecond: u32) -> XsdDateTime`: Creates a `XsdDateTime` from components (UTC).
- `datetime_from_components_with_tz(year: u32, month: u32, day: u32, hour: u32, minute: u32, second: u32, microsecond: u32, tz_offset_minutes: i32) -> XsdDateTime`: Creates a `XsdDateTime` with a specified timezone offset in minutes.
- `year_from_datetime(dt: XsdDateTime) -> u32`: Extracts the year from a `XsdDateTime`.
- `month_from_datetime(dt: XsdDateTime) -> u32`: Extracts the month from a `XsdDateTime`.
- `datetime_less_than(dt1: XsdDateTime, dt2: XsdDateTime) -> bool`: Compares two `XsdDateTime` values and returns true if `dt1` is earlier than `dt2`.
- `timezone_from_datetime(dt: XsdDateTime) -> Duration`: Extracts the timezone offset as a `Duration`.
```

--------------------------------

### Implement Float Rounding

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the rounding function for floating-point numbers. This is a P1 priority function.

```noir
round_float
```

--------------------------------

### Implement Integer Rounding

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the rounding function for integers, which acts as an identity function. This is a P0 priority function.

```noir
round_int
```

--------------------------------

### Noir Sequence/Aggregate Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Perform aggregate calculations on sequences of integers, including count, sum, average, minimum, and maximum. Requires an array of integers as input.

```noir
use dep::xpath::{sum_int, avg_int, min_int_seq, max_int_seq, count};

fn example() {
    let values: [i64; 5] = [10, 20, 30, 40, 50];
    
    assert(count(values) == 5);
    assert(sum_int(values) == 150);
    assert(avg_int(values) == 30);
    assert(min_int_seq(values) == 10);
    assert(max_int_seq(values) == 50);
}
```

--------------------------------

### Implement Float Multiplication

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements multiplication for floating-point numbers. This is a P0 priority function.

```noir
numeric_multiply_float
```

--------------------------------

### Implement Integer Unary Plus

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the unary plus operation for integers. This is a P0 priority function.

```noir
numeric_unary_plus
```

--------------------------------

### Sequence/Aggregate Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Includes functions for common aggregate operations on sequences of integers, such as sum, average, min, max, and count.

```APIDOC
## Sequence/Aggregate Operations

### Description
Functions to perform aggregate calculations on sequences (arrays) of integers.

### Functions
- `count<T>(seq: [T; _]) -> u32`: Counts the number of elements in a sequence.
- `sum_int(seq: [i64; _]) -> i64`: Calculates the sum of integers in a sequence.
- `avg_int(seq: [i64; _]) -> i64`: Calculates the average of integers in a sequence.
- `min_int_seq(seq: [i64; _]) -> i64`: Finds the minimum integer in a sequence.
- `max_int_seq(seq: [i64; _]) -> i64`: Finds the maximum integer in a sequence.
```

--------------------------------

### Run Specific Generated Noir Test Package

Source: https://github.com/jeswr/noir_xpath/blob/main/TESTING.md

Executes tests for a single generated package, such as 'xpath_test_fnabs'. This is useful for targeting specific function tests.

```bash
nargo test --package xpath_test_fnabs
```

--------------------------------

### Update FUNCTION_TEST_FILES in generate_tests.py

Source: https://github.com/jeswr/noir_xpath/blob/main/PARALLEL_WORK_ITEMS.md

Add new entries to the FUNCTION_TEST_FILES list in `scripts/generate_tests.py` to include test cases for dayTimeDuration operations.

```python
"op:add-dayTimeDuration-to-dateTime": "op/add-dayTimeDuration-to-dateTime.xml",
     "op:subtract-dayTimeDuration-from-dateTime": "op/subtract-dayTimeDuration-from-dateTime.xml",
     "op:subtract-dateTimes": "op/subtract-dateTimes.xml",
     "op:add-dayTimeDurations": "op/add-dayTimeDurations.xml",
     "op:subtract-dayTimeDurations": "op/subtract-dayTimeDurations.xml",
     "op:dayTimeDuration-equal": "op/dayTimeDuration-equal.xml",
     "op:dayTimeDuration-less-than": "op/dayTimeDuration-less-than.xml",
     "op:dayTimeDuration-greater-than": "op/dayTimeDuration-greater-than.xml",
```

--------------------------------

### Implement Integer Greater Than Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the greater than comparison for integers. This is a P0 priority function.

```noir
numeric_greater_than_int
```

--------------------------------

### Generate Duration Function Tests

Source: https://github.com/jeswr/noir_xpath/blob/main/PARALLEL_WORK_ITEMS.md

Execute the test generation script to create test packages for specific duration functions. This command specifies which functions to generate tests for.

```bash
python generate_tests.py --functions "fn:days-from-duration,fn:hours-from-duration,fn:minutes-from-duration,fn:seconds-from-duration"
```

--------------------------------

### Generic Value Comparison in Noir

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Provides generic functions for comparing values of any type that implements the Eq (for equality) or Ord (for ordering) traits. Useful for general-purpose comparisons.

```noir
// Value comparison for numeric types
fn value_equal<T>(a: T, b: T) -> bool where T: Eq
fn value_less_than<T>(a: T, b: T) -> bool where T: Ord
fn value_greater_than<T>(a: T, b: T) -> bool where T: Ord
```

--------------------------------

### Float Rounding Function Signatures (Noir)

Source: https://github.com/jeswr/noir_xpath/blob/main/PARALLEL_WORK_ITEMS.md

Defines the function signatures for rounding, ceiling, flooring, and half-to-even rounding of XsdFloat types. These functions are intended for use in the numeric_types.nr file.

```noir
pub fn round_float(x: XsdFloat) -> XsdFloat
pub fn ceil_float(x: XsdFloat) -> XsdFloat
pub fn floor_float(x: XsdFloat) -> XsdFloat
pub fn round_half_to_even_float(x: XsdFloat, precision: i32) -> XsdFloat
```

--------------------------------

### Implement Integer Unary Minus

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the unary minus operation for integers. This is a P0 priority function.

```noir
numeric_unary_minus
```

--------------------------------

### Implement Integer Absolute Value

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the absolute value function for integers. This is a P0 priority function.

```noir
abs_int
```

--------------------------------

### Implement Boolean Greater Than Comparison

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the greater than comparison for boolean values. This is a P1 priority function.

```noir
boolean_greater_than
```

--------------------------------

### Double Rounding Function Signatures (Noir)

Source: https://github.com/jeswr/noir_xpath/blob/main/PARALLEL_WORK_ITEMS.md

Defines the function signatures for rounding, ceiling, flooring, and half-to-even rounding of XsdDouble types. These functions are intended for use in the numeric_types.nr file.

```noir
pub fn round_double(x: XsdDouble) -> XsdDouble
pub fn ceil_double(x: XsdDouble) -> XsdDouble
pub fn floor_double(x: XsdDouble) -> XsdDouble
pub fn round_half_to_even_double(x: XsdDouble, precision: i32) -> XsdDouble
```

--------------------------------

### Noir Numeric Operations (Integers)

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Perform basic integer arithmetic including addition, multiplication, modulo, absolute value, minimum, and maximum. These functions are specifically for integer types.

```noir
use dep::xpath({
    numeric_add_int, 
    numeric_multiply_int,
    numeric_mod_int,
    abs_int,
    min_int,
    max_int,
});

fn example() {
    // Integer operations
    let sum = numeric_add_int(5, 3);  // 8
    let product = numeric_multiply_int(-5, 3);  // -15
    let remainder = numeric_mod_int(7, 3);  // 1
    let absolute = abs_int(-42);  // 42
    let minimum = min_int(5, 3);  // 3
    let maximum = max_int(5, 3);  // 5
}
```

--------------------------------

### Noir DateTime Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Create, manipulate, and compare DateTime values. Supports creating from components (with or without timezone) and extracting year, month, and timezone information.

```noir
use dep::xpath::{
    XsdDateTime,
    datetime_from_components,
    datetime_from_components_with_tz,
    year_from_datetime,
    month_from_datetime,
    datetime_less_than,
    timezone_from_datetime,
};

fn example() {
    // Create a DateTime: 2024-06-15T14:30:45.123456Z (UTC)
    let dt = datetime_from_components(2024, 6, 15, 14, 30, 45, 123456);
    
    // Create a DateTime with timezone: 2024-06-15T14:30:45.123456-05:00
    let dt_tz = datetime_from_components_with_tz(2024, 6, 15, 14, 30, 45, 123456, -300);
    
    // Extract components
    assert(year_from_datetime(dt) == 2024);
    assert(month_from_datetime(dt) == 6);
    
    // Extract timezone as duration (SPARQL TIMEZONE function)
    let tz = timezone_from_datetime(dt_tz);
    // tz represents -PT5H (negative 5 hours)
    
    // Compare dates
    let dt_earlier = datetime_from_components(2024, 1, 1, 0, 0, 0, 0);
    assert(datetime_less_than(dt_earlier, dt));
}
```

--------------------------------

### Define XsdDateTime Structure

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Defines the XsdDateTime structure for representing time in microseconds since the Unix epoch. Optimized for circuit efficiency.

```noir
struct XsdDateTime {
    epoch_microseconds: Field,
}
```

--------------------------------

### Implement Float Absolute Value

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the absolute value function for floating-point numbers. This is a P0 priority function.

```noir
abs_float
```

--------------------------------

### Numeric Module Functions

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Provides unary and binary numeric operations, as well as comparison and rounding functions.

```APIDOC
## Numeric Module (`numeric.nr`)

Implements numeric operations required by SPARQL operator mapping:

```noir
// Unary operators
fn numeric_unary_plus<T>(a: T) -> T
fn numeric_unary_minus<T>(a: T) -> T

// Binary arithmetic (using ieee754 for floats)
fn numeric_add<T>(a: T, b: T) -> T
fn numeric_subtract<T>(a: T, b: T) -> T
fn numeric_multiply<T>(a: T, b: T) -> T
fn numeric_divide<T>(a: T, b: T) -> T

// Comparison
fn numeric_equal<T>(a: T, b: T) -> bool
fn numeric_less_than<T>(a: T, b: T) -> bool
fn numeric_greater_than<T>(a: T, b: T) -> bool

// Functions
fn abs<T>(value: T) -> T
fn round<T>(value: T) -> T
fn ceil<T>(value: T) -> T
fn floor<T>(value: T) -> T
fn rand() -> u64  // Returns bits of xsd:double in [0, 1)
```
```

--------------------------------

### DateTime Comparison in Noir

Source: https://github.com/jeswr/noir_xpath/blob/main/ARCHITECTURE.md

Efficiently compares two XsdDateTime values by comparing their underlying epoch_microseconds fields. Supports equality, less than, and greater than operations.

```noir
// Comparison (efficient single-field comparisons)
fn datetime_equal(a: XsdDateTime, b: XsdDateTime) -> bool {
    a.epoch_microseconds == b.epoch_microseconds
}

fn datetime_less_than(a: XsdDateTime, b: XsdDateTime) -> bool {
    a.epoch_microseconds as u64 < b.epoch_microseconds as u64
}

fn datetime_greater_than(a: XsdDateTime, b: XsdDateTime) -> bool {
    a.epoch_microseconds as u64 > b.epoch_microseconds as u64
}
```

--------------------------------

### Noir Boolean Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Perform logical AND, OR, and NOT operations using Noir's boolean functions. Ensure correct imports for logical operations.

```noir
use dep::xpath::{fn_not, logical_and, logical_or, boolean_equal};

fn example() {
    let result = logical_and(true, fn_not(false));  // true
    assert(boolean_equal(result, true));
}
```

--------------------------------

### Compare DateTimes

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Compares two XsdDateTime objects for less than relationship using UTC seconds. This function requires the datetime_to_utc_seconds helper.

```noir
fn datetime_less_than(a: XsdDateTime, b: XsdDateTime) -> bool {
    datetime_to_utc_seconds(a) < datetime_to_utc_seconds(b)
}
```

--------------------------------

### Skip Running Nargo Format

Source: https://github.com/jeswr/noir_xpath/blob/main/scripts/README.md

Use the `--skip-fmt` option to disable the automatic execution of `nargo fmt` after test generation.

```bash
python generate_tests.py --skip-fmt
```

--------------------------------

### Noir Duration Operations

Source: https://github.com/jeswr/noir_xpath/blob/main/README.md

Work with durations, including creating them from components and performing arithmetic with DateTime values. Supports adding durations to datetimes and calculating datetime differences.

```noir
use dep::xpath::{
    duration_from_components,
    datetime_add_duration,
    datetime_difference,
    days_from_duration,
};

fn example() {
    // Create a duration: 1 day, 2 hours, 30 minutes
    let dur = duration_from_components(false, 1, 2, 30, 0, 0);
    
    // Add duration to datetime
    let dt = datetime_from_components(2024, 1, 1, 0, 0, 0, 0);
    let dt_later = datetime_add_duration(dt, dur);
    
    // Compute difference between datetimes
    let diff = datetime_difference(dt_later, dt);
    assert(days_from_duration(diff) == 1);
}
```

--------------------------------

### Define XsdTime Struct in Noir

Source: https://github.com/jeswr/noir_xpath/blob/main/PARALLEL_WORK_ITEMS.md

Defines the XsdTime struct with microseconds and timezone offset. Ensure microseconds are within the valid range.

```noir
struct XsdTime {
    microseconds_of_day: u64, // Microseconds since midnight (0-86399999999)
    tz_offset_minutes: i16,   // Timezone offset
}
```

--------------------------------

### Update scripts/generate_tests.py for Duration Functions

Source: https://github.com/jeswr/noir_xpath/blob/main/PARALLEL_WORK_ITEMS.md

Modify the test generation script to include duration component extraction functions. Ensure these functions are mapped correctly for test file generation.

```python
FUNCTION_TEST_FILES = {
    ...
    "fn:days-from-duration": "fn/days-from-duration.xml",
    "fn:hours-from-duration": "fn/hours-from-duration.xml",
    "fn:minutes-from-duration": "fn/minutes-from-duration.xml",
    "fn:seconds-from-duration": "fn/seconds-from-duration.xml",
    ...
}

FUNCTION_MAP = {
    ...
    "fn:days-from-duration": "days_from_duration",
    "fn:hours-from-duration": "hours_from_duration",
    "fn:minutes-from-duration": "minutes_from_duration",
    "fn:seconds-from-duration": "seconds_from_duration",
    ...
}
```

--------------------------------

### Implement Boolean NOT Operation

Source: https://github.com/jeswr/noir_xpath/blob/main/IMPLEMENTATION_PLAN.md

Implements the logical NOT operation for boolean values. This is a P0 priority function.

```noir
fn_not
```

--------------------------------

### Update Test Generation Script for Boolean Comparison Operators

Source: https://github.com/jeswr/noir_xpath/blob/main/PARALLEL_WORK_ITEMS.md

Modifies the test generation script to include coverage for boolean less than and greater than operators. Ensure correct mapping to internal functions.

```python
"op:boolean-less-than": "op/boolean-less-than.xml",
     "op:boolean-greater-than": "op/boolean-greater-than.xml",
```

```python
"op:boolean-less-than": "boolean_less_than",
     "op:boolean-greater-than": "boolean_greater_than",
```