<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-E525E177-1FE5-5845-9BF8-B76D434B838D" xml:lang="en"><title>Integral
types</title><shortdesc>This document describes the integer data types.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p><xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> is the natural machine word integer and should
be used in all general contexts where integer arithmetic is desired.</p>
<p><xref href="GUID-49ACAE7B-1FE4-3BA6-8772-F104D3F01E41.dita"><apiname>TInt32</apiname></xref>, <xref href="GUID-6BE0B3FC-2B36-3982-AA51-971F3354925E.dita"><apiname>TInt16</apiname></xref>, and <xref href="GUID-F2669E84-D47E-3C83-A549-D77A883787CC.dita"><apiname>TInt8</apiname></xref> map
onto C++ built-in types in most implementations. These types should only be
used where the size of the integer is of first importance: sometimes, this
is relevant for C++ arrays and struct/class members. Note that C++ passes
all function arguments as <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref>, so there is nothing to
be gained by using narrower types in function interfaces.</p>
<p><xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> is an unsigned integer of the natural machine
word size. Experience with C and C++ suggests that unsigned integers are not
suitable for representing quantities whose valid values should always be positive. <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> should
be used in these circumstances instead. The main reasons behind this surprising
assertion are, firstly, that surprises occur when C++ performs implicit type
conversions for arithmetic and assignment, and, secondly, that C++ does not
trap bounds errors, with the result that <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> s which
"accidentally" go negative actually take on very large positive values instead.</p>
<p><xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> should be used for flag and handle words, which
are manipulated using bitwise and equality-comparison operations rather than
arithmetic. <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref> should also be used in exceptional circumstances
where the full range of a machine word is required for arithmetic: this use
is exceptional and must always be carefully controlled.</p>
<p><xref href="GUID-F58A1C0D-1B36-37EA-8012-1C74B2D12CAD.dita"><apiname>TUint32</apiname></xref>, <xref href="GUID-4BB532F8-938E-37C7-9D40-6010EB716E7A.dita"><apiname>TUint16</apiname></xref>, and <xref href="GUID-F894527F-13A6-3E6D-BA7B-187812CDF20E.dita"><apiname>TUint8</apiname></xref> types
are available where the specific representation width is important.</p>
</conbody></concept>