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

  - 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 whitespace? Matches on pattern '%s' so matches space, newline, tabs, etc.

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

  utils.splitv

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

  - pl.List
  - fill
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:

  wrap

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

  - 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)
  initial 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 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