STRPTR

Syntax

Description

Returns the memory address of the string data — a pointer to the first character of string$. This is the most common way to pass a PowerBASIC string to external DLL functions that expect a C-style char* or LPCSTR parameter.

STRPTR returns the data pointer from the string descriptor. It does NOT return the address of the descriptor itself (use VARPTR for that). The distinction between STRPTR (data) and VARPTR (descriptor) is critical for correct DLL interop.

The returned pointer is valid as long as the string variable remains in scope and is not reassigned. For string concatenation expressions, the compiler allocates a temporary scratch buffer and returns its address.

Parameters

Return Value

A DWORD (32-bit) or QUAD (64-bit) memory address pointing to the first character of the string data. The address points to NUL-terminated (C-compatible) memory.

Example

FUNCTION PBMAIN() AS LONG
    LOCAL s AS STRING
    LOCAL p AS DWORD
    
    s = "Hello World"
    p = STRPTR(s)                ' p = address of 'H' character
    PRINT "Data address: "; p
    
    ' STRPTR vs VARPTR difference
    PRINT "STRPTR = data pointer (char*)"
    PRINT "VARPTR = descriptor pointer (string handle)"
    
    ' Practical: pass string to Windows API
    ' DECLARE FUNCTION MessageBoxA LIB "user32.dll" _
    '     ALIAS "MessageBoxA" (BYVAL hWnd AS DWORD, _
    '     lpText AS ASCIIZ, lpCaption AS ASCIIZ, _
    '     BYVAL uType AS DWORD) AS LONG
    '
    ' LOCAL msg AS STRING
    ' msg = "Operation complete"
    ' MessageBoxA(0, BYVAL STRPTR(msg), BYVAL STRPTR(msg), 0)
    
    ' Inspect raw bytes of a string
    s = "ABC"
    p = STRPTR(s)
    PRINT "Byte 0: "; PEEK$(p)
    PRINT "Byte 1: "; PEEK$(p + 1)
    PRINT "Byte 2: "; PEEK$(p + 2)
    
    ' STRPTR with concatenation expression
    s = "Hello" + " World"
    p = STRPTR(s)                ' p = address of concatenated result
    PRINT "Concat data at: "; p
    
    FUNCTION = 0
END FUNCTION

Generated Assembly

; Local STRING: load data pointer from descriptor
mov    rax, [rbp - offset]              ; string data pointer

; BYREF STRING: dereference pointer
mov    r11, [rbp - offset]              ; get pointer-address
mov    rax, [r11]                       ; deref to data pointer

; Concatenation expression: scratch buffer address
lea    rax, [rbp - asciiz_scratch_offset]

Notes

• STRPTR vs VARPTR: STRPTR(s$) returns the address of the character data (char*). VARPTR(s$) returns the address of the string descriptor (a PowerBASIC internal structure). DLL functions expecting string data need STRPTR.
• BYREF strings: For BYREF parameters, the compiler emits a double dereference: first loads the pointer-to-descriptor, then loads the data pointer from the descriptor.
• Temporary expressions: For concatenation or function-return expressions, STRPTR returns the address of a compiler-managed scratch buffer. This pointer is only valid for the duration of the statement.
• NUL termination: All PowerBASIC strings are NUL-terminated, so the memory at STRPTR is safe to pass to C/C++ functions expecting null-terminated strings.
• When calling DLL functions, always use BYVAL STRPTR(s$) to pass the pointer by value, not by reference.