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 (including determining the  length  of  a
              Tcl  ByteArray  object).   Refer  to the Tcl_NumUt-
              fChars 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  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 a 32-bit inte-
                        ger 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_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 ?lastIndex?
              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 lastIndex is specified (in  any
              of  the  forms  accepted by the index method), then
              only the characters in string2  at  or  before  the
              specified  lastIndex  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.   If  the object is a ByteArray object
              (such as  those  returned  from  reading  a  binary
              encoded  channel), then this will return the actual
              byte length of the object.

       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,
