Numeric Functions

/**
 * Sum numeric values in array
 * @param args - Array of numbers to sum
 * @returns Sum of all numeric values, undefined if input is undefined
 */
function $sum(args);

const data = { values: [1, 2, 3, 4, 5] };
const expr = jsonata("$sum(values)");
const result = await expr.evaluate(data); // 15

// With path expression
const orders = { orders: [{ total: 100 }, { total: 200 }, { total: 150 }] };
const total = await jsonata("$sum(orders.total)").evaluate(orders); // 450

/**
 * Count elements in array
 * @param args - Array to count
 * @returns Number of elements, 0 if undefined
 */
function $count(args);

const data = { items: ["a", "b", "c"] };
const count = await jsonata("$count(items)").evaluate(data); // 3

// Count filtered results
const users = { users: [{ active: true }, { active: false }, { active: true }] };
const activeCount = await jsonata("$count(users[active])").evaluate(users); // 2

/**
 * Find maximum value in array
 * @param args - Array of numbers
 * @returns Maximum value, undefined if array is empty or undefined
 */
function $max(args);

const data = { scores: [85, 92, 78, 96, 88] };
const highest = await jsonata("$max(scores)").evaluate(data); // 96

// With date comparison
const events = { 
  events: [
    { date: "2023-01-15" },
    { date: "2023-03-22" }, 
    { date: "2023-02-08" }
  ]
};
const latest = await jsonata("$max(events.date)").evaluate(events); // "2023-03-22"

/**
 * Find minimum value in array
 * @param args - Array of numbers
 * @returns Minimum value, undefined if array is empty or undefined
 */
function $min(args);

/**
 * Calculate average of numeric values
 * @param args - Array of numbers
 * @returns Average value, undefined if array is empty or undefined
 */
function $average(args);

const data = { temperatures: [20, 22, 19, 23, 21] };
const avg = await jsonata("$average(temperatures)").evaluate(data); // 21

// Calculate grade point average
const student = {
  grades: [
    { course: "Math", points: 3.7 },
    { course: "Science", points: 3.9 },
    { course: "English", points: 3.5 }
  ]
};
const gpa = await jsonata("$average(grades.points)").evaluate(student); // 3.7

/**
 * Calculate absolute value
 * @param arg - Number input
 * @returns Absolute value of the input
 */
function $abs(arg);

const result1 = await jsonata("$abs(-5)").evaluate({}); // 5
const result2 = await jsonata("$abs(3.14)").evaluate({}); // 3.14

// With data
const data = { difference: -10.5 };
const absolute = await jsonata("$abs(difference)").evaluate(data); // 10.5

/**
 * Calculate floor value
 * @param arg - Number input
 * @returns Floor value
 */
function $floor(arg);

/**
 * Calculate ceiling value
 * @param arg - Number input
 * @returns Ceiling value
 */
function $ceil(arg);

/**
 * Round number to specified precision
 * @param arg - Number to round
 * @param precision - Number of decimal places (optional, defaults to 0)
 * @returns Rounded number
 */
function $round(arg, precision);

const result1 = await jsonata("$round(3.14159)").evaluate({}); // 3
const result2 = await jsonata("$round(3.14159, 2)").evaluate({}); // 3.14
const result3 = await jsonata("$round(3.14159, 4)").evaluate({}); // 3.1416

// Financial calculations
const price = { amount: 123.456 };
const rounded = await jsonata("$round(amount, 2)").evaluate(price); // 123.46

/**
 * Calculate square root
 * @param arg - Number input (must be non-negative)
 * @returns Square root of the input
 */
function $sqrt(arg);

const result = await jsonata("$sqrt(16)").evaluate({}); // 4

// Calculate distance
const point = { x: 3, y: 4 };
const distance = await jsonata("$sqrt($power(x, 2) + $power(y, 2))").evaluate(point); // 5

/**
 * Calculate power (base^exponent)
 * @param arg - Base number
 * @param exp - Exponent
 * @returns Base raised to the power of exponent
 */
function $power(arg, exp);

const result1 = await jsonata("$power(2, 3)").evaluate({}); // 8
const result2 = await jsonata("$power(9, 0.5)").evaluate({}); // 3

// Compound interest calculation
const investment = { principal: 1000, rate: 0.05, years: 3 };
const future = await jsonata("principal * $power(1 + rate, years)").evaluate(investment);

/**
 * Generate random number
 * @returns Random number between 0 (inclusive) and 1 (exclusive)
 */
function $random();

const random = await jsonata("$random()").evaluate({}); // e.g., 0.7341234

// Random integer between 1 and 10
const randomInt = await jsonata("$floor($random() * 10) + 1").evaluate({});

// Random element from array
const data = { options: ["red", "green", "blue"] };
const randomChoice = await jsonata("options[$floor($random() * $count(options))]").evaluate(data);

/**
 * Convert value to number
 * @param arg - Value to convert
 * @returns Numeric representation of the value
 */
function $number(arg);

const result1 = await jsonata('$number("123")').evaluate({}); // 123
const result2 = await jsonata('$number("3.14")').evaluate({}); // 3.14
const result3 = await jsonata('$number(true)').evaluate({}); // 1

// Convert string data to numbers
const data = { prices: ["10.99", "25.50", "7.25"] };
const numbers = await jsonata("prices.$number($)").evaluate(data); // [10.99, 25.5, 7.25]

/**
 * Format number according to picture string
 * @param value - Number to format
 * @param picture - Picture string defining the format
 * @param options - Optional formatting options
 * @returns Formatted string representation
 */
function $formatNumber(value, picture, options);

// Basic formatting
const result1 = await jsonata('$formatNumber(1234.5, "#,###.00")').evaluate({}); // "1,234.50"
const result2 = await jsonata('$formatNumber(0.75, "0%")').evaluate({}); // "75%"

// Currency formatting
const price = { amount: 1234.56 };
const formatted = await jsonata('$formatNumber(amount, "$#,##0.00")').evaluate(price); // "$1,234.56"

/**
 * Format number in specified radix
 * @param value - Number to format
 * @param radix - Base (2-36)
 * @returns String representation in specified base
 */
function $formatBase(value, radix);

const binary = await jsonata("$formatBase(10, 2)").evaluate({}); // "1010"
const hex = await jsonata("$formatBase(255, 16)").evaluate({}); // "ff"
const octal = await jsonata("$formatBase(64, 8)").evaluate({}); // "100"

// Convert array of numbers to hex
const data = { values: [10, 15, 255] };
const hexValues = await jsonata("values.$formatBase($, 16)").evaluate(data); // ["a", "f", "ff"]