Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for string (opendarwin section n)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

_________________________________________________________________________________________________

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 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 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 specified, then the strings are compared in a case-insensi-
	      tive 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 spec-
	      ified,  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  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 corre-
	      sponds to the first character of the string.  charIndex may be  specified  as  fol-
	      lows:

	      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 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 character 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_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 a 32-bit integer in Tcl, with optional sur-
			rounding 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 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 characters in string.  Note that this
	      is  not  necessarily  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 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 insensi-
	      tive 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, 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 con-
			verted 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 spe-
			cial 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 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  con-
	      verted  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 speci-
	      fied,  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 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 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 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 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  consid-
	      ered 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, ctype

Tcl					       8.1					string(n)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:47 PM.