lib_core_utils

Library "lib_core_utils"
Core utility functions for Pine Script strategies
Provides safe mathematical operations, array management, and basic helpers
Version: 1.0.0
Author: NQ Hybrid Strategy Team
Last Updated: 2025-06-18
===================================================================

safe_division(numerator, denominator)
  safe_division
description Performs division with safety checks for zero denominators and invalid values
  Parameters:
    numerator (float): (float) The numerator value
    denominator (float): (float) The denominator value
  Returns: (float) Result of division, or 0.0 if invalid

safe_division_detailed(numerator, denominator)
  safe_division_detailed
description Enhanced division with detailed result information
  Parameters:
    numerator (float): (float) The numerator value
    denominator (float): (float) The denominator value
  Returns: (SafeCalculationResult) Detailed calculation result

safe_multiply(a, b)
  safe_multiply
description Performs multiplication with safety checks for overflow and invalid values
  Parameters:
    a (float): (float) First multiplier
    b (float): (float) Second multiplier
  Returns: (float) Result of multiplication, or 0.0 if invalid

safe_add(a, b)
  safe_add
description Performs addition with safety checks
  Parameters:
    a (float): (float) First addend
    b (float): (float) Second addend
  Returns: (float) Result of addition, or 0.0 if invalid

safe_subtract(a, b)
  safe_subtract
description Performs subtraction with safety checks
  Parameters:
    a (float): (float) Minuend
    b (float): (float) Subtrahend
  Returns: (float) Result of subtraction, or 0.0 if invalid

safe_abs(value)
  safe_abs
description Safe absolute value calculation
  Parameters:
    value (float): (float) Input value
  Returns: (float) Absolute value, or 0.0 if invalid

safe_max(a, b)
  safe_max
description Safe maximum value calculation
  Parameters:
    a (float): (float) First value
    b (float): (float) Second value
  Returns: (float) Maximum value, handling NA cases

safe_min(a, b)
  safe_min
description Safe minimum value calculation
  Parameters:
    a (float): (float) First value
    b (float): (float) Second value
  Returns: (float) Minimum value, handling NA cases

safe_array_get(arr, index)
  safe_array_get
description Safely retrieves value from array with bounds checking
  Parameters:
    arr (array<float>): (array<float>) The array to access
    index (int): (int) Index to retrieve
  Returns: (float) Value at index, or na if invalid

safe_array_push(arr, value, max_size)
  safe_array_push
description Safely pushes value to array with size management
  Parameters:
    arr (array<float>): (array<float>) The array to modify
    value (float): (float) Value to push
    max_size (int): (int) Maximum array size
  Returns: (bool) True if push was successful

safe_array_unshift(arr, value, max_size)
  safe_array_unshift
description Safely adds value to beginning of array with size management
  Parameters:
    arr (array<float>): (array<float>) The array to modify
    value (float): (float) Value to add at beginning
    max_size (int): (int) Maximum array size
  Returns: (bool) True if unshift was successful

get_array_stats(arr, max_size)
  get_array_stats
description Gets statistics about an array
  Parameters:
    arr (array<float>): (array<float>) The array to analyze
    max_size (int): (int) The maximum allowed size
  Returns: (ArrayStats) Statistics about the array

cleanup_array(arr, target_size)
  cleanup_array
description Cleans up array by removing old elements if it's too large
  Parameters:
    arr (array<float>): (array<float>) The array to cleanup
    target_size (int): (int) Target size after cleanup
  Returns: (int) Number of elements removed

is_valid_price(price)
  is_valid_price
description Checks if a price value is valid for trading calculations
  Parameters:
    price (float): (float) Price to validate
  Returns: (bool) True if price is valid

is_valid_volume(vol)
  is_valid_volume
description Checks if a volume value is valid
  Parameters:
    vol (float): (float) Volume to validate
  Returns: (bool) True if volume is valid

sanitize_price(price, default_value)
  sanitize_price
description Sanitizes price value to ensure it's within valid range
  Parameters:
    price (float): (float) Price to sanitize
    default_value (float): (float) Default value if price is invalid
  Returns: (float) Sanitized price value

sanitize_percentage(pct)
  sanitize_percentage
description Sanitizes percentage value to 0-100 range
  Parameters:
    pct (float): (float) Percentage to sanitize
  Returns: (float) Sanitized percentage (0-100)

is_session_active(session_string, timezone)
  Parameters:
    session_string (string)
    timezone (string)

get_session_progress(session_string, timezone)
  Parameters:
    session_string (string)
    timezone (string)

format_price(price, decimals)
  Parameters:
    price (float)
    decimals (int)

format_percentage(pct, decimals)
  Parameters:
    pct (float)
    decimals (int)

bool_to_emoji(condition, true_emoji, false_emoji)
  Parameters:
    condition (bool)
    true_emoji (string)
    false_emoji (string)

log_debug(message, level)
  Parameters:
    message (string)
    level (string)

benchmark_start()

benchmark_end(start_time)
  Parameters:
    start_time (int)

get_library_info()

get_library_version()

SafeCalculationResult
  SafeCalculationResult
  Fields:
    value (series float): (float) The calculated value
    is_valid (series bool): (bool) Whether the calculation was successful
    error_message (series string): (string) Error description if calculation failed

ArrayStats
  ArrayStats
  Fields:
    size (series int): (int) Current array size
    max_size (series int): (int) Maximum allowed size
    is_full (series bool): (bool) Whether array has reached max capacity