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 rep-
              resent  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  rep-
              resentation.

       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  con-
              strained 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  inte-
                        ger  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 char-
              acter classes are recognized (the class  name  can  be  abbrevi-
              ated):

              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 char-
                        acter set.

              wordchar  Any Unicode word character.  That is any  alphanumeric
                        character, and any Unicode connector punctuation char-
                        acters (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  char-
              acters  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 num-
              ber 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, includ-
                        ing 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 consid-
                        ered  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 charac-
                        ters *?[]\ 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 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 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 charac-
              ters 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 charac-
              ters  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.


SEE ALSO
       expr(n), list(n)


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