====== LUA String Usages =====

----
===== Introduction =====

A string in Lua is a fundamental data type that is used to store and manipulate text data. It represents a sequence of characters, such as** letters, numbers, symbols, spaces, and other special characters**.

Strings in Lua can be created by enclosing the text within either **single quotes ( ' ), double quotes ( " ) or string delimiters( <nowiki>[[ ]]</nowiki> )for multi-line strings**. For example, "Hello, Mini World!" and 'Mini World is great!' are both valid string representations in Lua.

Strings can be assigned to variables, allowing you to store and manipulate text data. For example:

  * A string of characters between single quotes.
<code lua>
local str1 = 'This is a string.' 
local str2 = "This is also a string." 
</code>

  * A string of characters between double quotes.
<code lua>
local str = "Hello, " 
str = str .. "World!" -- Create a new string and assign it to str
print ( str ) -- Output "Hello, World!"     
</code>

  * A string of characters between <nowiki>[[  and  ]]</nowiki> .
<code lua>
local multilineString = [[
This is a multiline string.
It can contain multiple lines of text.
No need for escape characters.
]]

print(multilineString)  
</code>

String examples of the above three methods are as follows:
<code lua>
string1 = "Lua"
Chat:sendSystemMsg(" \" String1 is \" " .. string1,0)

string2 = 'Mini World'
Chat:sendSystemMsg(" \" String2 is \" " .. string2,0)

string3 = [["Lua Tutorial"]]
Chat:sendSystemMsg(" \" String3 is \" " .. string3,0)
</code>
The output result of executing the above code is:\\
<code lua>
 String 1 is Lua 
 String 2 is Mini World
 String 3 is Lua Tutorial  
</code>
----
===== String length calculation =====

In Lua, you can calculate the length of a string using the string.len() function. The length of a string represents the number of characters it contains. Here's a step-by-step guide on how to calculate the length of a string in Lua:

__Step 1: Define a String__\\
To get started, let's define a string variable that we will use to calculate its length. For example, we can set a variable named myString to the value "Hello, Lua!":
<code lua>
local myString = "Hello, Lua!"
</code>

__Step 2: Calculate the Length__\\
To calculate the length of the string, we can use the string.len() function. This function takes a string as an input and returns the length of the string. In our case, we will pass the myString variable to the string.len() function:
<code lua>
local length = string.len(myString)
</code>

__Step 3: Display the Result__\\
To see the calculated length of the string, we can print it to the back log using the print() function:
<code lua>
print("The length of the string is: " .. length)
</code>

Complete Code Example:
Putting it all together, here's the complete code example:
<code lua>
-- Define the string
local myString = "Hello, Lua!"

-- Calculate the length
local length = string.len(myString)

-- Display the result
print("The length of the string is: " .. length)
</code>

Output:
When you run the code, it will output the following:
<code lua>
The length of the string is: 12
</code>

:!: But, the string.len() function in Lua is based on the <nowiki>ASCII</nowiki> encoding, which means it counts the number of bytes in a string. If you use string.len() on a string that contains characters outside the <nowiki>ASCII</nowiki> range or characters represented by multiple bytes in UTF-8 encoding, it may result in an inaccurate length.\\
For eaxmple, you want to count the string that is not in english or number, it might output incorrect data. In this case, You would use **utf8.len()** instead of string.len() in Lua when you are working with strings that contain UTF-8 encoded characters. Here's when and why you would use utf8.len():

  - **Handling UTF-8 Characters**: UTF-8 is a variable-length encoding that allows representing characters from various languages and scripts. Some characters in UTF-8 can be represented by multiple bytes. If you're working with strings that contain UTF-8 encoded characters, using utf8.len() ensures accurate counting of characters or graphemes.
  - **Counting Graphemes**: In some languages, a single visible character or grapheme can be composed of multiple code points. For example, in languages like Thai or Devanagari, a single character may consist of multiple code points. utf8.len() treats each grapheme as a single unit and returns the correct count of visible characters.
  - **Accurate Length Calculation**: string.len() counts the number of bytes in a string, regardless of the encoding. However, this does not always correspond to the actual number of visible characters or graphemes in the string when dealing with UTF-8 encoded characters. utf8.len() provides the correct count considering the specific encoding.

Here's an example to illustrate the difference between string.len() and utf8.len():
<code lua>
local myString = "Café"
print(string.len(myString))    -- Output: 6
print(utf8.len(myString))      -- Output: 4
</code>
In this example, string.len() counts the total number of bytes in the string, including the two bytes used to represent the "é" character in UTF-8 encoding. On the other hand, utf8.len() correctly counts the number of visible characters or graphemes, resulting in a count of 4.

In summary, use utf8.len() when working with strings that contain UTF-8 encoded characters to ensure accurate counting of characters or graphemes. For strings without UTF-8 characters, you can continue to use string.len() for length calculation.

----
===== String Manipulation =====

^  Serial Number  ^  Methods & Usage  ^
|  1  | **string.upper(argument):** \\ Convert all strings to uppercase letters. |
|  2  | **string.lower(argument):** \\ Convert all strings to lowercase letters. |
|  3  | **string.gsub(mainString,findString,replaceString,num)** \\ Returns a string by replacing occurrences of findString with mainString. \\ __mainString__: original string \\   __findString__: character to be replaced \\ __replaceString__: character to be replaced \\ __num__: number of replacements (can be ignored, then all will be replaced) |
|  4  | **string.find (str, substr, [init, [plain]])** \\ Search for the specified content substr in a specified target string str. If a matching substring is found, the starting index and ending index of the substring will be returned. If it does not exist, nil will be returned. |
|  5  | **string.format(arg)** \\ returns a formatted string similar to printf in C |
|  6  | **string.char(arg) and string.byte(arg[,int])** \\ char converts integer numbers into characters and connects them, byte converts characters into integer values (a certain character can be specified, the default is the first character). |
|  7  | **string.len(arg)** \\ calculates the string length. |
|  8  | **string.rep(string, n)** \\ returns n copies of string string |
|  9  | **..concatenate** \\ combine two strings |
|  10  | **string.gmatch(str, pattern)** \\ returns an iterator function. Each time this function is called, it returns the next substring found in the string str that matches the pattern description. If the string described by the parameter pattern is not found, the iteration function returns nil. |
|  11  | **string.match(str, pattern, init)** \\ string.match() only looks for the first match in the source string str. The parameter init is optional and specifies the starting point of the search process. The default is 1. On a successful pairing, the function returns all captures in the pairing expression; if no capture flag is set, the entire pairing string is returned. When there is no successful pairing, nil is returned. |

Here are examples for each of the string manipulation functions listed above:
1. string.upper(argument)\\
<code lua>
local str = "hello world"
local result = string.upper(str)
print(result) -- Output: "HELLO WORLD"
</code>
2.string.lower(argument)\\
<code lua>
local str = "Hello World"
local result = string.lower(str)
print(result) -- Output: "hello world"
</code>
3. string.gsub(mainString, findString, replaceString, num)\\
<code lua>
local str = "Hello, World!"
local result = string.gsub(str, "o", "a")
print(result) -- Output: "Hella, Warld!"
</code>
4. string.find(str, substr, [init, [plain]])\\
<code lua>
local str = "Hello, World!"
local startPos, endPos = string.find(str, "World")
print(startPos, endPos) -- Output: 8 12
</code>
5. string.format(arg)\\
<code lua>
local name = "John"
local age = 30
local result = string.format("My name is %s and I am %d years old.", name, age)
print(result) -- Output: "My name is John and I am 30 years old."
</code>
6. string.char(arg) and string.byte(arg[,int])\\
<code lua>
local str = string.char(65, 66, 67)--ASCII Code
print(str) -- Output: "ABC"

local char = string.byte("A")
print(char) -- Output: 65(ASCII Code)
</code>
7. string.len(arg)\\
<code lua>
local str = "Hello, World!"
local length = string.len(str)
print(length) -- Output: 13
</code>
8. string.rep(string, n)\\
<code lua>
local str = "Hello!"
local result = string.rep(str, 3)
print(result) -- Output: "Hello!Hello!Hello!"
</code>
9. ..concatenate\\
<code lua>
local str1 = "Hello"
local str2 = "World"
local result = str1 .. " " .. str2
print(result) -- Output: "Hello World"
</code>
10. string.gmatch(str, pattern)\\
<code lua>
local str = "The quick brown fox"
for word in string.gmatch(str, "%a+") do
    print(word)
end
-- Output:
-- "The"
-- "quick"
-- "brown"
-- "fox"
</code>
11. string.match(str, pattern, init)\\
<code lua>
local str = "Hello, World!"
local match = string.match(str, "%a+")
print(match) -- Output: "Hello"
</code>