text_utils
// This source code is subject to the terms of the Mozilla Public License 2.0 at https://mozilla.org/MPL/2.0/
// © Kaspricci

//@version=5

// @description a set of functions to handle placeholder in texts 
library("text_utils")


// user defined type placeholder to be used in your local script to creat an array of placeholder objects e.g. array<placeholder> list = array.new<placeholder>()
export type placeholder
    string key
    string value


// @function add a placehodler key and value to a local list
// @param list - reference to a local string array containing all placeholders, add string[] list = array.new_string(0) to your code
// @param key - a string representing the placeholder in a text, e.g. '{ticker}'
// @param value - a string representing the value of the placeholder e.g. 'EURUSD'
// @returns void
export add_placeholder(string[] list, string key, string value) =>
    // add key and string value to placeholder list
    array.push(list, key + "=" + value)


// @function add a placehodler key and value to a local list
// @param list - reference to a local array of user defined type placeholder containing all placeholders, add "array<placeholder> list = array.new<placeholder>()" to your code
// @param key - a string representing the placeholder in a text, e.g. '{ticker}'
// @param value - a string representing the value of the placeholder e.g. 'EURUSD'
// @returns void
export add_placeholder(array<placeholder> list, string key, string value) =>
    // add key and string value to placeholder list
    newPlaceholder = placeholder.new(key, value)

    array.push(list, newPlaceholder)


// @function add a placehodler key and value to a local list
// @param list - reference to a local string array containing all placeholders, add string[] list = array.new_string(0) to your code
// @param key - a string representing the placeholder in a text, e.g. '{ticker}'
// @param value - an integer value representing the value of the placeholder e.g. 10
// @param format - optional format string to be used when converting integer value to string, see str.format() for details, must contain '{0}'
// @returns void
export add_placeholder(string[] list, string key, int value, string format = "") =>
    // set default fromat string
    formatString = format == "" ? "{0}" : format
    // add key and int value to placeholder list
    array.push(list, key + "=" + str.format(formatString, value))


// @function add a placehodler key and value to a local list
// @param list - reference to a local array of user defined type placeholder containing all placeholders, add "array<placeholder> list = array.new<placeholder>()" to your code
// @param key - a string representing the placeholder in a text, e.g. '{quantity}'
// @param value - an integer value representing the value of the placeholder e.g. 10
// @param format - optional format string to be used when converting integer value to string, see str.format() for details, must contain '{0}'
// @returns void
export add_placeholder(array<placeholder> list, string key, int value, string format = "") =>
    // set default fromat string
    formatString = format == "" ? "{0}" : format

    // add key and string value to placeholder list
    newPlaceholder = placeholder.new(key, str.format(formatString, value))

    array.push(list, newPlaceholder)


// @function add a placehodler key and value to a local list
// @param list - reference to a local string array containing all placeholders, add string[] list = array.new_string(0) to your code
// @param key - a string representing the placeholder in a text, e.g. '{ticker}'
// @param value - a float value representing the value of the placeholder e.g. 1.5
// @param format - optional format string to be used when converting float value to string, see str.format() for details, must contain '{0}'
// @returns void
export add_placeholder(string[] list, string key, float value, string format = "") =>
    // set default fromat string
    formatString = format == "" ? "{0}" : format
    // add key and int value to placeholder list
    array.push(list, key + "=" + str.format(formatString, value))


// @function add a placehodler key and value to a local list
// @param list - reference to a local array of user defined type placeholder containing all placeholders, add "array<placeholder> list = array.new<placeholder>()" to your code
// @param key - a string representing the placeholder in a text, e.g. '{quantity}'
// @param value - a float value representing the value of the placeholder e.g. 1.5
// @param format - optional format string to be used when converting integer value to string, see str.format() for details, must contain '{0}'
// @returns void
export add_placeholder(array<placeholder> list, string key, float value, string format = "") =>
    // set default fromat string
    formatString = format == "" ? "{0}" : format
    
    // add key and string value to placeholder list
    newPlaceholder = placeholder.new(key, str.format(formatString, value))

    array.push(list, newPlaceholder)


// @function replace all placeholder keys with their value in a given text
// @param list - reference to a local string array containing all placeholders
// @param text_to_covert - a text with placeholder keys before their are replaced by their values
// @returns text with all replaced placeholder keys 
export replace_all_placeholder(string[] list, string text_to_convert) =>
    // get number of defined placeholders
    n = nz(array.size(list), 0)
    // save text locally
    tempText = text_to_convert
    // check if there is at least one placeholder defined
    if (n > 1)
        // replace all placeholders by their values
        for i = 0 to n - 1
            element = array.get(list, i)
            values  = str.split(element, "=") // returns a string array with key and value separated
            key     = array.get(values, 0)
            value   = array.get(values, 1)
            tempText := str.replace_all(tempText, key, value)
    // return text with replaced variables
    tempText


// @function replace all placeholder keys with their value in a given text
// @param list - reference to a local array of user defined type placeholder containing all placeholders
// @param text_to_covert - a text with placeholder keys before they are replaced by their values
// @returns text with all replaced placeholder keys
export replace_all_placeholder(array<placeholder> list, string text_to_convert) =>
    // get number of defined placeholders
    n = nz(array.size(list), 0)
    // save text locally
    tempText = text_to_convert
    // check if there is at least one placeholder defined
    if (n > 1)
        // replace all placeholders by their values
        for i = 0 to n - 1
            element = array.get(list, i)
            key     = element.key
            value   = element.value

            tempText := str.replace_all(tempText, key, value)
    // return text with replaced variables
    tempText