DateTime

Library with enums that can be used as script inputs to allow users to set their preferred date and/or time formats. The user-selected formats can be passed to the library functions (which use 𝚜𝚝𝚛.𝚏𝚘𝚛𝚖𝚊𝚝_𝚝𝚒𝚖𝚎() under the hood) to get formatted date and time strings from a UNIX time.



PREFACE
The target audience of this publication is users creating their own indicators/strategies.

Sometimes a date and/or time needs to be displayed to the user. As a Pine Coder, it is natural to focus our initial attention on the primary calculations or functions of a script, which can lead to the display format of dates and times being an afterthought. While it may not be crucial for the main use case of a script, increased customizability can help push indicators/strategies to the next level in the eyes of the user.

The purpose of this library is to provide an easy-to-use mechanism for allowing script users to choose the formats of dates and times that are displayed to them. Not only is this helpful for users from around the world who may be accustomed to different date/time formats, but it also makes it easier for the script author because it offloads the date/time formatting decision from the author to the user.



HOW TO USE

Step 1
Import the library. Replace <version> with the latest available version number for this library.

//@version=6indicator("Example") import n00btraders/DateTime/<version> as dt

Step 2
Select a date format and/or time format enum to be used as an input.

dateFormatInput = input.enum(dt.DateFormat.FORMAT_3, "Date format")timeFormatInput = input.enum(dt.TimeFormat.TWENTY_FOUR_HOURS, "Time hours format")

Step 3
Pass the user's selection as the `format` parameter in the formatting functions from this library. The `timestamp` & `timezone` parameters can be any value that would otherwise be used in 𝚜𝚝𝚛.𝚏𝚘𝚛𝚖𝚊𝚝_𝚝𝚒𝚖𝚎(𝚝𝚒𝚖𝚎, 𝚏𝚘𝚛𝚖𝚊𝚝, 𝚝𝚒𝚖𝚎𝚣𝚘𝚗𝚎).

string formattedDate = dt.formatDate(timestamp, dateFormatInput, timezone)string formattedTime = dt.formatTime(timestamp, timeFormatInput, timezone)

LIMITATIONS
The library's ease-of-use comes at a few costs:

• Fixed date/time formats.
  Using the library's pre-defined date & time formats means that additional custom formats cannot be utilized. For example, this library does not include seconds or fractional seconds in formatted time strings. If a script's use case requires displaying the 'seconds' from a time of day, then 𝚜𝚝𝚛.𝚏𝚘𝚛𝚖𝚊𝚝_𝚝𝚒𝚖𝚎() must be used directly.
  
• Fixed time zone offset format.
  The `formatTime()` function of this library can optionally add the time zone offset at the end of the time string, but the format of the offset cannot be specified. Note: if the default format for time zone offset is not sufficient, the Timezone library can be imported directly to get the time zone offset string in a preferred format.
  

ADVANTAGES
There are benefits to utilizing this library instead of directly using 𝚜𝚝𝚛.𝚏𝚘𝚛𝚖𝚊𝚝_𝚝𝚒𝚖𝚎():

• Easy to use from the user's perspective.
  The date & time format enums provide a similar look and feel to the "Date format" and "Time hours format" options that already exist in the TradingView chart settings.
  
• Easy to use from the author's perspective.
  The exported functions from this library are modeled to behave similarly to the 𝚜𝚝𝚛.𝚏𝚘𝚛𝚖𝚊𝚝_𝚝𝚒𝚖𝚎(𝚝𝚒𝚖𝚎, 𝚏𝚘𝚛𝚖𝚊𝚝, 𝚝𝚒𝚖𝚎𝚣𝚘𝚗𝚎) built-in function from Pine Script.
  
• Format quarter of the year.
  The date formatting function from this library can display a fiscal quarter if it's included in the user-selected format. This is currently not possible with the built-in 𝚜𝚝𝚛.𝚏𝚘𝚛𝚖𝚊𝚝_𝚝𝚒𝚖𝚎().
  

EXPORTED ENUM TYPES
This section will list the available date/time formats that can be used as a script input. Each enum type has a detailed //@𝚏𝚞𝚗𝚌𝚝𝚒𝚘𝚗 description in the source code to help determine the best choice for your scripts.

Date Format Enums:

• 𝙳𝚊𝚝𝚎𝙵𝚘𝚛𝚖𝚊𝚝
  
• 𝙳𝚊𝚝𝚎𝙵𝚘𝚛𝚖𝚊𝚝𝙳𝚊𝚢𝙾𝚏𝚆𝚎𝚎𝚔𝙰𝚋𝚋𝚛
  
• 𝙳𝚊𝚝𝚎𝙵𝚘𝚛𝚖𝚊𝚝𝙳𝚊𝚢𝙾𝚏𝚆𝚎𝚎𝚔𝙵𝚞𝚕𝚕
  
• 𝙲𝚞𝚜𝚝𝚘𝚖𝙳𝚊𝚝𝚎𝙵𝚘𝚛𝚖𝚊𝚝
  

Supporting Date Enums:

• 𝙳𝚊𝚝𝚎𝙿𝚛𝚎𝚏𝚒𝚡
  

Time Format Enums:

• 𝚃𝚒𝚖𝚎𝙵𝚘𝚛𝚖𝚊𝚝
  

Supporting Time Enums:

• 𝚃𝚒𝚖𝚎𝙰𝚋𝚋𝚛𝚎𝚟𝚒𝚊𝚝𝚒𝚘𝚗
  
• 𝚃𝚒𝚖𝚎𝚂𝚎𝚙𝚊𝚛𝚊𝚝𝚘𝚛
  
• 𝚃𝚒𝚖𝚎𝙿𝚘𝚜𝚝𝚏𝚒𝚡
  

Note: all exported enums have custom titles for each field. This means that the supporting enums could also be exposed to the end-user as script inputs if necessary. The supporting enums are used as optional parameters in this library's formatting functions to allow further customizability.



EXPORTED FUNCTIONS

formatDate(timestamp, format, timezone, prefix, trim)
  Converts a UNIX time into a date string formatted according to the selected `format`.
  Parameters:
    timestamp (series int): A UNIX time.
    format (series DateFormat): A date format.
    timezone (series string): A UTC/GMT offset or IANA time zone identifier.
    prefix (series DatePrefix): Optional day of week prefix.
    trim (series bool): Optional truncation of numeric month / day.
  Returns: Calendar date string using the selected format.

⸻⸻⸻⸻⸻⸻⸻⸻
Required parameters: `timestamp`, `format`.

Note: there is a version of this function for each Date Format enum type. The only difference is the type of the `format` parameter.

Tip: hover over the `formatDate()` function in the Pine Editor to display useful details:

• Function description
  
• Parameter descriptions + default values
  
• Example function usage
  

formatTime(timestamp, format, timezone, trim, separator, postfix, space, offset)
  Converts a UNIX time into a formatted time string using the 24-hour clock or 12-hour clock.
  Parameters:
    timestamp (series int): A UNIX time.
    format (series TimeFormat): A time format.
    timezone (series string): A UTC/GMT offset or IANA time zone identifier.
    trim (series TimeAbbreviation): Optional truncation of the hour and minute portion.
    separator (series TimeSeparator): Optional time separator.
    postfix (series TimePostfix): Optional format for the AM/PM postfix.
    space (series bool): Optional space between the time and the postfix.
    offset (series bool): Optional UTC offset as a suffix.
  Returns: Time of day string using the selected format.

⸻⸻⸻⸻⸻⸻⸻⸻
Required parameters: `timestamp`, `format`.

Note: the `trim`, `postfix`, and `space` optional parameters are not applicable and will be ignored when using the 24-hour clock (`format` = TimeFormat.TWENTY_FOUR_HOURS).

Tip: hover over the `formatTime()` function in the Pine Editor to display useful details:

• Function description
  
• Parameter descriptions + default values
  
• Example function usage
  
• Example outputs for combinations of TimeFormat.* enum values & optional parameters
  

NOTES

• This library can be used in conjunction with the Timezone library to increase the usability of scripts that can benefit from allowing the user to input their preferred time zone.
  
• Credits to HoanGhetti for publishing an informative Markdown resource which I referenced to create the formatted function descriptions that pop up when hovering over `formatDate()` and `formatTime()` function calls in the Pine Editor.