HTLL_Libs_x86.txt

$$$$is_nint_negative$$$$
; =============================================================================
; UTILITY FUNCTIONS (Correct and Properly Formatted)
; =============================================================================



; is_nint_negative: Reads a signed number, updates its corresponding sign
;                   flag, AND converts the original number to its positive
;                   magnitude if it was negative.
;
; [In]
;   rdi - Pointer to the nint variable (which holds a signed value).
;   rsi - Pointer to the is_negative flag variable for that nint.
;
; [Out]
;   The memory at [rsi] will be overwritten with 0 or 1.
;   The memory at [rdi] will be overwritten with its positive magnitude.

is_nint_negative:
    push rbp
    mov rbp, rsp
    push rax

    ; Load the actual signed value from the first pointer
    mov rax, [rdi]

    ; Check its sign using the CPU's Sign Flag
    test rax, rax
    jns .is_positive_or_zero    

.is_negative:
    ; The number is negative.
    ; 1. Update the flag variable to 1.
    mov qword [rsi], 1
    
    ; 2. Negate the value to get its positive magnitude.
    neg rax
    
    ; 3. Store the positive magnitude BACK into the original variable.
    mov [rdi], rax
    jmp .done

.is_positive_or_zero:
    ; The number is positive or zero.
    ; 1. Update the flag variable to 0.
    mov qword [rsi], 0
    ; 2. The value at [rdi] is already its own positive magnitude, so we do nothing to it.

.done:
    pop rax
    pop rbp
    ret
%%%%is_nint_negative%%%%
$$$$divide_and_store$$$$
; divide_and_store: Performs fixed-point division and stores results in memory.
; [In] rdi: dividend_int, rsi: dividend_dec
;      rdx: divisor_int,  rcx: divisor_dec
;      r8:  ptr to result_int, r9: ptr to result_dec

divide_and_store:
    ; Prologue
    push rbx
    push r12
    push r13
    push r14
    push r15

    ; --- THE FIX: Save all volatile input arguments immediately ---
    mov r12, rdi            
    mov r13, rsi            
    mov r14, rdx            
    mov r15, rcx            
    
    ; --- Step 1: Scale the Dividend ---
    mov rax, r12
    mov rbx, [SCALE_FACTOR]
    mul rbx
    add rax, r13 
    mov r12, rax 

    ; --- Step 2: Scale the Divisor ---
    mov rax, r14 
    mov rbx, [SCALE_FACTOR]
    mul rbx
    add rax, r15 
    mov r13, rax 
    
    ; --- Step 3: Perform the main 128-bit division ---
    mov rax, r12        
    mov rbx, [SCALE_FACTOR]
    mul rbx
    div r13
    
    ; --- Step 4: De-scale the final result ---
    mov rbx, [SCALE_FACTOR]
    xor rdx, rdx
    div rbx

    ; --- Step 5: Store the results using the pointers from r8 and r9 ---
    mov [r8], rax 
    mov [r9], rdx 

    ; Epilogue
    pop r15
    pop r14
    pop r13
    pop r12
    pop rbx
    ret
%%%%divide_and_store%%%%
$$$$print_div$$$$

; print_div: (Unchanged logic, but now properly formatted)
; [In] rdi: integer part, rsi: decimal part

print_div:
    ; Prologue
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push rcx
    push rsi

    ; --- Print integer part ---
    mov rax, rdi
    lea r12, [print_buffer + 19]
    mov byte [r12], 0
    dec r12
    mov rbx, 10
.int_convert_loop:
    xor rdx, rdx
    div rbx
    add rdx, '0'
    mov [r12], dl
    dec r12
    cmp rax, 0
    jne .int_convert_loop

    inc r12
    mov rsi, r12
    lea rdx, [print_buffer + 19]
    sub rdx, rsi
    mov rax, 1
    mov rdi, 1
    syscall

    ; --- Print decimal point ---
    mov rax, 1
    mov rdi, 1
    mov rsi, dot
    mov rdx, 1
    syscall

    ; --- Print decimal part ---
    pop rax
    lea r12, [print_buffer + 5]
    mov rbx, 10
    mov rcx, 6
.dec_convert_loop:
    xor rdx, rdx
    div rbx
    add rdx, '0'
    mov [r12], dl
    dec r12
    loop .dec_convert_loop

    mov rax, 1
    mov rdi, 1
    lea rsi, [print_buffer]
    mov rdx, 6
    syscall

    ; Print a final newline.
    mov rax, 1
    mov rdi, 1
    mov rsi, nl
    mov rdx, 1
    syscall

    ; Epilogue
    pop rcx
    pop r12
    pop rbx
    pop rbp
    ret
%%%%print_div%%%%
$$$$print_number$$$$

; print_number: Prints a number, prepending a '-' sign if requested.
;
; [In]
;   rdi - The number to print (as an unsigned, positive magnitude).
;   rsi - The "is_negative" flag. 0 for positive, 1 for negative.

print_number:
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push rdi    

    ; Check the is_negative flag passed in rsi
    cmp rsi, 0
    je .skip_sign_print

    ; Flag is 1, so print a minus sign.
    ; This is safe because the number is preserved on the stack.
    mov rax, 1
    mov rdi, 1
    mov rsi, minus_sign
    mov rdx, 1
    syscall

.skip_sign_print:
    ; Restore the saved number from the stack directly into RAX,
    ; which is the register we need for the division loop.
    pop rax

    ; The conversion loop, which now operates on the correct number in rax.
    lea r12, [print_buffer + 19]
    mov byte [r12], 0
    dec r12
    mov rbx, 10
.conversion_loop:
    xor rdx, rdx
    div rbx
    add rdx, '0'
    mov [r12], dl
    dec r12
    cmp rax, 0
    jne .conversion_loop

    inc r12
    mov rsi, r12
    lea rdx, [print_buffer + 20]
    sub rdx, rsi
    mov rax, 1
    mov rdi, 1
    syscall

    ; Print a final newline.
    mov rax, 1
    mov rdi, 1
    mov rsi, nl
    mov rdx, 1
    syscall

    ; The stack is balanced because we pushed RDI and popped it into RAX.
    pop r12
    pop rbx
    pop rbp
    ret
%%%%print_number%%%%
$$$$print_str$$$$
print_str:
    push rbp
    mov rbp, rsp
    mov rax, 1
    mov rdi, 1
    ; rsi and rdx are expected to be set by the caller
    syscall
    pop rbp
    ret
%%%%print_str%%%%
$$$$input$$$$

; input: Reads a line from stdin, handles empty input, removes the trailing
;        newline, and stores the raw string and its length.
;
; [In]
;   rdi - Pointer to the buffer where the string should be stored.
;   rsi - Pointer to a qword where the length of the clean string will be stored.

input:
    push rbp
    mov rbp, rsp
    push r12
    push r13

    ; Save the pointers passed as arguments immediately
    mov r12, rdi 
    mov r13, rsi 

    ; Correctly set up all registers for the sys_read syscall
    mov rax, 0
    mov rdi, 0
    mov rsi, r12
    mov rdx, 100
    syscall
    ; The program waits here. rax will return with bytes read.

    ; Check if the user entered anything. If they just press Enter, rax will be 1.
    ; If they press Ctrl+D, rax will be 0. Both cases mean empty input.
    cmp rax, 1
    jle .read_empty

    ; This code only runs for valid input (rax > 1).
    ; The length of the clean string is (bytes_read - 1).
    dec rax
    jmp .store_length

.read_empty:
    ; === THE FIX IS HERE ===
    ; If the input was empty, explicitly set the length to 0.
    xor rax, rax

.store_length:
    ; Store the final calculated length (either from dec rax or xor rax)
    ; into the memory location pointed to by r13.
    mov [r13], rax

    pop r13
    pop r12
    pop rbp
    ret
%%%%input%%%%
$$$$array_copy$$$$
; =============================================================================
; DYNAMIC ARRAY LIBRARY FUNCTIONS (Final, Corrected Version)
; =============================================================================
; array_clear: Clears a dynamic array by setting its size to 0.

; =============================================================================
; array_copy: Copies all elements from a source array to a destination array.
; The destination array will be resized if necessary. Any existing data in
; the destination array will be overwritten.
; [In]
;   rdi - Pointer to the destination DynamicArray struct.
;   rsi - Pointer to the source DynamicArray struct.
; =============================================================================
; =============================================================================
; TRULY BULLETPROOF array_copy
; =============================================================================
array_copy:
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push r13
    push r14
    push r15

    mov r12, rdi
    mov r13, rsi             

    ; --- Step 1: Free the destination's old memory block ---
    mov rdi, [r12 + DynamicArray.pointer]
    cmp rdi, 0
    je .copy_skip_munmap_fix 
    mov rsi, [r12 + DynamicArray.capacity]
    imul rsi, 8
    mov rax, 11
    syscall

.copy_skip_munmap_fix:
    ; --- Step 2: Set new size and capacity ---
    mov rbx, [r13 + DynamicArray.size] 
    mov [r12 + DynamicArray.size], rbx
    mov [r12 + DynamicArray.capacity], rbx 

    ; --- Step 3: Allocate new memory ---
    cmp rbx, 0
    je .copy_epilogue_fix      
    
    mov r14, rbx
    imul r14, 8 

    ; ======================= THE CRITICAL FIX IS HERE =========================
    ; Syscalls clobber registers. We need r12 and r13 after. Save them.
    push r12
    push r13
    
    mov rax, 9  
    mov rdi, 0
    mov rsi, r14
    mov rdx, 3
    mov r10, 34
    mov r8, -1
    mov r9, 0
    syscall
    
    ; Restore our precious struct pointers immediately after the syscall.
    pop r13
    pop r12
    ; ========================================================================
    
    cmp rax, 0
    jl .copy_epilogue_fix    

    mov [r12 + DynamicArray.pointer], rax

    ; --- Step 4: Copy the data ---
    mov rsi, [r13 + DynamicArray.pointer]
    mov rdi, [r12 + DynamicArray.pointer]
    mov rcx, [r13 + DynamicArray.size]
    rep movsq

.copy_epilogue_fix:
    pop r15
    pop r14
    pop r13
    pop r12
    pop rbx
    pop rbp
    ret
%%%%array_copy%%%%
$$$$array_clear$$$$
; [In] rdi: Pointer to the DynamicArray struct.

array_clear:
    push rbp
    mov rbp, rsp
    ; Set the .size field of the struct pointed to by rdi to 0.
    mov qword [rdi + DynamicArray.size], 0
    pop rbp
    ret
%%%%array_clear%%%%
$$$$array_append$$$$
; =============================================================================
; array_append: (Final, Robust Version with Error Checking)
; Appends a qword value to a dynamic array, resizing if necessary.
; =============================================================================
array_append:
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push r13
    push r14
    push r15

    mov r12, rdi
    mov r13, rsi

    mov rcx, [r12 + DynamicArray.size]
    cmp rcx, [r12 + DynamicArray.capacity]
    jl .has_space

; --- Resize Logic ---
.resize:
    mov r14, [r12 + DynamicArray.pointer]   
    mov r15, [r12 + DynamicArray.capacity]  
    
    mov rbx, r15
    cmp rbx, 0
    jne .double_it
    mov rbx, INITIAL_CAPACITY
    jmp .capacity_calculated
.double_it:
    shl rbx, 1
.capacity_calculated:
    mov [r12 + DynamicArray.capacity], rbx

    ; --- Allocate new memory ---
    push r12
    push r13
    push r14
    push r15

    imul rbx, 8                             
    mov rax, 9              
    mov rdi, 0
    mov rsi, rbx
    mov rdx, 3
    mov r10, 34
    mov r8, -1
    mov r9, 0
    syscall

    pop r15
    pop r14
    pop r13
    pop r12

    ; ========================= THE CRITICAL FIX =========================
    ; Syscalls return a negative value on error. We must check for this.
    ; A valid pointer will be a small positive number. An error is a large
    ; number close to -1 (0xFFFFFFFFFFFFFFFF).
    cmp rax, 0
    jl .mmap_failed
    ; ====================================================================

    ; --- Copy old data to new block ---
    cmp r14, 0
    je .skip_copy                           

    mov rdi, rax
    mov rsi, r14
    mov rcx, [r12 + DynamicArray.size]      
    rep movsq                               

    ; --- Free the OLD memory block ---
    push rax
    push r12
    push r13

    imul r15, 8 
    mov rdi, r14
    mov rsi, r15
    mov rax, 11 
    syscall

    pop r13
    pop r12
    pop rax

.skip_copy:
    mov [r12 + DynamicArray.pointer], rax

.has_space:
    mov rbx, [r12 + DynamicArray.pointer]
    mov rcx, [r12 + DynamicArray.size]
    mov [rbx + rcx * 8], r13
    inc qword [r12 + DynamicArray.size]
    jmp .append_epilogue

.mmap_failed:
    ; If mmap fails, we can't continue. Exit with an error code (e.g., 1).
    mov rax, 60
    mov rdi, 1
    syscall

.append_epilogue:
    pop r15
    pop r14
    pop r13
    pop r12
    pop rbx
    pop rbp
    ret
%%%%array_append%%%%
$$$$array_pop$$$$
array_pop:
    push rbp
    mov rbp, rsp
    push rbx
    push rcx
    push r8

    mov r8, rdi
    mov rcx, [r8 + DynamicArray.size]
    cmp rcx, 0
    je .pop_empty

    dec rcx
    mov [r8 + DynamicArray.size], rcx
    mov rbx, [r8 + DynamicArray.pointer]
    mov rax, [rbx + rcx * 8]
    jmp .pop_done

.pop_empty:
    xor rax, rax

.pop_done:
    pop r8
    pop rcx
    pop rbx
    pop rbp
    ret
%%%%array_pop%%%%
$$$$print_char$$$$

print_char:
    push rbp
    mov rbp, rsp

    ; Push the entire RDI register. This subtracts 8 bytes from RSP,
    ; which keeps the stack correctly aligned. The character is in DIL,
    ; the lowest byte of RDI, so this works perfectly.
    push rdi

    mov rax, 1                 
    mov rdi, 1                 
    mov rsi, rsp               
    mov rdx, 1                 
    syscall

    ; Clean up the stack by popping the value we pushed.
    ; This adds 8 back to RSP, restoring it.
    pop rdi

    pop rbp
    ret
%%%%print_char%%%%
$$$$sys_read_line$$$$
; =============================================================================
; sys_read_line: A low-level wrapper around the sys_read syscall for stdin.
; [In]
;   rdi - Pointer to the buffer where the string should be stored.
;   rsi - Max number of bytes to read.
; [Out]
;   rax - The number of bytes actually read (including newline).
; =============================================================================
sys_read_line:
    push rbp
    mov rbp, rsp

    ; Prepare arguments for the sys_read syscall
    mov rax, 0      
    mov rdx, rsi    
    mov rsi, rdi    
    mov rdi, 0      
    
    syscall         

    pop rbp
    ret
%%%%sys_read_line%%%%
$$$$get_user_input$$$$
; =============================================================================
; get_user_input: (Final, Clean, Production Version)
; Correctly prompts, reads, and appends user input.
; =============================================================================
get_user_input:
    ; --- Prologue: Save all callee-saved registers we will use. ---
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push r13
    push r14
    push r15

    ; Correctly align the entire stack frame for all subsequent calls.
    sub rsp, 8

    ; Save arguments immediately into safe callee-saved registers.
    mov r12, rdi
    mov r13, rsi

    ; --- Part 1: Print the prompt string ---
    mov rcx, [r13 + DynamicArray.size]
    cmp rcx, 0
    je .read_from_user

    mov r14, rcx            
    add rcx, 15             
    and rcx, -16
    mov rbx, rcx            
    sub rsp, rbx            

    ; Pack the prompt into the stack buffer.
    mov rdi, rsp
    mov rsi, [r13 + DynamicArray.pointer]
    push rbx
    xor rbx, rbx
.pack_loop:
    cmp rbx, r14
    jge .do_prompt_print
    mov al, [rsi + rbx*8]
    mov [rdi + rbx], al
    inc rbx
    jmp .pack_loop
.do_prompt_print:
    pop rbx 
    
    mov rax, 1
    mov rdi, 1
    mov rsi, rsp
    mov rdx, r14
    syscall

    add rsp, rbx

    ; --- Part 2: Read user's input ---
.read_from_user:
    mov rax, 0
    mov rdi, 0
    mov rsi, input_buffer
    mov rdx, 255
    syscall

    ; --- Part 3: Append the input to the dynamic array ---
    cmp rax, 1
    jle .done

    dec rax
    mov r14, rax
    mov r15, input_buffer
.append_char_loop:
    cmp r14, 0
    je .done

    mov rdi, r12
    movzx rsi, byte [r15]
    call array_append

    inc r15
    dec r14
    jmp .append_char_loop

.done:
    ; --- Epilogue: Restore the stack and all saved registers. ---
    add rsp, 8
    pop r15
    pop r14
    pop r13
    pop r12
    pop rbx
    pop rbp
    ret
%%%%get_user_input%%%%
$$$$fileread_from_ptr$$$$
; =============================================================================
; =============================================================================
; HTLL DYNAMIC FILE I/O LIBRARY - POINTER-BASED VERSIONS
; These functions are the key to building a truly dynamic compiler.
; =============================================================================
; =============================================================================

; =============================================================================
; file_read_from_ptr: Appends a file's contents to a dynamic array.
; [In]
;   rdi - Pointer to the destination DynamicArray struct.
;   rsi - A POINTER to a null-terminated string containing the file path.
; =============================================================================
fileread_from_ptr:
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push r13
    push r14
    push r15

    mov r12, rdi             
    mov r13, rsi             

    ; --- Open the file ---
    mov rax, 2               
    mov rdi, r13
    xor rsi, rsi             
    syscall
    
    ; ======================= THE ARMOR PLATE =========================
    ; A valid file descriptor is a small positive number. Errors are negative.
    cmp rax, 0
    jl .read_error_ptr
    ; ===================================================================
    mov r14, rax      

.read_loop_ptr:
    mov rax, 0        
    mov rdi, r14
    mov rsi, file_read_buffer
    mov rdx, 4096
    syscall
    cmp rax, 0
    jle .close_and_exit_ptr      

    mov r15, rax             
    mov rsi, file_read_buffer
.append_byte_loop_ptr:
    cmp r15, 0
    je .read_loop_ptr            

    movzx rbx, byte [rsi]    
    
    push rsi                 
    mov rdi, r12             
    mov rsi, rbx             
    call array_append
    pop rsi                  

    inc rsi                  
    dec r15                  
    jmp .append_byte_loop_ptr

.close_and_exit_ptr:
    mov rax, 3
    mov rdi, r14             
    syscall
    jmp .read_done_ptr

.read_error_ptr:
    ; The open failed. We do nothing. The destination array remains empty.
    ; A real-world version would print an error to stderr.
.read_done_ptr:
    pop r15
    pop r14
    pop r13
    pop r12
    pop rbx
    pop rbp
    ret
%%%%fileread_from_ptr%%%%
$$$$fileappend_from_ptr$$$$
; =============================================================================
; file_append_from_ptr: Appends an array of character codes to a file.
; [In]
;   rdi - A POINTER to a null-terminated string containing the file path.
;   rsi - Pointer to the source DynamicArray struct.
; =============================================================================
fileappend_from_ptr:
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push r13
    push r14
    push r15

    mov r12, rdi
    mov r13, rsi

    mov rcx, [r13 + DynamicArray.size]
    cmp rcx, 0
    je .append_epilogue_ptr

    ; --- Pack the array into a byte buffer on the stack ---
    mov r14, rcx
    mov rbx, rcx
    add rbx, 15
    and rbx, -16
    sub rsp, rbx
    
    mov r15, rsp
    mov rsi, [r13 + DynamicArray.pointer]
    xor rcx, rcx
.pack_loop_ptr:
    cmp rcx, r14
    jge .pack_done_ptr
    mov al, [rsi + rcx*8]
    mov [r15 + rcx], al
    inc rcx
    jmp .pack_loop_ptr
.pack_done_ptr:

    ; --- Open the file ---
    mov rax, 2
    mov rdi, r12
    mov rsi, 1089       
    mov rdx, 420
    syscall

    ; ======================= THE ARMOR PLATE =========================
    cmp rax, 0
    jl .append_error_ptr     
    ; ===================================================================
    mov r14, rax            

    ; --- Write the packed data ---
    mov rax, 1
    mov rdi, r14
    mov rsi, r15
    mov rdx, [r13 + DynamicArray.size]
    syscall

    ; --- Close the file ---
    mov rax, 3
    mov rdi, r14
    syscall

.append_error_ptr:
    ; This label is jumped to if open fails. We just clean up the stack.
.append_cleanup_ptr:
    add rsp, rbx 

.append_epilogue_ptr:
    pop r15
    pop r14
    pop r13
    pop r12
    pop rbx
    pop rbp
    ret
%%%%fileappend_from_ptr%%%%
$$$$filedelete_from_ptr$$$$
; =============================================================================
; file_delete_from_ptr: Deletes a file from the filesystem.
; [In]
;   rdi - A POINTER to a null-terminated string containing the file path.
; =============================================================================
filedelete_from_ptr:
    push rbp
    mov rbp, rsp
    
    mov rax, 87
    syscall
    ; For robustness, you could check if rax is 0 (success) or -1 (failure)
    
    pop rbp
    ret
%%%%filedelete_from_ptr%%%%
$$$$file_read$$$$
; =============================================================================
; =============================================================================
; ORIGINAL STATIC (LABEL-BASED) FUNCTIONS
; Kept for compatibility and for handling hardcoded file paths.
; =============================================================================
; =============================================================================

; =============================================================================
; file_read: Appends a file's contents to a dynamic array.
; =============================================================================
file_read:
    ; This function's logic is already pointer-based, so it works as is.
    ; We can simply call the new, more clearly named function.
    jmp fileread_from_ptr
%%%%file_read%%%%
$$$$file_append$$$$
; =============================================================================
; file_append: Appends an array of character codes to a file.
; =============================================================================
file_append:
    ; This function's logic is also already pointer-based.
    jmp fileappend_from_ptr
%%%%file_append%%%%
$$$$file_delete$$$$
; =============================================================================
; file_delete: Deletes a file from the filesystem.
; =============================================================================
file_delete:
    ; This function's logic is also already pointer-based.
    jmp filedelete_from_ptr
%%%%file_delete%%%%
$$$$array_pack_to_bytes$$$$


; =============================================================================
; ADAPTER FUNCTION 1: HTLL arr -> C-style string (char*)
; =============================================================================
; Takes an HTLL array and creates a C-style string from it.
; [In]  rdi - Pointer to the source DynamicArray struct.
; [Out] rax - Pointer to the new C-style string (or 0 on error).
;==============================================================================
; =============================================================================
; ADAPTER FUNCTION 1: HTLL arr -> C-style string (char*) (Robust Version)
; =============================================================================
array_pack_to_bytes:
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push r13
    push r14

    ; --- ROBUSTNESS CHECK 1 ---
    ; Check if the struct pointer itself is null
    cmp rdi, 0
    je .pack_fail

    mov r14, [rdi + DynamicArray.pointer] 
    mov r12, [rdi + DynamicArray.size]    

    ; --- ROBUSTNESS CHECK 2 ---
    ; Check if the array's internal data pointer is null or if size is zero
    cmp r14, 0
    je .pack_fail
    cmp r12, 0
    je .pack_fail 

    ; === Step A: Ask the kernel for memory ===
    mov r13, r12
    inc r13
    mov rax, 9
    mov rdi, 0
    mov rsi, r13
    mov rdx, 3
    mov r10, 34
    mov r8, -1
    mov r9, 0
    syscall
    
    cmp rax, 0
    jl .pack_fail

    ; === Step B: Copy the bytes, one by one ===
    mov r13, rax
    xor rbx, rbx

.pack_loop:
    cmp rbx, r12
    jge .pack_add_null

    mov rcx, [r14 + rbx*8]
    mov [r13 + rbx], cl
    
    inc rbx
    jmp .pack_loop

.pack_add_null:
    mov byte [r13 + rbx], 0
    mov rax, r13
    mov rdx, r12
    inc rdx     
    jmp .pack_done

.pack_fail:
    xor rax, rax

.pack_done:
    pop r14
    pop r13
    pop r12
    pop rbx
    pop rbp
    ret
%%%%array_pack_to_bytes%%%%
$$$$array_unpack_from_bytes$$$$
; =============================================================================
; ADAPTER FUNCTION 2: C-style string (char*) -> HTLL arr
; =============================================================================
; Takes a C-style string and populates an HTLL DynamicArray with its characters.
; [In]
;   rdi - Pointer to the destination DynamicArray struct.
;   rsi - Pointer to the source, null-terminated C-style string.
;==============================================================================
; =============================================================================
; ADAPTER FUNCTION 2: C-style string (char*) -> HTLL arr (Robust Version)
; =============================================================================
array_unpack_from_bytes:
    push rbp
    mov rbp, rsp
    push rbx
    push r12
    push r13

    mov r12, rdi  
    mov r13, rsi  

    ; --- THE FIX IS HERE ---
    ; Before we do anything, check if the C-string pointer is NULL.
    cmp r13, 0
    je .unpack_done       
    ; --- END FIX ---

    ; Clear the destination array to be safe.
    mov rdi, r12
    call array_clear

.unpack_loop:
    movzx rbx, byte [r13]
    cmp rbx, 0           
    je .unpack_done      

    ; Append the character to the HTLL array.
    mov rdi, r12
    mov rsi, rbx
    call array_append
    
    inc r13
    jmp .unpack_loop

.unpack_done:
    pop r13
    pop r12
    pop rbx
    pop rbp
    ret
%%%%array_unpack_from_bytes%%%%
$$$$free_packed_string$$$$
; =============================================================================
; free_packed_string: Frees memory allocated by sys_mmap.
; [In]
;   rdi - Pointer to the memory block.
;   rsi - The size of the memory block in bytes.
; =============================================================================
free_packed_string:
    push rbp
    mov rbp, rsp
    
    ; Robustness check: Don't try to free a null pointer.
    cmp rdi, 0
    je .free_done

    mov rax, 11
    ; rdi (pointer) and rsi (size) are already set by the caller.
    syscall

.free_done:
    pop rbp
    ret
%%%%free_packed_string%%%%
$$$$sleep_ms$$$$
; =============================================================
; sleep_ms
; [In] rdi = milliseconds to sleep
; =============================================================
sleep_ms:
    ; --- 1. Math: Split ms into Seconds and Nanoseconds ---
    mov rax, rdi            
    xor rdx, rdx            
    mov rcx, 1000
    div rcx                 

    imul rdx, rdx, 1000000  

    ; --- 2. Build 'timespec' Struct on Stack ---
    ; Struct is 16 bytes: { qword tv_sec, qword tv_nsec }
    sub rsp, 16              
    mov [rsp], rax           
    mov [rsp+8], rdx         

    ; --- 3. Call Kernel ---
    mov rax, 35              
    mov rdi, rsp             
    xor rsi, rsi             
    syscall

    ; --- 4. Cleanup ---
    add rsp, 16              
    ret
%%%%sleep_ms%%%%