FreeBasic UInteger Keyword
Last modified October 18, 2026
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 an unsigned integer type whose size
depends on the target platform: it is 8 bytes (64 bits) on 64-bit builds and
4 bytes (32 bits) on 32-bit builds. On a 64-bit build the range is 0 to
18,446,744,073,709,551,615 (264-1). Unlike signed integers, it
cannot represent negative numbers. Use SizeOf(UInteger) to check
the size on your build.
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 of the same size.
Declaring UInteger Variables
This example shows how to declare and initialize UInteger variables.
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 4294967295. The literal 4294967295 is the largest 32-bit unsigned value; on a 64-bit build UInteger can hold far larger values (up to 18446744073709551615). Assigning a negative value does not cause an error; it wraps to a large positive number.
UInteger Arithmetic Operations
UInteger supports standard arithmetic operations with some unique behaviors.
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, subtraction and multiplication work normally here because the results stay within range on a 64-bit build. Subtracting a larger number from a smaller one would wrap around to a large positive value. Multiplication shows how UInteger can handle very large positive numbers.
UInteger in Loops
UInteger is ideal for loop counters that need a large range.
Dim counter As Integer
For counter = 10 To 0 Step -1
Print "Countdown: "; counter
Sleep 500
Next
Print "Blast off!"
This countdown loop uses an Integer counter. A countdown to 0 with a negative step cannot be written with an unsigned counter: the compiler warns that the FOR counter variable is unable to exceed the limit value, and after 0 the unsigned counter wraps to a large positive number, so the loop would never end. This is why signed types are the right choice for counting down past 0.
UInteger with Bitwise Operations
UInteger works well with bitwise operations since it directly represents binary values.
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.
Dim buffer(100) As Byte Dim address As UInteger = Cast(UInteger, @buffer(0)) Print "Buffer address: "; Hex(address) Print "Buffer size: "; (UBound(buffer) + 1) * SizeOf(Byte); " 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.
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 behavior at the limits. On a 64-bit build the maximum value here is 4294967295, which is not the type's limit, so incrementing it gives 4294967296 with no wrap. Decrementing 0 wraps to the type's maximum, 18446744073709551615 on a 64-bit build. Unsigned overflow is well defined and wraps around; it is not undefined behavior as it is for signed integers.
UInteger Type Conversion
FreeBasic handles conversions between UInteger and other numeric types.
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 a UInteger to Integer gives a negative number only when the value exceeds the Integer range (on a 64-bit build, Integer is also 8 bytes, so 4000000000 converts unchanged). Converting a negative Integer to UInteger wraps it to a large positive value (on a 64-bit build, -1000000000 becomes 18446744072709551616). Converting a Single truncates the fractional part.
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
List all FreeBasic Tutorials.