tcl/doc/GetInt.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tcl.h>\fR
  18 .sp
  19 int
  20 \fBTcl_GetInt\fR(\fIinterp, string, intPtr\fR)
  21 .sp
  22 int
  23 \fBTcl_GetDouble\fR(\fIinterp, string, doublePtr\fR)
  24 .sp
  25 int
  26 \fBTcl_GetBoolean\fR(\fIinterp, string, boolPtr\fR)
  27 .SH ARGUMENTS
  28 .AS Tcl_Interp *doublePtr
  29 .AP Tcl_Interp *interp in
  30 Interpreter to use for error reporting.
  31 .AP "CONST char" *string in
  32 Textual value to be converted.
  33 .AP int *intPtr out
  34 Points to place to store integer value converted from \fIstring\fR.
  35 .AP double *doublePtr out
  36 Points to place to store double-precision floating-point
  37 value converted from \fIstring\fR.
  38 .AP int *boolPtr out
  39 Points to place to store boolean value (0 or 1) converted from \fIstring\fR.
  40 .BE
  41
  42 .SH DESCRIPTION
  43 .PP
  44 These procedures convert from strings to integers or double-precision
  45 floating-point values or booleans (represented as 0- or 1-valued
  46 integers).  Each of the procedures takes a \fIstring\fR argument,
  47 converts it to an internal form of a particular type, and stores
  48 the converted value at the location indicated by the procedure's
  49 third argument.  If all goes well, each of the procedures returns
  50 TCL_OK.  If \fIstring\fR doesn't have the proper syntax for the
  51 desired type then TCL_ERROR is returned, an error message is left
  52 in the interpreter's result, and nothing is stored at *\fIintPtr\fR
  53 or *\fIdoublePtr\fR or *\fIboolPtr\fR.
  54 .PP
  55 \fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection
  56 of integer digits, optionally signed and optionally preceded by
  57 white space.  If the first two characters of \fIstring\fR are ``0x''
  58 then \fIstring\fR is expected to be in hexadecimal form;  otherwise,
  59 if the first character of \fIstring\fR is ``0'' then \fIstring\fR
  60 is expected to be in octal form;  otherwise, \fIstring\fR is
  61 expected to be in decimal form.
  62 .PP
  63 \fBTcl_GetDouble\fR expects \fIstring\fR to consist of a floating-point
  64 number, which is:  white space;  a sign; a sequence of digits;  a
  65 decimal point;  a sequence of digits;  the letter ``e'';  and a
  66 signed decimal exponent.  Any of the fields may be omitted, except that
  67 the digits either before or after the decimal point must be present
  68 and if the ``e'' is present then it must be followed by the
  69 exponent number.
  70 .PP
  71 \fBTcl_GetBoolean\fR expects \fIstring\fR to specify a boolean
  72 value.  If \fIstring\fR is any of \fB0\fR, \fBfalse\fR,
  73 \fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero
  74 value at \fI*boolPtr\fR.
  75 If \fIstring\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
  76 then 1 is stored at \fI*boolPtr\fR.
  77 Any of these values may be abbreviated, and upper-case spellings
  78 are also acceptable.
  79
  80 .SH KEYWORDS
  81 boolean, conversion, double, floating-point, integer