# This file is automatically generated. Please don't edit it manually.
# To submit a bug report on the content, see
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72

name: os
type: library
summary: |
  This library provides functions related to time and date.
description: |
  This library currently serves the purpose of providing information about the
  system time under the UTC format. It has been heavily sandboxed from the
  standard Lua `Library.os` library and does not allow you to perform any
  system-altering operations.
tags: []
code_samples: []
properties: []
functions:
  - name: os.clock
    summary: |
      Returns elapsed time in seconds since an arbitrary baseline with
      sub-microsecond precision.
    description: |
      Returns elapsed time in seconds since an arbitrary baseline with
      sub-microsecond precision. This function is useful for comparing durations
      between two events that occur on the same computer, and is the best option
      for benchmarking.

      Unlike with functions such as `Library.os.time()` or
      `Datatype.DateTime.now()`, adjustments to the system clock (such as by the
      user or [NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)) do not
      cause time to jump forwards or backwards.

      ```lua
      -- Record the initial time:
      local startTime = os.clock()
      -- Do something you want to measure the performance of:
      local a, b = 0, 1
      for _ = 1, 5000000 do
          a, b = b, a
      end
      -- Measure amount of time this took:
      local deltaTime = os.clock() - startTime
      print("Elapsed time: " .. deltaTime)
      -->  Elapsed time: 0.044425600033719 (actual number may vary)
      ```
    parameters: []
    returns:
      - type: double
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: os.date
    summary: |
      Formats the given string with date/time information based on the given
      time.
    description: |
      Formats the given `formatString` with date/time information based on the
      given time, or if not provided, the value returned by `Library.os.time()`.

      This function should be avoided in new work. Instead, use the
      `Datatype.DateTime` API, which supports localized formatting.

      The following specifiers (based on the C function strftime) are supported:

      <table>
        <thead>
          <tr>
            <th>Specifier</th>
            <th>Meaning</th>
            <th>Example<sup>&dagger;</sup></th>
           </tr>
        </thead>
      <tbody>
      <tr>
        <td><code>%a</code></td>
        <td>Abbreviated weekday name *</td>
        <td>Mon</td>
      </tr>
      <tr>
        <td><code>%A</code></td>
        <td>Full weekday name *</td>
        <td>Monday</td>
      </tr>
      <tr>
        <td><code>%b</code></td>
        <td>Abbreviated month name *</td>
        <td>Feb</td>
      </tr>
      <tr>
        <td><code>%B</code></td>
        <td>Full month name *</td>
        <td>February</td>
      </tr>
      <tr>
        <td><code>%c</code></td>
        <td>Date and time *</td>
        <td>Mon Feb 12 14:14:35 2024</td>
      </tr>
      <tr>
        <td><code>%d</code></td>
        <td>Day of the month</td>
        <td>12</td>
      </tr>
      <tr>
        <td><code>%H</code></td>
        <td>Hour, using 24-hour clock</td>
        <td>14</td>
      </tr>
      <tr>
        <td><code>%I</code></td>
        <td>Hour, using 12-hour clock</td>
        <td>02</td>
      </tr>
      <tr>
        <td><code>%j</code></td>
        <td>Day of year</td>
        <td>043</td>
      </tr>
      <tr>
        <td><code>%m</code></td>
        <td>Month</td>
        <td>02</td>
      </tr>
      <tr>
        <td><code>%M</code></td>
        <td>Minute</td>
        <td>14</td>
      </tr>
      <tr>
        <td><code>%p</code></td>
        <td>Either "AM" or "PM"</td>
        <td>PM</td>
      </tr>
      <tr>
        <td><code>%S</code></td>
        <td>Second</td>
        <td>35</td>
      </tr>
      <tr>
        <td><code>%U</code></td>
        <td>Week number (first Sunday as the first day of week one)</td>
        <td>06</td>
      </tr>
      <tr>
        <td><code>%w</code></td>
        <td>Weekday</td>
        <td>1</td>
      </tr>
      <tr>
        <td><code>%W</code></td>
        <td>Week number (first Monday as the first day of week one)</td>
        <td>07</td>
      </tr>
      <tr>
        <td><code>%x</code></td>
        <td>Date *</td>
        <td>02/12/24</td>
      </tr>
      <tr>
        <td><code>%X</code></td>
        <td>Time *</td>
        <td>14:14:35</td>
      </tr>
      <tr>
        <td><code>%y</code></td>
        <td>Two-digit year</td>
        <td>24</td>
      </tr>
      <tr>
        <td><code>%Y</code></td>
        <td>Full year</td>
        <td>2024</td>
      </tr>
      <tr>
        <td><code>%z</code></td>
        <td>ISO 8601 offset from UTC in timezone (1 minute = 1, 1 hour = 100)</td>
        <td>-0800</td>
      </tr>
      <tr>
        <td><code>%Z</code></td>
        <td>Timezone name or abbreviation *</td>
        <td>PST</td>
      </tr>
      <tr>
        <td><code>%%</code></td>
        <td>The % character</td>
        <td>%</td>
      </tr>
      </tbody>
      </table>

      \* This value can vary depending on the current locale.

      &dagger; The example provided is for February 12th, 2024 (Monday) at
      2:14:35 PM (14:14:35), run using locale "en-us" in Pacific Standard Time
      (PST).

      If the provided `formatString` is exactly `"*t"` (local time) or `"!*t"`
      (UTC time), this function instead returns a dictionary containing the
      following components, which are normally available in the specifiers
      above.

      <table>
        <thead>
          <tr>
            <th>Field</th>
            <th>Type</th>
            <th>Description</th>
          </tr>
        </thead>
      <tbody>
        <tr>
          <td>year</td>
          <td>int</td>
          <td>An integer that describes the current year of the Current Era (ex. 2017)</td>
        </tr>
        <tr>
          <td>month</td>
          <td>int</td>
          <td>An integer between 1 and 12 (starting from January) that describes the current month.</td>
        </tr>
        <tr>
          <td>wday</td>
          <td>int</td>
          <td>An integer between 1 and 7 (starting from Sunday) that describes the current week day.</td>
        </tr>
        <tr>
          <td>yday</td>
          <td>int</td>
          <td>An integer between 1 and 366 describing how many days we are into the year.<br />There can be 366 days if it is a leap year.</td>
        </tr>
        <tr>
          <td>day</td>
          <td>int</td>
          <td>An integer between 1 and 31 describing the current day of the month.</td>
        </tr>
        <tr>
          <td>hour</td>
          <td>int</td>
          <td>An integer between 1 and 24 describing the current hour of the day.</td>
        </tr>
        <tr>
          <td>min</td>
          <td>int</td>
          <td>An integer between 0 and 59 describing the current minute of the hour.</td>
        </tr>
        <tr>
          <td>sec</td>
          <td>int</td>
          <td>An integer between 0 and 60 describing the current second of the hour.<br />(60 because the function is described to indicate leap seconds, but in practice it probably doesn't).</td>
        </tr>
        <tr>
          <td>isdst</td>
          <td>bool</td>
          <td>A boolean describing if daylight savings time is currently active.</td>
        </tr>
      </tbody>
      </table>
    parameters:
      - name: formatString
        type: string
        default:
        summary: |
          Must be either `"*t"` or `"!*t"`.
      - name: time
        type: int
        default:
        summary: |
          The time value to format.
    returns:
      - type: Dictionary
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: os.difftime
    summary: |
      Returns the number of seconds from one time to another.
    description: |
      Returns the number of seconds from `t1` to `t2`. The difference is
      computed assuming that `t1` and `t2` are correctly casted to the
      [time_t](http://en.cppreference.com/w/cpp/chrono/c/time_t) format.
    parameters:
      - name: t2
        type: int
        default:
        summary: ''
      - name: t1
        type: int
        default:
        summary: ''
    returns:
      - type: int
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: os.time
    summary: |
      Returns how many seconds have passed since the Unix epoch (1 January 1970,
      00:00:00) under current UTC time.
    description: |
      Returns how many seconds have passed since the Unix epoch (1 January 1970,
      00:00:00), under current UTC time. If provided a table formatted similarly
      to that returned by `Library.os.date()`, it returns the number of seconds
      from the Unix epoch to that time instead.

      Note that the returned time uses the device's local clock. Most operating
      systems automatically sync their local time against online time servers,
      so this should be within a few hundred milliseconds. However, users can
      easily disable sync behavior and set the system time to anything they
      want; for synchronized time between client and server, use
      `Class.Workspace:GetServerTimeNow()` instead.

      This function should be avoided in new work. Instead, use the
      `Datatype.DateTime` API, which supports localized formatting.

      When you need to precisely measure the time elapsed between two points in
      time, like when testing performance, use `Library.os.clock()` instead.
    parameters:
      - name: time
        type: table
        default: UTC time
        summary: |
          A dictionary table describing a specific time, similar to that
          returned by `Library.os.date()`. If not provided, uses the current UTC
          time.
    returns:
      - type: int
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''