Module pl.stringx

Python-style extended string library.

see 3.6.1 of the Python reference. If you want to make these available as string methods, then say stringx.import() to bring them into the standard string table.

See the Guide

Dependencies: pl.utils, pl.types

String Predicates

isalpha (s) does s only contain alphabetic characters?
isdigit (s) does s only contain digits?
isalnum (s) does s only contain alphanumeric characters?
isspace (s) does s only contain whitespace?
islower (s) does s only contain lower case characters?
isupper (s) does s only contain upper case characters?
startswith (s, prefix) does s start with prefix or one of prefixes?
endswith (s, suffix) does s end with suffix or one of suffixes?

Strings and Lists

join (s, seq) concatenate the strings using this string as a delimiter.
splitlines (s[, keep_ends]) Split a string into a list of lines.
split (s[, re[, n]]) split a string into a list of strings using a delimiter.
expandtabs (s, tabsize) replace all tabs in s with tabsize spaces.

Finding and Replacing

lfind (s, sub[, first[, last]]) find index of first instance of sub in s from the left.
rfind (s, sub[, first[, last]]) find index of first instance of sub in s from the right.
replace (s, old, new[, n]) replace up to n instances of old by new in the string s.
count (s, sub[, allow_overlap]) count all instances of substring in string.

Stripping and Justifying

ljust (s, w[, ch=' ']) left-justify s with width w.
rjust (s, w[, ch=' ']) right-justify s with width w.
center (s, w[, ch=' ']) center-justify s with width w.
lstrip (s[, chrs='%s']) trim any characters on the left of s.
rstrip (s[, chrs='%s']) trim any characters on the right of s.
strip (s[, chrs='%s']) trim any characters on both left and right of s.

Partitioning Strings

splitv (s[, re='%s']) split a string using a pattern.
partition (s, ch) partition the string using first occurrence of a delimiter
rpartition (s, ch) partition the string p using last occurrence of a delimiter
at (s, idx) return the 'character' at the index.

Text handling

indent (s, n[, ch=' ']) indent a multiline string.
dedent (s) dedent a multiline string by removing any initial indent.
wrap (s[, width=70[, breaklong=false]]) format a paragraph into lines so that they fit into a line width.
fill (s[, width=70[, breaklong=false]]) format a paragraph so that it fits into a line width.

Template

Template (tmpl) Creates a new Template class.
Template:substitute (tbl) substitute values into a template, throwing an error.
Template:safe_substitute (tbl) substitute values into a template.
Template:indent_substitute (tbl) substitute values into a template, preserving indentation.

Miscellaneous

lines (s) return an iterator over all lines in a string
title (s) initial word letters uppercase ('title case').
shorten (s, w, tail) Return a shortened version of a string.
quote_string (s) Quote the given string and preserve any control or escape characters, such that reloading the string in Lua returns the same result.
format_operator () Python-style formatting operator.
import () import the stringx functions into the global string (meta)table


String Predicates

isalpha (s)
does s only contain alphabetic characters?

Parameters:

isdigit (s)
does s only contain digits?

Parameters:

isalnum (s)
does s only contain alphanumeric characters?

Parameters:

isspace (s)
does s only contain whitespace? Matches on pattern '%s' so matches space, newline, tabs, etc.

Parameters:

islower (s)
does s only contain lower case characters?

Parameters:

isupper (s)
does s only contain upper case characters?

Parameters:

startswith (s, prefix)
does s start with prefix or one of prefixes?

Parameters:

  • s string a string
  • prefix a string or an array of strings
endswith (s, suffix)
does s end with suffix or one of suffixes?

Parameters:

  • s string a string
  • suffix a string or an array of strings

Strings and Lists

join (s, seq)
concatenate the strings using this string as a delimiter. Note that the arguments are reversed from string.concat.

Parameters:

  • s string the string
  • seq a table of strings or numbers

Usage:

    stringx.join(' ', {1,2,3}) == '1 2 3'
splitlines (s[, keep_ends])
Split a string into a list of lines. "\r", "\n", and "\r\n" are considered line ends. They are not included in the lines unless keepends is passed. Terminal line end does not produce an extra line. Splitting an empty string results in an empty list.

Parameters:

  • s string the string.
  • keep_ends boolean include line ends. (optional)

Returns:

    List of lines
split (s[, re[, n]])
split a string into a list of strings using a delimiter.

Parameters:

  • s string the string
  • re string a delimiter (defaults to whitespace) (optional)
  • n integer maximum number of results (optional)

Returns:

    List

Usage:

  • #(stringx.split('one two')) == 2
  • stringx.split('one,two,three', ',') == List{'one','two','three'}
  • stringx.split('one,two,three', ',', 2) == List{'one','two,three'}
expandtabs (s, tabsize)
replace all tabs in s with tabsize spaces. If not specified, tabsize defaults to 8. Tab stops will be honored.

Parameters:

  • s string the string
  • tabsize integer [opt=8] number of spaces to expand each tab

Returns:

    expanded string

Usage:

  • stringx.expandtabs('\tone,two,three', 4)   == '    one,two,three'
  • stringx.expandtabs('  \tone,two,three', 4) == '    one,two,three'

Finding and Replacing

lfind (s, sub[, first[, last]])
find index of first instance of sub in s from the left.

Parameters:

  • s string the string
  • sub string substring
  • first integer first index (optional)
  • last integer last index (optional)

Returns:

    start index, or nil if not found
rfind (s, sub[, first[, last]])
find index of first instance of sub in s from the right.

Parameters:

  • s string the string
  • sub string substring
  • first integer first index (optional)
  • last integer last index (optional)

Returns:

    start index, or nil if not found
replace (s, old, new[, n])
replace up to n instances of old by new in the string s. If n is not present, replace all instances.

Parameters:

  • s string the string
  • old string the target substring
  • new string the substitution
  • n integer optional maximum number of substitutions (optional)

Returns:

    result string
count (s, sub[, allow_overlap])
count all instances of substring in string.

Parameters:

  • s string the string
  • sub string substring
  • allow_overlap boolean allow matches to overlap (optional)

Usage:

    assert(stringx.count('banana', 'ana') == 1)
assert(stringx.count('banana', 'ana', true) == 2)

Stripping and Justifying

ljust (s, w[, ch=' '])
left-justify s with width w.

Parameters:

  • s string the string
  • w integer width of justification
  • ch string padding character (default ' ')

Usage:

    stringx.ljust('hello', 10, '*') == '*****hello'
rjust (s, w[, ch=' '])
right-justify s with width w.

Parameters:

  • s string the string
  • w integer width of justification
  • ch string padding character (default ' ')

Usage:

    stringx.rjust('hello', 10, '*') == 'hello*****'
center (s, w[, ch=' '])
center-justify s with width w.

Parameters:

  • s string the string
  • w integer width of justification
  • ch string padding character (default ' ')

Usage:

    stringx.center('hello', 10, '*') == '**hello***'
lstrip (s[, chrs='%s'])
trim any characters on the left of s.

Parameters:

  • s string the string
  • chrs string default any whitespace character, but can be a string of characters to be trimmed (default '%s')
rstrip (s[, chrs='%s'])
trim any characters on the right of s.

Parameters:

  • s string the string
  • chrs string default any whitespace character, but can be a string of characters to be trimmed (default '%s')
strip (s[, chrs='%s'])
trim any characters on both left and right of s.

Parameters:

  • s string the string
  • chrs string default any whitespace character, but can be a string of characters to be trimmed (default '%s')

Usage:

    stringx.strip('  --== Hello ==--  ', "- =")  --> 'Hello'

Partitioning Strings

splitv (s[, re='%s'])
split a string using a pattern. Note that at least one value will be returned!

Parameters:

  • s string the string
  • re string a Lua string pattern (defaults to whitespace) (default '%s')

Returns:

    the parts of the string

See also:

Usage:

    a,b = line:splitv('=')
partition (s, ch)
partition the string using first occurrence of a delimiter

Parameters:

  • s string the string
  • ch string delimiter (match as plain string, no patterns)

Returns:

  1. part before ch
  2. ch
  3. part after ch

Usage:

  • {stringx.partition('a,b,c', ','))} == {'a', ',', 'b,c'}
  • {stringx.partition('abc', 'x'))} == {'abc', '', ''}
rpartition (s, ch)
partition the string p using last occurrence of a delimiter

Parameters:

  • s string the string
  • ch string delimiter (match as plain string, no patterns)

Returns:

  1. part before ch
  2. ch
  3. part after ch

Usage:

  • {stringx.rpartition('a,b,c', ','))} == {'a,b', ',', 'c'}
  • {stringx.rpartition('abc', 'x'))} == {'', '', 'abc'}
at (s, idx)
return the 'character' at the index.

Parameters:

  • s string the string
  • idx integer an index (can be negative)

Returns:

    a substring of length 1 if successful, empty string otherwise.

Text handling

indent (s, n[, ch=' '])
indent a multiline string.

Parameters:

  • s string the (multiline) string
  • n integer the size of the indent
  • ch string the character to use when indenting (default ' ')

Returns:

    indented string
dedent (s)
dedent a multiline string by removing any initial indent. useful when working with [[..]] strings. Empty lines are ignored.

Parameters:

  • s string the (multiline) string

Returns:

    a string with initial indent zero.

Usage:

    local s = dedent [[
         One

       Two

     Three
]]
assert(s == [[
    One

  Two

Three
]])
wrap (s[, width=70[, breaklong=false]])
format a paragraph into lines so that they fit into a line width. It will not break long words by default, so lines can be over the length to that extent.

Parameters:

  • s string the string to format
  • width integer the margin width (default 70)
  • breaklong boolean if truthy, words longer than the width given will be forced split. (default false)

Returns:

    a list of lines (List object), use fill to return a string instead of a List.

See also:

fill (s[, width=70[, breaklong=false]])
format a paragraph so that it fits into a line width.

Parameters:

  • s string the string to format
  • width integer the margin width (default 70)
  • breaklong boolean if truthy, words longer than the width given will be forced split. (default false)

Returns:

    a string, use wrap to return a list of lines instead of a string.

See also:

Template

Template (tmpl)
Creates a new Template class. This is a shortcut to Template.new(tmpl).

Parameters:

  • tmpl string the template string

Returns:

    Template
Template:substitute (tbl)
substitute values into a template, throwing an error. This will throw an error if no name is found.

Parameters:

  • tbl table a table of name-value pairs.

Returns:

    string with place holders substituted
Template:safe_substitute (tbl)
substitute values into a template. This version just passes unknown names through.

Parameters:

  • tbl table a table of name-value pairs.

Returns:

    string with place holders substituted
Template:indent_substitute (tbl)
substitute values into a template, preserving indentation.
If the value is a multiline string or a template, it will insert the lines at the correct indentation.
Furthermore, if a template, then that template will be substituted using the same table.

Parameters:

  • tbl table a table of name-value pairs.

Returns:

    string with place holders substituted

Miscellaneous

lines (s)
return an iterator over all lines in a string

Parameters:

Returns:

    an iterator

Usage:

    local line_no = 1
for line in stringx.lines(some_text) do
  print(line_no, line)
  line_no = line_no + 1
end
title (s)
initial word letters uppercase ('title case'). Here 'words' mean chunks of non-space characters.

Parameters:

Returns:

    a string with each word's first letter uppercase

Usage:

    stringx.title("hello world") == "Hello World")
shorten (s, w, tail)
Return a shortened version of a string. Fits string within w characters. Removed characters are marked with ellipsis.

Parameters:

  • s string the string
  • w integer the maximum size allowed
  • tail boolean true if we want to show the end of the string (head otherwise)

Usage:

  • ('1234567890'):shorten(8) == '12345...'
  • ('1234567890'):shorten(8, true) == '...67890'
  • ('1234567890'):shorten(20) == '1234567890'
quote_string (s)
Quote the given string and preserve any control or escape characters, such that reloading the string in Lua returns the same result.

Parameters:

  • s The string to be quoted.

Returns:

    The quoted string.
format_operator ()
Python-style formatting operator. Calling text.format_operator() overloads the % operator for strings to give Python/Ruby style formatted output. This is extended to also do template-like substitution for map-like data.

Note this goes further than the original, and will allow these cases:

  1. a single value
  2. a list of values
  3. a map of var=value pairs
  4. a function, as in gsub

For the second two cases, it uses $-variable substitution.

When called, this function will monkey-patch the global string metatable by adding a __mod method.

See the lua-users wiki

Usage:

    require 'pl.text'.format_operator()
local out1 = '%s = %5.3f' % {'PI',math.pi}                   --> 'PI = 3.142'
local out2 = '$name = $value' % {name='dog',value='Pluto'}   --> 'dog = Pluto'
import ()
import the stringx functions into the global string (meta)table
generated by LDoc 1.5.0