Provided by: aolserver4-dev_4.5.1-16_amd64 
NAME
Ns_DStringAppend, Ns_DStringAppendArg, Ns_DStringAppendElement, Ns_DStringExport,
Ns_DStringFree, Ns_DStringInit, Ns_DStringLength, Ns_DStringNAppend, Ns_DStringPop,
Ns_DStringPrintf, Ns_DStringPush, Ns_DStringSetLength, Ns_DStringTrunc, Ns_DStringValue,
Ns_DStringVarAppend - library procedures
SYNOPSIS
#include "ns.h"
char *
Ns_DStringAppend(Ns_DString *dsPtr, char *string)
char *
Ns_DStringAppendArg(Ns_DString *dsPtr, char *string)
char *
Ns_DStringAppendElement(Ns_DString *dsPtr, char *string)
char *
Ns_DStringExport(Ns_DString *dsPtr)
void
Ns_DStringFree(Ns_DString *dsPtr)
void
Ns_DStringInit(Ns_DString *dsPtr)
int
Ns_DStringLength(Ns_DString *dsPtr)
char *
Ns_DStringNAppend(Ns_DString *dsPtr, char *string, int length)
Ns_DString *
Ns_DStringPop(void)
char *
Ns_DStringPrintf(Ns_DString *dsPtr, char *fmt,...)
void
Ns_DStringPush(Ns_DString *dsPtr)
void
Ns_DStringSetLength(Ns_DString *dsPtr, int length)
void
Ns_DStringTrunc(Ns_DString *dsPtr, int length)
char *
Ns_DStringValue(Ns_DString *dsPtr)
char *
Ns_DStringVarAppend(Ns_DString *dsPtr, ...)
_________________________________________________________________
DESCRIPTION
These functions create, manipulate and destroy Ns_DStrings. Ns_DStrings are structures
that store strings and information about the string length. These dynamic strings grow as
need to fit the strings placed in them or appended to them. If the Ns_DString plus the
appended string are larger than the size of original string within the Ns_DString, for
example, the Ns_DString will be automatically extended by allocating more memory to it.
Many functions return string pointers that point directly to the string within an
Ns_DString structure. You must not free these returned string pointers with Ns_Free or any
other freeing function, but must instead use Ns_DStringFree to free memory associated with
the Ns_DString.
Ns_DStringAppend(dsPtr, string)
Append the specified string plus a terminating null character to the end of the
Ns_DString. Returns the string associated with the current Ns_DString.
The Ns_DString ds of the following code would contain "foo " and have a length of
3:
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringAppend(&ds, "foo");
/* do something with the dstring */
printf("%s0, ds.string);
/* finished with dstring */
Ns_DStringFree(&ds);
Ns_DStringAppendArg(dsPtr, string)
Append the specified argument plus a terminating null character to the end of the
Ns_DString. It is useful for making strings like "foo bar baz ". The string pointer
associated with the current Ns_DString is returned.
Ns_DStringAppendElement(dsPtr, string)
Append a list element to the current value of a dynamic string. The string argument
is reformatted as a list element and added to the current value of the Ns_DString.
The return value is a pointer to the dynamic string's new value.
Ns_DStringExport(dsPtr)
Returns the current Ns_DString string and leaves the Ns_DString in the initialized
state. In this case, the string returned needs to be freed eventually with Ns_Free
because the string pointer returned is not a part of the Ns_DString any longer.
Ns_DString ds;
char *stringdest;
Ns_DStringInit(&ds);
Ns_DStringAppend(&ds, "foo");
stringdest = Ns_DStringExport(&ds);
/* do something with .stringdest. */
Ns_Free(stringdest);
Ns_DStringFree(dsPtr)
Free any allocated memory used by an Ns_DString.
Ns_DStringInit(dsPtr)
Initialize an Ns_DString. Before using an Ns_DString, you must initialize it with
Ns_DStringInit. Storage for an Ns_DString is often on the stack in the calling
function. The example below shows a typical usage.
int MyFunctions(int a, int b)
{
Ns_DString ds;
Ns_DStringInit(&ds);
/*
* ds is now initialized and ready to
* pass to another function
*/
...
}
Ns_DStringLength(dsPtr)
Return the current length of the string value that is contained within an
Ns_DString.
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringAppend(&ds, "<html></html>");
printf("len=%d0, Ns_DStringLength(&ds));
/* finished with dstring */
Ns_DStringFree(&ds);
Ns_DStringNAppend(dsPtr, string, length)
Append n-characters of string to Ns_DString dsPtr. The function appends a string up
to the specified number of characters, plus a terminating null character. Unlike
the Tcl_DStringAppend function, which only works with string data, the AOLserver
Ns_DStringNAppend function can append binary data. Returns the string associated
with the current Ns_DString.
The resulting Ns_DString in this example, ds would
contain "foo " and have a length of 3:
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringNAppend(&ds, "fooasdf", 3);
printf("%s0, ds.string);
Ns_DStringFree(&ds); /* finished with dstring */
If you need a null-terminated list of null-terminated
strings, such as "foo bar ", you would add one to
the length of the appended strings to get the extra
terminating null character. For example:
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringNAppend(&ds, "foo", 4);
Ns_DStringNAppend(&ds, "bar", 4);
Ns_DStringPop(void)
Pop an Ns_DString from the per-thread cache, allocating the space for the
Ns_DString if necessary. This will initialize Thread Local Storage (TLS) and
configure parameters on first use. TLS is a means of storing data associated with a
particular thread within the thread's context, so that it is always available to
that thread. A pointer to the initialized Ns_DString is returned.
Ns_DStringPrintf(dsPtr, fmt, ...)
Append a formatted string to an Ns_DString. The Ns_DStringPrintf function appends a
string that has been created by calling the sprintf function with the given format
and optional arguments. This function currently uses a fixed length buffer of 1024
characters to sprintf() the data before appending to the Ns_DString.
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringPrintf(&ds, "/path%d", getpid());
/* do something with dstring */
printf ("%s0, ds.string);
/* finished with dstring */
Ns_DStringFree(&ds);
Ns_DStringPush(dsPtr)
Push an Ns_DString onto the per-thread cache. The Ns_DString will be free'd if the
maximum number of entries or the maximum size parameters have been exceeded. The
contents held by the Ns_DString are destroyed.
This is a performance function. Creating Ns_DStrings is a more expensive operation
than cleaning out an already-existing Ns_DString and storing it for later use by
the same thread.
Ns_DStringSetLength(dsPtr, length)
The length of dsPtr is changed to length and a null byte is stored at that position
in the string. If length is larger than the space allocated for dsPtr, then a
panic occurs.
Ns_DStringTrunc(dsPtr, length)
Truncate an Ns_DString. The Ns_DStringTrunc function truncates an Ns_DString to the
given length. Unlike Ns_DStringFree, which truncates the Ns_DString to length 0 and
frees any memory that may have been allocated on the heap, Ns_DStringTrunc allows
you to truncate the string to any length. It maintains any memory allocated on the
heap. This function is useful in a loop where the Ns_DString is likely to overflow
the static space each time through. Using Ns_DStringTrunc instead of Ns_DStringFree
will avoid having the Ns_DString call malloc to obtain the addition space in each
iteration. You will need to call Ns_DStringFree eventually to free any space that
may have been allocated for the Ns_DString.
Ns_DString ds;
int i;
Ns_DStringInit(&ds);
for (i=0; i < 50; i++) {
Ns_DStringPrintf(&ds, "%s%d", "aBigString", i);
/* do something with the dstring constructed above */
Ns_DStringTrunc(&ds, 0);
}
Ns_DStringValue(dsPtr)
Return the current value of an Ns_DString. The Ns_DStringValue macro returns a
pointer to the current value of an Ns_DString. This may be a pointer to the
Ns_DString.s static space or to a string allocated on the heap if the static space
has overflowed. It is not safe to use the value returned by this macro after an
intervening call to Ns_DStringAppend because the Ns_DString string could overflow
to or move within the heap.
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringAppend(&ds, "foo");
/* do something with the dstring */
printf ("%s0, Ns_DStringValue(&ds));
Ns_DStringFree(&ds);
Ns_DStringVarAppend(dsPtr, ...)
Append a variable number of strings to an Ns_DString. The Ns_DStringVarAppend
function appends a variable number of strings to an Ns_DString. The list must end
with NULL.
Ns_DString ds;
Ns_DStringInit(&ds);
Ns_DStringVarAppend(&ds, "foo", "bar", NULL);
/* do something with the dstring */
printf ("%s0, ds.string);
Ns_DStringFree(&ds);
SEE ALSO
nsd(1), info(n)