FreeBasic Cptr Keyword

Last modified October 18, 2026

The FreeBasic Cptr keyword is used for pointer type conversion. It allows casting between different pointer types while maintaining the same memory address. This is useful for low-level memory operations.

Basic Definition

Cptr converts an expression to a specified pointer type. The conversion does not change the address value; it only changes the pointer type that the compiler uses for subsequent dereferencing and arithmetic.

The general syntax is Cptr(target_type, expression). The expression may be a pointer of any type or an Integer. The target type should be a pointer type, such as Integer Ptr or Any Ptr, or a type alias for one. The compiler does not strictly enforce this for every case.

Basic Pointer Conversion

This example shows the simplest use of Cptr to convert between pointer types.

cptr_basic.bas

Dim i As Integer = 42
Dim pi As Integer Ptr = @i
Dim pv As Any Ptr = Cptr(Any Ptr, pi)

Print "Original value: "; *pi
Print "Converted pointer: "; pv
Print "Dereferenced: "; *Cptr(Integer Ptr, pv)

Here we create an integer and get its pointer. We then use Cptr to convert the integer pointer to a generic pointer (Any Ptr). Finally, we convert it back to access the original value. The memory address remains unchanged.

Accessing Memory as Different Types

Cptr can reinterpret memory as different types, similar to unions in C.

cptr_reinterpret.bas

Dim value As Integer = &H41424344
Dim p As Byte Ptr = Cptr(Byte Ptr, @value)

Print "Integer value: "; Hex(value)
Print "Bytes: ";
For i As Integer = 0 To 3
    Print Hex(p[i]); " ";
Next

This code treats an integer as an array of bytes. We use Cptr to get a byte pointer to the integer. This lets us examine each byte individually, showing how the value is stored in memory.

Working with Structures

Cptr is useful when working with structures and needing to access members through different pointer types.

cptr_structure.bas

Type Point
    x As Integer
    y As Integer
End Type

Dim pt As Point = (10, 20)
Dim p As Any Ptr = @pt

Dim px As Integer Ptr = Cptr(Integer Ptr, p)
Print "x: "; px[0]
Print "y: "; px[1]

We create a Point structure and get a generic pointer to it. Using Cptr, we convert this to an integer pointer to access the x and y members as array elements. This demonstrates direct memory access to structure members.

Function Pointer Conversion

Cptr can be used with function pointers for calling functions through different pointer types.

cptr_function.bas

Function AddNumbers(a As Integer, b As Integer) As Integer
    Return a + b
End Function

Dim func As Function(a As Integer, b As Integer) As Integer = @AddNumbers
Dim p As Any Ptr = Cptr(Any Ptr, func)

Dim result As Integer = Cptr(Function(a As Integer, b As Integer) As Integer, p)(3, 4)
Print "3 + 4 = "; result

This example shows converting between function pointer types. We store the function address in a generic pointer, then convert it back to call the function. This technique is useful for callback mechanisms.

Working with Arrays

Cptr can help when you need to treat an array as a different type.

cptr_array.bas

Dim bytes(3) As Byte = {65, 66, 67, 0}
Dim p As Integer Ptr = Cptr(Integer Ptr, @bytes(0))

Print "As bytes: "; bytes(0); " "; bytes(1); " "; bytes(2); " "; bytes(3)
Print "As integer: "; Hex(*p)

Here we have a byte array containing ASCII characters. Using Cptr, we treat the array as an integer pointer. This lets us see how the bytes are interpreted when read as an integer value. The output is 434241, because the bytes 65, 66, 67, 0 are stored in little-endian order and the zero high byte is not shown by Hex.

Interfacing with C Libraries

Cptr is particularly useful when calling C functions that expect specific pointer types.

cptr_clib.bas

Extern "C"
    Declare Sub c_function Lib "mylib" (p As Byte Ptr)
End Extern

Dim buffer As String = "Hello"
c_function(Cptr(Byte Ptr, Strptr(buffer)))

This demonstrates using Cptr to pass a FreeBasic string pointer to a C function expecting a byte pointer. The Strptr gets the string's character data, and Cptr ensures the correct pointer type is passed.

Pointer Arithmetic

Cptr can be used with pointer arithmetic to navigate memory structures.

cptr_arithmetic.bas

Dim values(3) As Integer = {10, 20, 30, 40}
Dim p As Any Ptr = @values(0)

For i As Integer = 0 To 3
    Print "Value "; i; ": "; *Cptr(Integer Ptr, p + i * SizeOf(Integer))
Next

This example shows how to use Cptr with pointer arithmetic. We convert the generic pointer to an integer pointer at each offset to access array elements. The SizeOf operator ensures correct byte offsets.

Best Practices

Type Safety: Use Cptr only when necessary and be aware of type sizes.
Alignment: Ensure memory is properly aligned for the target type.
Documentation: Comment Cptr usage to explain why conversion is needed.
Alternatives: Consider using unions or proper type definitions first.
Debugging: Be cautious as improper Cptr usage can cause hard-to-find bugs.

This tutorial covered the FreeBasic Cptr keyword with practical examples showing its usage in different scenarios requiring pointer conversion.

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