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
              characters, 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
              specified, 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
              specified, 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
              first such match within  string2.   If  not  found,
              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
              specified 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
              character  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
                        range).

              boolean   Any    of    the    forms    allowed   to
                        Tcl_GetBoolean.

              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
                        whitespace.  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_GetBoolean  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
                        whitespace.  In case of under/overflow in
                        the value, 0 is returned and the  varname
                        will contain -1.

              lower     Any    Unicode    lower   case   alphabet
                        character.

              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_GetBoolean where the value is true.

              upper     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
              characters  in  string.   Note  that  this  is  not
              necessarily 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
              replacements will have  no  affect  for  later  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
              pattern:

              *         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.

       string replace string first last ?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
              modifying.   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
              Unicode 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 (inclusive).  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
              modifying.   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
              then   white   space   is  removed  (spaces,  tabs,
              newlines, 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
              carriage 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
              carriage 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
              contiguous 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)
              characters,  or  any  single  character  other than
              these.


KEYWORDS
       case conversion, compare, index, match,  pattern,  string,
