Penlight Documentation

# 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

## 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 spaces?
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 whitespace on the left of s.
rstrip (s[, chrs='%s']) | trim any whitespace on the right of s.
strip (s[, chrs='%s']) | trim any whitespace on both left and right of s.

## Partioning Strings

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

## Miscelaneous

lines (s) | return an iterator over all lines in a string
title (s) | inital 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.

## String Predicates

isalpha (s)
  does s only contain alphabetic characters?

  ### Parameters:

  - s string a string
isdigit (s)
  does s only contain digits?

  ### Parameters:

  - s string a string
isalnum (s)
  does s only contain alphanumeric characters?

  ### Parameters:

  - s string a string
isspace (s)
  does s only contain spaces?

  ### Parameters:

  - s string a string
islower (s)
  does s only contain lower case characters?

  ### Parameters:

  - s string a string
isupper (s)
  does s only contain upper case characters?

  ### Parameters:

  - s string a string
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 bool 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 int 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 int [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 int first index (optional)
  - last int 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 int first index (optional)
  - last int 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 int 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 bool 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 int 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 int 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 int width of justification
  - ch string padding character (default ' ')

  ### Usage:

      stringx.center('hello', 10, '*') == '**hello***'

lstrip (s[, chrs='%s'])
  trim any whitespace 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 whitespace 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 whitespace 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')

## Partioning 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:

  utils.splitv

  ### Usage:

      a,b = line:splitv('=')

partition (s, ch)
  partition the string using first occurance of a delimiter

  ### Parameters:

  - s string the string
  - ch string delimiter

  ### 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 occurance of a delimiter

  ### Parameters:

  - s string the string
  - ch string delimiter

  ### 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 int an index (can be negative)

  ### Returns:

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

## Miscelaneous

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

  ### Parameters:

  - s string the string

  ### 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)
  inital word letters uppercase ('title case'). Here 'words' mean chunks of non-space characters.

  ### Parameters:

  - s string the string

  ### 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 int the maxinum size allowed
  - tail bool 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.

generated by LDoc 1.4.6