List

List

List represents the type of a list.

Specifications

Type	Size	Possible Values	Memory Management Model	File
List	32 bytes	Lists of a Single Type	Ownership	2.7/List.adept

Definition

struct <$T> List (items *$T, length, capacity usize, ownership Ownership)

where

$T is any valid type

Fields

Name	Type	Description
items	*$T	Pointer to raw array of items
length	usize	Length of items in units
capacity	usize	Capacity of items in units
ownership	Ownership	Whether this list is responsible for freeing items

Value Management Definitions

• func __defer__(this *<$T> List)
• func __pass__(list POD <$T> List) <$T> List
• func __array__(this *<$T> List) *$T
• func __length__(this *<$T> List) usize
• func __access__(this *<$T> List, index usize) *$T
• func __assign__(this *<$T> List, other POD <$T> List)
• implicit func __as__(initializer <$T> InitializerList) <$T> List
• implicit func __as__(initializer <long> InitializerList) <int> List
• implicit func __as__(initializer <double> InitializerList) <float> List

List Literals

Lists can be created from initializer lists:

food <String> List = {"Spaghetti", "Pizza", "Garlic Bread"}

board <<int> List> List = {
    {0, 0, 0, 0} as <int> List,
    {0, 0, 0, 0},
    {0, 0, 0, 0},
    {0, 0, 0, 0}
}

Memory Management

Lists are automatically freed when they run out of scope.

import basics

func main {
    names <String> List
    names.add("Isaac")
    names.add("Andy")
    names.add("Zack")
    names.add("Ellie")
    
    // names is freed
}

In order to pass lists around to other scopes, you can use the commit() method. my_list.commit() gives up any ownership held by my_list and returns a copy with the original's ownership:

import basics

func main {
    outlives <String> List = getList()
    
    // outlives is freed
}

func getList() <String> List {
    shortlived_list <String> List
    shortlived_list.add("Apples")
    shortlived_list.add("Bananas")
    shortlived_list.add("Oranges")
    
    return shortlived_list.commit() // Transfer ownership
}

List Scoping Rules:

• Lists are freed when they go out of scope
• Lists are freed when inside a value that goes out of scope
• Lists can transfer scopes using new_scoped_list = old_scoped_list.commit()
• Lists are freed when they are returned and never assigned
• Lists reference the data of other Lists when assigned to them
• Lists can point to specific parts of other Lists
• Variables/Parameters marked as POD will not have __pass__ and __defer__ calls automatically made
• When add()ed to things like other Lists, a reference will be used by default
• To commit ownership of a list to another List, you must use list_of_lists.add(list.commit())

Functions

• func List(items *$T, length usize, ownership Ownership = Ownership::REFERENCE) <$T> List

  Constructs a list from individual components.

  [view src]

• func List(items *$T, length, capacity usize, ownership Ownership = Ownership::REFERENCE) <$T> List

  Constructs a list from individual components.

  [view src]

Methods

• func add(this *<$T> List, item POD $~T) void

  Adds an item to a list.

  [view src]

• func add(this *<$T> List) *$T

  Adds a blank zero-initialized item to a list and returns a pointer to the new item.

  [view src]

• func insert(this *<$T> List, index usize) *$T

  Inserts a blank zero-initialized item into a list and returns a pointer to the new item.

  [view src]

• func insert(this *<$T> List, index usize, item POD $~T) void

  Inserts an item into a list.

  [view src]

• func append(this *<$T> List, item POD $~T) void

  Appends an item to a list.

  [view src]

• func prepend(this *<$T> List, item POD $~T) void

  Prepends an item to a list.

  [view src]

• func remove(this *<$T> List, index usize) void

  Removes an item from a list.

  [view src]

• func reserve(this *<$T> List, count usize) void

  Ensures a list can hold at least count items before having to expand.

  [view src]

• func get(this *<$T> List, index usize) $T

  Gets an item from a list.

  [view src]

• func getPointer(this *<$T> List, index usize) *$T

  Gets a pointer to an item in a list. The pointer may be invalidated when the list is modified.

  [view src]

• func clear(this *<$T> List)

  Clears a list.

  [view src]

• func empty(this *<$T> List) bool

  Returns whether this.length == 0

  [view src]

• func commit(this *<$T> List) <$T> List

  Changes the ownership of a list to be Ownership::REFERENCE. If the list previously had ownership, then a list value will be returned with Ownership::GIVEN, otherwise the original list will be returned. This method is used for transferring ownership of internal array data of lists to other lists.

  [view src]

• func donate(this *<$T> List) <$T> List

  If the list has ownership, then the list's ownership will be changed to Ownership::DONOR and a list value will be returned with Ownership::GIVEN, otherwise the original list will be returned. This method is used for transferring ownership of internal array data of lists to other lists. If ownership was transferred, then the subject value will be completely invalidated and will be unable to be used afterwards.

  [view src]

• func give() <$T> List

  Like commit(), except requires ownership. Not having ownership will cause a runtime error.

  [view src]

• func reverse(this *<$T> List) void

  Reverses a list.

  [view src]

• func reduce(this *<$T> List) void

  Removes the last item from a list.

  [view src]

• func reduce(this *<$T> List, amount usize) void

  Removes the last amount items from a list.

  [view src]

• func first(this *<$T> List) *$T

  Returns a pointer to the first item in the list. Will return null if the list is empty.

  [view src]

• func last(this *<$T> List) *$T

  Returns a pointer to the last item in the list. Will return null if the list is empty.

  [view src]

• func contains(this *<$T> List, value $~T) bool

  Returns whether a list contains an item that is equal to value.

  [view src]

• func map(this *<$T> List, function func($~T) $S) <$S> List

  Applies function to every item in a list to form another list.

  [view src]

Settings

#default List_bounds_checks       true
#default List_error_with_type     __typeinfo__
#default List_ownership_checks    true
#default List_disable_safety      false
#default List_preparation_checks  false
#default List_experimental        false
#default List_warn_experimental   true
#default List_error_on_donor_usage true