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: null)  #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: null) bool #inline

Duplicate the last array element into out argument (if not null) and reduce the array length by one. Returns true in case the element was erased.

File: array.bl

array_pop_first

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

Duplicate first array element into out location (if not null) and shift all other elements by one slot left (the ordeing is kept). Returns true in case the element was erased.

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 allocated block is large enough to hold n elements, the allocated memory block might be bigger then requested size.

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_erase_keep_order

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

Erase element on index i and move all following elements left. This might be slow in case the array is large.

File: array.bl

array_insert

array_insert :: fn (_arr: *[..]?T, before_index: s64, value: T) s64

Insert a new element into the array before position before_index and return index of the new inserted element. All elements after the new one are moved in the memory by one slot.

Value of before_index must be in range <0, arr.len>. Inserting at before_index = 0 basically adds a new element at the array begin; insering at before_index = arr.len is the same as array_push.

Order of already existing elements is preserved.

File: array.bl

array_clear

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

Erase all elements in dynamic array but keep allocated memory.

File: array.bl

array_allocated_bytes

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

File: array.bl