Module `String`

Module Status: Experimental 2020-10-31.

Usage:

local String = require('__eradicators-library__/erlib/lua/String')()

Constants

UPPER_LETTERS	'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
UPPER_ARGS	'A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z'
LOWER_LETTERS	'abcdefghijklmnopqrstuvwxyz'
LOWER_ARGS	'a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z'
UNICODE_SPACE	A dense array of different unicode spaces.

Analyze strings

count(str, pattern)

Counts number of occurances of pattern in string.

Create strings

to_string(object)

Creates a pretty string representation of an object.

Create tables

find_all(str, pattern[, multi_capture=false])	Find all occurances of a pattern in a string.
find_fuzzy(str, pattern)	Factorio style "fuzzy" string search.
split(str, pattern, raw)	Splits a string into an array of sub-strings.
to_array(ustr)	Converts a string into an array of characters.

Manipulate strings

trim(str)	Trims whitespace from both sides of a string.
ltrim(str)	Trims whitespace from left side of a string.
rtrim(str)	Trims whitespace from right side of a string.
remove_whitespace(ustr)	Removes all whitespace from a string.
replace(str, pattern, replacement[, n=inf[, raw=true]])	Replaces a raw substring with another raw substring.
splice(str[, pattern='.'], seperator[, i=1[, j=#str]])	Puts a seperator between each pattern of the input string.
enforce_length(str, length[, left_pad=false])	Either pads or chops a string to an exact length.
to_camel_case(str)	Removes spaces, dashes and underscores then capitalizes words.
to_snake_case(str)	Converts CamelCase or dash-case to snake_case.

Factorio specific

remove_rich_text_tags(str)

Removes the rich text tags from a string.

Proof of Concepts / Drafts / Other Garbage

to_one_line_function(str)	Converts multi-line functions to one-line.
smart_format(str)	PROOF OF CONCEPT.

Constants

UPPER_LETTERS: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
UPPER_ARGS: 'A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z'
LOWER_LETTERS: 'abcdefghijklmnopqrstuvwxyz'
LOWER_ARGS: 'a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z'
UNICODE_SPACE: A dense array of different unicode spaces. (From here)

Analyze strings

count(str, pattern)

Counts number of occurances of pattern in string.

Parameters:

str string
pattern Pattern

Returns:

NaturalNumber

Create strings

to_string(object)

Creates a pretty string representation of an object. Differs from native tostring in that it knows about factorio userdata and can show the content of tables.

Parameters:

object AnyValue

Returns:

string

Usage:

for _,v in pairs{nil,true,42,'test',LuaPlayer,LuaPosition,function()end} do
  print(String.tostring(v))
  end

> nil
> true
> 42
> test
> {<LuaPlayer>}
> {x = -17.2109375, y = 14.265625}
> <function>

Create tables

find_all(str, pattern[, multi_capture=false])

Find all occurances of a pattern in a string.

Parameters:

str string
pattern Pattern
multi_capture boolean If the pattern can return more than one capture at a time. If true the result will return a sub-table for every group of captures. If false the result will be a plain array of strings. (default false)

Usage:

local test = 'ABCDEFG'
print(String.to_string(String.find_all(test,'(..)')))
> {"AB", "CD", "EF"}

print(String.to_string(String.find_all(test,'(.)(.)')))
> {"A", "C", "E"}

print(String.to_string(String.find_all(test,'(.)(.)',true)))
> {{"A", "B"}, {"C", "D"}, {"E", "F"}}

find_fuzzy(str, pattern)

Factorio style "fuzzy" string search. For true factorio style matching you must remove all whitespace from your input pattern.

Parameters:

str string
pattern DenseArray An array of strings (see String.to_array).

Returns:

boolean

Usage:

local needle   = 'r p e'
local haystack = 'Iron Plate'
print(String.find_fuzzy(
  haystack:lower(), String.to_array(String.remove_whitespace(needle:lower()))
  ))
> true

split(str, pattern, raw)

Splits a string into an array of sub-strings. The pattern is entirely removed from the result.

Parameters:

str string
pattern Pattern
raw boolean If the pattern should be treated as a raw string. See string.find "plain".

Returns:

table

Usage:

local test = 'AB12CD34EF56'
print(String.to_string(String.split(test,'%d%d')))
> {"AB", "CD", "EF"}

print(String.to_string(String.split(test,'%a%d')))
> {"A", "2C", "4E", "6"}

to_array(ustr)

Converts a string into an array of characters. Has limited unicode awareness.

Parameters:

ustr string

Returns:

DenseArray

Manipulate strings

trim(str)

Trims whitespace from both sides of a string.

Parameters:

str string

Returns:

string

ltrim(str)

Trims whitespace from left side of a string.

Parameters:

str string

Returns:

string

rtrim(str)

Trims whitespace from right side of a string.

Parameters:

str string

Returns:

string

remove_whitespace(ustr)

Removes all whitespace from a string. Does not remove line breaks. Uses String.UNICODE_SPACE.

Parameters:

ustr string

Returns:

string

replace(str, pattern, replacement[, n=inf[, raw=true]])

Replaces a raw substring with another raw substring. Similar to string.gsub, but ignores all Lua Patterns.

Parameters:

str string
pattern string
replacement string
n NaturalNumber How often the pattern should be replaced. Specify nil for infinite. (default inf)
raw boolean If the pattern and replacement are raw strings. Non-raw calls will be redirected to native string.gsub. (default true)

Returns:

string The new replacified string.
NaturalNumber How many replacements happend.

Usage:

local test = '%a%d%l%a'

print(String.replace(test,'%a','%d'))
> %d%d%l%d 2

print(String.replace(test,'%a','%d',1))
> %d%d%l%a 1

splice(str[, pattern='.'], seperator[, i=1[, j=#str]])

Puts a seperator between each pattern of the input string.

Parameters:

str string
pattern Pattern (default '.')
seperator string (default ',')
i double Start point in str. (default 1)
j double End point in str. (default #str)

Usage:

print(String.splice('ABCDEFG','..',':',3,7))
> CD:EF

enforce_length(str, length[, left_pad=false])

Either pads or chops a string to an exact length. Too long strings will be chopped up in the middle, too short strings will be either right- or left-padded.

Parameters:

str string
length NaturalNumber
left_pad boolean If the padding of short strings should be applied on the left instead of the right side. (default false)

Returns:

string

Usage:

local long_test  = 'The quick brown fox jumps over the lazy dog.'
local short_test = 'Nice boat.'

print(String.enforce_length(long_test,21))
> "The quick...lazy dog."

print(String.enforce_length(short_test,21))
> "Nice boat.           "

print(String.enforce_length(short_test,21,true))
> "           Nice boat."

to_camel_case(str)

Removes spaces, dashes and underscores then capitalizes words. Preserves leading and trailing underscores.

Parameters:

str string

Returns:

string

Usage:

print(String.to_camel_case '_private_function_name')
> _PrivateFunctionName
print(String.to_camel_case 'prototype-name')
> PrototypeName
print(String.to_camel_case '__mod-root__')
> __ModRoot__
print(String.to_camel_case 'A random sentence!')
> ARandomSentence

to_snake_case(str)

Converts CamelCase or dash-case to snake_case.

Parameters:

str string

Returns:

string

Factorio specific

remove_rich_text_tags(str)

Removes the rich text tags from a string. Useful for use with LuaRendering which doesn't support them.

Parameters:

str string

Returns:

string

Usage:

local test = '[test][color=red]![/color]1[img=bla]2[item=bla]3'
print(String.remove_rich_text_tags(test))
> [test]!123

Proof of Concepts / Drafts / Other Garbage

to_one_line_function(str)

Converts multi-line functions to one-line.

Removes new-lines and simple end-of-line comments.

Intended for including local copies of library functions into very simply stand-alone mods.

Does not have any complex handling whatsoever. You have to manually remove multi-line comments, strings containing newlines, strings containing --, or anything complicated like that.

Parameters:

str string A string representing a function.

Returns:

The

smart_format(str)

PROOF OF CONCEPT. SLOW. Do not use in production.
Python-esque string formatting from locals and upvalues.

Quirk: Lua functions only see upvalues that they actually use. If an upvalue is not used inside the format-calling function then a same named global variable will be used if it exists.

Parameters:

str string The template to be formatted.

Returns:

string The formatted output.
NaturalNumber The total number of formatted patterns.

Usage:

-- A variable name in curly brackets is the basic pattern.
local t = '{varname}'
-- You can also use string.format() syntax.
local t = '{varname:2.2f'}

local F = String.smart_format
function test(name,surname)
  print(F'Hi. My name is {name} {surname}!')
  end
test('E.R.','Adicator')
> Hi. My name is E.R. Adicator!

ldoc

Contents

Modules

Source

Module String

Usage:

Constants

Analyze strings

Create strings

Create tables

Manipulate strings

Factorio specific

Proof of Concepts / Drafts / Other Garbage

Constants

Analyze strings

Parameters:

Returns:

Create strings

Parameters:

Returns:

Usage:

Create tables

Parameters:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Manipulate strings

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Factorio specific

Parameters:

Returns:

Usage:

Proof of Concepts / Drafts / Other Garbage

Parameters:

Returns:

Parameters:

Returns:

Usage:

Module `String`