FirstElement()

Syntax

FirstElement(linkedlist())

Changes the current list element to the first list element.

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 first element exists or not (it will not exist if the list is empty). If the first item exists, this command will return a value which is not equal to zero. If the first element does not exist then it will return a value of zero.

Advanced users only:
The value that this command returns is a pointer to the first element or zero if the first element does not exist. 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:

  ; An example of simple usage
  NewList numbers.w()

  AddElement(numbers())
  numbers() = 5
  AddElement(numbers())
  numbers() = 8

  FirstElement(numbers())
  MessageRequester("Information", "First element value is "+Str(numbers()), #PB_MessageRequester_OK)


  ; An example which uses the return value
  NewList numbers.w()

  If FirstElement(numbers()) <> 0
    MessageRequester("Information", "First element value is "+Str(numbers()), #PB_MessageRequester_OK)
  Else
    MessageRequester("Information", "List is empty", #PB_MessageRequester_OK)
  EndIf

  AddElement(numbers())
  numbers() = 5
  AddElement(numbers())
  numbers() = 8

  If FirstElement(numbers()) <> 0
    MessageRequester("Information", "First element value is "+Str(numbers()), #PB_MessageRequester_OK)
  Else
    MessageRequester("Information", "List is empty", #PB_MessageRequester_OK)
  EndIf


  ; An example which is only for advanced users
  NewList numbers.w()

  AddElement(numbers())
  numbers() = 5
  AddElement(numbers())
  numbers() = 8

  *element.w = FirstElement(numbers())
  If *element
    MessageRequester("Information", "First element value is "+Str(PeekW(*element+8)), #PB_MessageRequester_OK)
  Else
    MessageRequester("Information", "List is empty", #PB_MessageRequester_OK)
  EndIf

Supported OS

All