CommonUtils

█ OVERVIEW


This library is a utility tool for Pine Script™ developers. It provides a collection of helper functions designed to simplify common tasks such as mapping user-friendly string inputs to Pine Script™ constants and formatting timeframe strings for display. The primary goal is to make main scripts cleaner, more readable, and reduce repetitive boilerplate code. It is envisioned as an evolving resource, with potential for new utilities to be added over time based on community needs and feedback.



█  CONCEPTS


The library primarily focuses on two main concepts:


Input Mapping

Pine Script™ often requires specific constants for function parameters (e.g., `line.style_dashed` for line styles, `position.top_center` for table positions). However, presenting these technical constants directly to users in script inputs can be confusing. Input mapping involves:

• Allowing users to select options from more descriptive, human-readable strings (e.g., "Dashed", "Top Center") in the script's settings.
  
• Providing functions within this library (e.g., `mapLineStyle`, `mapTablePosition`) that take these user-friendly strings as input.
  
• Internally, these functions use switch statements or similar logic to convert (map) the input string to the corresponding Pine Script™ constant required by built-in functions.
  

This approach enhances user experience and simplifies the main script's logic by centralizing the mapping process.


Timeframe Formatting

Raw timeframe strings obtained from variables like `timeframe.period` (e.g., "1", "60", "D", "W") or user inputs are not always ideal for direct display in labels or panels. The `formatTimeframe` function addresses this by:

• Taking a raw timeframe string as input.
  
• Parsing this string to identify its numerical part and unit (e.g., minutes, hours, days, weeks, months, seconds, milliseconds).
  
• Converting it into a more standardized and readable format (e.g., "1min", "60min", "Daily", "Weekly", "1s", "10M").
  
• Offering an optional `customSuffix` parameter (e.g., " FVG", " Period") to append to the formatted string, making labels more descriptive, especially in multi-timeframe contexts.
  

The function is designed to correctly interpret various common timeframe notations used in TradingView.



█  NOTES

• Ease of Use: The library functions are designed with simple and understandable signatures. They typically take a string input and return the corresponding Pine Script™ constant or a formatted string.
  
• Default Behaviors: Mapping functions (`mapLineStyle`, `mapTablePosition`, `mapTextSize`) generally return a sensible default value (e.g., `line.style_solid` for `mapLineStyle`) in case of a non-matching input. This helps prevent errors in the main script.
  
• Extensibility of Formatting: The `formatTimeframe` function, with its `customSuffix` parameter, allows for flexible customization of timeframe labels to suit the specific descriptive needs of different indicators or contexts.
  
• Performance Considerations: These utility functions primarily use basic string operations and switch statements. For typical use cases, their impact on overall script performance is negligible. However, if a function like `formatTimeframe` were to be called excessively in a loop with dynamic inputs (which is generally not its intended use), performance should be monitored.
  
• No Dependencies: This library is self-contained and does not depend on any other external Pine Script™ libraries.
  

█  EXPORTED FUNCTIONS


mapLineStyle(styleString)
  Maps a user-provided line style string to its corresponding Pine Script™ line style constant.
  Parameters:
    styleString (simple string): The input string representing the desired line style (e.g., "Solid", "Dashed", "Dotted" - typically from constants like LS1, LS2, LS3).
  Returns: The Pine Script™ constant for the line style (e.g., line.style_solid). Defaults to line.style_solid if no match.


mapTablePosition(positionString)
  Maps a user-provided table position string to its corresponding Pine Script™ position constant.
  Parameters:
    positionString (simple string): The input string representing the desired table position (e.g., "Top Right", "Top Center" - typically from constants like PP1, PP2).
  Returns: The Pine Script™ constant for the table position (e.g., position.top_right). Defaults to position.top_right if no match.


mapTextSize(sizeString)
  Maps a user-provided text size string to its corresponding Pine Script™ size constant.
  Parameters:
    sizeString (simple string): The input string representing the desired text size (e.g., "Tiny", "Small" - typically from constants like PTS1, PTS2).
  Returns: The Pine Script™ constant for the text size (e.g., size.tiny). Defaults to size.small if no match.


formatTimeframe(tfInput, customSuffix)
  Formats a raw timeframe string into a more display-friendly string, optionally appending a custom suffix.
  Parameters:
    tfInput (simple string): The raw timeframe string from user input or timeframe.period (e.g., "1", "60", "D", "W", "1S", "10M", "2H").
    customSuffix (simple string): An optional suffix to append to the formatted timeframe string (e.g., " FVG", " Period"). Defaults to an empty string.
  Returns: The formatted timeframe string (e.g., "1min", "60min", "Daily", "Weekly", "1s", "10min", "2h") with the custom suffix appended.