<?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>