NAME

       string - Manipulate strings


SYNOPSIS

       string option arg ?arg ...?
_________________________________________________________________


DESCRIPTION

       Performs  one  of  several string operations, depending on
       option.  The legal options (which may be abbreviated) are: |

       string bytelength                                          |
              string                                          |   |
              Returns a decimal string giving the number of bytes |
              used  to represent string in memory.  Because UTF-8 |
              uses one to three bytes to represent Unicode  char­ |
              acters, the byte length will not be the same as the |
              character length in general.   The  cases  where  a |
              script  cares  about  the byte length are rare.  In |
              almost all cases, you should use the string  length |
              operation.   Refer  to  the  Tcl_NumUtfChars manual |
              entry for more details on the UTF-8 representation. |

       string compare ?-nocase? ?-length int? string1             |
              string2            |                                |
              Perform  a  character-by-character  comparison   of
              strings  string1 and string2.  Returns -1, 0, or 1,
              depending on whether string1  is  lexicographically
              less  than,  equal to, or greater than string2.  If |
              -length is specified, then only  the  first  length |
              characters  are used in the comparison.  If -length |
              is negative, it is ignored.  If -nocase  is  speci­ |
              fied,  then  the  strings  are  compared in a case- |
              insensitive manner.                                 |

       string equal ?-nocase? ?-length int? string1               |
              string2              |                              |
              Perform   a  character-by-character  comparison  of |
              strings string1 and string2.  Returns 1 if  string1 |
              and  string2  are  identical,  or  0  when not.  If |
              -length is specified, then only  the  first  length |
              characters  are used in the comparison.  If -length |
              is negative, it is ignored.  If -nocase  is  speci­ |
              fied,  then  the  strings  are  compared in a case- |
              insensitive manner.                                 |

       string first string1 string2                               |
              ?startIndex?                         |              |
              Search  string2  for  a sequence of characters that
              exactly match the characters in string1.  If found,
              return  the  index  of  the  first character in the

              return  -1.   If startIndex is specified (in any of |
              the forms accepted by the index method),  then  the |
              search  is  constrained to start with the character |
              in string2 specified by the index.  For example,    |
                     string first a 0a23456789abcdef 5            |
              will return 10, but                                 |
                     string first a 0123456789abcdef 11           |
              will return -1.                                     |

       string index string charIndex
              Returns the charIndex'th character  of  the  string
              argument.   A  charIndex  of  0  corresponds to the
              first character of the string.   charIndex  may  be |
              specified as follows:                               |

              integer                                                           ||
                        The char specified at this integral index |

              end                                                               ||
                        The last char of the string.              |

              end-integer                                                       ||
                        The  last  char  of  the string minus the |
                        specified  integer  offset  (e.g.   end-1 |
                        would refer to the "c" in "abcd").        |

              If  charIndex  is  less  than  0 or greater than or
              equal to the length of the  string  then  an  empty
              string is returned.                                 |

       string is class ?-strict? ?-failindex varname?             |
              string             |                                |
              Returns 1 if string is a valid member of the speci­ |
              fied  character  class,  otherwise  returns  0.  If |
              -strict is specified, then an empty string  returns |
              0,  otherwise and empty string will return 1 on any |
              class.  If -failindex is  specified,  then  if  the |
              function  returns  0, the index in the string where |
              the class was no longer valid will be stored in the |
              variable  named  varname.   The varname will not be |
              set if the function returns 1.  The following char­ |
              acter classes are recognized (the class name can be |
              abbreviated):                                       |

              alnum                                                             ||
                        Any  Unicode alphabet or digit character. |

              alpha                                                             ||
                        Any Unicode alphabet character.           |

              ascii                                                             ||
                        Any character  with  a  value  less  than |
                        \u0080 (those that are in the 7-bit ascii |


              boolean                                                           ||
                        Any  of  the  forms  allowed  to Tcl_Get­ |
                        Boolean.                                  |

              control                                                           ||
                        Any Unicode control character.            |

              digit                                                             ||
                        Any Unicode digit character.   Note  that |
                        this  includes  characters outside of the |
                        [0-9] range.                              |

              double                                                            ||
                        Any  of  the  valid forms for a double in |
                        Tcl, with  optional  surrounding  whites­ |
                        pace.   In  case of under/overflow in the |
                        value, 0 is returned and the varname will |
                        contain -1.                               |

              false                                                             ||
                        Any of  the  forms  allowed  to  Tcl_Get­ |
                        Boolean where the value is false.         |

              graph                                                             ||
                        Any Unicode  printing  character,  except |
                        space.                                    |

              integer                                                           ||
                        Any of the valid forms for an integer  in |
                        Tcl,  with  optional  surrounding whites­ |
                        pace.  In case of under/overflow  in  the |
                        value, 0 is returned and the varname will |
                        contain -1.                               |

              lower                                                             ||
                        Any  Unicode  lower case alphabet charac­ |
                        ter.                                      |

              print                                                             ||
                        Any Unicode printing character, including |
                        space.                                    |

              punct                                                             ||
                        Any Unicode punctuation character.        |

              space                                                             ||
                        Any Unicode space character.              |

              true                                                              ||
                        Any  of  the  forms  allowed  to Tcl_Get­ |
                        Boolean where the value is true.          |

                        Any  upper case alphabet character in the |
                        Unicode character set.                    |

              wordchar                                                          ||
                        Any  Unicode word character.  That is any |
                        alphanumeric character, and  any  Unicode |
                        connector  punctuation  characters  (e.g. |
                        underscore).                              |

              xdigit                                                            ||
                        Any     hexadecimal    digit    character |
                        ([0-9A-Fa-f]).                            |

              In the case of boolean,  true  and  false,  if  the |
              function  will  return  0,  then  the  varname will |
              always be set to 0, due to the varied nature  of  a |
              valid boolean value.                                |

       string last string1 string2                                |
              ?startIndex?                          |             |
              Search string2 for a sequence  of  characters  that
              exactly match the characters in string1.  If found,
              return the index of the first character in the last
              such  match  within string2.  If there is no match,
              then return -1.  If startIndex is specified (in any |
              of  the  forms  accepted by the index method), then |
              only the characters in string2  at  or  before  the |
              specified  startIndex  will  be  considered  by the |
              search.  For example,                               |
                     string last a 0a23456789abcdef 15            |
              will return 10, but                                 |
                     string last a 0a23456789abcdef 9             |
              will return 1.                                      |

       string length string
              Returns a decimal string giving the number of char­
              acters  in string.  Note that this is not necessar­
              ily the same as the number of bytes used  to  store
              the string.                                         |

       string map ?-nocase? charMap                               |
              string                               |              |
              Replaces characters in string  based  on  the  key- |
              value  pairs  in charMap.  charMap is a list of key |
              value key value ...  as in  the  form  returned  by |
              array  get.   Each  instance of a key in the string |
              will be replaced with its corresponding value.   If |
              -nocase is specified, then matching is done without |
              regard to case differences. Both key and value  may |
              be  multiple characters.  Replacement is done in an |
              ordered manner, so the key appearing first  in  the |
              list  will  be checked first, and so on.  string is |
              only   iterated   over   once,   so   earlier   key |

              matches.  For example,                              |
                     string map {abc 1 ab 2 a 3 1 0} 1abcaababcabababc|
              will return the string 01321221.                    |

       string match ?-nocase? pattern                             |
              string                             |                |
              See if pattern matches string; return 1 if it does,
              0 if it doesn't.  If -nocase is specified, then the |
              pattern  attempts  to match against the string in a |
              case insensitive manner.  For the  two  strings  to
              match, their contents must be identical except that
              the following special sequences may appear in  pat­
              tern:

              *         Matches  any  sequence  of  characters in
                        string, including a null string.

              ?         Matches any single character in string.

              [chars]   Matches any character in the set given by
                        chars.   If  a  sequence  of the form x-y
                        appears  in  chars,  then  any  character
                        between  x  and y, inclusive, will match. |
                        When used with -nocase, the end points of |
                        the  range  are  converted  to lower case |
                        first.  Whereas {[A-z]} matches '_'  when |
                        matching   case-sensitively   ('_'  falls |
                        between the 'Z' and  'a'),  with  -nocase |
                        this  is  considered like {[A-Za-z]} (and |
                        probably what  was  meant  in  the  first |
                        place).

              \x        Matches  the  single  character  x.  This
                        provides a way of  avoiding  the  special
                        interpretation of the characters *?[]\ in
                        pattern.

       string range string first last
              Returns a  range  of  consecutive  characters  from
              string,  starting with the character whose index is
              first and ending with the character whose index  is
              last.  An  index of 0 refers to the first character |
              of the string.  first and last may be specified  as |
              for  the  index method.  If first is less than zero
              then it is treated as if it were zero, and if  last
              is  greater  than  or  equal  to  the length of the
              string then it is treated as if it  were  end.   If
              first  is greater than last then an empty string is
              returned.                                           |

       string repeat string                                       |
              count                                        |      |
              Returns string repeated count number of times.      |

              ?newstring?                      |                  |
              Removes a  range  of  consecutive  characters  from |
              string,  starting with the character whose index is |
              first and ending with the character whose index  is |
              last.   An index of 0 refers to the first character |
              of the string.  First and last may be specified  as |
              for  the  index method.  If newstring is specified, |
              then it is placed in the removed  character  range. |
              If first is less than zero then it is treated as if |
              it were zero, and if last is greater than or  equal |
              to  the  length of the string then it is treated as |
              if it were end.  If first is greater than  last  or |
              the  length  of the initial string, or last is less |
              than  0,  then  the  initial  string  is   returned |
              untouched.                                          |

       string tolower string ?first?                              |
              ?last?                              |               |
              Returns a value equal to  string  except  that  all |
              upper  (or  title) case letters have been converted |
              to lower case.  If first is specified, it refers to |
              the first char index in the string to start modify­ |
              ing.  If last is specified, it refers to  the  char |
              index  in the string to stop at (inclusive).  first |
              and last may be specified as for the index  method. |

       string totitle string ?first?                              |
              ?last?                              |               |
              Returns a value equal to  string  except  that  the |
              first  character in string is converted to its Uni­ |
              code title case variant (or upper case if there  is |
              no  title  case variant) and the rest of the string |
              is converted to lower case.  If first is specified, |
              it  refers to the first char index in the string to |
              start modifying.  If last is specified,  it  refers |
              to  the char index in the string to stop at (inclu­ |
              sive).  first and last may be specified as for  the |
              index method.                                       |

       string toupper string ?first?                              |
              ?last?                              |               |
              Returns a value equal to  string  except  that  all |
              lower  (or  title) case letters have been converted |
              to upper case.  If first is specified, it refers to |
              the first char index in the string to start modify­ |
              ing.  If last is specified, it refers to  the  char |
              index  in the string to stop at (inclusive).  first |
              and last may be specified as for the index  method.

       string trim string ?chars?
              Returns  a  value  equal  to string except that any
              leading or trailing characters from the  set  given
              by  chars  are  removed.  If chars is not specified

              lines, and carriage returns).

       string trimleft string ?chars?
              Returns  a  value  equal  to string except that any
              leading characters from the set given by chars  are
              removed.   If  chars  is  not  specified then white
              space is removed (spaces, tabs, newlines, and  car­
              riage returns).

       string trimright string ?chars?
              Returns  a  value  equal  to string except that any
              trailing characters from the set given by chars are
              removed.   If  chars  is  not  specified then white
              space is removed (spaces, tabs, newlines, and  car­
              riage returns).                                     |

       string wordend string                                      |
              charIndex                                   |       |
              Returns the index of the character just  after  the |
              last one in the word containing character charIndex |
              of string.  charIndex may be specified as  for  the |
              index  method.  A word is considered to be any con­ |
              tiguous range of alphanumeric (Unicode  letters  or |
              decimal  digits)  or  underscore (Unicode connector |
              punctuation) characters, or  any  single  character |
              other than these.                                   |

       string wordstart string                                    |
              charIndex                                 |         |
              Returns the index of the  first  character  in  the |
              word  containing  character  charIndex  of  string. |
              charIndex may be specified as for the index method. |
              A  word is considered to be any contiguous range of |
              alphanumeric (Unicode letters or decimal digits) or |
              underscore  (Unicode connector punctuation) charac­ |
              ters, or any single character other than these.


SEE ALSO

       expr(n), list(n)


KEYWORDS

       case conversion, compare, index, match,  pattern,  string,
       word, equal, ctype


Man(1) output converted with man2html