InsertElement()

Syntax

Result = InsertElement(List())

Inserts a new empty element before the current element, or at the start of the list if the list is empty (i.e. has no elements in it). This new element becomes the current element of the list.

Parameters

List()

The name of your list variable, created with the NewList function. You must include the brackets after the list name.

Return value

Returns non-zero if the new element was created and zero otherwise. The value returned is a pointer to the new element data.

Example

  ; The simplest way to use InsertElement
  NewList simple.w()
  InsertElement(simple())    ; Creates the first new element in the list
  simple() = 23

  InsertElement(simple())    ; Current position is the first element, so we add this element to the start of the list
  simple() = 45              ; The old first element is now the second element in the list


  ; This shows how to use the return-value of InsertElement
  NewList advanced.l()
  If InsertElement(advanced()) <> 0
    advanced() = 12345
  Else
    MessageRequester("Error!", "Unable to allocate memory for new element", #PB_MessageRequester_OK)
  EndIf


  ; A small structure to demonstrate the use of the pointer to the new element
  Structure Programmer
    Name.s
    Strength.b
  EndStructure

  NewList Programmers.Programmer()  ; The list for storing the elements

  *Element.Programmer = InsertElement(Programmers())
  If *Element<>0
    *Element\Name = "Dave"
    *Element\Strength = 3   ; Wow, super-strong geek! ;)
  Else
    MessageRequester("Error!", "Unable to allocate memory for new element", #PB_MessageRequester_OK)
  EndIf

See Also

AddElement(), DeleteElement(), ClearList()

Supported OS

All