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.13.2.1 2003/07/18 16:56:24 dgp 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.4 2000/08/25 06:18:32 ericm 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_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendStringsToObj, Tcl_AppendStringsToObjVA, Tcl_AppendObjToObj, Tcl_SetObjLength, Tcl_ConcatObj, Tcl_AttemptSetObjLength \- manipulate Tcl objects as strings
251 \fB#include <tcl.h>\fR
254 \fBTcl_NewStringObj\fR(\fIbytes, length\fR)
257 \fBTcl_NewUnicodeObj\fR(\fIunicode, numChars\fR)
260 \fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
263 \fBTcl_SetUnicodeObj\fR(\fIobjPtr, unicode, numChars\fR)
266 \fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
269 \fBTcl_GetString\fR(\fIobjPtr\fR)
272 \fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR)
275 \fBTcl_GetUnicode\fR(\fIobjPtr\fR)
278 \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
281 \fBTcl_GetCharLength\fR(\fIobjPtr\fR)
284 \fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
287 \fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
290 \fBTcl_AppendUnicodeToObj\fR(\fIobjPtr, unicode, numChars\fR)
293 \fBTcl_AppendObjToObj\fR(\fIobjPtr, appendObjPtr\fR)
296 \fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
299 \fBTcl_AppendStringsToObjVA\fR(\fIobjPtr, argList\fR)
302 \fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
305 \fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR)
308 \fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
310 .AS "CONST Tcl_UniChar" *appendObjPtr in/out
311 .AP "CONST char" *bytes in
313 Points to the first byte of an array of UTF-8-encoded bytes
314 used to set or append to a string object.
315 This byte array should not contain embedded null bytes
316 unless \fIlength\fR is negative. (Applications needing null bytes
317 should represent them as the two-byte sequence \fI\\700\\600\fR, use
318 \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
319 the string is a collection of uninterpreted bytes.)
322 The number of bytes to copy from \fIbytes\fR when
323 initializing, setting, or appending to a string object.
324 If negative, all bytes up to the first null are used.
325 .AP "CONST Tcl_UniChar" *unicode in
326 Points to the first byte of an array of Unicode characters
327 used to set or append to a string object.
328 This byte array may contain embedded null characters
329 unless \fInumChars\fR is negative.
331 The number of Unicode characters to copy from \fIunicode\fR when
332 initializing, setting, or appending to a string object.
333 If negative, all characters up to the first null character are used.
335 The index of the Unicode character to return.
337 The index of the first Unicode character in the Unicode range to be
338 returned as a new object.
340 The index of the last Unicode character in the Unicode range to be
341 returned as a new object.
342 .AP Tcl_Obj *objPtr in/out
343 Points to an object to manipulate.
344 .AP Tcl_Obj *appendObjPtr in
345 The object to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
346 .AP int *lengthPtr out
347 If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
348 the the length of an object's string representation.
349 .AP "CONST char" *string in
350 Null-terminated string value to append to \fIobjPtr\fR.
351 .AP va_list argList in
352 An argument list which must have been initialised using
353 \fBTCL_VARARGS_START\fR, and cleared using \fBva_end\fR.
355 New length for the string value of \fIobjPtr\fR, not including the
356 final null character.
358 The number of elements to concatenate.
359 .AP Tcl_Obj *objv[] in
360 The array of objects to concatenate.
365 The procedures described in this manual entry allow Tcl objects to
366 be manipulated as string values. They use the internal representation
367 of the object to store additional information to make the string
368 manipulations more efficient. In particular, they make a series of
369 append operations efficient by allocating extra storage space for the
370 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.
373 When using the \fBTcl_Append*\fR family of functions where the
374 interpreter's result is the object being appended to, it is important
375 to call Tcl_ResetResult first to ensure you are not unintentionally
376 appending to existing data in the result object.
378 \fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
379 or modify an existing object to hold a copy of the string given by
380 \fIbytes\fR and \fIlength\fR. \fBTcl_NewUnicodeObj\fR and
381 \fBTcl_SetUnicodeObj\fR create a new object or modify an existing
382 object to hold a copy of the Unicode string given by \fIunicode\fR and
383 \fInumChars\fR. \fBTcl_NewStringObj\fR and \fBTcl_NewUnicodeObj\fR
384 return a pointer to a newly created object with reference count zero.
385 All four procedures set the object to hold a copy of the specified
386 string. \fBTcl_SetStringObj\fR and \fBTcl_SetUnicodeObj\fR free any
387 old string representation as well as any old internal representation
390 \fBTcl_GetStringFromObj\fR and \fBTcl_GetString\fR return an object's
391 string representation. This is given by the returned byte pointer and
392 (for \fBTcl_GetStringFromObj\fR) length, which is stored in
393 \fIlengthPtr\fR if it is non-NULL. If the object's UTF string
394 representation is invalid (its byte pointer is NULL), the string
395 representation is regenerated from the object's internal
396 representation. The storage referenced by the returned byte pointer
397 is owned by the object manager. It is passed back as a writable
398 pointer so that extension author creating their own \fBTcl_ObjType\fR
399 will be able to modify the string representation within the
400 \fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR. Except for that
401 limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR
402 or \fBTcl_GetString\fR should be treated as read-only. It is
403 recommended that this pointer be assigned to a (CONST char *) variable.
404 Even in the limited situations where writing to this pointer is
405 acceptable, one should take care to respect the copy-on-write
406 semantics required by \fBTcl_Obj\fR's, with appropriate calls
407 to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any
408 in-place modification of the string representation.
409 The procedure \fBTcl_GetString\fR is used in the common case
410 where the caller does not need the length of the string
413 \fBTcl_GetUnicodeFromObj\fR and \fBTcl_GetUnicode\fR return an object's
414 value as a Unicode string. This is given by the returned pointer and
415 (for \fBTcl_GetUnicodeFromObj\fR) length, which is stored in
416 \fIlengthPtr\fR if it is non-NULL. The storage referenced by the returned
417 byte pointer is owned by the object manager and should not be modified by
418 the caller. The procedure \fBTcl_GetUnicode\fR is used in the common case
419 where the caller does not need the length of the unicode string
422 \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
423 object's Unicode representation.
425 \fBTcl_GetRange\fR returns a newly created object comprised of the
426 characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
427 object's Unicode representation. If the object's Unicode
428 representation is invalid, the Unicode representation is regenerated
429 from the object's string representation.
431 \fBTcl_GetCharLength\fR returns the number of characters (as opposed
432 to bytes) in the string object.
434 \fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
435 \fIlength\fR to the string representation of the object specified by
436 \fIobjPtr\fR. If the object has an invalid string representation,
437 then an attempt is made to convert \fIbytes\fR is to the Unicode
438 format. If the conversion is successful, then the converted form of
439 \fIbytes\fR is appended to the object's Unicode representation.
440 Otherwise, the object's Unicode representation is invalidated and
441 converted to the UTF format, and \fIbytes\fR is appended to the
442 object's new string representation.
444 \fBTcl_AppendUnicodeToObj\fR appends the Unicode string given by
445 \fIunicode\fR and \fInumChars\fR to the object specified by
446 \fIobjPtr\fR. If the object has an invalid Unicode representation,
447 then \fIunicode\fR is converted to the UTF format and appended to the
448 object's string representation. Appends are optimized to handle
449 repeated appends relatively efficiently (it overallocates the string
450 or Unicode space to avoid repeated reallocations and copies of
451 object's string value).
453 \fBTcl_AppendObjToObj\fR is similar to \fBTcl_AppendToObj\fR, but it
454 appends the string or Unicode value (whichever exists and is best
455 suited to be appended to \fIobjPtr\fR) of \fIappendObjPtr\fR to
458 \fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
459 except that it can be passed more than one value to append and
460 each value must be a null-terminated string (i.e. none of the
461 values may contain internal null characters). Any number of
462 \fIstring\fR arguments may be provided, but the last argument
463 must be a NULL pointer to indicate the end of the list.
465 \fBTcl_AppendStringsToObjVA\fR is the same as \fBTcl_AppendStringsToObj\fR
466 except that instead of taking a variable number of arguments it takes an
469 The \fBTcl_SetObjLength\fR procedure changes the length of the
470 string value of its \fIobjPtr\fR argument. If the \fInewLength\fR
471 argument is greater than the space allocated for the object's
472 string, then the string space is reallocated and the old value
473 is copied to the new space; the bytes between the old length of
474 the string and the new length may have arbitrary values.
475 If the \fInewLength\fR argument is less than the current length
476 of the object's string, with \fIobjPtr->length\fR is reduced without
477 reallocating the string space; the original allocated size for the
478 string is recorded in the object, so that the string length can be
479 enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
480 reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves
481 a null character at \fIobjPtr->bytes[newLength]\fR.
483 \fBTcl_AttemptSetObjLength\fR is identical in function to
484 \fBTcl_SetObjLength\fR except that if sufficient memory to satisfy the
485 request cannot be allocated, it does not cause the Tcl interpreter to
486 \fBpanic\fR. Thus, if \fInewLength\fR is greater than the space
487 allocated for the object's string, and there is not enough memory
488 available to satisfy the request, \fBTcl_AttemptSetObjLength\fR will take
489 no action and return 0 to indicate failure. If there is enough memory
490 to satisfy the request, \fBTcl_AttemptSetObjLength\fR behaves just like
491 \fBTcl_SetObjLength\fR and returns 1 to indicate success.
493 The \fBTcl_ConcatObj\fR function returns a new string object whose
494 value is the space-separated concatenation of the string
495 representations of all of the objects in the \fIobjv\fR
496 array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
497 as it copies the string representations of the \fIobjv\fR array to the
498 result. If an element of the \fIobjv\fR array consists of nothing but
499 white space, then that object is ignored entirely. This white-space
500 removal was added to make the output of the \fBconcat\fR command
501 cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
502 newly-created object whose ref count is zero.
505 Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
508 append, internal representation, object, object type, string object,
509 string type, string representation, concat, concatenate, unicode
OSDN Git Service
