Understanding the timestamp() Function in Pine Script

This article will dive into the timestamp() function, exploring its syntax, overloads, arguments, and practical examples to illustrate its usage.

Syntax

The timestamp() function can be called in multiple ways, depending on the required output and the input provided. Here are its syntax and overloads:

1. timestamp(dateString) → const int
2. timestamp(year, month, day, hour, minute, second) → simple int
3. timestamp(year, month, day, hour, minute, second) → series int
4. timestamp(timezone, year, month, day, hour, minute, second) → simple int
5. timestamp(timezone, year, month, day, hour, minute, second) → series int

Arguments

• dateString (const string): A string containing the date and, optionally, the time and time zone, adhering to IETF RFC 2822 or ISO 8601 standards. If only the date is provided, “00:00” is assumed for the time, and GMT+0 is used if no time zone is specified.
• year, month, day, hour, minute, second: Integer values representing the respective components of a date and time.
• timezone (string): A string indicating the time zone for the timestamp.

Examples

The following script demonstrates various uses of the timestamp() function:

//@version=5
indicator("MyCustomTimestamp")
plot(timestamp(2016, 01, 19, 09, 30), linewidth=3, color=color.green)
plot(timestamp(syminfo.timezone, 2016, 01, 19, 09, 30), color=color.blue)
plot(timestamp(2016, 01, 19, 09, 30), color=color.yellow)
plot(timestamp("GMT+6", 2016, 01, 19, 09, 30), color=color.orange)
plot(timestamp(2019, 06, 19, 09, 30, 15), color=color.lime)
plot(timestamp("GMT+3", 2019, 06, 19, 09, 30, 15), color=color.fuchsia)
plot(timestamp("Feb 01 2020 22:10:05"), color=color.red)
plot(timestamp("2011-10-10T14:48:00"), color=color.purple)
plot(timestamp("04 Dec 1995 00:12:00 GMT+5"), color=color.navy)

Walkthrough

• Script Declaration with Version:
  • The line //@version=5 indicates that this script is using version 5 of Pine Script. This is essential for compatibility and to ensure that the script utilizes the features and syntax specific to this version.
• Indicator Declaration:
  • indicator("MyCustomTimestamp") declares a new indicator named “MyCustomTimestamp”. This is what will be displayed as the name of the indicator on the chart.
• Plotting Timestamps without Time Zone:
  • plot(timestamp(2016, 01, 19, 09, 30), linewidth=3, color=color.green) plots a single point on the chart representing the UNIX timestamp for January 19, 2016, at 09:30 GMT+0. The point is plotted with a green line of width 3.
  • plot(timestamp(2016, 01, 19, 09, 30), color=color.yellow) plots another point for the same date and time, but with a yellow line, demonstrating how the same timestamp can be represented in different styles on the chart.
• Plotting Timestamps with Script’s Time Zone:
  • plot(timestamp(syminfo.timezone, 2016, 01, 19, 09, 30), color=color.blue) uses the syminfo.timezone to plot the timestamp according to the exchange’s time zone, not GMT+0. This shows the flexibility of using the script’s or chart’s current time zone.
• Plotting Timestamps with Specified Time Zones:
  • By specifying time zones, such as "GMT+6" and "GMT+3", the script plots timestamps adjusted for these time zones. This demonstrates how to adjust timestamps for different geographical locations directly within the script.
• Plotting Various Timestamp Formats:
  • The script also showcases plotting timestamps using different input formats, including specific dates and times in both RFC 2822 and ISO 8601 formats. This illustrates the function’s versatility in handling date-time strings.
• Color Coding for Distinction:
  • Each plot() function call uses a different color for the line (color=color.green, color=color.blue, etc.), making it easy to distinguish between the various timestamps and their conditions on the chart.
• Demonstration of UNIX Time Conversion:
  • All the timestamp() function calls convert the provided date-time values into UNIX time (milliseconds since January 1, 1970, UTC), which is then plotted on the chart. This illustrates the primary purpose of the timestamp() function: to facilitate time-based calculations and comparisons in trading scripts.

Key Features and Takeaways

• Versatility: The timestamp() function supports both fixed and dynamic timestamps, allowing scripts to handle specific dates, times, and time zones.
• UNIX Time: It returns UNIX time, enabling scripts to perform time-based calculations and comparisons efficiently.
• Time Zone Awareness: By including a time zone in the function call, scripts can accurately work with time data across different geographic locations.
• Overloads: Multiple overloads make the function flexible, accommodating various input formats.

By understanding and utilizing the timestamp() function, Pine Script developers can enhance their trading strategies and indicators with precise time-based logic.