Tcl_SetObjLength man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

Tcl_StringObj(3)	    Tcl Library Procedures	      Tcl_StringObj(3)

______________________________________________________________________________

NAME
       Tcl_NewStringObj,   Tcl_NewUnicodeObj,	Tcl_SetStringObj,  Tcl_SetUni-
       codeObj,	 Tcl_GetStringFromObj,	Tcl_GetString,	Tcl_GetUnicodeFromObj,
       Tcl_GetUnicode,	  Tcl_GetUniChar,   Tcl_GetCharLength,	 Tcl_GetRange,
       Tcl_AppendToObj,	   Tcl_AppendUnicodeToObj,     Tcl_AppendStringsToObj,
       Tcl_AppendStringsToObjVA,     Tcl_AppendObjToObj,     Tcl_SetObjLength,
       Tcl_ConcatObj, Tcl_AttemptSetObjLength  -  manipulate  Tcl  objects  as
       strings

SYNOPSIS
       #include <tcl.h>

       Tcl_Obj *
       Tcl_NewStringObj(bytes, length)

       Tcl_Obj *
       Tcl_NewUnicodeObj(unicode, numChars)

       void
       Tcl_SetStringObj(objPtr, bytes, length)

       void
       Tcl_SetUnicodeObj(objPtr, unicode, numChars)

       char *
       Tcl_GetStringFromObj(objPtr, lengthPtr)

       char *
       Tcl_GetString(objPtr)

       Tcl_UniChar *
       Tcl_GetUnicodeFromObj(objPtr, lengthPtr)

       Tcl_UniChar *
       Tcl_GetUnicode(objPtr)

       Tcl_UniChar
       Tcl_GetUniChar(objPtr, index)

       int
       Tcl_GetCharLength(objPtr)

       Tcl_Obj *
       Tcl_GetRange(objPtr, first, last)

       void
       Tcl_AppendToObj(objPtr, bytes, length)

       void
       Tcl_AppendUnicodeToObj(objPtr, unicode, numChars)

       void
       Tcl_AppendObjToObj(objPtr, appendObjPtr)

       void
       Tcl_AppendStringsToObj(objPtr, string, string, ... (char *) NULL)

       void
       Tcl_AppendStringsToObjVA(objPtr, argList)

       void
       Tcl_SetObjLength(objPtr, newLength)

       int
       Tcl_AttemptSetObjLength(objPtr, newLength)

       Tcl_Obj *
       Tcl_ConcatObj(objc, objv)

ARGUMENTS
       CONST char	   *bytes	   (in)	     Points  to the first byte |
						     of	   an	  array	    of |
						     UTF-8-encoded  bytes used |
						     to set  or	 append	 to  a |
						     string object.  This byte |
						     array should not  contain |
						     embedded	 null	 bytes |
						     unless  length  is	 nega- |
						     tive.	 (Applications |
						     needing null bytes should |
						     represent	 them  as  the |
						     two-byte	      sequence |
						     \700\600,		   use |
						     Tcl_ExternalToUtf to con- |
						     vert,  or	Tcl_NewByteAr- |
						     rayObj if the string is a |
						     collection	  of  uninter- |
						     preted bytes.)

       int		   length	   (in)	     The number	 of  bytes  to
						     copy from bytes when ini-
						     tializing,	 setting,   or
						     appending	 to  a	string
						     object.  If negative, all
						     bytes  up	to  the	 first
						     null are used.

       CONST Tcl_UniChar   *unicode	   (in)	     Points to the first  byte
						     of	 an  array  of Unicode
						     characters used to set or
						     append    to   a	string
						     object.  This byte	 array
						     may contain embedded null
						     characters	 unless	  num-
						     Chars is negative.

       int		   numChars	   (in)	     The   number  of  Unicode
						     characters to  copy  from
						     unicode  when  initializ-
						     ing, setting, or  append-
						     ing  to  a string object.
						     If negative, all  charac-
						     ters up to the first null
						     character are used.

       int		   index	   (in)	     The index of the  Unicode
						     character to return.

       int		   first	   (in)	     The  index	 of  the first
						     Unicode character in  the
						     Unicode   range   to   be
						     returned as a new object.

       int		   last		   (in)	     The  index	 of  the  last
						     Unicode character in  the
						     Unicode   range   to   be
						     returned as a new object.

       Tcl_Obj		   *objPtr	   (in/out)  Points  to	 an  object to
						     manipulate.

       Tcl_Obj		   *appendObjPtr   (in)	     The object to  append  to
						     objPtr  in Tcl_AppendObj-
						     ToObj.

       int		   *lengthPtr	   (out)     If non-NULL, the location
						     where   Tcl_GetStringFro-
						     mObj will store  the  the
						     length   of  an  object's
						     string representation.

       CONST char	   *string	   (in)	     Null-terminated	string
						     value    to   append   to
						     objPtr.

       va_list		   argList	   (in)	     An	 argument  list	 which
						     must   have   been	  ini-
						     tialised		 using
						     TCL_VARARGS_START,	   and
						     cleared using va_end.

       int		   newLength	   (in)	     New length for the string
						     value   of	  objPtr,  not
						     including the final  null
						     character.

       int		   objc		   (in)	     The number of elements to
						     concatenate.

       Tcl_Obj		   *objv[]	   (in)	     The array of  objects  to
						     concatenate.
_________________________________________________________________

DESCRIPTION
       The  procedures	described in this manual entry allow Tcl objects to be
       manipulated as string values.  They use the internal representation  of
       the object to store additional information to make the string manipula-
       tions more efficient.  In particular, they  make	 a  series  of	append
       operations  efficient  by allocating extra storage space for the string
       so that it doesn't have to be copied for each append.   Also,  indexing
       and length computations are optimized because the Unicode string repre-
       sentation  is  calculated  and  cached  as  needed.   When  using   the
       Tcl_Append*  family  of functions where the interpreter's result is the
       object being appended to, it is important to call Tcl_ResetResult first
       to ensure you are not unintentionally appending to existing data in the
       result object.

       Tcl_NewStringObj and Tcl_SetStringObj create a new object or modify  an
       existing object to hold a copy of the string given by bytes and length.
       Tcl_NewUnicodeObj and Tcl_SetUnicodeObj create a new object  or	modify
       an  existing  object to hold a copy of the Unicode string given by uni-
       code and numChars.  Tcl_NewStringObj  and  Tcl_NewUnicodeObj  return  a
       pointer	to a newly created object with reference count zero.  All four
       procedures set the object to hold  a  copy  of  the  specified  string.
       Tcl_SetStringObj	 and Tcl_SetUnicodeObj free any old string representa-
       tion as well as any old internal representation of the object.

       Tcl_GetStringFromObj and Tcl_GetString return an object's string repre-
       sentation.   This  is  given  by	 the  returned	byte  pointer and (for
       Tcl_GetStringFromObj) length, which is stored in	 lengthPtr  if	it  is
       non-NULL.   If  the  object's UTF string representation is invalid (its
       byte pointer is NULL), the string representation	 is  regenerated  from
       the  object's  internal	representation.	 The storage referenced by the
       returned byte pointer is owned by the object  manager.	It  is	passed
       back  as a writable pointer so that extension author creating their own
       Tcl_ObjType will be able to modify the string representation within the
       Tcl_UpdateStringProc  of	 their	Tcl_ObjType.   Except for that limited
       purpose, the pointer returned by Tcl_GetStringFromObj or	 Tcl_GetString
       should be treated as read-only.	It is recommended that this pointer be
       assigned to a (CONST char *) variable.  Even in the limited  situations
       where  writing  to  this pointer is acceptable, one should take care to
       respect the copy-on-write semantics required by Tcl_Obj's, with	appro-
       priate calls to Tcl_IsShared and Tcl_DuplicateObj prior to any in-place
       modification of the string representation.  The procedure Tcl_GetString
       is used in the common case where the caller does not need the length of
       the string representation.

       Tcl_GetUnicodeFromObj and Tcl_GetUnicode return an object's value as  a
       Unicode	string.	  This	is  given  by  the  returned  pointer and (for
       Tcl_GetUnicodeFromObj) length, which is stored in lengthPtr  if	it  is
       non-NULL.  The storage referenced by the returned byte pointer is owned
       by the object manager and should not be modified by  the	 caller.   The
       procedure  Tcl_GetUnicode  is  used in the common case where the caller
       does not need the length of the unicode string representation.

       Tcl_GetUniChar returns the index'th character in the  object's  Unicode
       representation.

       Tcl_GetRange returns a newly created object comprised of the characters
       between first and last (inclusive) in the object's Unicode  representa-
       tion.   If  the object's Unicode representation is invalid, the Unicode
       representation is regenerated from the object's string  representation.

       Tcl_GetCharLength  returns  the	number	of  characters	(as opposed to
       bytes) in the string object.

       Tcl_AppendToObj appends the data given  by  bytes  and  length  to  the
       string representation of the object specified by objPtr.	 If the object
       has an invalid string representation, then an attempt is made  to  con-
       vert  bytes is to the Unicode format.  If the conversion is successful,
       then the converted form of bytes is appended to	the  object's  Unicode
       representation.	 Otherwise,  the  object's  Unicode  representation is
       invalidated and converted to the UTF format, and bytes is  appended  to
       the object's new string representation.

       Tcl_AppendUnicodeToObj  appends the Unicode string given by unicode and
       numChars to the object specified by  objPtr.   If  the  object  has  an
       invalid	Unicode	 representation,  then unicode is converted to the UTF
       format and appended to the object's string representation.  Appends are
       optimized to handle repeated appends relatively efficiently (it overal-
       locates the string or Unicode space to avoid repeated reallocations and
       copies of object's string value).

       Tcl_AppendObjToObj  is  similar	to Tcl_AppendToObj, but it appends the
       string or Unicode value (whichever exists and  is  best	suited	to  be
       appended to objPtr) of appendObjPtr to objPtr.

       Tcl_AppendStringsToObj is similar to Tcl_AppendToObj except that it can
       be passed more than one value to append and each value must be a	 null-
       terminated  string  (i.e.  none of the values may contain internal null
       characters).  Any number of string arguments may be provided,  but  the
       last argument must be a NULL pointer to indicate the end of the list.

       Tcl_AppendStringsToObjVA	 is  the same as Tcl_AppendStringsToObj except
       that instead of taking a variable number of arguments it takes an argu-
       ment list.

       The  Tcl_SetObjLength  procedure changes the length of the string value
       of its objPtr argument.	If the newLength argument is greater than  the
       space allocated for the object's string, then the string space is real-
       located and the old value is copied to the new space; the bytes between
       the old length of the string and the new length may have arbitrary val-
       ues.  If the newLength argument is less than the current length of  the
       object's	 string,  with	objPtr->length is reduced without reallocating
       the string space;  the  original	 allocated  size  for  the  string  is
       recorded	 in the object, so that the string length can be enlarged in a
       subsequent call to Tcl_SetObjLength without reallocating	 storage.   In
       all    cases    Tcl_SetObjLength	   leaves    a	 null	character   at
       objPtr->bytes[newLength].

       Tcl_AttemptSetObjLength is identical in	function  to  Tcl_SetObjLength
       except that if sufficient memory to satisfy the request cannot be allo-
       cated, it does not cause	 the  Tcl  interpreter	to  panic.   Thus,  if
       newLength  is greater than the space allocated for the object's string,
       and there is not	 enough	 memory	 available  to	satisfy	 the  request,
       Tcl_AttemptSetObjLength	will  take  no action and return 0 to indicate
       failure.	  If  there  is	 enough	 memory	 to   satisfy	the   request,
       Tcl_AttemptSetObjLength	behaves just like Tcl_SetObjLength and returns
       1 to indicate success.

       The Tcl_ConcatObj function returns a new string object whose  value  is
       the  space-separated concatenation of the string representations of all
       of the objects in the objv array. Tcl_ConcatObj eliminates leading  and
       trailing	 white	space  as  it copies the string representations of the
       objv array to the result. If an element of the objv array  consists  of
       nothing	but  white  space,  then that object is ignored entirely. This
       white-space removal was added to make the output of the concat  command
       cleaner-looking.	 Tcl_ConcatObj	returns	 a  pointer to a newly-created
       object whose ref count is zero.

SEE ALSO
       Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount

KEYWORDS
       append, internal representation, object, object	type,  string  object,
       string type, string representation, concat, concatenate, unicode

Tcl				      8.1		      Tcl_StringObj(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net