Provided by: tcl8.5-doc_8.5.15-2ubuntu1_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_AppendObjToObj,           Tcl_AppendStringsToObj,            Tcl_AppendStringsToObjVA,
       Tcl_AppendLimitedToObj,       Tcl_Format,       Tcl_AppendFormatToObj,      Tcl_ObjPrintf,
       Tcl_AppendPrintfToObj,   Tcl_SetObjLength,   Tcl_AttemptSetObjLength,   Tcl_ConcatObj    -
       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_AppendLimitedToObj(objPtr, bytes, length, limit, ellipsis)                             │

       Tcl_Obj *                                                                                  │
       Tcl_Format(interp, format, objc, objv)                                                     │

       int                                                                                        │
       Tcl_AppendFormatToObj(interp, objPtr, format, objc, objv)                                  │

       Tcl_Obj *                                                                                  │
       Tcl_ObjPrintf(format, ...)                                                                 │

       int                                                                                        │
       Tcl_AppendPrintfToObj(objPtr, format, ...)                                                 │

       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  may
                                                     contain  embedded  null  characters   unless
                                                     numChars 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  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  va_start,  and  cleared
                                                     using va_end.

       int limit (in)                                Maximum number of bytes to be appended.

       const char *ellipsis (in)                     Suffix to append when  the  limit  leads  to
                                                     string  truncation.   If NULL is passed then
                                                     the suffix "..." is used.

       const char *format (in)                       Format control string including % conversion
                                                     specifiers.

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

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

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

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 does  not  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.

       Tcl_AppendLimitedToObj is similar to Tcl_AppendToObj except that it imposes a limit on how │
       many bytes are appended.  This can be handy when the string to be appended might  be  very │
       large,  but  the  value  being  constructed should not be allowed to grow without bound. A │
       common usage is when constructing an error message, where the end result  should  be  kept │
       short  enough to be read.  Bytes from bytes are appended to objPtr, but no more than limit │
       bytes total are to be appended. If the limit prevents all length bytes that are  available │
       from  being  appended, then the appending is done so that the last bytes appended are from │
       the string ellipsis. This allows for an indication of the truncation to  be  left  in  the │
       string.   When  length is -1, all bytes up to the first zero byte are appended, subject to │
       the limit. When ellipsis is NULL, the default string ... is used. When  ellipsis  is  non- │
       NULL,  it must point to a zero-byte-terminated string in Tcl's internal UTF encoding.  The │
       number of bytes appended can be less than the lesser of length and  limit  when  appending │
       fewer bytes is necessary to append only whole multi-byte characters.                       │

       Tcl_Format  is  the  C-level  interface  to  the engine of the format command.  The actual │
       command procedure for format is little more than                                           │
              Tcl_Format(interp, Tcl_GetString(objv[1]), objc-2, objv+2);                         │
       The objc Tcl_Obj values in objv are formatted into a string according  to  the  conversion │
       specification in format argument, following the documentation for the format command.  The │
       resulting formatted string is converted to  a  new  Tcl_Obj  with  refcount  of  zero  and │
       returned.   If  some  error  happens  during  production  of the formatted string, NULL is │
       returned, and an error message is recorded in interp, if interp is non-NULL.               │

       Tcl_AppendFormatToObj is an appending alternative form of  Tcl_Format  with  functionality │
       equivalent to                                                                              │
              Tcl_Obj *newPtr = Tcl_Format(interp, format, objc, objv);                           │
              if (newPtr == NULL) return TCL_ERROR;                                               │
              Tcl_AppendObjToObj(objPtr, newPtr);                                                 │
              return TCL_OK;                                                                      │
       but with greater convenience and efficiency when the appending functionality is needed.    │

       Tcl_ObjPrintf serves as a replacement for the common sequence                              │
              char buf[SOME_SUITABLE_LENGTH];                                                     │
              sprintf(buf, format, ...);                                                          │
              Tcl_NewStringObj(buf, -1);                                                          │
       but with greater convenience and no need to determine SOME_SUITABLE_LENGTH. The formatting │
       is done with the same core formatting engine used by Tcl_Format.  This means  the  set  of │
       supported  conversion specifiers is that of the format command and not that of the sprintf │
       routine where the two sets differ. When a conversion  specifier  passed  to  Tcl_ObjPrintf │
       includes a precision, the value is taken as a number of bytes, as sprintf does, and not as │
       a number of characters, as format does.  This is done on the assumption  that  C  code  is │
       more  likely  to  know  how  many  bytes  it  is passing around than the number of encoded │
       characters those bytes happen to represent.  The variable number of  arguments  passed  in │
       should  be  of  the  types  that  would  be suitable for passing to sprintf.  Note in this │
       example usage, x is of type long.                                                          │
              long x = 5;                                                                         │
              Tcl_Obj *objPtr = Tcl_ObjPrintf("Value is %d", x);                                  │
       If the value of format contains internal inconsistencies or invalid specifier formats, the │
       formatted  string result produced by Tcl_ObjPrintf will be an error message describing the │
       error.                                                                                     │

       Tcl_AppendPrintfToObj is an appending alternative form of Tcl_ObjPrintf with functionality │
       equivalent to                                                                              │
              Tcl_AppendObjToObj(objPtr, Tcl_ObjPrintf(format, ...));                             │
       but with greater convenience and efficiency when the appending functionality is needed.

       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, format, sprintf

KEYWORDS

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