Seth Woolley's Man Viewer

Manual for string - man n string

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

string(3,n)(n)                    Tcl Built-In Commands                   string(3,n)(n)



NAME
       string(3,n) - Manipulate strings

SYNOPSIS
       string(3,n) option arg ?arg ...?


DESCRIPTION
       Performs  one  of  several string(3,n) operations, depending on option.  The
       legal options (which may be abbreviated) are:

       string(3,n) bytelength string(3,n)
              Returns a decimal string(3,n) giving the number of bytes used to rep-
              resent  string(3,n) in(1,8) 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(1,8) general.  The cases where a
              script cares about the byte length  are  rare.   In  almost  all
              cases,  you  should  use  the string(3,n) 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(3,n) 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(1,3)  than,  equal  to,  or  greater  than
              string2.   If  -length  is specified, then only the first length
              characters are used in(1,8) the comparison.  If -length is  negative,
              it  is  ignored.   If -nocase is specified, then the strings are
              compared in(1,8) a case-insensitive manner.

       string(3,n) equal ?-nocase? ?-length int? string1 string2
              Perform a character-by-character comparison of  strings  string1
              and string2.  Returns 1 if(3,n) string1 and string2 are identical, or
              0 when not.  If -length is specified, then only the first length
              characters  are used in(1,8) the comparison.  If -length is negative,
              it is ignored.  If -nocase is specified, then  the  strings  are
              compared in(1,8) a case-insensitive manner.

       string(3,n) first string1 string2 ?startIndex?
              Search  string2  for a sequence of characters that exactly match
              the characters in(1,8) string1.  If found, return the  index  of  the
              first  character in(1,8) the first such match within string2.  If not
              found, return -1.  If startIndex is specified  (in(1,8)  any  of  the
              forms  accepted  by  the  index method), then the search is con-
              strained to start with the character in(1,8) string2 specified by the
              index.  For example,
              string(3,n)  first  a  0a23456789abcdef  5 will return 10, but string(3,n)
              first a 0123456789abcdef 11 will return -1.

       string(3,n) index string(3,n) charIndex
              Returns the charIndex'th character of the  string(3,n)  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(3,n) minus the specified  inte-
                        ger  offset  (e.g.  end-1  would  refer  to the "c" in(1,8)
                        "abcd").

              If charIndex is less(1,3) than 0 or greater  than  or  equal  to  the
              length of the string(3,n) then an empty string(3,n) is returned.

       string(3,n) is class ?-strict? ?-failindex varname? string(3,n)
              Returns 1 if(3,n) string(3,n) is a valid member of the specified character
              class, otherwise returns 0.  If -strict is  specified,  then  an
              empty string(3,n) returns 0, otherwise and empty string(3,n) will return 1
              on any class.  If -failindex is specified, then if(3,n) the  function
              returns 0, the index in(1,8) the string(3,n) where the class was no longer
              valid will be stored in(1,8) the variable named(5,8) varname.  The varname
              will  not be set(7,n,1 builtins) if(3,n) 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(1,7)     Any  character  with  a  value less(1,3) than \u0080 (those
                        that are in(1,8) the 7-bit ascii(1,7) 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(1,8) Tcl, with
                        optional   surrounding   whitespace.    In   case   of
                        under/overflow  in(1,8)  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 a 32-bit integer in(1,8) Tcl,
                        with optional  surrounding  whitespace.   In  case  of
                        under/overflow  in(1,8)  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(1,8) 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(3,n)  the  function  will
              return  0,  then the varname will always be set(7,n,1 builtins) to 0, due to the
              varied nature of a valid boolean value.

       string(3,n) last string1 string2 ?lastIndex?
              Search string2 for a sequence of characters that  exactly  match
              the  characters  in(1,8)  string1.  If found, return the index of the
              first character in(1,8) the last such match within string2.  If there
              is  no match, then return -1.  If lastIndex is specified (in(1,8) any
              of the forms accepted by the index method), then only the  char-
              acters  in(1,8)  string2 at or before the specified lastIndex will be
              considered by the search.  For example,
              string(3,n) last a 0a23456789abcdef 15 will  return  10,  but  string(3,n)
              last a 0a23456789abcdef 9 will return 1.

       string(3,n) length string(3,n)
              Returns  a  decimal  string(3,n)  giving  the number of characters in(1,8)
              string(3,n).  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(3,n) map ?-nocase? charMap string(3,n)
              Replaces characters in(1,8) string(3,n) based on the  key-value  pairs  in(1,8)
              charMap.   charMap  is  a list of key value key value ...  as in(1,8)
              the form returned by array get.  Each instance of a key  in(1,8)  the
              string(3,n)  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(1,8) an ordered manner, so the  key  appearing
              first  in(1,8)  the list will be checked first, and so on.  string(3,n) is
              only iterated over once, so earlier key replacements  will  have
              no affect for later key matches.  For example,
              string(3,n)  map  {abc  1 ab 2 a 3 1 0} 1abcaababcabababc will return
              the string(3,n) 01321221.

       string(3,n) match ?-nocase? pattern string(3,n)
              See if(3,n) pattern matches string(3,n); return 1 if(3,n)  it  does,  0  if(3,n)  it
              doesn't.   If -nocase is specified, then the pattern attempts to
              match against the string(3,n) in(1,8) a case insensitive manner.  For  the
              two  strings  to  match, their contents must be identical except
              that the following special sequences may appear in(1,8) pattern:

              *         Matches any sequence of characters in(1,8) string(3,n),  includ-
                        ing a null string.

              ?         Matches any single character in(1,8) string(3,n).

              [chars]   Matches any character in(1,8) the set(7,n,1 builtins) given by chars.  If a
                        sequence of the form x-y appears in(1,8)  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(1,8)
                        the first place).

              \x        Matches  the  single character x.  This provides a way
                        of avoiding the special interpretation of the  charac-
                        ters *?[]\ in(1,8) pattern.

       string(3,n) range string(3,n) first last
              Returns  a range of consecutive characters from string(3,n), 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(1,3) than zero then it is treated
              as if(3,n) it were zero, and if(3,n) last is greater than or equal to  the
              length  of  the string(3,n) then it is treated as if(3,n) it were end.  If
              first is greater than last then an empty string(3,n) is returned.

       string(3,n) repeat string(3,n) count
              Returns string(3,n) repeated count number of times.

       string(3,n) replace string(3,n) first last ?newstring?
              Removes a range of consecutive characters from string(3,n),  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(1,8)  the  removed character range.  If first is less(1,3) than
              zero then it is treated as if(3,n) it  were  zero,  and  if(3,n)  last  is
              greater  than  or  equal  to the length of the string(3,n) then it is
              treated as if(3,n) it were end.  If first is greater than last or the
              length  of  the initial string(3,n), or last is less(1,3) than 0, then the
              initial string(3,n) is returned untouched.

       string(3,n) tolower string(3,n) ?first? ?last?
              Returns a value equal to string(3,n) 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(1,8)  the  string(3,n)  to
              start  modifying.   If  last is specified, it refers to the char
              index in(1,8) the string(3,n) to stop at (inclusive).  first and last  may
              be specified as for the index method.

       string(3,n) totitle string(3,n) ?first? ?last?
              Returns  a value equal to string(3,n) except that the first character
              in(1,8) string(3,n) is converted to its Unicode  title  case  variant  (or
              upper  case  if(3,n)  there is no title case variant) and the rest of
              the string(3,n) is converted to lower case.  If first  is  specified,
              it refers to the first char index in(1,8) the string(3,n) to start modify-
              ing.  If last is specified, it refers to the char index  in(1,8)  the
              string(3,n)  to stop at (inclusive).  first and last may be specified
              as for the index method.

       string(3,n) toupper string(3,n) ?first? ?last?
              Returns a value equal to string(3,n) 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(1,8)  the  string(3,n)  to
              start  modifying.   If  last is specified, it refers to the char
              index in(1,8) the string(3,n) to stop at (inclusive).  first and last  may
              be specified as for the index method.

       string(3,n) trim string(3,n) ?chars?
              Returns  a  value  equal  to  string(3,n)  except that any leading or
              trailing characters from the set(7,n,1 builtins) given by chars are removed.  If
              chars  is  not  specified  then  white space is removed (spaces,
              tabs, newlines, and carriage returns).

       string(3,n) trimleft string(3,n) ?chars?
              Returns a value equal to string(3,n) except that any leading  charac-
              ters  from  the set(7,n,1 builtins) given by chars are removed.  If chars is not
              specified then white space is removed (spaces,  tabs,  newlines,
              and carriage returns).

       string(3,n) trimright string(3,n) ?chars?
              Returns a value equal to string(3,n) except that any trailing charac-
              ters from the set(7,n,1 builtins) given by chars are removed.  If chars  is  not
              specified  then  white space is removed (spaces, tabs, newlines,
              and carriage returns).

       string(3,n) wordend string(3,n) charIndex
              Returns the index of the character just after the  last  one  in(1,8)
              the  word  containing  character charIndex of string(3,n).  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(3,n) wordstart string(3,n) charIndex
              Returns  the index of the first character in(1,8) the word containing
              character charIndex of string(3,n).  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(1,3,n)(n), list(n)


KEYWORDS
       case conversion, compare, index, match, pattern, string(3,n),  word,  equal,
       ctype



Tcl                                   8.1                            string(3,n)(n)

References for this manual (incoming links)