Tcl Source Code

Check-in [42933eedc8]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:more fine-tuning of the revised docs
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 42933eedc8255c64f2ec83394cb8d27f62743fa2
User & Date: dgp 2006-04-18 18:06:48.000
Context
2006-04-19
16:43
fix for Martin Lemburg's DST conversion bug. http://groups.google.com/group/comp.lang.tcl/browse_thr... check-in: 48bbbafac1 user: kennykb tags: trunk
2006-04-18
18:06
more fine-tuning of the revised docs check-in: 42933eedc8 user: dgp tags: trunk
18:05
formatting fixes and note change that ::tcl_precision is now per-thread instead of per-process. check-in: e80c168dc6 user: dgp tags: trunk
Changes
Unified Diff Ignore Whitespace Patch
Changes to doc/IntObj.3.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: IntObj.3,v 1.10 2006/04/18 15:13:53 dkf Exp $
'\" 
.so man.macros
.TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_GetBignumAndClearObj \- manipulate Tcl_Obj values as integers
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewIntObj\fR(\fIintValue\fR)
.sp






|





|







1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: IntObj.3,v 1.11 2006/04/18 18:06:48 dgp Exp $
'\" 
.so man.macros
.TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_GetBignumAndClearObj \- manipulate Tcl objects as integer values
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewIntObj\fR(\fIintValue\fR)
.sp
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
\fBTcl_GetBignumAndClearObj\fR, this refers to the object from which
to retrieve an integral value.
.AP Tcl_Interp *interp in/out
When non-NULL, an error message is left here when integral value
retrieval fails.
.AP int *intPtr out
Points to place to store the integer value
obtained by \fBTcl_GetIntFromObj\fR from \fIobjPtr\fR.
.AP long *longPtr out
Points to place to store the long integer value
obtained by \fBTcl_GetLongFromObj\fR from \fIobjPtr\fR.
.AP Tcl_WideInt *widePtr out
Points to place to store the wide integer value
obtained by \fBTcl_GetWideIntFromObj\fR from \fIobjPtr\fR.
.AP mp_int *bigValue in/out
.VS 8.5
Points to a multi-precision integer structure consistent with
one declared by headers of the libtommath library.
.VE 8.5
.BE

.SH DESCRIPTION
.PP
.VS 8.5
These procedures are used to create, modify, and read Tcl objects







|
<

|
<

|
<


|
|







69
70
71
72
73
74
75
76

77
78

79
80

81
82
83
84
85
86
87
88
89
90
91
\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
\fBTcl_GetBignumAndClearObj\fR, this refers to the object from which
to retrieve an integral value.
.AP Tcl_Interp *interp in/out
When non-NULL, an error message is left here when integral value
retrieval fails.
.AP int *intPtr out
Points to place to store the integer value retrieved from \fIobjPtr\fR.

.AP long *longPtr out
Points to place to store the long integer value retrieved from \fIobjPtr\fR.

.AP Tcl_WideInt *widePtr out
Points to place to store the wide integer value retrieved from \fIobjPtr\fR.

.AP mp_int *bigValue in/out
.VS 8.5
Points to a multi-precision integer structure declared by the LibTomMath
library.
.VE 8.5
.BE

.SH DESCRIPTION
.PP
.VS 8.5
These procedures are used to create, modify, and read Tcl objects
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
and \fBTcl_NewBignumObj\fR routines each create and return a new
Tcl object initialized to the integral value of the argument.  The
returned Tcl object is unshared.
.PP
The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
and \fBTcl_SetBignumObj\fR routines each set the value of an existing
\fBTcl_Obj\fR pointed to by \fIobjPtr\fR to the integral value provided
by the other argument.  The \fIobjPtr\fR argument must point to an
unshared Tcl object.  Any attempt to set the value of a shared Tcl object
violates Tcl's copy-on-write policy.  Any existing string representation
or internal representation in the unshared Tcl object will be freed
as a consequence of setting the new value.
.PP
The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
\fBTcl_GetBignumAndClearObj\fR attempt to retrieve an integral value
of the appropriate type from the Tcl object \fIobjPtr\fR.  If the
attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
written to the storage provided by the caller.  The attempt might
fail if \fIobjPtr\fR does not hold an integral value, or if the
value exceeds the range of the target type.  If the attempt fails,
then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
of \fIobjPtr\fR may be changed to make subsequent calls to the
same routine more efficient. Unlike the other functions,
\fBTcl_GetBignumAndClearObj\fR may set the content of the Tcl object
\fIobjPtr\fR to an empty string in the process of retrieving the
multiple-precision integer library.
.PP
The choice between \fBTcl_GetBignumFromObj\fR and
\fBTcl_GetBignumAndClearObj\fR is governed by how the caller will
continue to use \fIobjPtr\fR.  If after the \fBmp_int\fR value
is retrieved from \fIobjPtr\fR, the caller will make no more
use of \fIobjPtr\fR, and in addition if \fIobjPtr\fR is unshared,
then using \fBTcl_GetBignumAndClearObj\fR requires less copying







|








|
|










|







106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
The \fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR, \fBTcl_NewWideIntObj\fR,
and \fBTcl_NewBignumObj\fR routines each create and return a new
Tcl object initialized to the integral value of the argument.  The
returned Tcl object is unshared.
.PP
The \fBTcl_SetIntObj\fR, \fBTcl_SetLongObj\fR, \fBTcl_SetWideIntObj\fR,
and \fBTcl_SetBignumObj\fR routines each set the value of an existing
Tcl object pointed to by \fIobjPtr\fR to the integral value provided
by the other argument.  The \fIobjPtr\fR argument must point to an
unshared Tcl object.  Any attempt to set the value of a shared Tcl object
violates Tcl's copy-on-write policy.  Any existing string representation
or internal representation in the unshared Tcl object will be freed
as a consequence of setting the new value.
.PP
The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
\fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
\fBTcl_GetBignumAndClearObj\fR routines attempt to retrieve an integral
value of the appropriate type from the Tcl object \fIobjPtr\fR.  If the
attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
written to the storage provided by the caller.  The attempt might
fail if \fIobjPtr\fR does not hold an integral value, or if the
value exceeds the range of the target type.  If the attempt fails,
then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
of \fIobjPtr\fR may be changed to make subsequent calls to the
same routine more efficient. Unlike the other functions,
\fBTcl_GetBignumAndClearObj\fR may set the content of the Tcl object
\fIobjPtr\fR to an empty string in the process of retrieving the
multiple-precision integer value.
.PP
The choice between \fBTcl_GetBignumFromObj\fR and
\fBTcl_GetBignumAndClearObj\fR is governed by how the caller will
continue to use \fIobjPtr\fR.  If after the \fBmp_int\fR value
is retrieved from \fIobjPtr\fR, the caller will make no more
use of \fIobjPtr\fR, and in addition if \fIobjPtr\fR is unshared,
then using \fBTcl_GetBignumAndClearObj\fR requires less copying