Provided by: tcl8.4-doc_8.4.20-7_all bug

NAME

       Tcl_NewStringObj,       Tcl_NewUnicodeObj,       Tcl_SetStringObj,      Tcl_SetUnicodeObj,
       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 │
                                                     negative.   (Applications needing null bytes │
                                                     should  represent  them  as   the   two-byte │
                                                     sequence  \700\600, use Tcl_ExternalToUtf to │
                                                     convert,  or  Tcl_NewByteArrayObj   if   the │
                                                     string  is  a  collection  of  uninterpreted │
                                                     bytes.)

       int                 length          (in)      The number of bytes to copy from bytes  when
                                                     initializing,  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
                                                     numChars is negative.

       int                 numChars        (in)      The  number  of  Unicode  characters to copy
                                                     from unicode when initializing, setting,  or
                                                     appending  to a string object.  If negative,
                                                     all  characters  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_AppendObjToObj.

       int                 *lengthPtr      (out)     If     non-NULL,    the    location    where
                                                     Tcl_GetStringFromObj  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
                                                     initialised   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 manipulations 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  representation  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 unicode  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  representation  as  well  as  any  old internal
       representation of the object.

       Tcl_GetStringFromObj and Tcl_GetString return an object's string representation.  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 appropriate 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  representation.   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  convert  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  overallocates
       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 argument 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 reallocated 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
       values.  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 allocated, 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