2 '\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" RCS: @(#) $Id: StringObj.3,v 1.5 1999/06/15 01:16:21 hershey Exp $
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
12 '\" .AP type name in/out ?indent?
13 '\" Start paragraph describing an argument to a library procedure.
14 '\" type is type of argument (int, etc.), in/out is either "in", "out",
15 '\" or "in/out" to describe whether procedure reads or modifies arg,
16 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 '\" needed; use .AS below instead)
20 '\" Give maximum sizes of arguments for setting tab stops. Type and
21 '\" name are examples of largest possible arguments that will be passed
22 '\" to .AP later. If args are omitted, default tab stops are used.
25 '\" Start box enclosure. From here until next .BE, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure.
32 '\" Begin code excerpt.
37 '\" .VS ?version? ?br?
38 '\" Begin vertical sidebar, for use in marking newly-changed parts
39 '\" of man pages. The first argument is ignored and used for recording
40 '\" the version when the .VS was added, so that the sidebars can be
41 '\" found and removed when they reach a certain age. If another argument
42 '\" is present, then a line break is forced before starting the sidebar.
45 '\" End of vertical sidebar.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines, in four columns separated
59 '\" End of list of standard options for a Tk widget.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option's name as specified in the class command, dbName gives
64 '\" the option's name in the option database, and dbClass gives
65 '\" the option's class in the option database.
68 '\" Print arg1 underlined, then print arg2 normally.
70 '\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page,
174 .\" draw two sides but no top otherwise.
175 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .nr ^x \\n(^tu+1v-\\n(^Yu
180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
248 Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj \- manipulate Tcl objects as strings
251 \fB#include <tcl.h>\fR
254 \fBTcl_NewStringObj\fR(\fIbytes, length\fR)
258 \fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
262 \fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
266 \fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
270 \fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
273 \fBTcl_GetString\fR(\fIobjPtr\fR)
277 \fBTcl_GetUnicode\fR(\fIobjPtr\fR)
280 \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
283 \fBTcl_GetCharLength\fR(\fIobjPtr\fR)
286 \fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
290 \fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
294 \fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
298 \fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
301 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
304 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
307 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
310 \fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
312 .AS Tcl_Interp *appendObjPtr in/out
314 Points to the first byte of an array of bytes
315 used to set or append to a string object.
316 This byte array may contain embedded null bytes
317 unless \fIlength\fR is negative.
319 The number of bytes to copy from \fIbytes\fR when
320 initializing, setting, or appending to a string object.
321 If negative, all bytes up to the first null are used.
322 .AP Tcl_UniChar *unicode in
323 Points to the first byte of an array of Unicode characters
324 used to set or append to a string object.
325 This byte array may contain embedded null characters
326 unless \fInumChars\fR is negative.
329 The number of Unicode characters to copy from \fIunicode\fR when
330 initializing, setting, or appending to a string object.
331 If negative, all characters up to the first null character are used.
333 The index of the Unicode character to return.
335 The index of the first Unicode character in the Unicode range to be
336 returned as a new object.
338 The index of the last Unicode character in the Unicode range to be
339 returned as a new object.
341 .AP Tcl_Obj *objPtr in/out
342 Points to an object to manipulate.
343 .AP Tcl_Obj *appendObjPtr in
344 The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
345 .AP int *lengthPtr out
346 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
347 the the length of an object's string representation.
349 Null-terminated string value to append to \fIobjPtr\fR.
350 .AP va_list argList in
351 An argument list which must have been initialised using
352 \fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
354 New length for the string value of \fIobjPtr\fR, not including the
355 final NULL character.
357 The number of elements to concatenate.
358 .AP Tcl_Obj *objv[] in
359 The array of objects to concatenate.
364 The procedures described in this manual entry allow Tcl objects to
365 be manipulated as string values. They use the internal representation
366 of the object to store additional information to make the string
367 manipulations more efficient. In particular, they make a series of
368 append operations efficient by allocating extra storage space for the
369 string so that it doesn't have to be copied for each append.
371 Also, indexing and length computations are optimized because the
372 Unicode string representation is calculated and cached as needed.
376 \fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
377 or modify an existing object to hold a copy of the string given by
378 \fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and
379 \fBTcl_SetUnicodeObj\fR create a new object or modify an existing
380 object to hold a copy of the Unicode string given by \fIunicode\fR and
381 \fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
382 return a pointer to a newly created object with reference count zero.
383 All four procedures set the object to hold a copy of the specified
384 string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any
385 old string representation as well as any old internal representation
389 \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's
390 string representation. This is given by the returned byte pointer and
391 (for \fBTcl_GetStringFromObj\fR) length, which is stored in
392 \fIlengthPtr\fR if it is non-NULL. If the object's UTF string
393 representation is invalid (its byte pointer is NULL), the string
394 representation is regenerated from the object's internal
395 representation. The storage referenced by the returned byte pointer
396 is owned by the object manager and should not be modified by the
397 caller. The procedure \fBTcl_GetString\fR is used in the common case
398 where the caller does not need the length of the string
402 \fBTcl_GetUnicode\fR returns an object's value as a Unicode string.
403 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
404 object's Unicode representation.
406 \fBTcl_GetRange\fR returns a newly created object comprised of the
407 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
408 object's Unicode representation. If the object's Unicode
409 representation is invalid, the Unicode representation is regenerated
410 from the object's string representation.
412 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
413 to bytes) in the string object.
415 \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
416 \fIlength\fR to the string representation of the object specified by
417 \fIobjPtr\fR. If the object has an invalid string representation,
418 then an attempt is made to convert \fIbytes\fR is to the Unicode
419 format. If the conversion is successful, then the converted form of
420 \fIbytes\fR is appended to the object's Unicode representation.
421 Otherwise, the object's Unicode representation is invalidated and
422 converted to the UTF format, and \fIbytes\fR is appended to the
423 object's new string representation.
425 \fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
426 \fIunicode\fR and \fInumChars\fR to the object specified by
427 \fIobjPtr\fR. If the object has an invalid Unicode representation,
428 then \fIunicode\fR is converted to the UTF format and appended to the
429 object's string representation. Appends are optimized to handle
430 repeated appends relatively efficiently (it overallocates the string
431 or Unicode space to avoid repeated reallocations and copies of
432 object's string value).
434 \fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
435 appends the string or Unicode value (whichever exists and is best
436 suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to
440 \fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
441 except that it can be passed more than one value to append and
442 each value must be a null-terminated string (i.e. none of the
443 values may contain internal null characters). Any number of
444 \fIstring\fR arguments may be provided, but the last argument
445 must be a NULL pointer to indicate the end of the list.
447 \fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
448 except that instead of taking a variable number of arguments it takes an
451 The \fBTcl_SetObjLength\fR procedure changes the length of the
452 string value of its \fIobjPtr\fR argument. If the \fInewLength\fR
453 argument is greater than the space allocated for the object's
454 string, then the string space is reallocated and the old value
455 is copied to the new space; the bytes between the old length of
456 the string and the new length may have arbitrary values.
457 If the \fInewLength\fR argument is less than the current length
458 of the object's string, with \fIobjPtr->length\fR is reduced without
459 reallocating the string space; the original allocated size for the
460 string is recorded in the object, so that the string length can be
461 enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
462 reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves
463 a null character at \fIobjPtr->bytes[newLength]\fR.
465 The \fBTcl_ConcatObj\fR function returns a new string object whose
466 value is the space-separated concatenation of the string
467 representations of all of the objects in the \fIobjv\fR
468 array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
469 as it copies the string representations of the \fIobjv\fR array to the
470 result. If an element of the \fIobjv\fR array consists of nothing but
471 white space, then that object is ignored entirely. This white-space
472 removal was added to make the output of the \fBconcat\fR command
473 cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
474 newly-created object whose ref count is zero.
477 Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
480 append, internal representation, object, object type, string object,
481 string type, string representation, concat, concatenate, unicode