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
              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 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
                        range).

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

              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 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  replace-
              ments  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 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.

       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 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
              then white space is  removed  (spaces,  tabs,  new-
              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
