String API

Functionstring.byte
Return the byte of the first character in the given str. As string literals in Lua represent ASCII strings, this will most likely return ASCII codepoints. To convert a byte back into a string, use string.char.
Syntax string.byte(
  • str : string
)
Colon notation: str:byte()
Returns number
Part of Lua (source)
API string
ExamplePrint the bytes of the user input
Read a character from the user, then print the byte of each letter, separated by spaces.
Code 
<nowiki>
for character in read():gmatch(".") do
  write(string.byte(character))
  write(" ")
end
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the output would be 72 101 108 108 111 32 87 111 114 108 100.
Functionstring.char
Creates a string containing only the byte num. Hence, the number passed must be at least 0 and at most 255, and will be floored to the nearest integer.
Syntax string.char(
  • num : number
)
Returns string
Part of Lua (source)
API string
ExamplePrint the decoded character of the byte entered in the user's input
Read a line from the user, then prints the character that the entered codepoint represents.
Code 
<nowiki>
print(string.char(tonumber(read()))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter 65, the character printed would be A.
Functionstring.dump
Converts a function to a binary representation which can later be converted back to a function using loadstring. Functions not defined in Lua code (i.e. native CC functions such as type, pcall and os.date) cannot be dumped. Upvalues (local variables defined outside of a function and used within it) are not preserved.
Syntax string.dump(
  • func : function
)
Returns string
Part of Lua (source)
API string
ExampleDump and load a function
This dumps a function, writes the dump to a file, and then loads it again.
Code 
<nowiki>
local function example1()
    for i = 0, 10 do write(i .. " ") end
end

local f = fs.open("test", "w")
f.write(string.dump(example1))
f.close()

local f = fs.open("test", "r")
local dump = f.readAll()
f.close()

loadstring(dump)()
    </nowiki>
Output Prints 0 1 2 3 4 5 6 7 8 9 10 which is the output of the original function.
ExampleDump a function with upvalues
Upvalues are not preserved when a function is dumped and loaded, which can cause problems
Code 
<nowiki>
-- Within the example2 function, this is an upvalue
local x = "world"

local function example2()
    print("Hello", x)
end

print "example2 called directly"
example2()

print "example2 dumped and loaded, then called"
local dump = string.dump(example2)
local fn = loadstring(dump)
fn()
    </nowiki>
Output Prints Hello world when example2 is called directly, but prints Hello nil after the dump of example2 is loaded. x is "world" within example2, but within the dumped and loaded version it is nil.
ExampleDump a function not defined in Lua.
os.queueEvent is defined in CC itself, and has no Lua source code.
Code 
<nowiki>
string.dump(os.queueEvent)
    </nowiki>
Output Produces the error Unable to dump given function.
Functionstring.find
Finds a pattern in a sentence.
Syntax string.find(
  • sentence : string
  • pattern : string
  • start? : number
  • plain? : boolean
)
Colon notation: sentence:find(
  • pattern : string
  • start? : number
  • plain? : boolean
)
Returns number
Part of Lua (source)
API string
ExampleFind the word hello
Returns the start and end pos of the word.
Code 
<nowiki>
string.find("hello world","hello")
    </nowiki>
Output 1 5
ExampleFind the word hello with start at pos 2
Returns nil, because it starts at pos 2.
Code 
<nowiki>
string.find("hello world","hello",2)
    </nowiki>
Output nil
ExampleFind the letter "l" in the last 6 letters
Returns the start and end pos of the letter "l" in the word world.
Code 
<nowiki>
string.find("hello world","l",-6)
    </nowiki>
Output 10 10
ExampleFinding without pattern
Normaly it would find only the letter "l". When you turn the pattern finding off, it finds the letter "%" as well.
Code 
<nowiki>
string.find("%l","%l",1,true)
    </nowiki>
Output 1 2
Functionstring.format
Replaces placeholder strings in a string with the specified arguments.
Syntax string.format(
  • str : string
  • strings... : any
)
Returns string output
Part of Lua
API string
ExampleReplace placeholders in a string
Replace %s with what the user enters.
Code 
<nowiki>
local name = read()
print(string.format("Hello, %s!", name))
    </nowiki>
Output Prints "Hello," and whatever the user entered.
ExampleReplace placeholders in a variable
Replace %s with what the user enters.
Code 
<nowiki>
local name = read()
local output = "Hello, %s!"
print(output:format(name))
    </nowiki>
Output Prints "Hello," and whatever the user entered.

String.gmatch

Functionstring.gsub
Replaces a string in a sentence.
Syntax string.gsub(
  • sentence : string
  • string : string
  • count? : number
)
Colon notation: sentence:gsub(
  • string : string
  • count? : number
)
Returns string
Part of Lua (source)
API string
ExampleReplace all letter "l"
All letters "l" have been replaced by the letter "L".
Code 
<nowiki>
string.gsub("hello world","l","L")
    </nowiki>
Output heLLo worLd
ExampleLimit the substitutions
It limits the substitutions to the first 2 letters found
Code 
<nowiki>
string.gsub("hello world","l","L",2)
    </nowiki>
Output heLLo world
Functionstring.len
Return the number of bytes in str.
The number of bytes in a string is not necessarily equivalent to its amount of characters! Many Unicode characters take up more than one byte. For example, string.len("รถ") returns 2. Hence, string.len only returns the amount of characters if str is encoded in an encoding that only uses one byte per character, such as ASCII.
 Note: You can also use #str.
Syntax string.len(
  • str : string
)
Colon notation: str:len()
Returns number
Part of Lua (source)
API string
ExamplePrint the length of user input
Read a line from the user, then print the length of the string they entered.
Code 
<nowiki>
print(string.len(read()))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the number printed would be 11.
Functionstring.lower
Return a modified version of str where all uppercase characters have been converted to lowercase. Special characters and numbers are not affected.
Syntax string.lower(
  • str : string
)
Colon notation: str:lower()
Returns string
Part of Lua (source)
API string
ExamplePrint the user's input in all lowercase.
Read a line from the user, then print string in all lowercase.
Code 
<nowiki>
print(string.lower(read()))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the string printed would be hello world.

String.match

Functionstring.rep
Return the given str repeated repeat times.
Syntax string.rep(
  • str : string
  • repeat : number
)
Colon notation: str:rep(
  • repeat : number
)
Returns string
Part of Lua (source)
API string
ExampleRepeat user input 3 times
Read a line from the user, then print the the same line repeated 3 times.
Code 
<nowiki>
print(string.rep(read(), 3))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the output would be Hello WorldHello WorldHello World.
Functionstring.reverse
Return the given str with the character order reversed.
Syntax string.reverse(
  • str : string
)
Colon notation: str:reverse()
Returns string
Part of Lua (source)
API string
ExamplePrint the reverse of user input
Read a line from the user, then print the same input reversed.
Code 
<nowiki>
print(string.reverse(read()))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the output would be dlroW olleH.
Functionstring.sub
Return a string including the characters from start to end within str inclusively. If the arguments are negative, the character count will wrap the other way around. If the last argument end is not given, the substring will end at the end of the initial string.
Syntax string.sub(
  • str : string
  • start : number
  • end? : number
)
Colon notation: str:sub(
  • start : number
  • end? : number
)
Returns string
Part of Lua (source)
API string
ExampleStrip the first and last characters from users input
Read a line from the user, then print the same string without the first and last characters
Code 
<nowiki>
print(string.sub(read(), 2, -2))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the string printed would be ello Worl.
ExampleReturn ending of a string
Read a line from the user, then return the last 7 characters if the string.
Code 
<nowiki>
print(string.sub(read(), -7))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the string printed would be o World.
Functionstring.upper
Return a modified version of str where all lowercase characters have been converted to uppercase. Special characters and numbers are not affected.
Syntax string.upper(
  • str : string
)
Colon notation: str:upper()
Returns string
Part of Lua (source)
API string
ExamplePrint the user's input in all uppercase.
Read a line from the user, then print string in all uppercase.
Code 
<nowiki>
print(string.upper(read()))
    </nowiki>
Output Depends on what the user wrote. For instance, if they were to enter Hello World, the string printed would be HELLO WORLD.
This article is issued from Computercraft. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.