# Module: `gears.string`

Various string manipulation and introspection fuctions.

## Static module functions

gears.string.xml_escape (text) -> string | Escape a string from XML char. |
gears.string.xml_unescape (text) -> string | Unescape a string from entities. |
gears.string.linecount (text) -> int | Count number of lines in a string. |
gears.string.linewrap (text, width, indent) -> string | Split a string into multiple lines. |
gears.string.quote_pattern (s) -> string | Escape all special pattern-matching characters so that lua interprets them literally instead of as a character class. |
gears.string.query_to_pattern (q) -> string | Generate a pattern matching expression that ignores case. |
gears.string.split (str, delimiter) -> table | Split separates a string containing a delimiter into the list of substrings between that delimiter. |
gears.string.split (str, pattern) -> table | Pattern split separates a string by a pattern to the table of substrings. |
gears.string.startswith (str, sub) -> boolean | Check if a string starts with another string. |
gears.string.endswith (str, sub) -> boolean | Check if a string ends with another string. |

## Static module functions

🔗 gears.string.xml_escape (text) -> string
  Escape a string from XML char. Useful to set raw text in textbox.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  | string | Text to escape.

  ### Returns:

  string Escaped text.
🔗 gears.string.xml_unescape (text) -> string
  Unescape a string from entities.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  | string | Text to unescape.

  ### Returns:

  string Unescaped text.
🔗 gears.string.linecount (text) -> int
  Count number of lines in a string.

  **Usage example output**:

  Count is: 1 Count is: 3

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  | string | Input string.

  ### Returns:

  int Number of lines.

  ### Usage:

      local test = "do.t"
      local res = gears.string.linecount(test)
      print("Count is: " .. res)
      local test2 = "do\nit\nnow"
      local res2 = gears.string.linecount(test2)
      print("Count is: " .. res2)

🔗 gears.string.linewrap (text, width, indent) -> string
  Split a string into multiple lines.

  **Usage example output**:

  do it

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  text |  | string | String to wrap.
  width |  | number | Maximum length of each line. Default: 72.
  indent |  | number | Number of spaces added before each wrapped line. Default: 0.

  ### Returns:

  string The string with lines wrapped to width.

  ### Usage:

      local test = "do it"
      local res = gears.string.linewrap(test, 2, 0)
      print(res)

🔗 gears.string.quote_pattern (s) -> string
  Escape all special pattern-matching characters so that lua interprets them literally instead of as a character class. Source: http://stackoverflow.com/a/20778724/15690

  **Usage example output**:

  do%.it

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  s |  | string | String to generate pattern for

  ### Returns:

  string string with escaped characters

  ### Usage:

      local test = "do.it"
      local res = gears.string.quote_pattern(test)
      print(res)

🔗 gears.string.query_to_pattern (q) -> string
  Generate a pattern matching expression that ignores case.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  q |  | string | Original pattern matching expression.

  ### Returns:

  string The pattern.
🔗 gears.string.split (str, delimiter) -> table
  Split separates a string containing a delimiter into the list of substrings between that delimiter.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  str |  | string | String to be splitted
  delimiter |  | string | Character where the string will be splitted

  ### Returns:

  table list of the substrings
🔗 gears.string.split (str, pattern) -> table
  Pattern split separates a string by a pattern to the table of substrings.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  str |  | string | String to be splitted
  pattern |  | string[opt="\n"] | Pattern the target string will be splitted by.

  ### Returns:

  table A list of substrings.
🔗 gears.string.startswith (str, sub) -> boolean
  Check if a string starts with another string.

  **Usage example output**:

  true false false

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  str |  | string | String to search
  sub |  | string | String to check for.

  ### Returns:

  boolean `true` if string starts with specified string

  ### Usage:

      local test = "do.it"
      local res = gears.string.startswith(test,"do")
      print(tostring(res)) -- Print boolean value
      res = gears.string.startswith(test,"it")
      print(tostring(res)) -- print boolean value
      res = gears.string.startswith(nil,"do")
      print(tostring(res)) -- print boolean value

🔗 gears.string.endswith (str, sub) -> boolean
  Check if a string ends with another string.

  **Usage example output**:

  true false false

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  str |  | string | String to search
  sub |  | string | String to check for.

  ### Returns:

  boolean `true` if string ends with specified string

  ### Usage:

      local test = "do.it"
      local res = gears.string.endswith(test,"it")
      print(tostring(res))
      res = gears.string.endswith(test,"do")
      print(tostring(res))
      res = gears.string.endswith(nil,"it")
      print(tostring(res))

generated by LDoc 1.5.0