ABCDEFGHIJKLMNOPQRSTUVWXYZ

StringObj

Tcl_StringObj(3)            Tcl Library Procedures            Tcl_StringObj(3)



______________________________________________________________________________

NAME
       Tcl_NewStringObj,   Tcl_NewUnicodeObj,   Tcl_SetStringObj,  Tcl_SetUni-
       codeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicode, Tcl_GetU-
       niChar,  Tcl_GetCharLength,  Tcl_GetRange,  Tcl_AppendToObj, Tcl_Appen-
       dUnicodeToObj,    Tcl_AppendStringsToObj,     Tcl_AppendStringsToObjVA,
       Tcl_AppendObjToObj,  Tcl_SetObjLength,  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_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)

       Tcl_Obj *
       Tcl_ConcatObj(objc, objv)

ARGUMENTS
       char         *bytes          (in)      Points to the first byte  of  an
                                              array  of  bytes  used to set or
                                              append to a string object.  This
                                              byte  array may contain embedded
                                              null bytes unless length is neg-
                                              ative.

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

       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          num-                                                       |
       Chars        (in)                                       |               |
                                              The number of Unicode characters |
                                              to copy from unicode  when  ini- |
                                              tializing, setting, or appending |
                                              to a string  object.   If  nega- |
                                              tive,  all  characters up to the |
                                              first null character are used.   |

       int          index           (in)                                       ||
                                              The index of the Unicode charac- |
                                              ter 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  manipu-
                                              late.

       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.

       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 con-
                                              catenate.

       Tcl_Obj      *objv[]         (in)      The array of objects to concate-
                                              nate.
_________________________________________________________________


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.

       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 and should not  be
       modified  by  the  caller.   The procedure Tcl_GetString is used in the
       common case where the caller does not need the  length  of  the  string
       representation.

       Tcl_GetUnicode   returns   an  object's  value  as  a  Unicode  string. |
       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 |
       overallocates the string or Unicode space to avoid  repeated  realloca- |
       tions 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].

       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)