PriceFormatLibrary 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)
= PriceFormat.measurePriceChange(open, close, precision, language, allowPips = true)
// Labels to display formatted values on chart
string prices = str.format("Open: {0} ({1}) Close: {2} ({3})", formattedOpen, rawOpenPrice, formattedClose, rawClosePrice)
string change = str.format("Change (close - open): {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: .
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.
