time reference

UTC time helpers. Duration and timeframe math use fixed seconds; calendar starts use UTC day, week, month, and year boundaries.

tf

tf(value: string) -> timeframe

Converts a string to a timeframe.

value uses case-sensitive units: s, m, h, D, W, M, or Y, for example "15m" or "4h". The length must be positive.

An empty, invalid, or out-of-range value stops the script with an error. String literals are checked before the script runs. The result is never null.

Example

script "Time Tf"
data chart = subscribe(data.ohlcv, timeframe: tf("5m"))

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
}

time.session

time.session(start: string, end: string, name: string? = null) -> session

Defines a daily time window in UTC.

start is included and end is excluded. If end <= start, the session wraps across midnight. name is optional and defaults to null.

Pass clock times as string literals. Invalid times are rejected before the script runs.

Example

script "Time Session"
data chart = subscribe(data.ohlcv)

on chart.update {
  let regular = time.session("09:30", "16:00", "RTH")
}

time.sessionMinutes

time.sessionMinutes(start: int, end: int) -> session

Defines a daily UTC window using minutes after midnight.

start and end each accept 0 to 1440, inclusive. 1440 means the end of the day, like 24:00. The start is included and the end is excluded. If end <= start, the session wraps across midnight. The session has no name.

For example, time.sessionMinutes(570, 960) equals time.session("09:30", "16:00") and supports the same session methods.

Arguments can change while the script runs. An out-of-range value stops the script with an error; a constant out-of-range value is rejected before the script runs. To convert decimal hours, use int(math.round(hours * 60.0, 0)) ?? 0; int(x) can return null.

Contracts

• start: Accepted range: 0 to 1440. Invalid values are rejected.
• end: Accepted range: 0 to 1440. Invalid values are rejected.

Example

script "Time Session Minutes"
data chart = subscribe(data.ohlcv)
input openHour = input.float(9.5, title: "Open (UTC hours)", min: 0.0, max: 17.5)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let start = int(math.round(openHour * 60.0, 0)) ?? 0
  let regular = time.sessionMinutes(start, start + 390)
  let active = regular.contains(ts)
}

time.contains

time.contains(time: time) -> bool

Reports whether a timestamp is inside the session.

Checks time against the session's UTC window. The start is included and the end is excluded. Check for null before calling on a nullable session.

Example

script "Time Contains"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let regular = time.session("09:30", "16:00", "RTH")
  let active = regular.contains(ts)
}

time.overlaps

time.overlaps(time: time, end: time) -> bool

Reports whether a time range overlaps the session.

time is the start of the UTC range, included in the range. end is its end, excluded from the range. Both must be non-null; check for null before calling.

Example

script "Time Overlaps"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let regular = time.session("09:30", "16:00", "RTH")
  let hit = regular.overlaps(ts, ts + time.minutes(30))
}

time.entered

time.entered(prev: time, time: time) -> bool

Tests whether the current timestamp entered the session.

prev is the earlier timestamp and time is the current timestamp. The result is true when prev was outside the session and time is inside it. Both timestamps are non-null UTC instants.

Example

script "Time Entered"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let regular = time.session("09:30", "16:00", "RTH")
  let started = regular.entered(ts - time.minutes(1), ts)
}

time.exited

time.exited(prev: time, time: time) -> bool

Tests whether the current timestamp exited the session.

prev is the earlier timestamp and time is the current timestamp. The result is true when prev was inside the session and time is outside it. Both timestamps are non-null UTC instants.

Example

script "Time Exited"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let regular = time.session("09:30", "16:00", "RTH")
  let ended = regular.exited(ts - time.minutes(1), ts)
}

time.windowStart

time.windowStart(time: time) -> time?

Returns the session window start containing a timestamp.

time selects the session window. Returns the UTC start timestamp for that window, or null when time is outside the session. The input timestamp is non-null.

Example

script "Time Window Start"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let regular = time.session("09:30", "16:00", "RTH")
  let start = regular.windowStart(ts) ?? ts
}

time.windowEnd

time.windowEnd(time: time) -> time?

Returns the session window end containing a timestamp.

time selects the session window. Returns the UTC end timestamp for that window, or null when time is outside the session. The input timestamp is non-null.

Example

script "Time Window End"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let regular = time.session("09:30", "16:00", "RTH")
  let closeTime = regular.windowEnd(ts) ?? ts
}

time.seconds

time.seconds(n: int) -> duration

Creates a duration of n seconds.

n is the number of seconds and can be negative. Arithmetic with a null duration returns null.

Example

script "Time Seconds"
data chart = subscribe(data.ohlcv)

on chart.update {
  let latency = time.seconds(30)
}

time.minutes

time.minutes(n: int) -> duration

Creates a duration of n minutes.

Each minute is 60 seconds. n can be negative. Values too large for a duration are rejected, as with duration arithmetic.

Example

script "Time Minutes"
data chart = subscribe(data.ohlcv)

on chart.update {
  let delay = time.minutes(5)
}

time.hours

time.hours(n: int) -> duration

Creates a duration of n hours.

Each hour is 3,600 seconds. n can be negative. Arithmetic with a null duration returns null.

Example

script "Time Hours"
data chart = subscribe(data.ohlcv)

on chart.update {
  let lookback = time.hours(4)
}

time.days

time.days(n: int) -> duration

Constructs a duration of n fixed 24-hour days.

n is multiplied by 86,400 seconds. Calendar dates and daylight-saving rules do not affect this fixed-duration constructor.

Example

script "Time Days"
data chart = subscribe(data.ohlcv)

on chart.update {
  let span = time.days(7)
}

time.weeks

time.weeks(n: int) -> duration

Constructs a duration of n fixed seven-day weeks.

n is multiplied by 604,800 seconds, so one week of duration equals seven fixed days. A 1W timeframe is different: timeframe weeks align to calendar weeks.

Example

script "Time Weeks"
data chart = subscribe(data.ohlcv)

on chart.update {
  let retention = time.weeks(2)
}

time.bars

time.bars(n: int, tf: timeframe? = null) -> duration

Returns the nominal duration of n bars on tf.

n is the bar count. tf is optional; null or omitted tf uses the current timeframe: the chart's on a chart, the window's in a window, otherwise the run configuration's. Fixed units use exact spans, while M and Y use nominal spans of 30 and 365 days. Use time.shiftBars when period boundaries matter.

Example

script "Time Bars"
data chart = subscribe(data.ohlcv)

on chart.update {
  let twoBars = time.bars(2, tf: 4h)
}

time.shiftBars

time.shiftBars(ts: time, n: int, tf: timeframe? = null) -> time

Moves ts by n timeframe boundaries.

ts is the timestamp to move, n is the signed boundary count, and tf is optional. Null or omitted tf uses the current timeframe: the chart's on a chart, the window's in a window, otherwise the run configuration's. Nonzero n snaps to the current boundary before stepping; n == 0 returns ts. Calendar-aligned W, M, and Y timeframes use UTC boundaries.

Example

script "Time Shift Bars"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let nextDaily = time.shiftBars(ts, 1, tf: 1D)
}

time.diff

time.diff(a: time, b: time) -> duration

Returns the difference between two timestamps.

Returns a - b as a signed duration in seconds. Both timestamps must be non-null. Check for null before calling.

Example

script "Time Diff"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let age = time.diff(ts, time.dayStart(ts))
}

time.durationSeconds

time.durationSeconds(d: duration) -> int

Returns the raw second count of a duration.

d is returned as its signed second count. Use ?? or a null guard before the call when the duration expression is nullable.

Example

script "Time Duration Seconds"
data chart = subscribe(data.ohlcv)

on chart.update {
  let seconds = time.durationSeconds(time.minutes(2))
}

time.unixSeconds

time.unixSeconds(ts: time?) -> int?

Converts a timestamp to Unix seconds.

ts is measured in seconds since 1970-01-01 00:00:00 UTC. Returns that count as an int, or null if ts is null.

Example

script "Time Unix Seconds"
data chart = subscribe(data.ohlcv)

on chart.update {
  let unix = time.unixSeconds(chart.time) ?? 0
}

time.fromUnixSeconds

time.fromUnixSeconds(seconds: int) -> time

Creates a timestamp from Unix seconds.

seconds counts from 1970-01-01 00:00:00 UTC. Negative values represent earlier times.

Example

script "Time From Unix Seconds"
data chart = subscribe(data.ohlcv)

on chart.update {
  let epoch = time.fromUnixSeconds(0)
}

time.floor

time.floor(ts: time, tf: timeframe) -> time

Rounds ts down to the start of its tf period.

Fixed units are aligned to exact spans from the Unix epoch. W is aligned to Monday 00:00 UTC; M to the first day of its global month group; and Y to January 1 of its global year group. Multi-period groups remain continuous across year boundaries.

Example

script "Time Floor"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let day = time.floor(ts, 1D)
}

time.ceil

time.ceil(ts: time, tf: timeframe) -> time

Rounds ts up to the start of the next tf period unless already aligned.

ts is returned unchanged when already aligned to tf; otherwise the next tf boundary is returned after flooring. Arguments are non-null.

Example

script "Time Ceil"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let nextBoundary = time.ceil(ts, 1h)
}

time.next

time.next(ts: time, tf: timeframe) -> time

Returns the next tf boundary after ts.

ts is floored to its tf period, then one boundary is added. W, M, and Y use their UTC calendar alignment rather than nominal durations.

Example

script "Time Next"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let nextMonth = time.next(ts, 1M)
}

time.prev

time.prev(ts: time, tf: timeframe) -> time

Returns the previous tf boundary before ts.

ts is floored to its tf period, then one boundary is subtracted. W, M, and Y use their UTC calendar alignment rather than nominal durations.

Example

script "Time Prev"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let prevWeek = time.prev(ts, 1W)
}

time.count

time.count(from: time, to: time, tf: timeframe) -> int

Counts tf boundaries from from to to.

from and to are mapped to their containing tf periods, then the signed boundary difference is returned. W, M, and Y use UTC calendar periods. Reversing from and to negates the count.

Example

script "Time Count"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let days = time.count(time.monthStart(ts), ts, 1D)
}

time.isAligned

time.isAligned(ts: time, tf: timeframe) -> bool

Checks whether ts is exactly on a tf boundary.

ts is aligned when it equals time.floor(ts, tf), including UTC calendar alignment for W, M, and Y. The result is always a non-null bool.

Example

script "Time Is Aligned"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let opensHour = time.isAligned(ts, 1h)
}

time.isNewPeriod

time.isNewPeriod(ts: time, prev: time?, tf: timeframe) -> bool

Checks whether ts starts a different tf period than prev.

ts is compared with prev after both are floored to tf. If prev is null, the result is true so first samples can initialize period state without a separate guard. The return is always bool.

Example

script "Time Is New Period"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let changed = time.isNewPeriod(ts, chart.time[1], 1D)
}

time.isCalendar

time.isCalendar(tf: timeframe) -> bool

Checks whether a timeframe uses a calendar-length unit.

tf returns true for UTC calendar-aligned W, M, and Y timeframes. Fixed s, m, h, and D timeframes return false.

Example

script "Time Is Calendar"
data chart = subscribe(data.ohlcv)

on chart.update {
  let monthly = time.isCalendar(1M)
}

time.nominalDuration

time.nominalDuration(tf: timeframe) -> duration

Returns the nominal duration of one timeframe period.

tf returns its nominal duration. Fixed units use exact spans; calendar M and Y use 30-day and 365-day spans when a duration value is required.

Example

script "Time Nominal Duration"
data chart = subscribe(data.ohlcv)

on chart.update {
  let period = time.nominalDuration(1M)
}

time.tfSeconds

time.tfSeconds(tf: timeframe) -> int

Returns a timeframe's length in seconds.

For tf, 1m returns 60, 4h returns 14400, 1D returns 86400, and 1W returns 604800. Months and years use estimates of 30 and 365 days. Use time.isCalendar before treating the result as an exact bar length.

This equals time.durationSeconds(time.nominalDuration(tf)). You can use it with constants or context.timeframe during setup, including in subscribe arguments.

Example

script "Time Tf Seconds"
data chart = subscribe(data.ohlcv)
setup chartSeconds = time.tfSeconds(context.timeframe)

on chart.update {
  let barsPerDay = 86400 / chartSeconds
}

time.tfFromSeconds

time.tfFromSeconds(seconds: int) -> timeframe

Creates a fixed-length timeframe from seconds.

seconds must be positive and fit within the timeframe limit. Other values stop the script with an error.

The result uses seconds, minutes, hours, or days: 60 becomes 1m, 900 becomes 15m, 3600 becomes 1h, and 86400 becomes 1D. A value of 90 stays 90s. A value of 604800 becomes 7D; calendar weeks, months, and years are not produced.

You can use this during setup. For example, time.tfFromSeconds(time.tfSeconds(context.timeframe) * 4) selects four times the chart timeframe for a subscription.

Example

script "Time Tf From Seconds"
input mult = input.int(4, title: "Multiple", min: 1, max: 60)
setup higherTf = time.tfFromSeconds(time.tfSeconds(context.timeframe) * mult)
data (
  chart = subscribe(data.ohlcv)
  higher = subscribe(data.ohlcv, timeframe: higherTf)
)

on chart.update {
  let spread = (chart.close ?? 0.0) - (higher.close ?? 0.0)
}

time.format

time.format(ts: time, template: string) -> string

Formats a timestamp as UTC text.

ts is the timestamp. template must be a string literal. Use tokens in braces, for example "{YYYY}-{MM}-{DD} {HH}:{mm}".

Supported tokens: YYYY, YY, M, MM, D, DD, H, HH, m, mm, s, ss, dayOfWeek, and unix. Invalid templates and unknown tokens are rejected before the script runs.

Example

script "Time Format"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let label = time.format(ts, "{YYYY}-{MM}-{DD} {HH}:{mm}:{ss}")
}

time.year

time.year(ts: time) -> int

Returns the UTC calendar year of ts.

Reads ts in UTC using Gregorian calendar rules, including for dates before the calendar was introduced. Returns a non-null integer year.

Example

script "Time Year"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let y = time.year(ts)
}

time.month

time.month(ts: time) -> int

Returns the UTC month number of ts.

ts is read in the UTC calendar. The result is 1 through 12 and is always a non-null int.

Example

script "Time Month"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let m = time.month(ts)
}

time.dayOfMonth

time.dayOfMonth(ts: time) -> int

Returns the UTC day of month of ts.

ts is read in the UTC calendar month. The result is 1 through 31 and is always a non-null int.

Example

script "Time Day Of Month"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let dom = time.dayOfMonth(ts)
}

time.dayOfWeek

time.dayOfWeek(ts: time) -> int

Returns the UTC ISO day of week of ts.

ts is read in the UTC calendar. The result is 1 for Monday through 7 for Sunday and is always a non-null int.

Example

script "Time Day Of Week"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let dow = time.dayOfWeek(ts)
}

time.hour

time.hour(ts: time) -> int

Returns the UTC hour of day of ts.

ts is read as a UTC time of day. The result is 0 through 23 and is always a non-null int.

Example

script "Time Hour"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let h = time.hour(ts)
}

time.minute

time.minute(ts: time) -> int

Returns the UTC minute of hour of ts.

ts is read as a UTC time of day. The result is 0 through 59 and is always a non-null int.

Example

script "Time Minute"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let minute = time.minute(ts)
}

time.second

time.second(ts: time) -> int

Returns the UTC second of minute of ts.

Reads ts in UTC and returns 0 to 59. Leap seconds are not represented.

Example

script "Time Second"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let s = time.second(ts)
}

time.dayStart

time.dayStart(ts: time) -> time

Returns the UTC day start containing ts.

ts is rounded to 00:00:00 UTC on its calendar day. This matches the fixed one-day boundary for UTC timestamps.

Example

script "Time Day Start"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let start = time.dayStart(ts)
}

time.weekStart

time.weekStart(ts: time) -> time

Returns the start of the UTC week containing ts.

Rounds ts down to Monday at 00:00:00 UTC.

Example

script "Time Week Start"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let start = time.weekStart(ts)
}

time.monthStart

time.monthStart(ts: time) -> time

Returns the UTC month start containing ts.

ts is rounded to 00:00:00 UTC on day 1 of its calendar month. The return is a non-null timestamp.

Example

script "Time Month Start"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let start = time.monthStart(ts)
}

time.yearStart

time.yearStart(ts: time) -> time

Returns the UTC year start containing ts.

ts is rounded to 00:00:00 UTC on January 1 of its calendar year. The return is a non-null timestamp.

Example

script "Time Year Start"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let start = time.yearStart(ts)
}

time.date

time.date(ts: time) -> string

Formats the UTC date portion of ts.

ts is formatted as a UTC date string with the format {YYYY}-{MM}-{DD}. The result matches time.format with that template and is never null.

Example

script "Time Date"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let d = time.date(ts)
}

time.clock

time.clock(ts: time) -> string

Formats the UTC clock portion of ts.

ts is formatted as a UTC clock string with the format {HH}:{mm}:{ss}. The result matches time.format with that template and is never null.

Example

script "Time Clock"
data chart = subscribe(data.ohlcv)

on chart.update {
  let ts = chart.time ?? time.fromUnixSeconds(0)
  let hhmmss = time.clock(ts)
}