InsertElement()

Syntax

InsertElement(LinkedList())

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.

Parameter:
LinkedList() - The name of your linked list variable, created with the NewList function. You must include the brackets after the list name.

Return value:
The value returned by this function can be used to show whether the new element could be created or not (it may not be created if, for example, you have no more free memory on your computer). If the new element was created, this function will return a value which is not equal to zero. If the new element could not be created, then it will return a value of zero.

Advanced users only:
The value that this function returns is a pointer to the new element data or zero if the new element could not be created.

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 "advanced users" description (above)
  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

Supported OS

All