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
  • split
  • trim
  • trimstart
  • trimend
  • padstart
  • padend
  • ensurestart
  • ensureend
  • esc
  • unesc
  • escregex
  • unescregex
  • 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

split(self, sep, regex)

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

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

trim(self, chars)

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

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

trimstart(self, chars)

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

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

trimend(self, chars)

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

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

padstart(self, 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(self, 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(self, 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(self, 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(self, 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(self, eschar)

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

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

escregex(self)

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

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

unescregex(self)

Unescapes regexp special characters

("%^%[abc%]"):escregex() -- "^[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(self, len, suffix)

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

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

startswith(self, prefix)

Returns true if the string starts with specified string

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

endswith(self, 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

Make sure that luaunit package can be required using package.path variable.