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 (including
              determining the length of a Tcl ByteArray object).  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  ordinary  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 alphanu-
                          meric character, and any Unicode connector  punctua-
                          tion 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 char-
              acters 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 characters in
              string.  Note that this is not necessarily the same as the  num-
              ber  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? mapping string
              Replaces substrings in string based on the  key-value  pairs  in
              mapping.   mapping  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.

              Note  that if an earlier key is a prefix of a later one, it will
              completely mask the later one.  So if the  previous  example  is
              reordered like this,
                     string map {1 0 ab 2 a 3 abc 1} 1abcaababcabababc
              it will return the string 02c322c222c.

       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.

EXAMPLE
       Test  if the string in the variable string is a proper non-empty prefix
       of the string foobar.
              set length [string length $string]
              if {$length == 0} {
                 set isPrefix 0
              } else {
                 set isPrefix [string equal -length $string $string "foobar"]
              }


SEE ALSO
       expr(n), list(n)


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