Manual Pages for UNIX Darwin command on man StringObj

TclStringObj(3) Tcl Library Procedures TclStringObj(3)

NAME

TclNewStringObj, TclNewUnicodeObj, TclSetStringObj, TclSetUni-

codeObj, TclGetStringFromObj, TclGetString, TclGetUnicodeFromObj, TclGetUnicode, TclGetUniChar, TclGetCharLength, TclGetRange, TclAppendToObj, TclAppendUnicodeToObj, TclAppendStringsToObj, TclAppendStringsToObjVA, TclAppendObjToObj, TclSetObjLength,

TclConcatObj, TclAttemptSetObjLength - manipulate Tcl objects as

strings

SYNOPSIS

##iinncclluuddee <>

TclObj * TTccllNNeewwSSttrriinnggOObbjj(bytes, length) TclObj * TTccllNNeewwUUnniiccooddeeOObbjj(unicode, numChars) void TTccllSSeettSSttrriinnggOObbjj(objPtr, bytes, length) void TTccllSSeettUUnniiccooddeeOObbjj(objPtr, unicode, numChars) char * TTccllGGeettSSttrriinnggFFrroommOObbjj(objPtr, lengthPtr) char * TTccllGGeettSSttrriinngg(objPtr) TclUniChar * TTccllGGeettUUnniiccooddeeFFrroommOObbjj(objPtr, lengthPtr) TclUniChar * TTccllGGeettUUnniiccooddee(objPtr) TclUniChar TTccllGGeettUUnniiCChhaarr(objPtr, index) int TTccllGGeettCChhaarrLLeennggtthh(objPtr) TclObj * TTccllGGeettRRaannggee(objPtr, first, last) void TTccllAAppppeennddTTooOObbjj(objPtr, bytes, length) void TTccllAAppppeennddUUnniiccooddeeTTooOObbjj(objPtr, unicode, numChars) void TTccllAAppppeennddOObbjjTTooOObbjj(objPtr, appendObjPtr) void TTccllAAppppeennddSSttrriinnggssTTooOObbjj(objPtr, string, string, ... ((cchhaarr **)) NNUULLLL) void TTccllAAppppeennddSSttrriinnggssTTooOObbjjVVAA(objPtr, argList) void TTccllSSeettOObbjjLLeennggtthh(objPtr, newLength) int TTccllAAtttteemmppttSSeettOObbjjLLeennggtthh(objPtr, newLength) TclObj * TTccllCCoonnccaattOObbjj(objc, objv) AARRGGUUMMEENNTTSS CONST char *bytes (in) Points to the first byte | of an array of |

UTF-8-encoded bytes used |

to set or append to a | string object. This byte | array should not contain | embedded null bytes |

unless length is nega- |

tive. (Applications | needing null bytes should | represent them as the |

two-byte sequence |

\700\600, use |

TTccllEExxtteerrnnaallTTooUUttff to con- |

vert, or TTccllNNeewwBByytteeAArr- |

rraayyOObbjj if the string is a |

collection of uninter- |

preted bytes.) int length (in) The number of bytes to

copy from bytes when ini-

tializing, setting, or appending to a string object. If negative, all bytes up to the first null are used. CONST TclUniChar *unicode (in) Points to the first byte of an array of Unicode characters used to set or append to a string object. This byte array may contain embedded null

characters unless num-

Chars is negative. int numChars (in) The number of Unicode characters to copy from

unicode when initializ-

ing, setting, or append-

ing to a string object.

If negative, all charac-

ters up to the first null character are used. int index (in) The index of the Unicode character to return. int first (in) The index of the first Unicode character in the Unicode range to be returned as a new object. int last (in) The index of the last Unicode character in the Unicode range to be returned as a new object. TclObj *objPtr (in/out) Points to an object to manipulate. TclObj *appendObjPtr (in) The object to append to

objPtr in TTccllAAppppeennddOObbjj-

TTooOObbjj.

int *lengthPtr (out) If non-NULL, the location

where TTccllGGeettSSttrriinnggFFrroo-

mmOObbjj will store the the length of an object's string representation.

CONST char *string (in) Null-terminated string

value to append to objPtr. valist argList (in) An argument list which

must have been ini-

tialised using TTCCLLVVAARRAARRGGSSSSTTAARRTT, and cleared using vvaaeenndd. int newLength (in) New length for the string value of objPtr, not including the final null character. int objc (in) The number of elements to concatenate. TclObj *objv[] (in) The array of objects to concatenate.

DESCRIPTION

The procedures described in this manual entry allow Tcl objects to be manipulated as string values. They use the internal representation of

the object to store additional information to make the string manipula-

tions more efficient. In particular, they make a series of append operations efficient by allocating extra storage space for the string so that it doesn't have to be copied for each append. Also, indexing

and length computations are optimized because the Unicode string repre-

sentation is calculated and cached as needed. When using the TTccllAAppppeenndd** family of functions where the interpreter's result is the object being appended to, it is important to call TclResetResult first to ensure you are not unintentionally appending to existing data in the result object. TTccllNNeewwSSttrriinnggOObbjj and TTccllSSeettSSttrriinnggOObbjj create a new object or modify an existing object to hold a copy of the string given by bytes and length. TTccllNNeewwUUnniiccooddeeOObbjj and TTccllSSeettUUnniiccooddeeOObbjj create a new object or modify

an existing object to hold a copy of the Unicode string given by uni-

code and numChars. TTccllNNeewwSSttrriinnggOObbjj and TTccllNNeewwUUnniiccooddeeOObbjj return a pointer to a newly created object with reference count zero. All four procedures set the object to hold a copy of the specified string.

TTccllSSeettSSttrriinnggOObbjj and TTccllSSeettUUnniiccooddeeOObbjj free any old string representa-

tion as well as any old internal representation of the object.

TTccllGGeettSSttrriinnggFFrroommOObbjj and TTccllGGeettSSttrriinngg return an object's string repre-

sentation. This is given by the returned byte pointer and (for TTccllGGeettSSttrriinnggFFrroommOObbjj) length, which is stored in lengthPtr if it is

non-NULL. If the object's UTF string representation is invalid (its

byte pointer is NULL), the string representation is regenerated from the object's internal representation. The storage referenced by the returned byte pointer is owned by the object manager. It is passed back as a writable pointer so that extension author creating their own TTccllOObbjjTTyyppee will be able to modify the string representation within the TTccllUUppddaatteeSSttrriinnggPPrroocc of their TTccllOObbjjTTyyppee. Except for that limited purpose, the pointer returned by TTccllGGeettSSttrriinnggFFrroommOObbjj or TTccllGGeettSSttrriinngg

should be treated as read-only. It is recommended that this pointer be

assigned to a (CONST char *) variable. Even in the limited situations where writing to this pointer is acceptable, one should take care to

respect the copy-on-write semantics required by TTccllOObbjj's, with appro-

priate calls to TTccllIIssSShhaarreedd and TTccllDDuupplliiccaatteeOObbjj prior to any in-place

modification of the string representation. The procedure TTccllGGeettSSttrriinngg is used in the common case where the caller does not need the length of the string representation. TTccllGGeettUUnniiccooddeeFFrroommOObbjj and TTccllGGeettUUnniiccooddee return an object's value as a Unicode string. This is given by the returned pointer and (for TTccllGGeettUUnniiccooddeeFFrroommOObbjj) length, which is stored in lengthPtr if it is

non-NULL. The storage referenced by the returned byte pointer is owned

by the object manager and should not be modified by the caller. The procedure TTccllGGeettUUnniiccooddee is used in the common case where the caller does not need the length of the unicode string representation. TTccllGGeettUUnniiCChhaarr returns the index'th character in the object's Unicode representation. TTccllGGeettRRaannggee returns a newly created object comprised of the characters

between first and last (inclusive) in the object's Unicode representa-

tion. If the object's Unicode representation is invalid, the Unicode representation is regenerated from the object's string representation. TTccllGGeettCChhaarrLLeennggtthh returns the number of characters (as opposed to bytes) in the string object. TTccllAAppppeennddTTooOObbjj appends the data given by bytes and length to the string representation of the object specified by objPtr. If the object

has an invalid string representation, then an attempt is made to con-

vert bytes is to the Unicode format. If the conversion is successful, then the converted form of bytes is appended to the object's Unicode representation. Otherwise, the object's Unicode representation is invalidated and converted to the UTF format, and bytes is appended to the object's new string representation. TTccllAAppppeennddUUnniiccooddeeTTooOObbjj appends the Unicode string given by unicode and numChars to the object specified by objPtr. If the object has an invalid Unicode representation, then unicode is converted to the UTF format and appended to the object's string representation. Appends are

optimized to handle repeated appends relatively efficiently (it overal-

locates the string or Unicode space to avoid repeated reallocations and copies of object's string value). TTccllAAppppeennddOObbjjTTooOObbjj is similar to TTccllAAppppeennddTTooOObbjj, but it appends the string or Unicode value (whichever exists and is best suited to be appended to objPtr) of appendObjPtr to objPtr. TTccllAAppppeennddSSttrriinnggssTTooOObbjj is similar to TTccllAAppppeennddTTooOObbjj except that it can

be passed more than one value to append and each value must be a null-

terminated string (i.e. none of the values may contain internal null characters). Any number of string arguments may be provided, but the last argument must be a NULL pointer to indicate the end of the list. TTccllAAppppeennddSSttrriinnggssTTooOObbjjVVAA is the same as TTccllAAppppeennddSSttrriinnggssTTooOObbjj except

that instead of taking a variable number of arguments it takes an argu-

ment list. The TTccllSSeettOObbjjLLeennggtthh procedure changes the length of the string value of its objPtr argument. If the newLength argument is greater than the

space allocated for the object's string, then the string space is real-

located and the old value is copied to the new space; the bytes between

the old length of the string and the new length may have arbitrary val-

ues. If the newLength argument is less than the current length of the

object's string, with objPtr->length is reduced without reallocating

the string space; the original allocated size for the string is recorded in the object, so that the string length can be enlarged in a subsequent call to TTccllSSeettOObbjjLLeennggtthh without reallocating storage. In all cases TTccllSSeettOObbjjLLeennggtthh leaves a null character at

objPtr->bytes[newLength].

TTccllAAtttteemmppttSSeettOObbjjLLeennggtthh is identical in function to TTccllSSeettOObbjjLLeennggtthh

except that if sufficient memory to satisfy the request cannot be allo-

cated, it does not cause the Tcl interpreter to ppaanniicc. Thus, if newLength is greater than the space allocated for the object's string, and there is not enough memory available to satisfy the request, TTccllAAtttteemmppttSSeettOObbjjLLeennggtthh will take no action and return 0 to indicate failure. If there is enough memory to satisfy the request, TTccllAAtttteemmppttSSeettOObbjjLLeennggtthh behaves just like TTccllSSeettOObbjjLLeennggtthh and returns 1 to indicate success. The TTccllCCoonnccaattOObbjj function returns a new string object whose value is

the space-separated concatenation of the string representations of all

of the objects in the objv array. TTccllCCoonnccaattOObbjj eliminates leading and trailing white space as it copies the string representations of the objv array to the result. If an element of the objv array consists of nothing but white space, then that object is ignored entirely. This

white-space removal was added to make the output of the ccoonnccaatt command

cleaner-looking. TTccllCCoonnccaattOObbjj returns a pointer to a newly-created

object whose ref count is zero.