string

แสดงที่เลิกใช้งานแล้ว

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 string library.

See String Pattern Reference for details on using string.match() and string.gmatch() to find a piece, or substring, of a longer string.

สรุป

ฟังก์ชัน

  • 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.

  • 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.

  • find(s : string,pattern : string,init : number,plain : bool):number,number

    Looks for the first match of pattern in the string s and returns the indices of s where the occurrence starts and ends.

  • format(formatstring : string,... : string):string

    Returns a formatted version of its variable number of arguments following the description given in its first argument, which must be a string.

  • gmatch(s : string,pattern : string):function

    Returns an iterator function that returns the next captures from pattern over the string s each time it's called.

  • gsub(s : string,pattern : string,replacement : Variant,replacements : number):string,number

    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.

  • Returns the length of a string.

  • Returns a copy of a string with all uppercase letters changed to lowercase.

  • match(s : string,pattern : string,init : number):string

    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.

  • pack(format : string,... : Variant):string

    Returns a binary string containing the provided arguments.

  • Returns the size in bytes of any string packed with a given description.

  • Returns a string that is the concatenation of n copies of the string s.

  • Returns a string that is the string s reversed.

  • split(s : string,separator : string):table

    Splits a string into parts based on the defined separator character(s), returning a table of ordered results.

  • 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.

  • unpack(format : string,data : string,readStart : string):Tuple

    Extracts the values packed in the provided binary string.

  • Returns a copy of a string with all lowercase letters changed to uppercase.

ฟังก์ชัน

byte

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().

พารามิเตอร์

ค่าเริ่มต้น: 1
ค่าเริ่มต้น: i

ส่งค่ากลับ

char

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.

พารามิเตอร์

...: number

ส่งค่ากลับ

find

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.


-- 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

-- 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

-- 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

-- 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

พารามิเตอร์

The string to search within.

pattern: string

The pattern to search for in given string.

init: number

The starting index for the search.

ค่าเริ่มต้น: 1
plain: bool
ค่าเริ่มต้น: false

ส่งค่ากลับ

The starting index of the match.

The ending index of the match.

format

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 string.format() function. The function requires the following format:

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

Specifiers

The most important part of string formatting is the specifiers.

SpecifierAcceptsOutputsExample Output
cinteger3
d or iintegerDecimal representation. 321
e or EfloatScientific notation using e or E.3.296e2
3.296E2
ffloat3231.1231
g or GfloatThe shorter of e/E and f.3E14
3e14
ointegerOctal representation.610
qstringString in a form suitable to be safely read back by the Lua interpreter. The string is written between double quotes and all double quotes, new lines, embedded zeros, and backslashes are correctly escaped."print(\"Hi\")"
sstringHello world!
uintegerDecimal representation.3131
x or XintegerHexadecimal representation.7fa
7FA
*anyEquivalent to s but accepts any variable by converting it to a string using tostring().table: 0x0123456789abcdef
%% followed by another % will return the % sign itself.%

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

FlagDescription
-Left-justify the given field width (see Width below). Right justification is the default.
+Forces a "+" sign to precede a number. Has no effect on negative numbers.
(space)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.
#When used with o and x/X, writes a 0 (octal) or 0x/0X (hex) before values other than zero.
When used with e/E and f, 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).
When used with g or G, the result is the same as with e or E but trailing zeros are not removed.
0Left-pads the number with zeros instead of empty spaces (see Width below).

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

WidthDescription
(number)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.

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.

PrecisionDescription
.(number)For integer specifiers (d, i, o, u, x/X), 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.
For e/E and f specifiers, this is the number of digits to be printed after the decimal point.
For g/G specifiers, this is the maximum number of digits (before the e/E, if present).
For s, this is the maximum number of characters to be returned.
For c and q, this has no effect.

-- 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.

พารามิเตอร์

formatstring: string
...: string

ส่งค่ากลับ

gmatch

Returns an iterator function that returns the next captures from pattern over the string s each time it's called.

พารามิเตอร์

pattern: string

ส่งค่ากลับ

gsub

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


-- Simple replacement
string.gsub("I love tacos!", "tacos", "Roblox") --> I love Roblox! 1
-- Using a pattern (hint: %w+ matches whole words)
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

พารามิเตอร์

The string whose occurrences of the given pattern shall be replaced.

pattern: string

The pattern to be matched and replaced.

replacement: Variant

Determines what should replace the occurrence(s) of the given pattern.

replacements: number

The maximum number of substitutions to make.

ส่งค่ากลับ

Returns the length of a string.

พารามิเตอร์

ส่งค่ากลับ

lower

Returns a copy of a string with all uppercase letters changed to lowercase.

พารามิเตอร์

ส่งค่ากลับ

match

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.

พารามิเตอร์

pattern: string
init: number
ค่าเริ่มต้น: 1

ส่งค่ากลับ

pack

Returns a binary string containing the provided arguments. The first argument, format, determines the way the remaining arguments are packed; see here for options.

พารามิเตอร์

format: string
...: Variant

ส่งค่ากลับ

packsize

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 for options.

พารามิเตอร์

format: string

ส่งค่ากลับ

Returns a string that is the concatenation of n copies of the string s.

พารามิเตอร์

ส่งค่ากลับ

reverse

Returns a string that is the string s reversed.

พารามิเตอร์

ส่งค่ากลับ

split

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".


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


"" --> ""

Empty Slices


"foo,,bar" --> "foo", "", "bar"
",foo" --> "", "foo"
"foo," --> "foo", ""
"," --> "", ""
",," --> "", "", ""

Whitespace Preserved


" whitespace " --> " whitespace "
"foo , bar" --> "foo ", " bar"

Invalid UTF-8


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

Unicode


"," --> U+FF0C FULLWIDTH COMMA
"我很高兴,你呢?" --> "我很高兴", "你呢?"
"•" --> U+2022 BULLET
"hello•world" --> "hello", "world"

พารามิเตอร์

The string to split.

separator: string

The separator character(s) to be used for splitting the string.

ค่าเริ่มต้น: ,

ส่งค่ากลับ

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.

พารามิเตอร์

ค่าเริ่มต้น: 1
ค่าเริ่มต้น: -1

ส่งค่ากลับ

unpack

Extracts the values packed in the provided binary string based on the first argument, format, which should match the one originally used to pack() the string; see here for options. The optional third parameter determines the byte at which the reading starts.

พารามิเตอร์

format: string
data: string
readStart: string
ค่าเริ่มต้น: 1

ส่งค่ากลับ

The values packed into the provided binary string, plus the index of the first unread byte.

upper

Returns a copy of a string with all lowercase letters changed to uppercase.

พารามิเตอร์

ส่งค่ากลับ