[25] | 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: DString.3,v 1.17 2007/12/13 15:22:31 dgp Exp $ |
---|
| 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, bytes, length\fR) |
---|
| 23 | .sp |
---|
| 24 | char * |
---|
| 25 | \fBTcl_DStringAppendElement\fR(\fIdsPtr, element\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 in/out |
---|
| 48 | .AP Tcl_DString *dsPtr in/out |
---|
| 49 | Pointer to structure that is used to manage a dynamic string. |
---|
| 50 | .AP "const char" *bytes in |
---|
| 51 | Pointer to characters to append to dynamic string. |
---|
| 52 | .AP "const char" *element in |
---|
| 53 | Pointer to characters to append as list element to dynamic string. |
---|
| 54 | .AP int length in |
---|
| 55 | Number of bytes from \fIbytes\fR to add to dynamic string. If -1, |
---|
| 56 | add all characters up to null terminating character. |
---|
| 57 | .AP int newLength in |
---|
| 58 | New length for dynamic string, not including null terminating |
---|
| 59 | character. |
---|
| 60 | .AP Tcl_Interp *interp in/out |
---|
| 61 | Interpreter whose result is to be set from or moved to the |
---|
| 62 | dynamic string. |
---|
| 63 | .BE |
---|
| 64 | |
---|
| 65 | .SH DESCRIPTION |
---|
| 66 | .PP |
---|
| 67 | Dynamic strings provide a mechanism for building up arbitrarily long |
---|
| 68 | strings by gradually appending information. If the dynamic string is |
---|
| 69 | short then there will be no memory allocation overhead; as the string |
---|
| 70 | gets larger, additional space will be allocated as needed. |
---|
| 71 | .PP |
---|
| 72 | \fBTcl_DStringInit\fR initializes a dynamic string to zero length. |
---|
| 73 | The Tcl_DString structure must have been allocated by the caller. |
---|
| 74 | No assumptions are made about the current state of the structure; |
---|
| 75 | anything already in it is discarded. |
---|
| 76 | If the structure has been used previously, \fBTcl_DStringFree\fR should |
---|
| 77 | be called first to free up any memory allocated for the old |
---|
| 78 | string. |
---|
| 79 | .PP |
---|
| 80 | \fBTcl_DStringAppend\fR adds new information to a dynamic string, |
---|
| 81 | allocating more memory for the string if needed. |
---|
| 82 | If \fIlength\fR is less than zero then everything in \fIbytes\fR |
---|
| 83 | is appended to the dynamic string; otherwise \fIlength\fR |
---|
| 84 | specifies the number of bytes to append. |
---|
| 85 | \fBTcl_DStringAppend\fR returns a pointer to the characters of |
---|
| 86 | the new string. The string can also be retrieved from the |
---|
| 87 | \fIstring\fR field of the Tcl_DString structure. |
---|
| 88 | .PP |
---|
| 89 | \fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR |
---|
| 90 | except that it does not take a \fIlength\fR argument (it appends |
---|
| 91 | all of \fIelement\fR) and it converts the string to a proper list element |
---|
| 92 | before appending. |
---|
| 93 | \fBTcl_DStringAppendElement\fR adds a separator space before the |
---|
| 94 | new list element unless the new list element is the first in a |
---|
| 95 | list or sub-list (i.e. either the current string is empty, or it |
---|
| 96 | contains the single character |
---|
| 97 | .QW { , |
---|
| 98 | or the last two characters of the current string are |
---|
| 99 | .QW " {" ). |
---|
| 100 | \fBTcl_DStringAppendElement\fR returns a pointer to the |
---|
| 101 | characters of the new string. |
---|
| 102 | .PP |
---|
| 103 | \fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be |
---|
| 104 | used to create nested lists. |
---|
| 105 | To append a list element that is itself a sublist, first |
---|
| 106 | call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR |
---|
| 107 | for each of the elements in the sublist, then call |
---|
| 108 | \fBTcl_DStringEndSublist\fR to end the sublist. |
---|
| 109 | \fBTcl_DStringStartSublist\fR appends a space character if needed, |
---|
| 110 | followed by an open brace; \fBTcl_DStringEndSublist\fR appends |
---|
| 111 | a close brace. |
---|
| 112 | Lists can be nested to any depth. |
---|
| 113 | .PP |
---|
| 114 | \fBTcl_DStringLength\fR is a macro that returns the current length |
---|
| 115 | of a dynamic string (not including the terminating null character). |
---|
| 116 | \fBTcl_DStringValue\fR is a macro that returns a pointer to the |
---|
| 117 | current contents of a dynamic string. |
---|
| 118 | .PP |
---|
| 119 | .PP |
---|
| 120 | \fBTcl_DStringSetLength\fR changes the length of a dynamic string. |
---|
| 121 | If \fInewLength\fR is less than the string's current length, then |
---|
| 122 | the string is truncated. |
---|
| 123 | If \fInewLength\fR is greater than the string's current length, |
---|
| 124 | then the string will become longer and new space will be allocated |
---|
| 125 | for the string if needed. |
---|
| 126 | However, \fBTcl_DStringSetLength\fR will not initialize the new |
---|
| 127 | space except to provide a terminating null character; it is up to the |
---|
| 128 | caller to fill in the new space. |
---|
| 129 | \fBTcl_DStringSetLength\fR does not free up the string's storage space |
---|
| 130 | even if the string is truncated to zero length, so \fBTcl_DStringFree\fR |
---|
| 131 | will still need to be called. |
---|
| 132 | .PP |
---|
| 133 | \fBTcl_DStringTrunc\fR changes the length of a dynamic string. |
---|
| 134 | This procedure is now deprecated. \fBTcl_DStringSetLength\fR should |
---|
| 135 | be used instead. |
---|
| 136 | .PP |
---|
| 137 | \fBTcl_DStringFree\fR should be called when you are finished using |
---|
| 138 | the string. It frees up any memory that was allocated for the string |
---|
| 139 | and reinitializes the string's value to an empty string. |
---|
| 140 | .PP |
---|
| 141 | \fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of |
---|
| 142 | the dynamic string given by \fIdsPtr\fR. It does this by moving |
---|
| 143 | a pointer from \fIdsPtr\fR to the interpreter's result. |
---|
| 144 | This saves the cost of allocating new memory and copying the string. |
---|
| 145 | \fBTcl_DStringResult\fR also reinitializes the dynamic string to |
---|
| 146 | an empty string. |
---|
| 147 | .PP |
---|
| 148 | \fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR. |
---|
| 149 | It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and |
---|
| 150 | it clears \fIinterp\fR's result. |
---|
| 151 | If possible it does this by moving a pointer rather than by copying |
---|
| 152 | the string. |
---|
| 153 | |
---|
| 154 | .SH KEYWORDS |
---|
| 155 | append, dynamic string, free, result |
---|