通讯编程

开发平台：
Visual C++

DString.3：源码内容
							'"
'" Copyright (c) 1993 The Regents of the University of California.
'" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'"
'" See the file "license.terms" for information on usage and redistribution
'" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'" 
'" RCS: @(#) $Id: DString.3,v 1.9 2002/02/08 02:52:54 dgp Exp $
'" 
.so man.macros
.TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
.BS
.SH NAME
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
.SH SYNOPSIS
.nf
fB#include <tcl.h>fR
.sp
fBTcl_DStringInitfR(fIdsPtrfR)
.sp
char *
fBTcl_DStringAppendfR(fIdsPtr, string, lengthfR)
.sp
char *
fBTcl_DStringAppendElementfR(fIdsPtr, stringfR)
.sp
fBTcl_DStringStartSublistfR(fIdsPtrfR)
.sp
fBTcl_DStringEndSublistfR(fIdsPtrfR)
.sp
int
fBTcl_DStringLengthfR(fIdsPtrfR)
.sp
char *
fBTcl_DStringValuefR(fIdsPtrfR)
.sp
fBTcl_DStringSetLengthfR(fIdsPtr, newLengthfR)
.sp
fBTcl_DStringTruncfR(fIdsPtr, newLengthfR)
.sp
fBTcl_DStringFreefR(fIdsPtrfR)
.sp
fBTcl_DStringResultfR(fIinterp, dsPtrfR)
.sp
fBTcl_DStringGetResultfR(fIinterp, dsPtrfR)
.SH ARGUMENTS
.AS Tcl_DString newLength
.AP Tcl_DString *dsPtr in/out
Pointer to structure that is used to manage a dynamic string.
.AP "CONST char" *string in
Pointer to characters to add to dynamic string.
.AP int length in
Number of characters from string to add to dynamic string.  If -1,
add all characters up to null terminating character.
.AP int newLength in
New length for dynamic string, not including null terminating
character.
.AP Tcl_Interp *interp in/out
Interpreter whose result is to be set from or moved to the
dynamic string.
.BE
.SH DESCRIPTION
.PP
Dynamic strings provide a mechanism for building up arbitrarily long
strings by gradually appending information.  If the dynamic string is
short then there will be no memory allocation overhead;  as the string
gets larger, additional space will be allocated as needed.
.PP
fBTcl_DStringInitfR initializes a dynamic string to zero length.
The Tcl_DString structure must have been allocated 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, fBTcl_DStringFreefR should
be called first to free up any memory allocated for the old
string.
.PP
fBTcl_DStringAppendfR adds new information to a dynamic string,
allocating more memory for the string if needed.
If fIlengthfR is less than zero then everything in fIstringfR
is appended to the dynamic string;  otherwise fIlengthfR
specifies the number of bytes to append.
fBTcl_DStringAppendfR returns a pointer to the characters of
the new string.  The string can also be retrieved from the
fIstringfR field of the Tcl_DString structure.
.PP
fBTcl_DStringAppendElementfR is similar to fBTcl_DStringAppendfR
except that it doesn't take a fIlengthfR argument (it appends
all of fIstringfR) and it converts the string to a proper list element
before appending.
fBTcl_DStringAppendElementfR 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 `` {'').
fBTcl_DStringAppendElementfR returns a pointer to the
characters of the new string.
.PP
fBTcl_DStringStartSublistfR and fBTcl_DStringEndSublistfR can be
used to create nested lists.
To append a list element that is itself a sublist, first
call fBTcl_DStringStartSublistfR, then call fBTcl_DStringAppendElementfR
for each of the elements in the sublist, then call
fBTcl_DStringEndSublistfR to end the sublist.
fBTcl_DStringStartSublistfR appends a space character if needed,
followed by an open brace;  fBTcl_DStringEndSublistfR appends
a close brace.
Lists can be nested to any depth.
.PP
fBTcl_DStringLengthfR is a macro that returns the current length
of a dynamic string (not including the terminating null character).
fBTcl_DStringValuefR is a  macro that returns a pointer to the
current contents of a dynamic string.
.PP
.PP
fBTcl_DStringSetLengthfR changes the length of a dynamic string.
If fInewLengthfR is less than the string's current length, then
the string is truncated.
If fInewLengthfR 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, fBTcl_DStringSetLengthfR 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.
fBTcl_DStringSetLengthfR does not free up the string's storage space
even if the string is truncated to zero length, so fBTcl_DStringFreefR
will still need to be called.
.PP
fBTcl_DStringTruncfR changes the length of a dynamic string.
This procedure is now deprecated.  fBTcl_DStringSetLengthfR  should
be used instead.
.PP
fBTcl_DStringFreefR should be called when you're finished using
the string.  It frees up any memory that was allocated for the string
and reinitializes the string's value to an empty string.
.PP
fBTcl_DStringResultfR sets the result of fIinterpfR to the value of
the dynamic string given by fIdsPtrfR.  It does this by moving
a pointer from fIdsPtrfR to the interpreter's result.
This saves the cost of allocating new memory and copying the string.
fBTcl_DStringResultfR also reinitializes the dynamic string to
an empty string.
.PP
fBTcl_DStringGetResultfR does the opposite of fBTcl_DStringResultfR.
It sets the value of fIdsPtrfR to the result of fIinterpfR and
it clears fIinterpfR's result.
If possible it does this by moving a pointer rather than by copying
the string.
.SH KEYWORDS
append, dynamic string, free, result

						