Lua standard string library extension

The package extends default Lua's string library with several useful common methods which are present in most other languages. If you ever missed split, trim and other functions the this package provides such functions by extending Lua's default string library.

Table of contents

• Installation
• Usage
• API
  • __mul
  • __index
  • split
  • trim
  • trimstart
  • trimend
  • padstart
  • padend
  • ensurestart
  • ensureend
  • esc
  • unesc
  • escpattern
  • unescpattern
  • escregex (Deprecated)
  • unescregex (Deprecated)
  • iter
  • truncate
  • startswith
  • endswith
  • isempty
  • isblank
  • tobool
  • totable
• Testing

Installation

Via LuaRocks:

luarocks install lua-string

Or just download and require init.lua file from this repo.

Usage

Just require it in the code like in the example below:

require "lua-string" -- It will extend the default string library
("Hello world!"):trimend("!"):sub(6):trim():totable() -- {"H", "e", "l", "l", "o"}

API

__mul(n)

Overloads * operator. Works the same as string.rep() function.

("abc") * 2 -- "abcabc"

__index(i)

Overloads [] operator. It's possible to access individual chars with this operator. Index could be negative. In that case the counting will start from the end.

("abc")[1] -- "a"
("abc")[-1] -- "c"

split(sep, pattern)

Splits string by supplied separator. If the pattern parameter is set to true then the separator is considered as a pattern

("a b c"):split(" ") -- {"a", "b", "c"}
("a,b, c"):split("%s*,%s*", true) -- {"a", "b", "c"}

trim(chars)

Trims string's characters from its endings. Trims whitespaces by default. The chars argument is a pattern string containing which characters to trim

(" abc "):trim() -- "abc"
(" abc !"):trim("! ") -- "abc"

trimstart(chars)

Trims string's characters from its left side. Trims whitespaces by default. The chars argument is a pattern string containing which characters to trim

(" abc "):trimstart() -- "abc "
(" abc !"):trimstart("! ") -- "abc !"

trimend(chars)

Trims string's characters from its right side. Trims whitespaces by default. The chars argument is a pattern string containing which characters to trim

(" abc "):trimend() -- " abc"
(" abc !"):trimend("! ") -- " abc"

padstart(len, str)

Pads string at the start with specified string until specified length. " " pad string by default

("1"):padstart(3) -- "  1"
("1"):padstart(3, "0") -- "001"

padend(len, str)

Pads string at the end with specified string until specified length. " " pad string by default

("1"):padend(3) -- "1  "
("1"):padend(3, "0") -- "100"

ensurestart(prefix)

If the string starts with specified prefix then returns string itself, otherwise pads the string until it starts with the prefix

("domain.com"):ensurestart("https://") -- "https://domain.com"
("https://domain.com"):ensurestart("https://") -- "https://domain.com"

ensureend(suffix)

If the string ends with specified prefix then returns string itself, otherwise pads the string until it ends with the prefix

("path"):ensureend("/") -- "path/"
("path/"):ensureend("/") -- "path/"

esc(eschar, eschartbl)

Adds backslashes before ", ' and \ characters. Escape character can be specified ("\\" by default) as well as characters to escape ({"\"", "'", "\\"} by default)

("Quote'"):esc() -- "Quote\\'"
("string%"):esc("#", {"%"}) -- "string#%"

unesc(eschar)

Strips backslashes from the string. Escape character can be specified ("\\" by default)

("Quote\\'"):unesc() -- "Quote'"
("string#%"):unesc("#") -- "string%"

escpattern(self)

Escapes pattern special characters so the can be used in pattern matching functions as is

("^[abc]"):escpattern() -- "%^%[abc%]"

unescpattern(self)

Unescapes pattern special characters

("%^%[abc%]"):unescpattern() -- "^[abc]"

escregex(self)

Escapes pattern special characters so the can be used in pattern functions as is. Deprecated, use escpattern instead

("^[abc]"):escregex() -- "%^%[abc%]"

unescregex(self)

Unescapes pattern special characters. Deprecated, use unescpattern instead

("%^%[abc%]"):unescregex() -- "^[abc]"

iter(self)

Returns an iterator which can be used in for loops

for char in ("abc"):iter() do
	print(char)
end
> a
> b
> c

truncate(len, suffix)

Truncates string to a specified length with optional suffix (usually "...", nil by default)

("string"):truncate(3) -- "str"
("string"):truncate(5, "...") -- "st..."

startswith(prefix)

Returns true if the string starts with specified string

("string"):startswith("str") -- true

endswith(suffix)

Returns true if the string ends with specified string

("string"):endswith("ing") -- true

isempty(self)

Returns true if string's length is 0

(""):isempty() -- true

isblank(self)

Returns true if string consists of whitespace characters

(" "):isblank() -- true

tobool(self)

Converts "1", "true", "on", "yes", "y" and their contraries into real boolean. Returns nil if casting cannot be done. Case-insensetive

("true"):tobool() -- true
("off"):tobool() -- false
("string"):tobool() -- nil

totable(self)

Returns table containing all the chars in the string

("abc"):totable() -- {"a", "b", "c"}

Testing

Install luaunit package:

luarocks install luaunit

Then run from the console:

lua test.lua