Seth Woolley's Man Viewer

StringObj(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, 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 StringObj

([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
       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 negative.  (Applications needing
       null bytes should represent them as the two-byte sequence \700\600, use
       Tcl_ExternalToUtf to convert, or Tcl_NewByteArrayObj if(3,n) the string(3,n) is a
       collection of uninterpreted bytes.)  The number of bytes to  copy  from
       bytes  when initializing, setting, or appending to a string(3,n) object.  If
       negative, all bytes up to the first null are used.  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  numChars is negative.  The number of Unicode characters to copy
       from unicode when initializing,  setting,  or  appending  to  a  string(3,n)
       object.  If negative, all characters up to the first null character are
       used.  The index of the Unicode character to return.  The index of  the
       first  Unicode  character  in(1,8) the Unicode range to be returned as a new
       object.  The index of the last Unicode character in(1,8) the  Unicode  range
       to  be  returned  as  a new object.  Points to an object to manipulate.
       The object to append to objPtr in(1,8) Tcl_AppendObjToObj.  If non-NULL, the
       location  where  Tcl_GetStringFromObj  will  store the the length of an
       object's string(3,n) representation.  Null-terminated string(3,n) value to append
       to  objPtr.   An  argument  list which must have been initialised using
       TCL_VARARGS_START, and cleared using va_end.  New length for the string(3,n)
       value of objPtr, not including the final null character.  The number of
       elements to concatenate.  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)