ns_dstring(3)
NAME
- Ns_DStringAppend, Ns_DStringAppendArg, Ns_DStringAppen
- dElement, Ns_DStringExport, Ns_DStringFree, Ns_DStringInit,
- Ns_DStringLength, Ns_DStringNAppend, Ns_DStringPop, Ns_DString
- Printf, 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 mem
- ory 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 as
- sociated 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 asso
- ciated with the current Ns_DString.
- The Ns_DString ds of the following code would con
- tain "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 dy- namic string. The string argument is reformatted as a list ele
- ment and added to the current value of the Ns_DString. The re
- turn 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 char
- acters, 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-termi
- nated
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, allo- cating the space for the Ns_DString if necessary. This will ini
- tialize Thread Local Storage (TLS) and configure parameters on
- first use. TLS is a means of storing data associated with a par
- ticular 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 option
- al 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 func- tion 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 constructedabove */
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)