# 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: string
type: library
summary: |
  Provides generic functions to manipulate strings.
description: |
  The string library provides generic functions to manipulate strings, such as
  to extract substrings or match patterns. You can access the string library by
  the global `Library.string` library.

  See
  [String pattern reference](../../../luau/strings.md#string-pattern-reference)
  for details on using `Library.string.match()`, `Library.string.gmatch()`, and
  `Library.string.gsub()` to find (and replace) substrings.
tags: []
code_samples: []
properties: []
functions:
  - name: string.byte
    summary: |
      Returns the internal numerical codes of the characters
      `s[i], s[i+1], ..., s[j]`. The default value for `i` is 1; the default
      value for `j` is `i`. These indices are corrected following the same rules
      of function string.sub.
    description: |
      Returns the internal numerical codes of the characters
      `s[i], s[i+1], ..., s[j]`. The default value for `i` is 1; the default
      value for `j` is `i`. These indices are corrected following the same rules
      of function `Library.string.sub()`.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
      - name: i
        type: number
        default: 1
        summary: ''
      - name: j
        type: number
        default: i
        summary: ''
    returns:
      - type: int
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.char
    summary: |
      Receives zero or more integers and returns a string with length equal to
      the number of arguments, in which each character has the internal
      numerical code equal to its corresponding argument.
    description: |
      Receives zero or more integers and returns a string with length equal to
      the number of arguments, in which each character has the internal
      numerical code equal to its corresponding argument.
    parameters:
      - name: ...
        type: int
        default:
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.find
    summary: |
      Looks for the first match of pattern in the string `s` and returns the
      indices of `s` where the occurrence starts and ends.
    description: |
      Searches for the first occurrence of a pattern in a string and returns the
      start and end indices of the match. If no match is found, it returns
      `nil.` You can specify where to start the search using the optional `init`
      parameter which defaults to 1 and can be negative. An optional `plain`
      parameter turns off pattern matching, so the function performs a plain
      substring search; note that if you use `plain`, you must also provide
      `init.`

      ```lua
      -- Example 1: Basic usage
      local s = "Hello, world!"
      local pattern = "world"
      local start_index, end_index = string.find(s, pattern)
      print(start_index, end_index)  -- Output: 8 12
      ```

      ```lua
      -- Example 2: Using init parameter
      local s = "Hello, world! Hello, Roblox!"
      local pattern = "Hello"
      local start_index, end_index = string.find(s, pattern, 10)
      print(start_index, end_index)  -- Output: 15 19
      ```

      ```lua
      -- Example 3: Using plain parameter
      local s = "Hello, world! (Hello)"
      local pattern = "(Hello)"
      local start_index, end_index = string.find(s, pattern, 1, true)
      print(start_index, end_index)  -- Output: 14 20
      ```

      ```lua
      -- Example 4: No Pattern found
      local s = "Hello, world!"
      local pattern = "Roblox"
      local start_index, end_index = string.find(s, pattern)
      print(start_index, end_index)  -- Output: nil
      ```
    parameters:
      - name: s
        type: string
        default:
        summary: |
          The string to search within.
      - name: pattern
        type: string
        default:
        summary: |
          The pattern to search for in given string.
      - name: init
        type: number
        default: 1
        summary: |
          The starting index for the search.
      - name: plain
        type: bool
        default: false
        summary: ''
    returns:
      - type: number
        summary: |
          The starting index of the match.
      - type: number
        summary: |
          The ending index of the match.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.format
    summary: |
      Returns a formatted version of its variable number of arguments following
      the description given in its first argument, which must be a string.
    description: |
      Returns a formatted version of its variable number of arguments following
      the description given in its first argument, which must be a string.

      You can convert variables into user-friendly strings of text using the
      `Library.string.format()` function. The function requires the following
      format:

      `%[flags][width].[precision][specifier]`.

      #### Specifiers

      The most important part of string formatting is the **specifiers**.

      <table>
        <thead>
          <tr>
            <th>Specifier</th>
            <th>Accepts</th>
            <th>Outputs</th>
            <th>Example Output</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>c</code></td>
            <td>integer</td>
            <td></td>
            <td>3</td>
          </tr>
          <tr>
            <td><code>d</code> or <code>i</code></td>
            <td>integer</td>
            <td>Decimal representation.</td>
            <td> 321 </td>
          </tr>
          <tr>
            <td><code>e</code> or <code>E</code></td>
            <td>float</td>
            <td>Scientific notation using <code>e</code> or <code>E</code>.</td>
            <td>3.296e2<br>3.296E2</td>
          </tr>
          <tr>
            <td><code>f</code></td>
            <td>float</td>
            <td></td>
            <td>3231.1231</td>
          </tr>
          <tr>
            <td><code>g</code> or <code>G</code></td>
            <td>float</td>
            <td>The shorter of <code>e</code>/<code>E</code> and <code>f</code>.</td>
            <td>3E14<br>3e14</td>
          </tr>
          <tr>
            <td><code>o</code></td>
            <td>integer</td>
            <td>Octal representation.</td>
            <td>610</td>
          </tr>
          <tr>
            <td><code>q</code></td>
            <td>string</td>
            <td>String in a form suitable to be safely read back by the Luau interpreter. The string is written between double quotes and all double quotes, new lines, embedded zeros, and backslashes are correctly escaped.</td>
            <td>"print(\"Hi\")"</td>
          </tr>
          <tr>
            <td><code>s</code></td>
            <td>string</td>
            <td></td>
            <td>Hello world!</td>
          </tr>
          <tr>
            <td><code>u</code></td>
            <td>integer</td>
            <td>Decimal representation.</td>
            <td>3131</td>
          </tr>
          <tr>
            <td><code>x</code> or <code>X</code></td>
            <td>integer</td>
            <td>Hexadecimal representation.</td>
            <td>7fa<br>7FA</td>
          </tr>
          <tr>
            <td><code>*</code></td>
            <td>any</td>
            <td>Equivalent to <code>s</code> but accepts any variable by converting it to a string using <code>Global.LuaGlobals.tostring()</code>.</td>
            <td>table: 0x0123456789abcdef</td>
          </tr>
          <tr>
            <td><code>%</code></td>
            <td></td>
            <td><code>%</code> followed by another <code>%</code> will return the <code>%</code> sign itself.</td>
            <td>%</td>
          </tr>
        </tbody>
      </table>

      ```
      local str = "The magic word is %s"
      print(string.format(str, "Roblox"))
      -- The magic word is Roblox

      local str = "The magic word is %q"
      print(string.format(str, "Roblox"))
      -- The magic word is "Roblox"

      local str = "Skip to \na new line and \nanother new line!"
      print(string.format(str, "%q"))
      --[[ Output:
      Skip to
      a new line and
      another new line!
      ]]
      ```

      #### Flags

      <table>
      <thead>
        <tr>
          <th>Flag</th>
          <th>Description</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><code>-</code></td>
          <td>Left-justify the given field width (see <code>Width</code> below). Right justification is the default.</td>
        </tr>
        <tr>
          <td><code>+</code></td>
          <td>Forces a "+" sign to precede a number. Has no effect on negative numbers.</td>
        </tr>
        <tr>
          <td>(space)</td>
          <td>One blank space is inserted before a positive number, while negative numbers are unaffected. This is useful for making positive and negative numbers vertically align in a visual stacked list.</td>
        </tr>
        <tr>
          <td><code>#</code></td>
          <td>When used with <code>o</code> and <code>x</code>/<code>X</code>, writes a 0 (octal) or 0x/0X (hex) before values other than zero.<br>When used with <code>e</code>/<code>E</code> and <code>f</code>, forces the output to contain a decimal point, even if no digits would follow (by default, no decimal point is written if no digits follow).<br>When used with <code>g</code> or <code>G</code>, the result is the same as with <code>e</code> or <code>E</code> but trailing zeros are not removed.</td>
        </tr>
        <tr>
          <td><code>0</code></td>
          <td>Left-pads the number with zeros instead of empty spaces (see <code>Width</code> below).</td>
        </tr>
      </tbody>
      </table>

      ```lua
      local str = "%-10d"
      print(string.format(str, 300) .. "]")
      -- 300       ]
      -- There are 7 spaces between '300' and ']'

      local str = "%+i versus %+i"
      print(string.format(str, 300, -300)) -- +300 versus -300

      local str = "There is a% i%% chance of rain in Seattle today."
      print(string.format(str, 100))
      -- There is a 100% chance of rain in Seattle today.
      ```

      #### Width

      <table>
        <thead>
          <tr>
            <th>Width</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>(number)</td>
            <td>Minimum number of characters to return. If the number of characters to be formatted is less than this number, the result is padded with blank spaces.</td>
          </tr>
        </tbody>
      </table>

      ```lua
      local str = "%012i"
      print("Score: " .. string.format(str, 15000))
      -- Output: Score: 000000015000
      -- The output has 12 digits total, left-padded with zeros
      ```

      #### Precision

      The default precision is 1. If you give a period without a value, the
      default is 0.

      <table>
        <thead>
          <tr>
            <th>Precision</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>.</code>(number)</td>
            <td>For integer specifiers (<code>d</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>x</code>/<code>X</code>), precision specifies the minimum number of digits to be returned. If the value to be formatted is shorter than this number, the result is padded with leading zeros. A precision of 0 means that no character is written for the value 0.<br>For <code>e</code>/<code>E</code> and <code>f</code> specifiers, this is the number of digits to be printed after the decimal point.<br>For <code>g</code>/<code>G</code> specifiers, this is the maximum number of digits (before the <code>e</code>/<code>E</code>, if present).<br>For <code>s</code>, this is the maximum number of characters to be returned.<br>For <code>c</code> and <code>q</code>, this has no effect.</td>
          </tr>
        </tbody>
      </table>

      ```lua
      -- Add decimal with precision of 2 for a currency output
      local str = "$%.2f"
      print(string.format(str, 300)) -- Output: $300.00

      -- Return first 6 letters of a string
      local str = "%.6s"
      print(string.format(str, "Robloxian")) -- Output: Roblox

      local str = "Once upon a time, there was a dragon named %s and it had %.8f horns."
      print(string.format(str, "Pi", math.pi))
      -- Output: Once upon a time, there was a dragon named Pi and it had 3.14159265 horns.
      ```
    parameters:
      - name: formatstring
        type: string
        default:
        summary: ''
      - name: ...
        type: string
        default:
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.gmatch
    summary: |
      Returns an iterator function that returns the next captures from pattern
      over the string `s` each time it's called.
    description: |
      Returns an iterator function that returns the next captures from pattern
      over the string `s` each time it's called.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
      - name: pattern
        type: string
        default:
        summary: ''
    returns:
      - type: function
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.gsub
    summary: |
      Returns a copy of `s` in which all or the first `n` occurrences of the
      pattern are replaced with the given replacement. The second value returned
      is the total number of substitutions made.
    description: |
      Short for global substitution. Returns a copy of `s` in which all (or the
      first n, if given) occurrences of the pattern are substituted (replaced)
      with the given `replacement`. The second value returned is the total
      number of substitutions made.

      The `replacement` can be one of several types, each used differently to
      determine the actual string:

      - string: The pattern is replaced with the string directly
      - table: The string that matched the pattern is looked up in the table as
        a key, and the value (string) is what replaces it, if it exists.
      - function: Called with the string that matched the pattern, should return
        the string to replace the matched pattern.

      An optional final argument can be provided which specifies the maximum
      number of substitutions to make (for example, stop after 2 replacements)

      #### Various Examples

      ```lua
      -- Basic replacement
      string.gsub("I love tacos!", "tacos", "Roblox") --> I love Roblox! 1
      -- Replacement with a pattern
      string.gsub("I like red!", "%w+", "word") --> word word word! 3
      -- Replacement table
      string.gsub("I play Roblox.", "%w+", {I="Je", play="joue à"}) --> Je joue à Roblox. 3
      -- Replacement function
      string.gsub("I have 2 cats.", "%d+", function(n) return tonumber(n) * 12 end) --> I have 24 cats. 1
      -- Replace only twice
      string.gsub("aaa", "a", "b", 2) --> bba 2
      -- Replacement with capture groups (maximum of nine)
      string.gsub("love2play Roblox", "(%w+)(%d+)(%w+)%s+(%w+)", "I %1 %2 %3 %4!") --> I love 2 play Roblox! 1
      ```
    parameters:
      - name: s
        type: string
        default:
        summary: |
          The string whose occurrences of the given pattern shall be replaced.
      - name: pattern
        type: string
        default:
        summary: |
          The pattern to be matched and replaced.
      - name: replacement
        type: Variant
        default:
        summary: |
          Determines what should replace the occurrence(s) of the given pattern.
      - name: replacements
        type: number
        default:
        summary: |
          The maximum number of substitutions to make.
    returns:
      - type: string
        summary: ''
      - type: number
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.len
    summary: |
      Returns the length of a string.
    description: |
      Returns the length of a string.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
    returns:
      - type: int
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.lower
    summary: |
      Returns a copy of a string with all uppercase letters changed to
      lowercase.
    description: |
      Returns a copy of a string with all uppercase letters changed to
      lowercase.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.match
    summary: |
      Looks for the first match of pattern in the string `s`. If a match is
      found, it is returned; otherwise, it returns `nil`. A third, optional
      numerical argument, init, specifies where to start the search.
    description: |
      Looks for the first match of pattern in the string `s`. If a match is
      found, it is returned; otherwise, it returns `nil`. A third, optional
      numerical argument, init, specifies where to start the search; its default
      value is 1 and can be negative.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
      - name: pattern
        type: string
        default:
        summary: ''
      - name: init
        type: number
        default: 1
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.pack
    summary: |
      Returns a binary string containing the provided arguments.
    description: |
      Returns a binary string containing the provided arguments. The first
      argument, `format`, determines the way the remaining arguments are packed;
      see [here](https://www.lua.org/manual/5.3/manual.html#6.4.2) for options.
    parameters:
      - name: format
        type: string
        default:
        summary: ''
      - name: ...
        type: Variant
        default:
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.packsize
    summary: |
      Returns the size in bytes of any string packed with a given description.
    description: |
      Returns the size in bytes of any string packed with a given description.
      The sole argument, `format`, determines the way the remaining arguments
      are packed, but you cannot use `s` and `z` because they have variable
      lengths. See [here](https://www.lua.org/manual/5.3/manual.html#6.4.2) for
      options.
    parameters:
      - name: format
        type: string
        default:
        summary: ''
    returns:
      - type: number
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.rep
    summary: |
      Returns a string that is the concatenation of `n` copies of the string
      `s`.
    description: |
      Returns a string that is the concatenation of `n` copies of the string
      `s`.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
      - name: 'n'
        type: int
        default:
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.reverse
    summary: |
      Returns a string that is the string `s` reversed.
    description: |
      Returns a string that is the string `s` reversed.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.split
    summary: |
      Splits a string into parts based on the defined separator character(s),
      returning a table of ordered results.
    description: |
      Splits a string into parts based on the defined separator character(s),
      returning a table of ordered results.

      If an empty "slice" is located, that part will be returned as an empty
      string. For instance `string.split("abc||def", "|")` will return a table
      with three strings: `"abc"`, `""`, and `"def"`.

      ```lua
      local values = input:split(",")
      print(values[1], values[2], values[3])
      ```

      Also note that whitespace from the original string will be preserved, for
      example `string.split("abc _ def", "_")` will honor the whitespace on both
      sides of the `_` separator. By default, the separator character is `,` but
      you can specify an alternative character or series of characters.

      **Corner Cases**

      #### Empty String

      ```lua
      "" --> ""
      ```

      #### Empty Slices

      ```lua
      "foo,,bar" --> "foo", "", "bar"
      ",foo" --> "", "foo"
      "foo," --> "foo", ""
      "," --> "", ""
      ",," --> "", "", ""
      ```

      #### Whitespace Preserved

      ```lua
      "   whitespace   " --> "   whitespace   "
      "foo , bar" --> "foo ", " bar"
      ```

      #### Invalid UTF-8

      ```lua
      "\xFF" --> "\xFF"
      "\xFD,\xFE" --> "\xFD", "\xFE"
      ```

      #### Unicode

      ```lua
      "，" --> U+FF0C FULLWIDTH COMMA
      "我很高兴，你呢？" --> "我很高兴", "你呢？"
      "•" --> U+2022 BULLET
      "hello•world" --> "hello", "world"
      ```
    parameters:
      - name: s
        type: string
        default:
        summary: |
          The string to split.
      - name: separator
        type: string
        default: ','
        summary: |
          The separator character(s) to be used for splitting the string.
    returns:
      - type: table
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.sub
    summary: |
      Returns the substring of `s` that starts at `i` and continues until and
      including `j`. `i` and `j` can be negative. `i` defaults to 1 and `j`
      defaults to `-1`.
    description: |
      Returns the substring of `s` that starts at `i` and continues until and
      including `j`. `i` and `j` can be negative. `i` defaults to 1 and `j`
      defaults to `-1`.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
      - name: i
        type: int
        default: 1
        summary: ''
      - name: j
        type: int
        default: -1
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.unpack
    summary: |
      Extracts the values packed in the provided binary string.
    description: |
      Extracts the values packed in the provided binary string based on the
      first argument, `format`, which should match the one originally used to
      `Library.string.pack|pack()` the string; see
      [here](https://www.lua.org/manual/5.3/manual.html#6.4.2) for options. The
      optional third parameter determines the byte at which the reading starts.
    parameters:
      - name: format
        type: string
        default:
        summary: ''
      - name: data
        type: string
        default:
        summary: ''
      - name: readStart
        type: string
        default: 1
        summary: ''
    returns:
      - type: Tuple
        summary: |
          The values packed into the provided binary string, plus the index of
          the first unread byte.
    tags: []
    code_samples: []
    deprecation_message: ''
  - name: string.upper
    summary: |
      Returns a copy of a string with all lowercase letters changed to
      uppercase.
    description: |
      Returns a copy of a string with all lowercase letters changed to
      uppercase.
    parameters:
      - name: s
        type: string
        default:
        summary: ''
    returns:
      - type: string
        summary: ''
    tags: []
    code_samples: []
    deprecation_message: ''