FreeBasic UInteger Keyword

last modified June 16, 2025

The FreeBasic UInteger keyword represents an unsigned integer data type. It can store only positive whole numbers, providing a larger positive range than signed integers of the same size.

Basic Definition

In FreeBasic, UInteger is a 32-bit unsigned integer type. It can store values from 0 to 4,294,967,295 (2³²-1). Unlike signed integers, it cannot represent negative numbers.

UInteger is useful when you need to work with values that should never be negative, like counts, sizes, or memory addresses. It prevents accidental negative values and provides double the positive range of a signed integer.

Declaring UInteger Variables

This example shows how to declare and initialize UInteger variables.

uinteger_declare.bas

Dim population As UInteger
Dim fileSize As UInteger = 1024
Dim maxValue As UInteger = 4294967295

Print "population: "; population
Print "fileSize: "; fileSize
Print "maxValue: "; maxValue

Here we declare three UInteger variables. The first is uninitialized and defaults to 0. The others are explicitly set to 1024 and the maximum UInteger value. Attempting to assign a negative value would cause an error.

UInteger Arithmetic Operations

UInteger supports standard arithmetic operations with some unique behaviors.

uinteger_arithmetic.bas

Dim a As UInteger = 4000000000
Dim b As UInteger = 300000000
Dim result As UInteger

result = a + b
Print "Addition: "; result

result = a - b
Print "Subtraction: "; result

result = a * 2
Print "Multiplication: "; result

result = a \ 2
Print "Division: "; result

This demonstrates arithmetic with large UInteger values. Addition works normally, but subtracting a larger number from smaller would wrap around. Multiplication shows how UInteger can handle very large positive numbers.

UInteger in Loops

UInteger is ideal for loop counters that need a large range.

uinteger_loop.bas

Dim counter As UInteger

For counter = 10 To 0 Step -1
    Print "Countdown: "; counter
    Sleep 500
Next

Print "Blast off!"

This countdown loop uses a UInteger counter. While this specific example doesn't need UInteger's full range, it demonstrates proper usage. Note that the loop stops correctly at 0 despite being unsigned.

UInteger with Bitwise Operations

UInteger works well with bitwise operations since it directly represents binary values.

uinteger_bitwise.bas

Dim flags As UInteger = &b1010
Dim mask As UInteger = &b1100

Print "Original: "; Bin(flags, 32)
Print "AND: "; Bin(flags And mask, 32)
Print "OR: "; Bin(flags Or mask, 32)
Print "XOR: "; Bin(flags Xor mask, 32)
Print "NOT: "; Bin(Not flags, 32)
Print "Shift Left: "; Bin(flags Shl 2, 32)
Print "Shift Right: "; Bin(flags Shr 1, 32)

This example shows various bitwise operations on a UInteger. The Bin function displays the binary representation. UInteger is ideal for bit manipulation as it has no sign bit complications.

UInteger for Memory Addresses

UInteger is often used to handle memory addresses and pointers.

uinteger_memory.bas

Dim buffer(100) As Byte
Dim address As UInteger = Cast(UInteger, @buffer(0))

Print "Buffer address: "; Hex(address)
Print "Buffer size: "; SizeOf(buffer); " bytes"

Dim elementAddress As UInteger = address + 50
Print "Element 50 address: "; Hex(elementAddress)

Here we get the memory address of a buffer using @ operator and cast it to UInteger. We then perform pointer arithmetic. UInteger is natural for this as memory addresses are always positive.

UInteger Overflow Behavior

Understanding UInteger overflow is crucial for correct program behavior.

uinteger_overflow.bas

Dim max As UInteger = 4294967295
Dim min As UInteger = 0

Print "Max value: "; max
max += 1
Print "After overflow: "; max

Print "Min value: "; min
min -= 1
Print "After underflow: "; min

This demonstrates UInteger's wrap-around behavior. Incrementing the maximum value wraps to 0, and decrementing 0 wraps to the maximum value. Unlike signed integers, there's no undefined behavior with overflow.

UInteger Type Conversion

FreeBasic handles conversions between UInteger and other numeric types.

uinteger_conversion.bas

Dim ui As UInteger = 4000000000
Dim i As Integer = -1000000000

Print "UInteger to Integer: "; CInt(ui)
Print "Integer to UInteger: "; CUInt(i)

Dim f As Single = 3.14159
Print "Single to UInteger: "; CUInt(f)
Print "UInteger to Single: "; CSng(ui)

This shows explicit type conversion between UInteger and other types. Converting large UInteger to Integer may produce unexpected negative numbers. Converting negative numbers to UInteger wraps them to large values.

Best Practices

Use when needed: Prefer UInteger for values that should never be negative.
Range checking: Validate input that might exceed UInteger's range.
Pointer arithmetic: Use UInteger for memory addresses and offsets.
Bit operations: Choose UInteger for clean bit manipulation.
Document assumptions: Clearly document when UInteger is required.

This tutorial covered the FreeBasic UInteger keyword with practical examples showing its usage in different scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all FreeBasic Tutorials.

Ebooks