Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

OpenDarwin 7.2.1 - man page for tcl_getunichar (opendarwin section 3)

Tcl_StringObj(3)		      Tcl Library Procedures			 Tcl_StringObj(3)

_________________________________________________________________________________________________

NAME
       Tcl_NewStringObj,   Tcl_NewUnicodeObj,	Tcl_SetStringObj,   Tcl_SetUnicodeObj,	 Tcl_Get-
       StringFromObj,  Tcl_GetString,  Tcl_GetUnicodeFromObj,	Tcl_GetUnicode,   Tcl_GetUniChar,
       Tcl_GetCharLength,   Tcl_GetRange,  Tcl_AppendToObj,  Tcl_AppendUnicodeToObj,  Tcl_Append-
       StringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj,  Tcl_SetObjLength,  Tcl_Conca-
       tObj, 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 |
						     negative.	 (Applications needing null bytes |
						     should  represent	them  as   the	 two-byte |
						     sequence  \700\600, use Tcl_ExternalToUtf to |
						     convert,  or  Tcl_NewByteArrayObj	 if   the |
						     string  is  a  collection	of  uninterpreted |
						     bytes.)

       int		   length	   (in)      The number of bytes to copy from bytes  when
						     initializing,  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 Uni-
						     code characters used to set or append  to	a
						     string  object.  This byte array may contain
						     embedded null characters unless numChars  is
						     negative.

       int		   numChars	   (in)      The  number  of  Unicode  characters to copy
						     from unicode when initializing, setting,  or
						     appending	to a string object.  If negative,
						     all characters up to the first null  charac-
						     ter 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_Appen-
						     dObjToObj.

       int		   *lengthPtr	   (out)     If  non-NULL,  the  location  where Tcl_Get-
						     StringFromObj 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 manipulations 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  representation  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_SetUni-
       codeObj	create	a  new	object or modify an existing object 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 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  representation  as  well as any old internal representation of the
       object.

       Tcl_GetStringFromObj and Tcl_GetString return an object's string representation.  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 lim-
       ited 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 appropriate calls to
       Tcl_IsShared and Tcl_DuplicateObj prior to any in-place modification of the string  repre-
       sentation.   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 pro-
       cedure 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 representation.  If the object's  Unicode  repre-
       sentation  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 convert bytes is to the Unicode format.	If the conversion is suc-
       cessful, then the converted form of bytes is appended to the object's Unicode  representa-
       tion.   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 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 pro-
       vided, 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 tak-
       ing a variable number of arguments it takes an argument list.

       The  Tcl_SetObjLength procedure changes the length of the string value of its objPtr argu-
       ment.  If the newLength argument is greater than the  space  allocated  for  the  object's
       string, then the string space is reallocated 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  allo-
       cated  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 suffi-
       cient memory to satisfy the request cannot be allocated, it does not cause the Tcl  inter-
       preter  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_AttemptSetOb-
       jLength	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 repre-
       sentations 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)


All times are GMT -4. The time now is 05:25 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password