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 values 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)

       int
       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, ...)

       void
       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
						     value.  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    \300\200,   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
						     value.  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	value.
						     This byte array may  con-
						     tain  embedded null char-
						     acters unless numChars is
						     negative.

       int numChars (in)			     The   number  of  Unicode
						     characters	to  copy  from
						     unicode  when  initializ-
						     ing, setting, or  append-
						     ing  to  a	 string	value.
						     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 value.

       int last	(in)				     The  index	 of  the  last
						     Unicode  character	in the
						     Unicode range to  be  re-
						     turned as a new value.

       Tcl_Obj *objPtr (in/out)			     Points  to	a value	to ma-
						     nipulate.

       Tcl_Obj *appendObjPtr (in)		     The value	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   a   value'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 initial-
						     ized 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  values 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 values to be
       manipulated as string values.  They use the internal representation  of
       the  value 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 value being
       appended	to, it is important to call Tcl_ResetResult  first  to	ensure
       you  are	 not  unintentionally appending	to existing data in the	result
       value.

       Tcl_NewStringObj	and Tcl_SetStringObj create a new value	or  modify  an
       existing	 value to hold a copy of the string given by bytes and length.
       Tcl_NewUnicodeObj and Tcl_SetUnicodeObj create a	new value or modify an
       existing	 value	to  hold a copy	of the Unicode string given by unicode
       and numChars.  Tcl_NewStringObj and Tcl_NewUnicodeObj return a  pointer
       to  a  newly  created value with	reference count	zero.  All four	proce-
       dures set the value to hold a copy of the specified  string.   Tcl_Set-
       StringObj  and  Tcl_SetUnicodeObj free any old string representation as
       well as any old internal	representation of the value.

       Tcl_GetStringFromObj and	Tcl_GetString return a value'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  value's  UTF string	representation is invalid (its
       byte pointer is NULL), the string representation	 is  regenerated  from
       the value's internal representation.  The storage referenced by the re-
       turned byte pointer is owned by the value 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 a value'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 value 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  value's  Unicode
       representation.	If  the	 index	is out of range	or it references a low
       surrogate preceded by a high surrogate, it returns -1;

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

       Tcl_GetCharLength  returns  the	number	of  characters	(as opposed to
       bytes) in the string value.

       Tcl_AppendToObj appends the data	given  by  bytes  and  length  to  the
       string  representation  of the value specified by objPtr.  If the value
       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  value's  Unicode
       representation.	 Otherwise,  the value's Unicode representation	is in-
       validated and converted to the UTF format, and bytes is appended	to the
       value's new string representation.

       Tcl_AppendUnicodeToObj  appends the Unicode string given	by unicode and
       numChars	to the value specified by objPtr.  If the value	has an invalid
       Unicode representation, then unicode is converted to the	UTF format and
       appended	to the value's string representation.  Appends	are  optimized
       to  handle  repeated  appends relatively	efficiently (it	over-allocates
       the string or Unicode space to avoid repeated reallocations and	copies
       of value'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);
	      Tcl_DecrRefCount(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 int.

	      int 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.	It is impossi-
       ble however to provide runtime protection  against  mismatches  between
       the  format  and	any subsequent arguments.  Compile-time	protection may
       be provided by some compilers.

       Tcl_AppendPrintfToObj is	an appending alternative form of Tcl_ObjPrintf
       with functionality equivalent to

	      Tcl_Obj *newPtr =	Tcl_ObjPrintf(format, ...);
	      Tcl_AppendObjToObj(objPtr, newPtr);
	      Tcl_DecrRefCount(newPtr);

       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 value'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 value's string, with objPtr-_length  is  reduced  without
       reallocating  the  string  space;  the  original	allocated size for the
       string is recorded in the value,	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  value'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 value	whose value is
       the space-separated concatenation of the	string representations of  all
       of  the	values 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  value  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
       value whose ref count is	zero.

SEE ALSO
       Tcl_NewObj(3),	Tcl_IncrRefCount(3),  Tcl_DecrRefCount(3),  format(n),
       sprintf(3)

KEYWORDS
       append, internal	 representation,  value,  value	 type,	string	value,
       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.tcl87&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help