DString man page on BSDi

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



Tcl_DString(3)	      Tcl Library Procedures	   Tcl_DString(3)

_________________________________________________________________

NAME
       Tcl_DStringInit,	 Tcl_DStringAppend, Tcl_DStringAppendEle-
       ment,   Tcl_DStringStartSublist,	   Tcl_DStringEndSublist,
       Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength,
       Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult -
       manipulate dynamic strings

SYNOPSIS
       #include <tcl.h>

       Tcl_DStringInit(dsPtr)

       char *
       Tcl_DStringAppend(dsPtr, string, length)

       char *
       Tcl_DStringAppendElement(dsPtr, string)

       Tcl_DStringStartSublist(dsPtr)

       Tcl_DStringEndSublist(dsPtr)

       int
       Tcl_DStringLength(dsPtr)

       char *
       Tcl_DStringValue(dsPtr)

       Tcl_DStringSetLength(dsPtr, newLength)

       Tcl_DStringFree(dsPtr)

       Tcl_DStringResult(interp, dsPtr)

       Tcl_DStringGetResult(interp, dsPtr)

ARGUMENTS
       Tcl_DString   *dsPtr	 (in/out)  Pointer  to	structure
					   that is used to manage
					   a dynamic string.

       char	     *string	 (in)	   Pointer  to characters
					   to  add   to	  dynamic
					   string.

       int	     length	 (in)	   Number  of  characters
					   from string to add  to
					   dynamic   string.   If
					   -1, add all characters
					   up to null terminating
					   character.

Tcl			       7.4				1

Tcl_DString(3)	      Tcl Library Procedures	   Tcl_DString(3)

       int	     newLength	 (in)	   New length for dynamic
					   string,  not including
					   null terminating char-
					   acter.

       Tcl_Interp    *interp	 (in/out)  Interpreter	    whose
					   result is  to  be  set
					   from	 or  moved to the
					   dynamic string.
_________________________________________________________________

DESCRIPTION
       Dynamic strings provide a mechanism for building up  arbi-
       trarily	long  strings by gradually appending information.
       If the dynamic string is short then there will be no  mem-
       ory allocation overhead;	 as the string gets larger, addi-
       tional space will be allocated as needed.

       Tcl_DStringInit	initializes  a	dynamic	 string	 to  zero
       length.	 The  Tcl_DString  structure must have been allo-
       cated by the caller.  No assumptions are	 made  about  the
       current	state of the structure; anything already in it is
       discarded.  If the structure  has  been	used  previously,
       Tcl_DStringFree should be called first to free up any mem-
       ory allocated for the old string.

       Tcl_DStringAppend  adds	new  information  to  a	  dynamic
       string,	allocating  more memory for the string if needed.
       If length is less than zero then everything in  string  is
       appended	 to  the dynamic string;  otherwise length speci-
       fies the number of  bytes  to  append.	Tcl_DStringAppend
       returns	a  pointer  to	the characters of the new string.
       The string can also be retrieved from the string field  of
       the Tcl_DString structure.

       Tcl_DStringAppendElement	 is  similar to Tcl_DStringAppend
       except that it doesn't take a length argument (it  appends
       all of string) and it converts the string to a proper list
       element before appending.  Tcl_DStringAppendElement adds a
       separator space before the new list element unless the new
       list element is the first in  a	list  or  sub-list  (i.e.
       either  the  current  string  is empty, or it contains the
       single character ``{'', or the last two characters of  the
       current	string	are  ``	 {'').	 Tcl_DStringAppendElement
       returns a pointer to the characters of the new string.

       Tcl_DStringStartSublist and Tcl_DStringEndSublist  can  be
       used  to	 create	 nested	 lists.	 To append a list element
       that is itself a sublist, first call  Tcl_DStringStartSub-
       list,  then  call Tcl_DStringAppendElement for each of the
       elements in the sublist, then  call  Tcl_DStringEndSublist
       to  end	the  sublist.	Tcl_DStringStartSublist appends a
       space character if needed,  followed  by	 an  open  brace;

Tcl			       7.4				2

Tcl_DString(3)	      Tcl Library Procedures	   Tcl_DString(3)

       Tcl_DStringEndSublist appends a close brace.  Lists can be
       nested to any depth.

       Tcl_DStringLength is a  macro  that  returns  the  current
       length  of a dynamic string (not including the terminating
       null  character).   Tcl_DStringValue  is	 a   macro   that
       returns	a  pointer  to	the current contents of a dynamic
       string.

       Tcl_DStringSetLength  changes  the  length  of  a  dynamic
       string.	 If  newLength	is less than the string's current
       length, then the string is  truncated.	If  newLength  is
       greater	than the string's current length, then the string
       will become longer and new space will be allocated for the
       string  if needed.  However, Tcl_DStringSetLength will not
       initialize the new space except to provide  a  terminating
       null character;	it is up to the caller to fill in the new
       space.  Tcl_DStringSetLength does not free up the string's
       storage	space  even  if	 the  string is truncated to zero
       length, so Tcl_DStringFree will still need to be called.

       Tcl_DStringFree should  be  called  when	 you're	 finished
       using  the  string.  It frees up any memory that was allo-
       cated for the string and reinitializes the string's  value
       to an empty string.

       Tcl_DStringResult  sets	the result of interp to the value
       of the dynamic string given by dsPtr.   It  does	 this  by
       moving a pointer from dsPtr to interp->result.  This saves
       the cost of allocating new memory and copying the  string.
       Tcl_DStringResult also reinitializes the dynamic string to
       an empty string.

       Tcl_DStringGetResult does the opposite  of  Tcl_DStringRe-
       sult.   It sets the value of dsPtr to the result of interp
       and it clears interp's result.  If possible it  does  this
       by moving a pointer rather than by copying the string.

KEYWORDS
       append, dynamic string, free, result

Tcl			       7.4				3

[top]

List of man pages available for BSDi

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