mix stdlib string - remixlabs/docs-public GitHub Wiki

String functions

module string
  // Primitives
  def empty : string                     // or: ""
  def add : string -> word -> string     // or: s1 + s2
  def length : string -> number
  def fromCodePoint : number -> string
  def codePointAt : string -> number -> number

  // Comparisons
  // (see below)

  // Substrings
  def sub : number -> number -> string -> string   // sub(k_start, k_end, s)
  def indexOfLeft : string -> string -> number     // indexOfLeft(search, s)
  def indexOfLeft_ci : string -> string -> number  // indexOfLeft_ci(search, s)     // since PR1821
  def indexOfRight : string -> string -> number    // indexOfRight(search, s)
  def contains : string -> string -> bool          // contains(search, s)
  def contains_ci : string -> string -> bool       // contains_ci(search, s)        // since PR1821
  def hasPrefix : string -> string -> bool         // hasPrefix(prefix, s)
  def startsWith : string -> string -> bool        // startsWith(s, prefix)  (args swapped)
  def hasSuffix : string -> string -> bool         // hasSuffix(suffix, s)
  def endsWith : string -> string -> bool          // endsWith(s, suffix)   (args swapped)
  def replaceAll : string -> string -> string -> string  // replaceAll(old, new, s)

  // Case
  def uppercase : string -> string
  def lowercase : string -> string
  def capitalize : string -> string

  // Trimming
  def trimLeft : string -> string
  def trimRight : string -> string
  def trim : string -> string

  // split/concat
  def splitSep : string -> string -> array(string)    // splitSep(sep, s)
  def concat : string -> array(string) -> string      // concat(sep, array)
  def concatStream : string -> stream(string) -> string   // since PR1817

  // patterns
  def like : string -> string -> bool     // like(s, pat)
  def rlike : string -> string -> bool    // rlike(pat, s)    (args swapped)

  // JSON
  def parseJSON : string -> data
  def parseJSONResult : string -> result(string, data)
  def parseEscJSON : string -> data
  def parseEscJSONResult : string -> result(string, data)
  def formatJSON : data -> string
  def formatEscJSON : data -> string

  // Token
  def ofToken : token -> string
module end

Immutability

Strings are immutable - you cannot change an existing string.

Unicode

Positions (like in string.sub) are in multiples of Unicode characters (no matter from which Unicode plane). For example, the Unicode character U+1F535 (blue circle) is encoded as just one character, and not as two 16 bit entities (as e.g. in Javascript).

At the moment, there is no restriction regarding surrogate pairs, but we might add that in the future to get a (more) normalized encoding.

Style and undefined

The functions are defined so that the main string is passed last - this makes it easy to chain the functions:

  string.uppercase(s)
  |> string.sub(2, 5)

If any parameter is undefined the result of the function is undefined.

Primitives

  def empty : string                     // or: ""
  def add : string -> word -> string     // or: s1 + s2
  def length : string -> number
  def fromCodePoint : number -> string
  def codePointAt : string -> number -> number
  • string.empty is just the empty string (for symmetry with array.empty, map.empty etc.).
  • string.add(s, w) appends the string or number w to the string and returns the new string.
  • string.length(s) returns the number of characters of s
  • string.fromCodePoint(c): returns a string with a single character that is set to the Unicode code point c
  • string.codePointAt(s, k): returns the code point of the character at position k of s

Comparisons

You can use ==, !=, <, <=, >, >= to compare strings (like other data values).

Since PR1821, there are also case-insensitive string comparisons. The operator symbols have a :ci suffix, e.g.

"hello" ==:ci "HeLlO"

would return true.

Substrings

  def sub : number -> number -> string -> string   // sub(k_start, k_end, s)
  def indexOfLeft : string -> string -> number     // indexOfLeft(search, s)
  def indexOfLeft_ci : string -> string -> number  // indexOfLeft_ci(search, s)     // since PR1821
  def indexOfRight : string -> string -> number    // indexOfRight(search, s)
  def contains : string -> string -> bool          // contains(search, s)
  def contains_ci : string -> string -> bool       // contains_ci(search, s)        // since PR1821
  def hasPrefix : string -> string -> bool         // hasPrefix(prefix, s)
  def startsWith : string -> string -> bool        // startsWith(s, prefix)  (args swapped)
  def hasSuffix : string -> string -> bool         // hasSuffix(suffix, s)
  def endsWith : string -> string -> bool          // endsWith(s, suffix)   (args swapped)
  def replaceAll : string -> string -> string -> string  // replaceAll(old, new, s)
  • string.sub(k_start, k_end, s): returns the substring starting at position k_start and finishing just before k_end
  • string.indexOfLeft(search, s): returns the left-most position of search in s, or undefined
  • string.indexOfLeft_ci: same, but uses case-insensitive comparisons for finding the search string
  • string.indexOfRight(search, s): returns the right-most position of search in s, or undefined
  • string.contains(search, s): returns whether search is in s
  • string.comtains_ci(search, s): same, but uses case-insensitive comparisons for finding the search string
  • string.hasPrefix(prefix, s) or string.startsWith(s, prefix): whether s starts with prefix
  • string.hasSuffix(suffix, s) or string.endsWith(s, suffix): whether s ends with suffix
  • string.replaceAll(old, new, s): replaces all occurrences of old in s with new

Case

  def uppercase : string -> string
  def lowercase : string -> string
  def capitalize : string -> string
  • string.uppercase(s) returns all cased characters turned to uppercase
  • string.lowercase(s) returns all cased characters turned to lowercase
  • string.capitalize(s): the first character is turned to uppercase

Trimming

  def trimLeft : string -> string
  def trimRight : string -> string
  def trim : string -> string

Trim spaces on the left/right/both side(s). All Unicode space characters are recognized.

split/concat

  def splitSep : string -> string -> array(string)    // splitSep(sep, s)
  def concat : string -> array(string) -> string      // concat(sep, array)
  def concatStream : string -> stream(string) -> string   // since PR1817
  • string.splitSep(sep, s): splits the string on separator sep and return the array of strings before/between/after the separators. Special cases:
    • string.splitSep("", ""): is the empty array
    • string.splitSep("", s): splits between each character, i.e. you get an array that is as long as the string has characters, and each array element is set to one character of the string
    • If s does not contain sep, the function returns the one-element array [ s ]
    • If s starts with sep, the first element of the array is the empty string
    • If s ends with sep, the last element of the array is the empty string
  • string.concat(sep, a): concatenates the array elements and puts sep between the elements
  • string.concatStream(sep, s): same for a stream of input strings. This function works well for long, open-ended streams.

Examples:

splitSep("", "abc") == [ "a", "b", "c" ]
splitSep(",", "abc") == [ "abc" ]
splitSep(",", "") == [ "" ]                   // not the empty array!
splitSep(",", "a,b,c") == [ "a", "b", "c" ]
splitSep(",", ",b,c") == [ "", "b", "c" ]
splitSep(",", "a,b,") == [ "a", "b", "" ]

patterns

  def like : string -> string -> bool     // like(s, pat)
  def rlike : string -> string -> bool    // rlike(pat, s)    (args swapped)
  • string.like(s, pat): whether s matches the pattern pat
    • the pattern can contain % characters as wildcards
    • the doule percent "%%" counts as a literal percent character (no wildcard)

Examples:

like("abccba", "ab%ba") == true
like("accba", "ab%ba") == false

JSON

  def parseJSON : string -> data
  def parseJSONResult : string -> result(string, data)
  def parseEscJSON : string -> data
  def parseEscJSONResult : string -> result(string, data)
  def formatJSON : data -> string
  def formatEscJSON : data -> string

We have two parsing/formatting modes:

  • standard JSON
  • JSON with escaping tags
    • formatEscJSON(v) uses the escaping tags when a value is discovered that is not supported in JSON
    • parseEscJSON(s) recognizes the escaping tags in s and restores the value it had before formatting

Token

  def ofToken : token -> string

Many tokens can be converted to strings. Note, however, that tokens carry a permission bitset, and the conversion to string can be disabled, in which case the attempt to run ofToken will cause a runtime error.

⚠️ **GitHub.com Fallback** ⚠️