Array

#import "std/array"

Compiler builtin dynamic array is automatically growing memory storage allocated on heap. The array allocated memory block groves over time when we push new values to the array. It's guaranteed that all pushed elements are stored in single continuous block of memory. When there is no space reminding in currently allocated block, new one is allocated and all already pushed data are copied from old block to the new one.

Example

// First of all we must load API functions for dynamic array. The #load hash
// directive can be used to "include" other source files.
#import "std/array"

main :: fn () s32 {
    // Now we create new dynamic array to store numbers. No heap alloacation 
    // is done here, we only specify element type of the array. As it's with 
    // regular static arrays or slices, we can access the element count via 
    // .len and allocated memory block via .ptr member. Compared to static
    // arrays, there is additional member .allocated telling us how many
    // elements could array handle till next allocation is needed.
    nums: [..]s32;

    // Fill the dynamic array with some values.
    loop i := 0; i < 100; i += 1 {
        // To append new value at the end of the array we can use 'array_push'
        // function.
        array_push(&nums, i);

        // We can push only numbers of s32 type into the array (based on
        // declaration type), you can try to push something else and see what
        // happens.
    }

    // Dynamic arrays can be printed as usual...
    print("nums = %\n", nums);

    // We can use [N] operator to access single array elements like this:
    print("nums[10] = %\n", nums[10]);
    print("nums[20] = %\n", nums[20]);

    // Since dynamic array will allocate memory on heap, we must free this
    // memory by 'array_terminate' call when array is no longer needed.
    array_terminate(&nums);

    // There is lot of other ways to modify dynamic array content, check out
    // API documentation.

    return 0;
}

array_init

array_init :: fn (_arr: *[..]?T, n : s64: 0, allocator : *Allocator: )  #inline

Sets dynamic array to default state. If array contains already allocated memory array_terminate must be called first.

Initial capacity can be specified by n (count of elements). If n is greater than 0, needed memory is preallocated using specified allocator; otherwise no allocation is done.

It's usually enough to rely on default implicit initialization in case we don't need specify custom allocator or preallocate storage to specified n of entries.

File: array.bl

array_terminate

array_terminate :: fn (_arr: *[..]?T)  #inline

Release memory allocated by dynamic array. This function is supposed to be called when dynamic array is no longer needed. Passed dynamic array is set to default state also.

File: array.bl

array_push

array_push :: fn { 
    impl_push_empty; 
    impl_push; 
}

Append new value at the dynamic array end. New heap allocation is done here only in cases when there is not enough memory allocated to store all values. Returns pointer to the new appended element.

File: array.bl

array_push_all

array_push_all :: fn (_arr: *[..]?T, data: []T) 

Append all data at the dynamic array end. New heap allocation is done here only in cases when there is not enough memory allocated to store all values. Does nothing when data.len < 1.

File: array.bl

array_pop

array_pop :: fn (_arr: *[..]?T, out : *T: ) bool #inline

Duplicate the last array element into out argument (if not null) and reduce the array length by one. Returs true in case the array is not empty.

File: array.bl

array_reserve

array_reserve :: fn (_arr: *[..]?T, n: s64)  #inline

Reserve heap memory for n elements in array. Does nothing in case the already allocaed block is large enough to hold n elements.

File: array.bl

array_resize

array_resize :: fn (_arr: *[..]?T, n: s64)  #inline

File: array.bl

array_erase

array_erase :: fn (_arr: *[..]?T, i: s64) 

Erase element on index i. Call to this function can cause reordering of an dynamic array. Allocated memory is kept even if we erase entire dynamic array. Function invoke panic in case of index overflow.

File: array.bl

array_clear

array_clear :: fn (_arr: *[..]?T)  #inline

Erase all elements in dynamic array but keep allocated memory.

File: array.bl