# 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 (self, s2) | does string start with the substring?.
endswith (s, send) | does string end with the given substring?.

## Strings and Lists

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

## Finding and Replacing

lfind (self, sub, i1) | find index of first instance of sub in s from the left.
rfind (self, 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 (self, sub) | count all instances of substring in string.

## Stripping and Justifying

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

## Partioning Strings

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

## Miscelaneous

lines (self) | return an interator over all lines in a string
title (self) | iniital word letters uppercase ('title case').
shorten (self, sz, tail) | return a shorted 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 (self, s2)
  does string start with the substring?.

  ### Parameters:

  - self string the string
  - s2 string a string
endswith (s, send)
  does string end with the given substring?.

  ### Parameters:

  - s string a string
  - send a substring or a table of suffixes

## Strings and Lists

join (self, seq)
  concatenate the strings using this string as a delimiter.

  ### Parameters:

  - self string the string
  - seq a table of strings or numbers

  ### Usage:

      (' '):join {1,2,3} == '1 2 3'

splitlines (self, keepends)
  break string into a list of lines

  ### Parameters:

  - self string the string
  - keepends (currently not used)
split (self[, re], n)
  split a string into a list of strings using a delimiter.

  ### Parameters:

  - self string the string
  - re string a delimiter (defaults to whitespace) (optional)
  - n int maximum number of results

  ### Usage:

  -     #(('one two'):split()) == 2

  -     ('one,two,three'):split(',') == List{'one','two','three'}

  -     ('one,two,three'):split(',',2) == List{'one','two,three'}

expandtabs (self, n)
  replace all tabs in s with n spaces. If not specified, n defaults to 8. with 0.9.5 this now correctly expands to the next tab stop (if you really want to just replace tabs, use :gsub('\t',' ') etc)

  ### Parameters:

  - self string the string
  - n int number of spaces to expand each tab, (default 8)

## Finding and Replacing

lfind (self, sub, i1)
  find index of first instance of sub in s from the left.

  ### Parameters:

  - self string the string
  - sub string substring
  - i1 int start index
rfind (self, sub, first, last)
  find index of first instance of sub in s from the right.

  ### Parameters:

  - self string the string
  - sub string substring
  - first int first index
  - last int last index
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:

  1. result string
  2. the number of substitutions
count (self, sub)
  count all instances of substring in string.

  ### Parameters:

  - self string the string
  - sub string substring

## Stripping and Justifying

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

  ### Parameters:

  - self string the string
  - w int width of justification
  - ch string padding character (default '')
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 '')
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 '')
lstrip (self[, chrs='%x'])
  trim any whitespace on the left of s.

  ### Parameters:

  - self string the string
  - chrs string default any whitespace character, but can be a string of characters to be trimmed (default '%x')
rstrip (s[, chrs='%x'])
  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 '%x')
strip (self[, chrs='%x'])
  trim any whitespace on both left and right of s.

  ### Parameters:

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

## Partioning Strings

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

  ### Parameters:

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

  ### Returns:

  the parts of the string

  ### Usage:

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

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

  ### Parameters:

  - self string the string
  - ch string delimiter

  ### Returns:

  1. part before ch
  2. ch
  3. part after ch
rpartition (self, ch)
  partition the string p using last occurance of a delimiter

  ### Parameters:

  - self string the string
  - ch string delimiter

  ### Returns:

  1. part before ch
  2. ch
  3. part after ch
at (self, idx)
  return the 'character' at the index.

  ### Parameters:

  - self string the string
  - idx int an index (can be negative)

  ### Returns:

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

## Miscelaneous

lines (self)
  return an interator over all lines in a string

  ### Parameters:

  - self string the string

  ### Returns:

  an iterator
title (self)
  iniital word letters uppercase ('title case'). Here 'words' mean chunks of non-space characters.

  ### Parameters:

  - self string the string

  ### Returns:

  a string with each word's first letter uppercase
shorten (self, sz, tail)
  return a shorted version of a string.

  ### Parameters:

  - self string the string
  - sz int the maxinum size allowed
  - tail bool true if we want to show the end of the string (head otherwise)
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.3 Last updated Tue, 18 Aug 2015 11:21:53 +0200