Standard Libraries

String Manipulation

Lua has a powerful set of string manipulation functions, such as finding and extracting substrings. Unlike C, the first character of the string has "1" as the position index. You can also use negative indices in a string just like Python does - e.g the last character in a string is at position -1. You can use both methods, whichever you find convenient.

Note that the string library assumes one-byte character encodings.

The following table gives an overview of string manipulation commands. Have a look at them, and then study the examples below.

String Command	Meaning
string.byte (s [, i [, j]])	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.
string.find (s, pattern [, init [, plain]])	Looks for the first match of pattern in the string s. If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil
string.format (formatstring, ···)	Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string).
string.gmatch (s, pattern)	Returns an iterator function that, each time it is called, returns the next captures from pattern over string s.
string.len (s)	Returns the length of the string s.
string.lower (s)	Changes all characters of a string to lowercase.
string.upper (s)	Changes all characters of a string to uppercase.
string.reverse (s)	Returns a string which is a reverse of the string s.

File I/O

In an app, there always comes a point where you might want to persist some data. Persisting data in simple terms means retaining the data even after the app is exited. Some examples would include the current level, a high score, the player‘s name and so on. There could be other more complex examples where one might have levels stored in files. For all of these there’s an API, the File I/O API.

There are two ways to reference these functions, the explicit and the implicit. Explicit is when the file to be worked on is specified, it is seen in the form of file: type commands where as implicit is by passing the fileHandle to the function for file operations and are generally seen starting with io.

Example:

local playerName = "Awesome Player"
local file = io.open ( "settings.save" , "w+" )
file:write( "Playername:" , playerName )
file:close()

This has just saved a file called settings.save with the values "Playername: Awesome Player"

Now that we have some data saved in the file, let us try to read it from the file.

local playerName = nil
local file = io.open ( “settings.save”, “r” )
playerName = file:read()
file:close()
print ( “The playername saved is: ”, playerName)

Opening a File

To open a file using lua, we would use

file = io.open ( filename [, mode])

where the file called filename is opened and the file handle, a reference to this file is passed back in the variable file. The modes for opening the files can be one of the following.

• “r” read mode, this is the default mode
• “w” write mode
• “a” append mode
• “r+” update mode, all previous data is preserved
• “w+” update mode, all previous data is erased
• “a+” append update mode, previous data is preserved, writing is allowed only at the end of the file.

There is no explicit way to open a file, all files are opened using the io.open function.

Closing a File

To close a file, we would use

io.close([file])

This closes the file handle passed to the function, if nothing is passed, the default output file is closed.

The explicit way to close a file is file:close()

Getting Data/Input

In a complex application, we need to get several kinds of data from files stored on the device. In order to get data from a file, we are given a couple of options, including lines and read.

When we use the lines function, it offers an iterator function, which returns a new line from the file each time it is called. Therefore this is used as

for line in io.lines(filename) do … end

Note that this function does not require the file to be opened or closed, all of that is managed by the function internally.

There is an explicit version of the same, which is used as file:lines(), the difference between this and the implicit function is that to get the filehandle, we have to open the file, there is no parameter passed to the lines function and when the end of file is reached, the file is not automatically closed, we have to close it.

The other way to get data from a file is the read function, which is used as

data = io.read( format1, … )

The explicit equivalent is file:read( format1, … )

Since the function does not have a filehandle passed to it, io.read reads from the standard input and hence if you want to read from a file,

The formats that can be used for the function are:

• “*n” this will read a number, this returns a numeric value than a string
• “*a” this will read all the data in the file, starting from the current position.
• “*l” this will read the next line, this is the default for this command

where nn if a number is used for format, it tells the function to read those many (nn) characters from the file.

Temporary Files

Sometimes there might be the need to create a temporary file either to transfer portions of data or to save a backup copy before being certain. The easiest way to create one than trying to name the files through the code and then keeping track of the file open and close, etc is to use the io.tmpfile() function. This returns a file handle to a temporary file opened in update mode and this file is automatically removed when the app terminates.

Writing Data

To write data back to the files, it has to be opened in a mode that supports writing data to the file. The one and only way to write data is to use the function write.

io.write(value1, …)

The data passed to the function is written to the file, however since there is no filehandle passed to this function, it writes to the standard output, so if you want to write to a file, the file:write(value1, ...) function should be used.

Seeking Your Position in the File

Updating data is one of the easiest and one of the most difficult task. An easy way to update data is overwrite the entire file with the new data, but sometimes that can be very time consuming so the easier way is to position the write head to the position and then write the data there. We can get the position and set the position by using the function seek, this is an explicit function only.

position = file:seek( [mode] [,offset] )

By default, the mode is set to “cur” and the offset to 0. There are three modes which are

• “set” this is from the 0 position (start of file) and the head is moved to the position as specified by offset
• “cur” this is from the current position, so the offset is added to the current position
• “end” this is from the end of the file

so to get the size of the file, one can use

filesize = file:seek(“end”)

the set can be used to rewind the reading.

Buffering

The buffering for a file can be set by the file:setvbuf() command which is defined as

file:setvbuf( mode [, size] )

there are three modes that are available for this command:

• “no”: There is no buffering, the results are instantaneous
• “full”: The output operations occur only when the buffer is full, or when you flush
• “line”: The output is buffered on a per line basis (till a newline character is received)

The size is the size of the buffer in bytes.

Flushing Data

If you are using a buffer for writes, you might want to flush i.e. commit the file’s output buffer and save all of that to the file. Buffering is not really required in modern systems but still can be helpful at times. So before closing a file, if buffering was on, it is a good practice to flush and ensure that all the data is saved from the buffers to the file. This is an explicit function so is defined as

file:flush()

there are no parameters passed to this function.

Validating the File Operations

While working with files there are a lot of situations that could lead to errors, so it is very important to check for the return values, generally the return values are nil when the end of the file is reached or a file could not be opened, etc.

However to check the state of the file via the file handle can be with the type function as

result = io.type(fileHandle)

the return value is either “file” if the file is open, “closed” if the file is closed or nil if the fileHandle is not a file handle.