PriceFormat

Library for automatically converting price values to formatted strings
matching the same format that TradingView uses to display open/high/low/close prices on the chart.




█ OVERVIEW
This library is intended for Pine Coders who are authors of scripts that display numbers onto a user's charts. Typically, 𝚜𝚝𝚛.𝚝𝚘𝚜𝚝𝚛𝚒𝚗𝚐() would be used to convert a number into a string which can be displayed in a label / box / table, but this only works well for values that are formatted as a simple decimal number. The purpose of this library is to provide an easy way to create a formatted string for values which use other types of formats besides the decimal format.

The main functions exported by this library are:

• 𝚏𝚘𝚛𝚖𝚊𝚝𝙿𝚛𝚒𝚌𝚎() - creates a formatted string from a price value
  
• 𝚖𝚎𝚊𝚜𝚞𝚛𝚎𝙿𝚛𝚒𝚌𝚎𝙲𝚑𝚊𝚗𝚐𝚎() - creates a formatted string from the distance between two prices
  
• 𝚝𝚘𝚜𝚝𝚛𝚒𝚗𝚐() - an alternative to the built-in 𝚜𝚝𝚛.𝚝𝚘𝚜𝚝𝚛𝚒𝚗𝚐(𝚟𝚊𝚕𝚞𝚎, 𝚏𝚘𝚛𝚖𝚊𝚝)
  

This library also exports some auxiliary functions which are used under the hood of the previously mentioned functions, but can also be useful to Pine Coders that need fine-tuned control for customized formatting of numeric values:

• Functions that determine information about the current chart:
  𝚒𝚜𝙵𝚛𝚊𝚌𝚝𝚒𝚘𝚗𝚊𝚕𝙵𝚘𝚛𝚖𝚊𝚝(), 𝚒𝚜𝚅𝚘𝚕𝚞𝚖𝚎𝙵𝚘𝚛𝚖𝚊𝚝(), 𝚒𝚜𝙿𝚎𝚛𝚌𝚎𝚗𝚝𝚊𝚐𝚎𝙵𝚘𝚛𝚖𝚊𝚝(), 𝚒𝚜𝙳𝚎𝚌𝚒𝚖𝚊𝚕𝙵𝚘𝚛𝚖𝚊𝚝(), 𝚒𝚜𝙿𝚒𝚙𝚜𝙵𝚘𝚛𝚖𝚊𝚝()
  
• Functions that convert a 𝚏𝚕𝚘𝚊𝚝 value to a formatted string:
  𝚊𝚜𝙳𝚎𝚌𝚒𝚖𝚊𝚕(), 𝚊𝚜𝙿𝚒𝚙𝚜(), 𝚊𝚜𝙵𝚛𝚊𝚌𝚝𝚒𝚘𝚗𝚊𝚕(), 𝚊𝚜𝚅𝚘𝚕𝚞𝚖𝚎()
  

█ EXAMPLES

• Simple Example

This example shows the simplest way to utilize this library.

//@version=6
indicator("Simple Example")

import n00btraders/PriceFormat/1

var table t = table.new(position.middle_right, 2, 1, bgcolor = color.new(color.blue, 90), force_overlay = true)
if barstate.isfirst
    table.cell(t, 0, 0, "Current Price: ", text_color = color.black, text_size = 40)
    table.cell(t, 1, 0, text_color = color.blue, text_size = 40)

if barstate.islast
    string lastPrice = close.formatPrice()      // Simple, easy way to format price
    table.cell_set_text(t, 1, 0, lastPrice)

• Complex Example

This example calls all of the main functions and uses their optional arguments.

//@version=6
indicator("Complex Example")

import n00btraders/PriceFormat/1


// Enum values that can be used as optional arguments
precision = input.enum(PriceFormat.Precision.DEFAULT)
language = input.enum(PriceFormat.Language.ENGLISH)


// Main library functions used to create formatted strings
string formattedOpen = open.formatPrice(precision, language, allowPips = true)
string rawOpenPrice = PriceFormat.tostring(open, format.price)

string formattedClose = close.formatPrice(precision, language, allowPips = true)
string rawClosePrice = PriceFormat.tostring(close, format.price)

[distance, ticks] = PriceFormat.measurePriceChange(open, close, precision, language, allowPips = true)


// Labels to display formatted values on chart
string prices = str.format("Open:   {0}  ({1})\n\nClose:   {2}  ({3})", formattedOpen, rawOpenPrice, formattedClose, rawClosePrice)
string change = str.format("Change (close - open):\n\n{0}   /   {1}", distance, ticks)
label.new(chart.point.now(high), prices, yloc = yloc.abovebar, textalign = text.align_left, force_overlay = true)
label.new(chart.point.now(low), change, yloc = yloc.belowbar, style = label.style_label_up, force_overlay = true)

█ NOTES

• Function Descriptions

The library source code uses Markdown for the exported functions. Hover over a function/method call in the Pine Editor to display formatted, detailed information about the function/method.


• Precision Settings

The Precision option in the chart settings can change the format of how prices are displayed on the chart. Since the user's selected choice cannot be known through any Pine built-in variable, this library provides a 𝙿𝚛𝚎𝚌𝚒𝚜𝚒𝚘𝚗 enum that can be used as an optional script input for the user to specify their selected choice.


• Language Settings

The Language option in the user menu can change the decimal/grouping separators in the prices that are displayed on the chart. Since the user's selected choice cannot be known through any Pine built-in variable, this library provides a 𝙻𝚊𝚗𝚐𝚞𝚊𝚐𝚎 enum that can be used as an optional script input for the user to specify their selected choice.




█ EXPORTED FUNCTIONS

method formatPrice(price, precision, language, allowPips)
  Formats a price value to match how it would be displayed on the user's current chart.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    price (float): The value to format.
    precision (series Precision): A Precision.* enum value.
    language (series Language): A Language.* enum value.
    allowPips (simple bool): Whether to allow decimal numbers to display as pips.
  Returns: Automatically formatted price string.

measurePriceChange(startPrice, endPrice, precision, language, allowPips)
  Measures a change in price in terms of both distance and ticks.
  Parameters:
    startPrice (float): The starting price.
    endPrice (float): The ending price.
    precision (series Precision): A Precision.* enum value.
    language (series Language): A Language.* enum value.
    allowPips (simple bool): Whether to allow decimal numbers to display as pips.
  Returns: A tuple of formatted strings: [string distance, string ticks].

method tostring(value, format)
  Alternative to the Pine `str.tostring(value, format)` built-in function.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    value (float): (series float) The value to format.
    format (string): (series string) The format string.
  Returns: String in the specified format.

isFractionalFormat()
  Determines if the default behavior of the chart's price scale is to use a fractional format.
  Returns: True if the chart can display prices in fractional format.

isVolumeFormat()
  Determines if the default behavior of the chart's price scale is to display prices as volume.
  Returns: True if the chart can display prices as volume.

isPercentageFormat()
  Determines if the default behavior of the chart's price scale is to display percentages.
  Returns: True if the chart can display prices as percentages.

isDecimalFormat()
  Determines if the default behavior of the chart's price scale is to use a decimal format.
  Returns: True if the chart can display prices in decimal format.

isPipsFormat()
  Determines if the current symbol's prices can be displayed as pips.
  Returns: True if the chart can display prices as pips.

method asDecimal(value, precision, minTick, decimalSeparator, groupingSeparator, eNotation)
  Converts a number to a string in decimal format.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    value (float): The value to format.
    precision (int): Number of decimal places.
    minTick (float): Minimum tick size.
    decimalSeparator (string): The decimal separator.
    groupingSeparator (string): The thousands separator, aka digit group separator.
    eNotation (bool): Whether the result should use E notation.
  Returns: String in decimal format.

method asPips(value, priceScale, minMove, minMove2, decimalSeparator, groupingSeparator)
  Converts a number to a string in decimal format with the last digit replaced by a superscript.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    value (float): The value to format.
    priceScale (int): Price scale.
    minMove (int): Min move.
    minMove2 (int): Min move 2.
    decimalSeparator (string): The decimal separator.
    groupingSeparator (string): The thousands separator, aka digit group separator.
  Returns: String in decimal format with an emphasis on the pip value.

method asFractional(value, priceScale, minMove, minMove2, fractionalSeparator1, fractionalSeparator2)
  Converts a number to a string in fractional format.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    value (float): The value to format.
    priceScale (int): Price scale.
    minMove (int): Min move.
    minMove2 (int): Min move 2.
    fractionalSeparator1 (string): The primary fractional separator.
    fractionalSeparator2 (string): The secondary fractional separator.
  Returns: String in fractional format.

method asVolume(value, precision, minTick, decimalSeparator, groupingSeparator, spacing)
  Converts a number to a string in volume format.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    value (float): The value to format.
    precision (int): Maximum number of decimal places.
    minTick (float): Minimum tick size.
    decimalSeparator (string): The decimal separator.
    groupingSeparator (string): The thousands separator, aka digit group separator.
    spacing (string): The whitespace separator.
  Returns: String in volume format.