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 command. You must specify the brackets after the list name.

Return value:
The value returned by this command 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 command 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 command returns is a pointer to the new element or zero if the new element could not be created. The structure of each element is shown below:

  Structure Element
    *Next.Element        ; Pointer to next element in list or zero if at last element
    *Previous.Element    ; Pointer to previous element in list or zero if at first element

    ; The users data type which the list was created with will follow
    ; those two variables (which means the user data can be found at
    ; the address of the new element + 8
  EndStructure

You should not change the pointers at the start of the elements as this will break the structure of the list, leading to all sorts of problems.

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

  Structure SuperGeek
    *Next.SuperGeek
    *Previous.SuperGeek
    Name.s      ; The same field than the 'Programmer' structure
    Strength.b
  EndStructure

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

  *Element.SuperGeek = 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