StringObj man page on Tru64

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

Tcl_StringObj(3)	    Tcl Library Procedures	      Tcl_StringObj(3)

______________________________________________________________________________

NAME
       Tcl_NewStringObj,  Tcl_SetStringObj,  Tcl_GetStringFromObj, Tcl_Append‐
       ToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj - manipu‐
       late Tcl objects as strings

SYNOPSIS
       #include <tcl.h>

       Tcl_Obj *
       Tcl_NewStringObj(bytes, length)

       Tcl_SetStringObj(objPtr, bytes, length)

       char *
       Tcl_GetStringFromObj(objPtr, lengthPtr)

       Tcl_AppendToObj(objPtr, bytes, length)

       Tcl_AppendStringsToObj(objPtr, string, string, ... (char *) NULL)

       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 nega‐
					   tive.

       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.

       Tcl_Obj	    *objPtr	 (in/out)  Points to an object to manipulate.

       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.

       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  concate‐
					   nate.

       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.

       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_NewStringObj	 returns a pointer to a newly created object with ref‐
       erence count zero.  Both procedures set the object to hold  a  copy  of
       the  specified string.  Tcl_SetStringObj frees any old string represen‐
       tation as well as any old internal representation of the object.

       Tcl_GetStringFromObj returns an object's string	representation.	  This
       is  given  by  the returned byte pointer and length, which is stored in
       lengthPtr if it is non-NULL.  If the object's string representation  is
       invalid (its byte pointer is NULL), the string representation is regen‐
       erated from the object's internal representation.  The  storage	refer‐
       enced  by  the returned byte pointer is owned by the object manager and
       should not be modified by the caller.

       Tcl_AppendToObj appends the data given  by  bytes  and  length  to  the
       object  specified  by  objPtr.	It  does  this	in  a way that handles
       repeated calls relatively  efficiently  (it  overallocates  the	string
       space  to  avoid	 repeated  reallocations and copies of object's string
       value).

       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.

       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

Tcl				      8.0		      Tcl_StringObj(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

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