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 .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
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.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .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
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
277 Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj \- manipulate Tcl values as strings
280 \fB#include <tcl.h>\fR
283 \fBTcl_NewStringObj\fR(\fIbytes, length\fR)
286 \fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
289 \fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
292 \fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
295 \fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
298 \fBTcl_GetString\fR(\fIobjPtr\fR)
301 \fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR)
304 \fBTcl_GetUnicode\fR(\fIobjPtr\fR)
307 \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
310 \fBTcl_GetCharLength\fR(\fIobjPtr\fR)
313 \fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
316 \fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
319 \fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
322 \fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
325 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
328 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
331 \fBTcl_AppendLimitedToObj\fR(\fIobjPtr, bytes, length, limit, ellipsis\fR)
334 \fBTcl_Format\fR(\fIinterp, format, objc, objv\fR)
337 \fBTcl_AppendFormatToObj\fR(\fIinterp, objPtr, format, objc, objv\fR)
340 \fBTcl_ObjPrintf\fR(\fIformat, ...\fR)
343 \fBTcl_AppendPrintfToObj\fR(\fIobjPtr, format, ...\fR)
346 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
349 \fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR)
352 \fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
354 .AS "const Tcl_UniChar" *appendObjPtr in/out
355 .AP "const char" *bytes in
356 Points to the first byte of an array of UTF-8-encoded bytes
357 used to set or append to a string value.
358 This byte array may contain embedded null characters
359 unless \fInumChars\fR is negative. (Applications needing null bytes
360 should represent them as the two-byte sequence \fI\e700\e600\fR, use
361 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
362 the string is a collection of uninterpreted bytes.)
364 The number of bytes to copy from \fIbytes\fR when
365 initializing, setting, or appending to a string value.
366 If negative, all bytes up to the first null are used.
367 .AP "const Tcl_UniChar" *unicode in
368 Points to the first byte of an array of Unicode characters
369 used to set or append to a string value.
370 This byte array may contain embedded null characters
371 unless \fInumChars\fR is negative.
373 The number of Unicode characters to copy from \fIunicode\fR when
374 initializing, setting, or appending to a string value.
375 If negative, all characters up to the first null character are used.
377 The index of the Unicode character to return.
379 The index of the first Unicode character in the Unicode range to be
380 returned as a new value.
382 The index of the last Unicode character in the Unicode range to be
383 returned as a new value.
384 .AP Tcl_Obj *objPtr in/out
385 Points to a value to manipulate.
386 .AP Tcl_Obj *appendObjPtr in
387 The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
388 .AP int *lengthPtr out
389 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
390 the length of a value's string representation.
391 .AP "const char" *string in
392 Null-terminated string value to append to \fIobjPtr\fR.
393 .AP va_list argList in
394 An argument list which must have been initialized using
395 \fBva_start\fR, and cleared using \fBva_end\fR.
397 Maximum number of bytes to be appended.
398 .AP "const char" *ellipsis in
399 Suffix to append when the limit leads to string truncation.
400 If NULL is passed then the suffix
403 .AP "const char" *format in
404 Format control string including % conversion specifiers.
406 The number of elements to format or concatenate.
407 .AP Tcl_Obj *objv[] in
408 The array of values to format or concatenate.
410 New length for the string value of \fIobjPtr\fR, not including the
411 final null character.
415 The procedures described in this manual entry allow Tcl values to
416 be manipulated as string values. They use the internal representation
417 of the value to store additional information to make the string
418 manipulations more efficient. In particular, they make a series of
419 append operations efficient by allocating extra storage space for the
420 string so that it does not have to be copied for each append.
421 Also, indexing and length computations are optimized because the
422 Unicode string representation is calculated and cached as needed.
423 When using the \fBTcl_Append*\fR family of functions where the
424 interpreter's result is the value being appended to, it is important
425 to call Tcl_ResetResult first to ensure you are not unintentionally
426 appending to existing data in the result value.
428 \fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new value
429 or modify an existing value to hold a copy of the string given by
430 \fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and
431 \fBTcl_SetUnicodeObj\fR create a new value or modify an existing
432 value to hold a copy of the Unicode string given by \fIunicode\fR and
433 \fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
434 return a pointer to a newly created value with reference count zero.
435 All four procedures set the value to hold a copy of the specified
436 string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any
437 old string representation as well as any old internal representation
440 \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return a value's
441 string representation. This is given by the returned byte pointer and
442 (for \fBTcl_GetStringFromObj\fR) length, which is stored in
443 \fIlengthPtr\fR if it is non-NULL. If the value's UTF string
444 representation is invalid (its byte pointer is NULL), the string
445 representation is regenerated from the value's internal
446 representation. The storage referenced by the returned byte pointer
447 is owned by the value manager. It is passed back as a writable
448 pointer so that extension author creating their own \fBTcl_ObjType\fR
449 will be able to modify the string representation within the
450 \fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that
451 limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR
452 or \fBTcl_GetString\fR should be treated as read-only. It is
453 recommended that this pointer be assigned to a (const char *) variable.
454 Even in the limited situations where writing to this pointer is
455 acceptable, one should take care to respect the copy-on-write
456 semantics required by \fBTcl_Obj\fR's, with appropriate calls
457 to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any
458 in-place modification of the string representation.
459 The procedure \fBTcl_GetString\fR is used in the common case
460 where the caller does not need the length of the string
463 \fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return a value's
464 value as a Unicode string. This is given by the returned pointer and
465 (for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in
466 \fIlengthPtr\fR if it is non-NULL. The storage referenced by the returned
467 byte pointer is owned by the value manager and should not be modified by
468 the caller. The procedure \fBTcl_GetUnicode\fR is used in the common case
469 where the caller does not need the length of the unicode string
472 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
473 value's Unicode representation.
475 \fBTcl_GetRange\fR returns a newly created value comprised of the
476 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
477 value's Unicode representation. If the value's Unicode
478 representation is invalid, the Unicode representation is regenerated
479 from the value's string representation.
481 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
482 to bytes) in the string value.
484 \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
485 \fIlength\fR to the string representation of the value specified by
486 \fIobjPtr\fR. If the value has an invalid string representation,
487 then an attempt is made to convert \fIbytes\fR is to the Unicode
488 format. If the conversion is successful, then the converted form of
489 \fIbytes\fR is appended to the value's Unicode representation.
490 Otherwise, the value's Unicode representation is invalidated and
491 converted to the UTF format, and \fIbytes\fR is appended to the
492 value's new string representation.
494 \fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
495 \fIunicode\fR and \fInumChars\fR to the value specified by
496 \fIobjPtr\fR. If the value has an invalid Unicode representation,
497 then \fIunicode\fR is converted to the UTF format and appended to the
498 value's string representation. Appends are optimized to handle
499 repeated appends relatively efficiently (it over-allocates the string
500 or Unicode space to avoid repeated reallocations and copies of
501 value's string value).
503 \fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
504 appends the string or Unicode value (whichever exists and is best
505 suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to
508 \fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
509 except that it can be passed more than one value to append and
510 each value must be a null-terminated string (i.e. none of the
511 values may contain internal null characters). Any number of
512 \fIstring\fR arguments may be provided, but the last argument
513 must be a NULL pointer to indicate the end of the list.
515 \fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
516 except that instead of taking a variable number of arguments it takes an
519 \fBTcl_AppendLimitedToObj\fR is similar to \fBTcl_AppendToObj\fR
520 except that it imposes a limit on how many bytes are appended.
521 This can be handy when the string to be appended might be
522 very large, but the value being constructed should not be allowed to grow
523 without bound. A common usage is when constructing an error message, where the
524 end result should be kept short enough to be read.
525 Bytes from \fIbytes\fR are appended to \fIobjPtr\fR, but no more
526 than \fIlimit\fR bytes total are to be appended. If the limit prevents
527 all \fIlength\fR bytes that are available from being appended, then the
528 appending is done so that the last bytes appended are from the
529 string \fIellipsis\fR. This allows for an indication of the truncation
530 to be left in the string.
531 When \fIlength\fR is \fB-1\fR, all bytes up to the first zero byte are appended,
532 subject to the limit. When \fIellipsis\fR is NULL, the default
533 string \fB...\fR is used. When \fIellipsis\fR is non-NULL, it must point
534 to a zero-byte-terminated string in Tcl's internal UTF encoding.
535 The number of bytes appended can be less than the lesser
536 of \fIlength\fR and \fIlimit\fR when appending fewer
537 bytes is necessary to append only whole multi-byte characters.
539 \fBTcl_Format\fR is the C-level interface to the engine of the \fBformat\fR
540 command. The actual command procedure for \fBformat\fR is little more
544 \fBTcl_Format\fR(interp, \fBTcl_GetString\fR(objv[1]), objc-2, objv+2);
547 The \fIobjc\fR Tcl_Obj values in \fIobjv\fR are formatted into a string
548 according to the conversion specification in \fIformat\fR argument, following
549 the documentation for the \fBformat\fR command. The resulting formatted
550 string is converted to a new Tcl_Obj with refcount of zero and returned.
551 If some error happens during production of the formatted string, NULL is
552 returned, and an error message is recorded in \fIinterp\fR, if \fIinterp\fR
555 \fBTcl_AppendFormatToObj\fR is an appending alternative form
556 of \fBTcl_Format\fR with functionality equivalent to:
559 Tcl_Obj *newPtr = \fBTcl_Format\fR(interp, format, objc, objv);
560 if (newPtr == NULL) return TCL_ERROR;
561 \fBTcl_AppendObjToObj\fR(objPtr, newPtr);
562 \fBTcl_DecrRefCount\fR(newPtr);
566 but with greater convenience and efficiency when the appending
567 functionality is needed.
569 \fBTcl_ObjPrintf\fR serves as a replacement for the common sequence
572 char buf[SOME_SUITABLE_LENGTH];
573 sprintf(buf, format, ...);
574 \fBTcl_NewStringObj\fR(buf, -1);
577 but with greater convenience and no need to
578 determine \fBSOME_SUITABLE_LENGTH\fR. The formatting is done with the same
579 core formatting engine used by \fBTcl_Format\fR. This means the set of
580 supported conversion specifiers is that of the \fBformat\fR command and
581 not that of the \fBsprintf\fR routine where the two sets differ. When a
582 conversion specifier passed to \fBTcl_ObjPrintf\fR includes a precision,
583 the value is taken as a number of bytes, as \fBsprintf\fR does, and not
584 as a number of characters, as \fBformat\fR does. This is done on the
585 assumption that C code is more likely to know how many bytes it is
586 passing around than the number of encoded characters those bytes happen
587 to represent. The variable number of arguments passed in should be of
588 the types that would be suitable for passing to \fBsprintf\fR. Note in
589 this example usage, \fIx\fR is of type \fBint\fR.
593 Tcl_Obj *objPtr = \fBTcl_ObjPrintf\fR("Value is %d", x);
596 If the value of \fIformat\fR contains internal inconsistencies or invalid
597 specifier formats, the formatted string result produced by
598 \fBTcl_ObjPrintf\fR will be an error message describing the error.
599 It is impossible however to provide runtime protection against
600 mismatches between the format and any subsequent arguments.
601 Compile-time protection may be provided by some compilers.
603 \fBTcl_AppendPrintfToObj\fR is an appending alternative form
604 of \fBTcl_ObjPrintf\fR with functionality equivalent to
607 Tcl_Obj *newPtr = \fBTcl_ObjPrintf\fR(format, ...);
608 \fBTcl_AppendObjToObj\fR(objPtr, newPtr);
609 \fBTcl_DecrRefCount\fR(newPtr);
612 but with greater convenience and efficiency when the appending
613 functionality is needed.
615 The \fBTcl_SetObjLength\fR procedure changes the length of the
616 string value of its \fIobjPtr\fR argument. If the \fInewLength\fR
617 argument is greater than the space allocated for the value's
618 string, then the string space is reallocated and the old value
619 is copied to the new space; the bytes between the old length of
620 the string and the new length may have arbitrary values.
621 If the \fInewLength\fR argument is less than the current length
622 of the value's string, with \fIobjPtr->length\fR is reduced without
623 reallocating the string space; the original allocated size for the
624 string is recorded in the value, so that the string length can be
625 enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
626 reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves
627 a null character at \fIobjPtr->bytes[newLength]\fR.
629 \fBTcl_AttemptSetObjLength\fR is identical in function to
630 \fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the
631 request cannot be allocated, it does not cause the Tcl interpreter to
632 \fBpanic\fR. Thus, if \fInewLength\fR is greater than the space
633 allocated for the value's string, and there is not enough memory
634 available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take
635 no action and return 0 to indicate failure. If there is enough memory
636 to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like
637 \fBTcl_SetObjLength\fR and returns 1 to indicate success.
639 The \fBTcl_ConcatObj\fR function returns a new string value whose
640 value is the space-separated concatenation of the string
641 representations of all of the values in the \fIobjv\fR
642 array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
643 as it copies the string representations of the \fIobjv\fR array to the
644 result. If an element of the \fIobjv\fR array consists of nothing but
645 white space, then that value is ignored entirely. This white-space
646 removal was added to make the output of the \fBconcat\fR command
647 cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
648 newly-created value whose ref count is zero.
650 Tcl_NewObj(3), Tcl_IncrRefCount(3), Tcl_DecrRefCount(3), format(n), sprintf(3)
652 append, internal representation, value, value type, string value,
653 string type, string representation, concat, concatenate, unicode
OSDN Git Service
