tcl/doc/DString.3

   1 '\"
   2 '\" Copyright (c) 1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringTrunc, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tcl.h>\fR
  18 .sp
  19 \fBTcl_DStringInit\fR(\fIdsPtr\fR)
  20 .sp
  21 char *
  22 \fBTcl_DStringAppend\fR(\fIdsPtr, string, length\fR)
  23 .sp
  24 char *
  25 \fBTcl_DStringAppendElement\fR(\fIdsPtr, string\fR)
  26 .sp
  27 \fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
  28 .sp
  29 \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
  30 .sp
  31 int
  32 \fBTcl_DStringLength\fR(\fIdsPtr\fR)
  33 .sp
  34 char *
  35 \fBTcl_DStringValue\fR(\fIdsPtr\fR)
  36 .sp
  37 \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
  38 .sp
  39 \fBTcl_DStringTrunc\fR(\fIdsPtr, newLength\fR)
  40 .sp
  41 \fBTcl_DStringFree\fR(\fIdsPtr\fR)
  42 .sp
  43 \fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
  44 .sp
  45 \fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
  46 .SH ARGUMENTS
  47 .AS Tcl_DString newLength
  48 .AP Tcl_DString *dsPtr in/out
  49 Pointer to structure that is used to manage a dynamic string.
  50 .AP "CONST char" *string in
  51 Pointer to characters to add to dynamic string.
  52 .AP int length in
  53 Number of characters from string to add to dynamic string.  If -1,
  54 add all characters up to null terminating character.
  55 .AP int newLength in
  56 New length for dynamic string, not including null terminating
  57 character.
  58 .AP Tcl_Interp *interp in/out
  59 Interpreter whose result is to be set from or moved to the
  60 dynamic string.
  61 .BE
  62
  63 .SH DESCRIPTION
  64 .PP
  65 Dynamic strings provide a mechanism for building up arbitrarily long
  66 strings by gradually appending information.  If the dynamic string is
  67 short then there will be no memory allocation overhead;  as the string
  68 gets larger, additional space will be allocated as needed.
  69 .PP
  70 \fBTcl_DStringInit\fR initializes a dynamic string to zero length.
  71 The Tcl_DString structure must have been allocated by the caller.
  72 No assumptions are made about the current state of the structure;
  73 anything already in it is discarded.
  74 If the structure has been used previously, \fBTcl_DStringFree\fR should
  75 be called first to free up any memory allocated for the old
  76 string.
  77 .PP
  78 \fBTcl_DStringAppend\fR adds new information to a dynamic string,
  79 allocating more memory for the string if needed.
  80 If \fIlength\fR is less than zero then everything in \fIstring\fR
  81 is appended to the dynamic string;  otherwise \fIlength\fR
  82 specifies the number of bytes to append.
  83 \fBTcl_DStringAppend\fR returns a pointer to the characters of
  84 the new string.  The string can also be retrieved from the
  85 \fIstring\fR field of the Tcl_DString structure.
  86 .PP
  87 \fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
  88 except that it doesn't take a \fIlength\fR argument (it appends
  89 all of \fIstring\fR) and it converts the string to a proper list element
  90 before appending.
  91 \fBTcl_DStringAppendElement\fR adds a separator space before the
  92 new list element unless the new list element is the first in a
  93 list or sub-list (i.e. either the current string is empty, or it
  94 contains the single character ``{'', or the last two characters of
  95 the current string are `` {'').
  96 \fBTcl_DStringAppendElement\fR returns a pointer to the
  97 characters of the new string.
  98 .PP
  99 \fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be
 100 used to create nested lists.
 101 To append a list element that is itself a sublist, first
 102 call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR
 103 for each of the elements in the sublist, then call
 104 \fBTcl_DStringEndSublist\fR to end the sublist.
 105 \fBTcl_DStringStartSublist\fR appends a space character if needed,
 106 followed by an open brace;  \fBTcl_DStringEndSublist\fR appends
 107 a close brace.
 108 Lists can be nested to any depth.
 109 .PP
 110 \fBTcl_DStringLength\fR is a macro that returns the current length
 111 of a dynamic string (not including the terminating null character).
 112 \fBTcl_DStringValue\fR is a  macro that returns a pointer to the
 113 current contents of a dynamic string.
 114 .PP
 115 .PP
 116 \fBTcl_DStringSetLength\fR changes the length of a dynamic string.
 117 If \fInewLength\fR is less than the string's current length, then
 118 the string is truncated.
 119 If \fInewLength\fR is greater than the string's current length,
 120 then the string will become longer and new space will be allocated
 121 for the string if needed.
 122 However, \fBTcl_DStringSetLength\fR will not initialize the new
 123 space except to provide a terminating null character;  it is up to the
 124 caller to fill in the new space.
 125 \fBTcl_DStringSetLength\fR does not free up the string's storage space
 126 even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
 127 will still need to be called.
 128 .PP
 129 \fBTcl_DStringTrunc\fR changes the length of a dynamic string.
 130 This procedure is now deprecated.  \fBTcl_DStringSetLength\fR  should
 131 be used instead.
 132 .PP
 133 \fBTcl_DStringFree\fR should be called when you're finished using
 134 the string.  It frees up any memory that was allocated for the string
 135 and reinitializes the string's value to an empty string.
 136 .PP
 137 \fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of
 138 the dynamic string given by \fIdsPtr\fR.  It does this by moving
 139 a pointer from \fIdsPtr\fR to the interpreter's result.
 140 This saves the cost of allocating new memory and copying the string.
 141 \fBTcl_DStringResult\fR also reinitializes the dynamic string to
 142 an empty string.
 143 .PP
 144 \fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
 145 It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
 146 it clears \fIinterp\fR's result.
 147 If possible it does this by moving a pointer rather than by copying
 148 the string.
 149
 150 .SH KEYWORDS
 151 append, dynamic string, free, result