Seth Woolley's Man Viewer

Tcl_NewStringObj(3) - Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AttemptSetObjLength, Tcl_ConcatObj, Tcl_GetCharLength, Tcl_GetRange, Tcl_GetString, Tcl_GetStringFromObj, Tcl_GetUniChar, Tcl_GetUnicode, Tcl_GetUnicodeFromObj, Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetObjLength, Tcl_SetStringObj, Tcl_SetUnicodeObj - manipulate Tcl objects as strings - man 3 Tcl_NewStringObj

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

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(3,n), string(3,n), ... (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(1,8))      Points  to the first byte |
                                                     of    an     array     of |
                                                     UTF-8-encoded  bytes used |
                                                     to set(7,n,1 builtins)  or  append  to  a |
                                                     string(3,n) 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(3,n) the string(3,n) is a |
                                                     collection   of  uninter- |
                                                     preted bytes.)

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

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

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

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

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

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

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

       Tcl_Obj             *appendObjPtr   (in(1,8))      The object to  append  to
                                                     objPtr  in(1,8) 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(3,n) representation.

       CONST char          *string(3,n)         (in(1,8))      Null-terminated    string(3,n)
                                                     value    to   append   to
                                                     objPtr.

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

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

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

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


DESCRIPTION
       The  procedures  described in(1,8) this manual entry allow Tcl objects to be
       manipulated as string(3,n) values.  They use the internal representation  of
       the object to store additional information to make the string(3,n) manipula-
       tions more efficient.  In particular, they  make  a  series  of  append
       operations  efficient  by allocating extra storage space for the string(3,n)
       so that it doesn't have to be copied for each append.   Also,  indexing
       and length computations are optimized because the Unicode string(3,n) 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(1,8) the
       result object.

       Tcl_NewStringObj and Tcl_SetStringObj create a new object or modify  an
       existing object to hold a copy of the string(3,n) 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(3,n) 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(7,n,1 builtins) the object to hold  a  copy  of  the  specified  string.
       Tcl_SetStringObj  and Tcl_SetUnicodeObj free any old string(3,n) representa-
       tion as well as any old internal representation of the object.

       Tcl_GetStringFromObj and Tcl_GetString return an object's string(3,n) repre-
       sentation.   This  is  given  by  the  returned  byte  pointer and (for
       Tcl_GetStringFromObj) length, which is stored in(1,8)  lengthPtr  if(3,n)  it  is
       non-NULL.   If  the  object's UTF string(3,n) representation is invalid (its
       byte pointer is NULL), the string(3,n) 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(3,n) 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(1,8) 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(3,n) representation.  The procedure Tcl_GetString
       is used in(1,8) the common case where the caller does not need the length of
       the string(3,n) 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(1,8) lengthPtr  if(3,n)  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(1,8) the common case where the caller
       does not need the length of the unicode string(3,n) representation.

       Tcl_GetUniChar returns the index'th character in(1,8) the  object's  Unicode
       representation.

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

       Tcl_GetCharLength  returns  the  number  of  characters  (as opposed to
       bytes) in(1,8) the string(3,n) object.

       Tcl_AppendToObj appends the data given  by  bytes  and  length  to  the
       string(3,n) representation of the object specified by objPtr.  If the object
       has an invalid string(3,n) 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(3,n) representation.

       Tcl_AppendUnicodeToObj  appends the Unicode string(3,n) 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(3,n) representation.  Appends are
       optimized to handle repeated appends relatively efficiently (it overal-
       locates the string(3,n) or Unicode space to avoid repeated reallocations and
       copies of object's string(3,n) value).

       Tcl_AppendObjToObj  is  similar  to Tcl_AppendToObj, but it appends the
       string(3,n) 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(3,n)  (i.e.  none of the values may contain internal null
       characters).  Any number of string(3,n) 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(3,n) value
       of its objPtr argument.  If the newLength argument is greater than  the
       space allocated for the object's string(3,n), then the string(3,n) space is real-
       located and the old value is copied to the new space; the bytes between
       the old length of the string(3,n) and the new length may have arbitrary val-
       ues.  If the newLength argument is less(1,3) than the current length of  the
       object's  string(3,n),  with  objPtr->length is reduced without reallocating
       the string(3,n) space;  the  original  allocated  size  for  the  string(3,n)  is
       recorded  in(1,8) the object, so that the string(3,n) length can be enlarged in(1,8) 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(1,8)  function  to  Tcl_SetObjLength
       except that if(3,n) sufficient memory to satisfy the request cannot be allo-
       cated, it does not cause  the  Tcl  interpreter  to  panic.   Thus,  if(3,n)
       newLength  is greater than the space allocated for the object's string(3,n),
       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(3,n) object whose  value  is
       the  space-separated concatenation of the string(3,n) representations of all
       of the objects in(1,8) the objv array. Tcl_ConcatObj eliminates leading  and
       trailing  white  space  as  it copies the string(3,n) 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(3,n)  object,
       string(3,n) type, string(3,n) representation, concat, concatenate, unicode



Tcl                                   8.1                     Tcl_StringObj(3)

References for this manual (incoming links)