🗐 STRING.E for Euphoria 3.1.1


                 Version 1.01, January/10/2018, by Shian Lee.


                             1. Introduction


 This library provides traditional string manipulation routines, for any
 platform. A string is a flat sequence, without any (sub)sequences within it.
 Strings are used extensively and exclusively for any I/O operation.

 Although most of this library routines can manipulate a sequence, not only a
 string-sequence, the term "string" is used in this manual instead of
 "sequence", since the purpose of this library is to focus on traditional
 string manipulation routines. Code examples are given for both cases.

 Note that where speed and efficiency are critical, it might be better to
 write an optimized routine for the task, or to manipulate a string in-line,
 rather then to call a library routine.

 To make sure that a string-sequence is actually passed in and out from a
 routine, you can declare your variables with a string type. See also
 Machine2.e (www.RapidEuphoria.com archive) for a string() type and for other
 string functions such as bin(), oct(), hex(), flatten() and EMPTY.

 Tip: EMPTY, {}, can be useful in some cases for manipulating an unknown
 object type (a single character or a string). For example:

 i = length('x' & EMPTY)    -- i is 1
 i = length("x" & EMPTY)    -- i is 1

 s = trim('x' & EMPTY, WSPACE)     -- s is "x"
 s = trim(" x " & EMPTY, WSPACE)   -- s is "x"


 Disclaimer
 ==========

 Use this library at your own risk. The author will not be responsible for
 any damage or data loss.

 This library is tested on FreeDOS 1.1 operating system. The code or the
 documentation might still contain errors or mistakes.


 In the descriptions below, to indicate what kind of object may be passed in
 and returned, the following prefixes are used:

 x     - a general object (atom or sequence)

 s     - a sequence (...or a string-sequence)

 a     - an atom

 i     - an integer

 fn    - an integer used as a file number

 st    - a string sequence, or single-character atom



                      2. Routines by Application Area


 2.1 String
 ==========

 spc             - return a string of spaces

 chr             - return a string of a repeating character or string

 lset            - left justify a string in a field

 rset            - right justify a string in a field

 mset            - middle justify a string in a field

 quote           - enclose a string with quotation marks

 str             - return a string representation of a number

 val             - convert a string representation of a number to a number

 WSPACE          - a string of white spaces (" \t\n\r")



 2.2 Trimming
 ============

 ltrim           - remove leading characters from a string

 rtrim           - remove trailing characters from a string

 trim            - remove leading and trailing characters from a string



 2.3 Searching
 =============

 rfind           - find an object in a sequence - start searching from the
                   last element (reverse find())

 rfind_from      - find an object in a sequence - start searching from any
                   element number (reverse find_from())

 rmatch          - find a sequence as a slice of another sequence - start
                   searching from the last element (reverse match())

 rmatch_from     - find a sequence as a slice of another sequence - start
                   searching from any element number (reverse match_from())



 2.4 Substring
 =============

 left            - return n leftmost characters in a string

 right           - return n rightmost characters in a string

 left_of         - return leftmost characters in a string before a substring

 right_of        - return rightmost characters in a string after a substring

 mid             - return part of a string

 change          - replace part of a string with another string

 translate       - replace all occurrences of a substring with another string



 2.5 Words (Substrings)
 ======================

 squeeze         - remove characters from a string and straighten up words

 count_words     - return the number of words and characters in a string

 match_words     - search in string to form a sequence of words-locations

 split           - split a string to form a sequence of words

 join            - join a sequence of words to form a string




                   3. Alphabetical Listing of all Routines



 ---------------------------------<change>-----------------------------------

 Syntax:      include string.e
              s2 = change(s1, x, i1, i2)

 Description: Replace i1 characters in string s1 with string x, start at
              index i2.

 Comments:    change() can actually replace, insert, or delete characters in
              string s1.

 Example 1:

              s = change("Euphoria", "**", 0, 1)   -- s is "**Euphoria"

              s = change("Euphoria", "**", 2, 1)   -- s is "**phoria"

              s = change("Euphoria", "**", 4, 3)   -- s is "Eu**ia"

              s = change("Euphoria", "**", 0, 3)   -- s is "Eu**phoria"

              s = change("Euphoria", "**", 0, 12)  -- s is "Euphoria   **"

              s = change("Euphoria", "**", 12, 1)  -- s is "**"

              s = change("Euphoria", "" , 10, 3)   -- s is "Eu"

              s = change("Euphoria", 'U' , 1, 2)   -- s is "EUphoria"


 Example 2:

              s = change({"x", "y", "z"}, "abc", 1, 2)
              -- s is {"x", 'a', 'b', 'c', "z"}

              s = change({"x", "y", "z"}, {"abc"}, 1, 2)
              -- s is {"x", "abc", "z"}


 See Also:    translate, mid, squeeze


 -----------------------------------<chr>------------------------------------

 Syntax:      include string.e
              s = chr(x, i)

 Description: Create a string of length i where each element is x.

 Comments:    When x is an atom this is a shorthand for repeat(x, i).

 Example 1:

              s = chr('*', 5)    -- s is "*****"

              s = chr("<*>", 5)  -- s is "<*><*><*><*><*>"


 Example 2:

              s = chr({"<*>"}, 5)
              -- s is {"<*>","<*>","<*>","<*>","<*>"}


 See Also:    spc, lset
              Euphoria 3.1.1: repeat


 -------------------------------<count_words>--------------------------------

 Syntax:      include string.e
              s3 = count_words(s1, s2)

 Description: Return the number of words (substrings) and characters in string
              s1, using a sequence of delimiters s2 to find the gaps between
              words. s3 will be {number of words, number of characters}.

 Comments:    The number of characters is the sum of the length of all words.

 Example 1:

              s = count_words(" RapidEuphoria.com ", "")
              -- s is {1, 19} -- i.e. entire string is a word

              s = count_words("\t Rapid  Euphoria\r  .   com \n", WSPACE)
              -- s is {4, 17}
              -- i.e. {length({"Rapid", "Euphoria", ".", "com"}),
              --       length("RapidEuphoria.com")}

              s = count_words(" Rapid|| Euphoria||.&&com", "&| ")
              -- s is {4, 17}
              -- i.e. {length({"Rapid", "Euphoria", ".", "com"}),
              --       length("RapidEuphoria.com")}


 Example 2:

              s = count_words({"x", '*', "y", '*', 'z', "abc"}, {'*'})
              -- s is {3, 4}
              -- i.e. {length({{"x"}, {"y"}, {'z', "abc"}}),
              --       1 + 1 + 2}

              s = count_words({"x", "*", "y", "*", 'z', "abc", '@'}, {"*"})
              -- s is {3, 5}
              -- i.e. {length({{"x"}, {"y"}, {'z', "abc", '@'}}),
              --       1 + 1 + 3}


 See Also:    match_words, split, join, squeeze, rmatch, WSPACE
              Euphoria 3.1.1: match, match_from, find, wildcard_match


 ----------------------------------<join>------------------------------------

 Syntax:      include string.e
              s2 = join(s1, x)

 Description: Join a sequence of words (substrings) s1, to form a string s2,
              using character x to fill up the gaps between words.

 Example 1:

              s = join({"Rapid", "Euphoria", '.', "com"}, "")
              -- s is "RapidEuphoria.com"

              s = join({"Rapid", "Euphoria", '.', "com"}, ' ')
              -- s is "Rapid Euphoria . com"

              s = join({"Rapid", "Euphoria", '.', "com"}, "||")
              -- s is "Rapid||Euphoria||.||com"


 Example 2:

              s = join({{"x"}, {"y"}, {'z', "abc"}}, '*')
              -- s is {"x", '*', "y", '*', 'z', "abc"}

              s = join({{"x"}, {"y"}, {'z', "abc"}}, {"*"})
              -- s is {"x", "*", "y", "*", 'z', "abc"}


 See Also:    split, match_words


 ----------------------------------<left>------------------------------------

 Syntax:      include string.e
              s2 = left(s1, i)

 Description: Return i leftmost characters in string s1.

 Example 1:

              s = left("RapidEuphoria", 20)  -- s is "RapidEuphoria"

              s = left("RapidEuphoria", 5)   -- s is "Rapid"

              s = left("RapidEuphoria", 0)   -- s is ""


 Example 2:

              s = left({"x", "y", "z"}, 2)   -- s is {"x", "y"}


 See Also:    right, left_of, mid, change


 --------------------------------<left_of>--------------------------------

 Syntax:      include string.e
              s3 = left_of(s1, s2, i)

 Description: Return leftmost characters in string s1 before a match with
              substring s2. If i is 1 then search forward starting from index
              1. If i is 0 then search backward starting from index length(s1).
              If unsuccessful, return an empty string, "".

 Example 1:

              s = left_of("www.RapidEuphoria.com", "Eup", 1)
              -- s is "www.Rapid"

              s = left_of("www.RapidEuphoria.com", ".", 1)
              -- s is "www"

              s = left_of("www.RapidEuphoria.com", ".", 0)
              -- s is "www.RapidEuphoria"


 Example 2:

              s = left_of({"x", "y", "z"}, {"z"}, 1)
              -- s is {"x", "y"}

              s = left_of({"x", "y", "z", "abc"}, {"z", "abc"}, 1)
              -- s is {"x", "y"}


 See Also:    right_of, left, rmatch, rmatch_from, rfind
              Euphoria 3.1.1: match, match_from, find


 ----------------------------------<lset>------------------------------------

 Syntax:      include string.e
              s2 = lset(s1, i, x)

 Description: Left justify string s1 in a field of length i, using character
              x to fill up the field. The length of s2 will be i.

 Example 1:

              s = lset("RapidEuphoria", 17, ' ')  -- s is "RapidEuphoria    "

              s = lset("RapidEuphoria", 5, ' ')   -- s is "Rapid"

              s = lset("RapidEuphoria", 0, ' ')   -- s is ""


 Example 2:

              s = lset({"x", "y", "z"}, 5, "[]")
              -- s is {"x", "y", "z", "[]", "[]"}


 See Also:    rset, mset, spc, trim, squeeze


 ---------------------------------<ltrim>------------------------------------

 Syntax:      include string.e
              s3 = ltrim(s1, s2)

 Description: Remove leading characters contained in s2, from string s1.

 Example 1:

              s = ltrim("*.*.*... Rapid Euphoria *.*.*...", ".*")
              -- s is " Rapid Euphoria *.*.*..."

              s = ltrim(" \t  Rapid  Euphoria  \r\n", WSPACE)
              -- s is "Rapid  Euphoria  \r\n" -- i.e. remove white spaces


 Example 2:

              s = ltrim({"x", "y", "z", "x"}, {"x"})
              -- s is {"y", "z", "x"}

              s = ltrim({"x", "y", "z", "x"}, {"y", "x"})
              -- s is {"z", "x"}


 See Also:    trim, rtrim, squeeze, WSPACE, lset


 -------------------------------<match_words>--------------------------------

 Syntax:      include string.e
              s3 = match_words(s1, s2)

 Description: Search in string s1, to form a sequence of words-locations
              (substrings-locations) s3, using a sequence of delimiters s2 to
              find the gaps between words.

 Comments:    The difference between match_words() and split() is that
              match_words() returns a sequence of the *location* of all words,
              while split() returns a sequence of all words.

 Example 1:

              s = match_words(" RapidEuphoria.com ", "")
              -- s is {{1, 19}}
              -- i.e. entire string {{start-location, end-location}}

              s = match_words("\t Rapid  Euphoria\r  .   com \n", WSPACE)
              -- s is {{3, 7}, {10, 17}, {21, 21}, {25, 27}}
              -- i.e. locations of {"Rapid", "Euphoria", ".", "com"}

              s = match_words(" Rapid|| Euphoria||.&&com", "&| ")
              -- s is {{2, 6}, {10, 17}, {20, 20}, {23, 25}}
              -- i.e. locations of {"Rapid", "Euphoria", ".", "com"}


 Example 2:

              s = match_words({"x", '*', "y", '*', 'z', "abc"}, {'*'})
              -- s is {{1, 1}, {3, 3}, {5, 6}}
              -- i.e. locations of {{"x"}, {"y"}, {'z', "abc"}}

              s = match_words({"x", '*', "y", '*', 'z', "abc"}, {'*', "x"})
              -- s is {{3, 3}, {5, 6}}
              -- i.e. locations of {{"y"}, {'z', "abc"}}


 See Also:    count_words, split, join, squeeze, rmatch, rfind, WSPACE
              Euphoria 3.1.1: match, match_from, find, wildcard_match


 -----------------------------------<mid>------------------------------------

 Syntax:      include string.e
              s2 = mid(s1, i1, i2)

 Description: Return i1 characters in string s1, start at index i2.

 Example 1:

              s = mid("RapidEuphoria", 2, 6)    -- s is "Eu"

              s = mid("RapidEuphoria", 20, 1)   -- s is "RapidEuphoria"

              s = mid("RapidEuphoria", 20, 30)  -- s is ""

              s = mid("RapidEuphoria", 0, 1)    -- s is ""


 Example 2:

              s = mid({"x", {"y"}, "z"}, 5, 2)    -- s is {{"y"}, "z"}


 See Also:    left, right, change


 ----------------------------------<mset>------------------------------------

 Syntax:      include string.e
              s2 = mset(s1, i, x)

 Description: Middle justify string s1 in a field of length i, using character
              x to fill up the field. The length of s2 will be i.

 Example 1:

              s = mset("RapidEuphoria", 17, ' ')  -- s is "  RapidEuphoria  "

              s = mset("RapidEuphoria", 16, ' ')  -- s is " RapidEuphoria  "

              s = mset("RapidEuphoria", 11, ' ')  -- s is "apidEuphori"

              s = mset("RapidEuphoria", 10, ' ')  -- s is "apidEuphor"

              s = mset("RapidEuphoria", 0, ' ')   -- s is ""


 Example 2:

              s = mset({"x", "y", "z"}, 5, "[]")
              -- s is {"[]", "x", "y", "z", "[]"}


 See Also:    lset, rset, spc, trim


 ----------------------------------<quote>-----------------------------------

 Syntax:      include string.e
              s = quote(x)

 Description: Enclose string x with quotation marks (ASCII 34).

 Example 1:

              s = quote("C:\\Long File Name")
              -- s is "\"C:\\Long File Name\""

              s = quote('X')
              -- s is "\"X\""


 Example 2:

              system("copy " & quote("c:\\Long Name") & " a:\\temp.bak", 2)


 See Also:    trim, left, mset


 ----------------------------------<rfind>-----------------------------------

 Syntax:      include string.e
              i = rfind(x, s)

 Description: Find x as an element of s. If successful, return the index of
              the last element of s that matches. If unsuccessful return 0.
              (i.e. reverse find()).

 Comments:    rfind() is not as fast as find().

 Example 1:

              location = rfind('i', "RapidEuphoria")
              -- location is set to 12

              location = rfind('.', "www.RapidEuphoria.com")
              -- location is set to 18


 Example 2:

              location = rfind({"x", "z"}, {"x", "y", {"x", "z"}, "abc"})
              -- location is set to 3


 See Also:    rfind_from, rmatch, match_words, right_of
              Euphoria 3.1.1: find, find_from, match, compare, wildcard_match


 --------------------------------<rfind_from>--------------------------------

 Syntax:      include string.e
              i1 = rfind_from(x, s, i2)

 Description: Find x as an element of s. Start the search at index i2. If
              successful, return the index of the last element of s that
              matches. If unsuccessful return 0. i2 may have any value from 0
              to the length of s. (i.e. reverse find_from()).

 Comments:    rfind_from() is not as fast as find_from().

 Example 1:

              location = rfind_from('a', "RapidEuphoria", 10)
              -- location is set to 2

              location = rfind_from('.', "www.RapidEuphoria.com", 17)
              -- location is set to 4


 Example 2:

              location = rfind_from({"x", "z"}, {"y", {"x", "z"}, "abc"}, 3)
              -- location is set to 2


 See Also:    rfind, rmatch_from, match_words, right_of
              Euphoria 3.1.1: find, find_from, match, compare, wildcard_match


 ----------------------------------<right>-----------------------------------

 Syntax:      include string.e
              s2 = right(s1, i)

 Description: Return i rightmost characters in string s1.

 Example 1:

              s = right("RapidEuphoria", 20)  -- s is "RapidEuphoria"

              s = right("RapidEuphoria", 8)   -- s is "Euphoria"

              s = right("RapidEuphoria", 0)   -- s is ""


 Example 2:

              s = right({"x", "y", "z"}, 2)   -- s is {"y", "z"}


 See Also:    left, right_of, mid, change, rset


 -------------------------------<right_of>--------------------------------

 Syntax:      include string.e
              s3 = right_of(s1, s2, i)

 Description: Return rightmost characters in string s1 after a match with
              substring s2. If i is 1 then search forward starting from index
              1. If i is 0 then search backward starting from index length(s1).
              If unsuccessful, return an empty string, "".

 Example 1:

              s = right_of("www.RapidEuphoria.com", "Rapid", 1)
              -- s is "Euphoria.com"

              s = right_of("www.RapidEuphoria.com", ".", 1)
              -- s is "RapidEuphoria.com"

              s = right_of("www.RapidEuphoria.com", ".", 0)
              -- s is "com"


 Example 2:

              s = right_of({"x", "y", "z"}, {"x"}, 1)
              -- s is {"y", "z"}

              s = right_of({"x", "y", "z", "abc"}, {"x", "y"}, 1)
              -- s is {"z", "abc"}


 See Also:    left_of, right, rmatch, rmatch_from, rfind
              Euphoria 3.1.1: match, match_from, find


 ---------------------------------<rmatch>-----------------------------------

 Syntax:      include string.e
              i = rmatch(s1, s2)

 Description: Try to match s1 against some slice of s2. If successful, return
              the element number of s2 where the (last) matching slice begins,
              else return 0. (i.e. reverse match()).

 Comments:    rmatch() is not as fast as match().

 Example 1:

              location = rmatch("pho", "Euphoria")
              -- location is set to 3

              location = rmatch(".", "www.RapidEuphoria.com")
              -- location is set to 18


 Example 2:

              location = rmatch({"x", "z"}, {"x", "y", "x", "z", "abc"})
              -- location is set to 3


 See Also:    rmatch_from, rfind, match_words, right_of
              Euphoria 3.1.1: match, match_from, find, compare, wildcard_match


 -------------------------------<rmatch_from>--------------------------------

 Syntax:      include string.e
              i1 = rmatch_from(s1, s2, i2)

 Description: Try to match s1 against some slice of s2, starting from index i2.
              If successful, return the element number of s2 where the (last)
              matching slice begins, else return 0. i2 may have any value from
              0 to the length of s2. (i.e. reverse match_from()).

 Comments:    rmatch_from() is not as fast as match_from().

 Example 1:

              location = rmatch_from("Eup", "EuphoriaEup", 10)
              -- location is set to 1

              location = rmatch_from(".", "www.RapidEuphoria.com", 17)
              -- location is set to 4


 Example 2:

              location = rmatch_from({"x", "z"}, {"y", "x", "z", "abc"}, 3)
              -- location is set to 2


 See Also:    rmatch, rfind_from, match_words, right_of
              Euphoria 3.1.1: match, match_from, find, compare, wildcard_match


 ----------------------------------<rset>------------------------------------

 Syntax:      include string.e
              s2 = rset(s1, i, x)

 Description: Right justify string s1 in a field of length i, using character
              x to fill up the field. The length of s2 will be i.

 Example 1:

              s = rset("RapidEuphoria", 17, ' ')  -- s is "    RapidEuphoria"

              s = rset("RapidEuphoria", 8, ' ')   -- s is "Euphoria"

              s = rset("RapidEuphoria", 0, ' ')   -- s is ""


 Example 2:

              s = rset({"x", "y", "z"}, 5, "[]")
              -- s is {"[]", "[]", "x", "y", "z"}


 See Also:    lset, mset, spc, trim, squeeze


 ---------------------------------<rtrim>------------------------------------

 Syntax:      include string.e
              s3 = rtrim(s1, s2)

 Description: Remove trailing characters contained in s2, from string s1.

 Example 1:

              s = rtrim("*.*.*... Rapid Euphoria *.*.*...", ".*")
              -- s is "*.*.*... Rapid Euphoria "

              s = rtrim(" \t  Rapid  Euphoria  \r\n", WSPACE)
              -- s is " \t  Rapid  Euphoria" -- i.e. remove white spaces


 Example 2:

              s = rtrim({"x", "y", "z", "x"}, {"x"})
              -- s is {"x", "y", "z"}

              s = rtrim({"x", "y", "z", "x"}, {"x", "z"})
              -- s is {"x", "y"}


 See Also:    trim, ltrim, squeeze, WSPACE, rset


 -----------------------------------<spc>------------------------------------

 Syntax:      include string.e
              s = spc(i)

 Description: Create a string of i spaces (ASCII 32).

 Comments:    This is a shorthand for repeat(32, i)

 Example:

              s = spc(5)  -- s is "     "


 See Also:    chr, lset, trim
              Euphoria 3.1.1: repeat


 ----------------------------------<split>-----------------------------------

 Syntax:      include string.e
              s3 = split(s1, s2)

 Description: Split string s1 to form a sequence of words (substrings) s3,
              using a sequence of delimiters s2 to find the gaps between
              words.

 Example 1:

              s = split(" RapidEuphoria.com ", "")
              -- s is {" RapidEuphoria.com "}

              s = split("\t Rapid  Euphoria\r  .   com \n", WSPACE)
              -- s is {"Rapid", "Euphoria", ".", "com"}

              s = split(" Rapid|| Euphoria||.&&com", "&| ")
              -- s is {"Rapid", "Euphoria", ".", "com"}


 Example 2:

              s = split({"x", '*', "y", '*', 'z', "abc"}, {'*'})
              -- s is {{"x"}, {"y"}, {'z', "abc"}}

              s = split({"x", '*', "y", '*', 'z', "abc"}, {"y", '*'})
              -- s is {{"x"}, {'z', "abc"}}


 See Also:    join, match_words, count_words, squeeze, rmatch, rfind, WSPACE
              Euphoria 3.1.1: match, find


 ---------------------------------<squeeze>----------------------------------

 Syntax:      include string.e
              s3 = squeeze(s1, s2, x)

 Description: Squeeze (remove) characters contained in s2, from string s1,
              using character x to fill up the gaps between words.

 Comments:    squeeze() is similar to trim() but it also removes characters
              between words (substrings) and replace them with character (or
              string) x.

 Example 1:

              s = squeeze("*.*.* Rapid*.*.*Euphoria *.*.*", ".*", ' ')
              -- s is " Rapid Euphoria "

              s = squeeze(" \t  Rapid \n  Euphoria  \r\n", WSPACE, "__")
              -- s is "Rapid__Euphoria" -- i.e. squeeze white spaces


 Example 2:

              s = squeeze({"x", "y", "x", "z", "x"}, {"x"}, "<>")
              -- s is {"y", '<', '>', "z"}

              s = squeeze({"x", "y", "x", "z", "x"}, {"x"}, {"<>"})
              -- s is {"y", "<>", "z"}

              s = squeeze({"x", "y", "x", "z", "x"}, {"x", "z"}, {"<>"})
              -- s is {"y"}


 See Also:    trim, ltrim, rtrim, translate, WSPACE, split, match_words


 -----------------------------------<str>------------------------------------

 Syntax:      include string.e
              s = str(x)

 Description: Return a string representation of the number x.

 Comments:    This is a shorthand for sprint(x).

              The atoms contained within x will be displayed to a maximum of
              10 significant digits, just as with print().

 Example 1:

              s = str(-12345.99)
              -- s is "-12345.99"

              s = str(-12345678999)
              -- s is "-1.2345679e+010"

              s = str(#FF)
              -- s is "255"


 Example 2:

              s = str({10,20,30}+5)
              -- s is "{15,25,35}"


 See Also:    val
              Euphoria 3.1.1: sprint, print, sprintf, value, get


 --------------------------------<translate>---------------------------------

 Syntax:      include string.e
              s4 = translate(s1, s2, s3)

 Description: Replace all occurrences of substring s2, in string s1, with
              another string s3.

 Comments:    translate() can actually replace or delete substrings in string
              s1.

 Example 1:

              s = translate("*.*.* Rapid*.*.*Euphoria *.*.*", "*.*.*", "")
              -- s is " RapidEuphoria "

              s = translate("abc abcd abcde abcdefab", "ab", "~AB~")
              -- s is "~AB~c ~AB~cd ~AB~cde ~AB~cdef~AB~"

              s = translate("xxxxxxx.xx", "xx", "*")
              -- s is "***x.*"


 Example 2:

              s = translate({"x", "y", "x", "z", "x"}, {"x"}, "[]")
              -- s is {'[',']', "y", '[',']', "z", '[',']'}

              s = translate({"x", "y", "x", "z", "x"}, {"x"}, {"[]"})
              -- s is {"[]", "y", "[]", "z", "[]"}

              s = translate({"x", "y", "x", "z", "x"}, {"x", "z"}, {"<>"})
              -- s is {"x", "y", "<>", "x"}


 See Also:    change, mid, rmatch, rmatch_from, rfind, squeeze
              Euphoria 3.1.1: match, match_from, find


 ----------------------------------<trim>------------------------------------

 Syntax:      include string.e
              s3 = trim(s1, s2)

 Description: Remove leading and trailing characters contained in s2, from
              string s1.

 Example 1:

              s = trim("*.*.*... Rapid Euphoria *.*.*...", ".*")
              -- s is " Rapid Euphoria "

              s = trim(" \t  Rapid  Euphoria  \r\n", WSPACE)
              -- s is "Rapid  Euphoria" -- i.e. remove white spaces


 Example 2:

              s = trim({"x", "y", "z", "x"}, {"x"})
              -- s is {"y", "z"}

              s = trim({"x", "y", "z", "x"}, {"x", "z"})
              -- s is {"y"}


 See Also:    ltrim, rtrim, squeeze, translate, WSPACE, mset, spc


 -----------------------------------<val>------------------------------------

 Syntax:      include string.e
              x = val(s)

 Description: Convert a string representation of the number s, to a number.
              s must be a string-sequence.

 Comments:    This is a shorthand for value(s).

 Example 1:

              a = val("12345.99")
              -- a is 12345.99

              a = val("-1.2345679e+010")
              -- a is -1.2345679e+010

              a = val("#FF")
              -- a is 255

              a = val("+++")
              -- a is 0


 Example 2:

              s = val("{0, 1, -99.9}")
              -- s is {0, 1, -99.9}


 See Also:    str
              Euphoria 3.1.1: value, get, sprint, sprintf, print


 ----------------------------------<WSPACE>----------------------------------

 Syntax:      include string.e
              WSPACE

 Description: WSPACE (" \t\n\r") has been defined as a global constant.

 Comments:    WSPACE is a string of white space characters, i.e. space,
              horizontal-tabulation (tab), line-feed and carriage-return (new-
              line characters). (or ASCII 32, 9, 10, 13).

 Example 1:

              x = WSPACE  -- x is " \t\n\r" -- i.e. {32, 9, 10, 13}


 Example 2:

              s = trim(" \t  < Rapid Euphoria >  \r\n", WSPACE)
              -- s is "< Rapid Euphoria >" -- i.e. trim white spaces


 See Also:    trim, ltrim, squeeze, split, count_words