Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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_AppendObjToObj,  Tcl_Ap-
       pendStringsToObj,   Tcl_AppendStringsToObjVA,   Tcl_AppendLimitedToObj,
       Tcl_Format,  Tcl_AppendFormatToObj,   Tcl_ObjPrintf,   Tcl_AppendPrint-
       fToObj,	Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj - ma-
       nipulate	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-en-
						     coded bytes used  to  set
						     or	append to a string ob-
						     ject.   This  byte	 array
						     may contain embedded null
						     characters	 unless	  num-
						     Chars  is negative.  (Ap-
						     plications	 needing  null
						     bytes   should  represent
						     them as the two-byte  se-
						     quence    \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 ob-
						     ject.  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 ob-
						     ject.   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 re-
						     turned as a new object.

       int last	(in)				     The  index	 of  the  last
						     Unicode  character	in the
						     Unicode range to  be  re-
						     turned 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
						     length   of  an  object's
						     string representation.

       const char *string (in)			     Null-terminated	string
						     value  to	append	to ob-
						     jPtr.

       va_list argList (in)			     An	 argument  list	 which
						     must   have   been	  ini-
						     tialised 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 in-
						     cluding	%   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 in-
						     cluding  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 manipula-
       tions more efficient.  In particular, they make a series	of append  op-
       erations	 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 represen-
       tation 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  in-
       validated 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 in-
       valid Unicode representation, then unicode is converted to the UTF for-
       mat  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 ap-
       pended 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.

       Tcl_AppendLimitedToObj is similar to Tcl_AppendToObj except that	it im- |
       poses  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 con- |
       structed	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  pre- |
       vents 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 ap- |
       pending	fewer bytes is necessary to append only	whole multi-byte char- |
       acters.								       |

       Tcl_Format is the C-level interface to the engine of  the  format  com- |
       mand.  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 docu- |
       mentation  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 re- |
       turned, 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	 func- |
       tionality 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_SUIT- |
       ABLE_LENGTH. The	formatting is done with	the same core  formatting  en- |
       gine  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 ar- |
       guments	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_Ob- |
       jPrintf 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 func- |
       tionality 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  re-
       allocated  and  the old value is	copied to the new space; the bytes be-
       tween the old length of the string and the new length  may  have	 arbi-
       trary  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  en-
       larged  in  a  subsequent call to Tcl_SetObjLength without reallocating
       storage.	 In all	cases Tcl_SetObjLength leaves a	null character at  ob-
       jPtr-_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_At-
       temptSetObjLength 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 ob-
       ject 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

Tcl				      8.1		      Tcl_StringObj(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_AppendFormatToObj.tcl85&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help