--- name: "Ns_DStringAppend" section: "3aolserver" platform: "linux" package: "aolserver4-dev" version: "4.5.1-18.1" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/Ns_DStringAppend/3aolserver" --- # Ns\_DStringAppend(3aolserver) library procedures ``` ``` ## 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, ""); 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)](/info/n.md) ## KEYWORDS