TimezoneFormatIANAUTCLibrary "TimezoneFormatIANAUTC"
Provides either the full IANA timezone identifier or the corresponding UTC offset for TradingView’s built-in variables and functions.
tz(_tzname, _format)
Parameters:
_tzname (string) : "London", "New York", "Istanbul", "+1:00", "-03:00" etc.
_format (string) : "IANA" or "UTC"
Returns: "Europe/London", "America/New York", "UTC+1:00"
Example Code
import ARrowofTime/TimezoneFormatIANAUTC/1 as libtz
sesTZInput = input.string(defval = "Singapore", title = "Timezone")
example1 = libtz.tz("London", "IANA") // Return Europe/London
example2 = libtz.tz("London", "UTC") // Return UTC+1:00
example3 = libtz.tz("UTC+5", "IANA") // Return UTC+5:00
example4 = libtz.tz("UTC+4:30", "UTC") // Return UTC+4:30
example5 = libtz.tz(sesTZInput, "IANA") // Return Asia/Singapore
example6 = libtz.tz(sesTZInput, "UTC") // Return UTC+8:00
sesTime1 = time("","1300-1700", example1) // returns the UNIX time of the current bar in session time or na
sesTime2 = time("","1300-1700", example2) // returns the UNIX time of the current bar in session time or na
sesTime3 = time("","1300-1700", example3) // returns the UNIX time of the current bar in session time or na
sesTime4 = time("","1300-1700", example4) // returns the UNIX time of the current bar in session time or na
sesTime5 = time("","1300-1700", example5) // returns the UNIX time of the current bar in session time or na
sesTime6 = time("","1300-1700", example6) // returns the UNIX time of the current bar in session time or na
Parameter Format Guide
This section explains how to properly format the parameters for the tz(_tzname, _format) function.
_tzname (string) must be either;
A valid timezone name exactly as it appears in the chart’s lower-right corner (e.g. New York, London).
A valid UTC offset in ±H:MM or ±HH:MM format. Hours: 0–14 (zero-padded or not, e.g. +1:30, +01:30, -0:00). Minutes: Must be 00, 15, 30, or 45
examples;
"New York" → ✅ Valid chart label
"London" → ✅ Valid chart label
"Berlin" → ✅ Valid chart label
"America/New York" → ❌ Invalid chart label. (Use "New York" instead)
"+1:30" → ✅ Valid offset with single-digit hour
"+01:30" → ✅ Valid offset with zero-padded hour
"-05:00" → ✅ Valid negative offset
"-0:00" → ✅ Valid zero offset
"+1:1" → ❌ Invalid (minute must be 00, 15, 30, or 45)
"+2:50" → ❌ Invalid (minute must be 00, 15, 30, or 45)
"+15:00" → ❌ Invalid (hour must be 14 or below)
_tztype (string) must be either;
"IANA" → returns full IANA timezone identifier (e.g. "Europe/London"). When a time function call uses an IANA time zone identifier for its timezone argument, its calculations adjust automatically for historical and future changes to the specified region’s observed time, such as daylight saving time (DST) and updates to time zone boundaries, instead of using a fixed offset from UTC.
"UTC" → returns UTC offset string (e.g. "UTC+01:00")
Timezone
TimezoneLibrary with pre-defined timezone enums that can be used to request a timezone input from the user. The library provides a `tostring()` function to convert enum values to a valid string that can be used as a `timezone` parameter in pine script built-in functions. The library also includes a bonus function to get a formatted UTC offset from a UNIX timestamp.
The timezone enums in this library were compiled by referencing the available timezone options from TradingView chart settings as well as multiple Wikipedia articles relating to lists of time zones.
Some enums from this library are used to retrieve an IANA time zone identifier, while other enums only use UTC/GMT offset notation. It is important to note that the Pine Script User Manual recommends using IANA notation in most cases.
HOW TO USE
This library is intended to be used by Pine Coders who wish to provide their users with a simple way to input a timezone. Using this library is as easy as 1, 2, 3:
Step 1
Import the library into your script. Replace with the latest available version number for this library.
//@version=6
indicator("Example")
import n00btraders/Timezone/ as tz
Step 2
Select one of the available enums from the library and use it as an input. Tip: view the library source code and scroll through the enums at the top to find the best choice for your script.
timezoneInput = input.enum(tz.TimezoneID.EXCHANGE, "Timezone")
Step 3
Convert the user-selected input into a valid string that can be used in one of the pine script built-in functions that have a `timezone` parameter.
string timezone = tz.tostring(timezoneInput)
EXPORTED FUNCTIONS
There are multiple 𝚝𝚘𝚜𝚝𝚛𝚒𝚗𝚐() functions in this library: one for each timezone enum. The function takes a single parameter: any enum field from one of the available timezone enums that are exported by this library. Depending on the selected enum, the function will return a time zone string in either UTC/GMT notation or IANA notation.
Note: to avoid confusion with the built-in `str.tostring()` function, it is recommended to use this library's `tostring()` as a method rather than a function:
string timezone = timezoneInput.tostring()
offset(timestamp, format, timezone, prefix, colon)
Formats the time offset from a UNIX timestamp represented in a specified timezone.
Namespace types: series OffsetFormat
Parameters:
timestamp (int) : (series int) A UNIX time.
format (series OffsetFormat) : (series OffsetFormat) A time offset format.
timezone (string) : (series string) A UTC/GMT offset or IANA time zone identifier.
prefix (string) : (series string) Optional 'UTC' or 'GMT' prefix for the result.
colon (bool) : (series bool) Optional usage of colon separator.
Returns: Time zone offset using the selected format.
The 𝚘𝚏𝚏𝚜𝚎𝚝() function is provided as a convenient alternative to manually using `str.format_time()` and then manipulating the result.
The OffsetFormat enum is used to decide the format of the result from the `offset()` function. The library source code contains comments above this enum declaration that describe how each enum field will modify a time offset.
Tip: hover over the `offset()` function call in the Pine Editor to display a pop-up containing:
Function description
Detailed parameter list, including default values
Example function calls
Example outputs for different OffsetFormat.* enum values
NOTES
At the time of this publication, Pine cannot be used to access a chart's selected time zone. Therefore, the main benefit of this library is to provide a quick and easy way to create a pine script input for a time zone (most commonly, the same time zone selected in the user's chart settings).
At the time of the creation of this library, there are 95 Time Zones made available in the TradingView chart settings. If any changes are made to the time zone settings, this library will be updated to match the new changes.
All time zone enums (and their individual fields) in this library were manually verified and tested to ensure correctness.
An example usage of this library is included at the bottom of the source code.
Credits to HoanGhetti for providing a nice Markdown resource which I referenced to be able to create a formatted informational pop-up for this library's `offset()` function.
