Tcl_AppendStringsToObj man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

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, 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	 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 the string is a │
						     collection	  of  uninter‐ │
						     preted bytes.)

       int		   length	   (in)	     The number	 of  bytes  to
						     copy from bytes when ini‐
						     tializing,	 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	  num‐
						     Chars is negative.

       int		   numChars	   (in)	     The   number  of  Unicode
						     characters to  copy  from
						     unicode  when  initializ‐
						     ing, setting, or  append‐
						     ing  to  a string object.
						     If negative, all  charac‐
						     ters 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_AppendObj‐
						     ToObj.

       int		   *lengthPtr	   (out)     If non-NULL, the location
						     where   Tcl_GetStringFro‐
						     mObj 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	  ini‐
						     tialised		 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 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.   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 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.	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	appro‐
       priate 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  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 overal‐
       locates 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 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].

       Tcl_AttemptSetObjLength	is  identical  in function to Tcl_SetObjLength
       except that if sufficient memory to satisfy the request cannot be allo‐
       cated,  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

Tcl				      8.1		      Tcl_StringObj(3)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net