LCB Lists and Arrays

Two important types in LCB, which deserve some more attention are lists and arrays.

• list – a list is a sequence of values, each element of the sequence is assigned a numerical index, starting with 1 and proceeding sequentially
• array – an array is a mapping from a string to any value (i.e. an associative array, just like in LiveCode Script)

Creating Lists in LiveCode Builder

Creating a list in LiveCode Builder is very simple, you put a comma-separated list of values between square brackets as shown.

Each element in a list can hold a different type of value.

library community.livecode.elanorb.example

metadata title is "Example Library@
metadata author is "Elanor Buchanan"
metadata version is "1.0.0"

public handler CreateList() returns nothing
    variable tLetterList as List
    variable tNumberList as List
    variable tMixedList as List

    put ["a","b","c"] into tLetterList
    put [1,2,3] into tNumberList
    put ["one","two","three",4,5,6] into tMixedList
end handler

end library

You can also split a string into a list using the split keyword.

You specify the delimiter you want to use and the string is split into a list of strings using the delimiter.

public handler CreateListFromString() returns String
   variable tVar as String
   variable tSplit as List
   
   put "first,second,third,fourth,fifth" into tVar
   split tVar by "," into tSplit
end handler

List elements

You can access the individual elements of a list using the element keyword.

You can

• Get the value of an element
• Set the value of an element
• Delete an element

To add an element to a list you push a value onto the list, you can push a value onto the front or end of a list.

public handler ListElement() returns any
  variable tMixedList as List
  put ["one","two","three",4,5,6] into tMixedList

  delete element 2 of tMixedList -- tMixedList = ["one","three",4,5,6]

  put "five" into element 4 of tMixedList  -- tMixedList = ["one","three",4,"five",6]

  push "zero" onto front of tMixedList   -- tMixedList = ["zero","one","three",4,"five",6]

   return element 1 of tMixedList -- returns "0"   
end handler

Note: LCB lists are 1 based.

Note: It is an error if the index is out of range.

Creating Arrays in LCB

Arrays in LCB are created in the same was as in LiveCode Script, so you are likely familiar with the syntax.

You specify an element of an array variable by using the variable name along with the element’s key. You enclose the key in square brackets. In LiveCode Builder array keys are always strings.

public handler CreateArray() returns nothing
  variable tCapitals as Array

  put "Kabul" into tCapitals["Afghanistan"]
  put "Tirana" into tCapitals["Albania"]
  put "Algiers" into tCapitals["Algeria"]
  put "Andorra la Vella" into tCapitals["Andorra"]
  put "Luanda" into tCapitals["Angola"]
end handler

You can also create LiveCode Builder arrays using {} notation with the syntax:

{Key 1:Value 1,Key 2:Value 2,...,Key n:Value n}

public handler CreateBracketedArray() returns nothing
  variable tCapitals as Array

  put {"Afghanistan":"Kabul", "Albania":"Tirana", "Algeria":"Algiers", "Andorra":"Andorra la Vella", "Angola":"Luanda"} into tCapitals

  return tCapitals
end handler

Array elements

You can access the individual elements on array using square bracket notation.

You can

• Get the value of an element
• Set the value of an element
• Delete an element

public handler CreateArray() returns nothing
  … previous array code

  -- Add an element to the array
  put "St. John" into tCapitals["Antigua and Barbuda"] -- adds an element to the array

  -- Update an existing element of the array
  put "St. John's" into tCapitals["Antigua and Barbuda"] -- updates an existing element of the array

  -- Delete the specified element of the array
  delete tCapitals["Antigua and Barbuda"] -- deletes the specified element of the array
end handler

Nested elements

Both lists and arrays can be nested. This means an element in a list can contain another list, or an element in an array can contain another array.

public handler CreateNested() returns nothing
    -- A nested  list (list of lists)
    variable tListOfLetters as List
    put ["a", ["b","B"]] into tListOfLetters

    -- A nested array
       variable tCapitals as Array
       variable tSpain as Array

       put "Madrid" into tSpain["name"]
       put "3,165,000" into tSpain["population"]
       put tSpain into tCapitals["Spain"]
end handler

Elements of a nested list can be accessed by using multiple element values. For example:

return element 2 of element 2 of tListOfLetters -- returns “B”

Elements of a nested array can be accessed by using multiple sets of square brackets containing the keys. For example:

return tCapitals["Spain"]["name"] -- returns “Madrid”

You can also create nested arrays directly using the syntax:

{Key 1:Value 1,Key 2:Value 2,...,Key n:Value n}

Where each value can also be an array expression
{Key 1:{Key a:Value a,Key b:{Key α:Value α,Key β:Value β}},Key 2:Value 2,...,Key n:Value n}

For example:

public handler CreateNested() returns nothing
    variable tCapitals as Array
    put {"Spain": {"Name": "Madrid","Population":"3,165,000"},"UK":{"Name": "London","Population":"8,539,000"}} into tCapitals
end handler

Returns: