Someone should make a FAQ about memory allocation, stack vs. heap, etc.

You can allocate something in two ways:
1) stack
whenever you put "var myvar" or "int myint" or "somestruct mystruct" in a function, you are allocating data on the stack.

2) heap
You can allocate a certain number of bytes from the heap with malloc(numbytes). Malloc returns a pointer to the allocated memory (the first byte). You can use it like this: mystruct* p; p = malloc(SIZEOF(mystruct);
There are creating functions for all structs in the a7 engine, like string_create(), that use malloc (or C++ new operator).

Deallocation:
1) stack
Memory on the stack is deallocated automatically for you when the function ends (actually, when the current scope ends, I think).

2) heap
Memory on the heap must be deallocated by you when you don't need it anymore. You can use free() for that. You should use ptr_remove for STRINGs, BMAPs, etc.




So if you want a function that creates a new object (var, float, some struct, whatever), you want that object to still exist after the creating function ends. So you must allocate it on the heap with malloc, and return a pointer to it.