Lingo Doc+ for LISTs (971210)

Ldoc+ Lingo Group:
LISTs
 info D5/601:
      [ ] (list brackets)
 6     6 elements new in Director 6.0,
  !   17 contain Dictionary fixes 601 & 501,
   +  14 miss from the 'Appendix' 6.0 for LISTS.


General List Functions (10):
  !   [ ] (list brackets)
  !   [:] (list brackets)
      list()
      listP()
  !   count(list/object/script)
      duplicate(list)
      ilk(list/object)
      max(list)
      min(list)
      sort(list)

List Reading Functions (9):
      findPos()
      findPosNear()
      getaProp()
      getAt()
      getLast()
      getOne()
      getPos()
  !   getProp()
      getPropAt()

List Editing Functions (11):
  !   add()
  !   addAt()
  !   addProp()
  !   append()
 6!   deleteAll()
  !   deleteAt()
  !   deleteOne()
  !   deleteProp()
  !   setaProp()
  !   setAt()
  !   setProp()

Properties (8):
 6 +  on getPropertyDescriptionList
 6 +  on runPropertyDialog
   +  property
   +  set...=, set...to
  !+  # (symbol operator)
 6!+  symbol()
  !+  symbolP()
   +  the

Director's System Lists (6)
   +  actorList
   +  windowList
   +  deskTopRectList
 6 +  cuePointNames of member
 6 +  cuePointTimes of member
 6 +  scriptInstanceList of sprite

Director's String Listings (3):
      labelList
      mMessageList(xtra "name")
      xFactoryList

--

New LIST Lingo:
The 'deleteAll()' command works on all lists in D5/601,
also 'count(list/object/script)' works in D5/601.
[index] _ D5/601 _ 971210:

[ ] and [:]

Lingo's list brackets
6.0 Dictionary Errors, partly the same in 5.0:
"...useful...in the mechanical simulation."
= Delete that left-over part from earlier versions!

"You sort a list by using the appropriate command
 for a linear list or property list."
= Should read:
"You sort a linear or property list with the 'sort(list)'
 command. Most list commands work faster on sorted lists."

"In linear lists, symbols and strings are case-sensitive."
= Wrong: Symbols in any list are NOT case-sensitive:
  'set x = [#AB, #ab] .. put x .. -- [#ab, #ab]'!

"An empty list consists of two square brackets ([ ])."
= Should read:
"An empty LINEAR list consists of two square brackets ([ ]),
 an empty property list is '[:]'."

...if you temporarily 'set aPropList = [ ]', your list variable's
   type is changed and it won't be a property list anymore,
   and you CANNOT add any new properties into it after doing that.

"You can modifiy...items in a list..."
= Repeated error; should read:
"You can modifiy...ENTRIES in a list..."
...'item' is a Lingo chunk term for strings!

"Note: Lingo passes instances of a list as a reference to the list."
= Not understandable! Should read:
"Note: When you assign a list to a variable, the variable just
 contains a reference to the original list, not the list itself.
 Use the 'duplicate(list)' function to create true copies of lists."

"This handler sorts the list 'aList', and then..."
= Example 2 should read:
"This handler sorts the SUBMITTED PARAMETER 'aList', and then..."

= Missing:
"See Also:...addProp, deleteAll, deleteOne, deleteProp, getProp, setProp,
 listP(), ilk(#linearList), ilk(#propList), property (keyword)..."
 --

From the '601 ReadMe':
  Using 'set myList = value(myString)' no longer fails
  when 'myString' is bigger than 32K.
  --
1. TIP: All of Lingo's list commands work much faster on sorted lists, so whenever you can, use the 'sort(aLinearOrPropertyList)' function after initializing a list (see EXAMPLEs at 'setAt()').
2. TIP: If you use a list command (like 'addAt()' or 'addProp()' etc) on a thing that is NOT a list, or not the right type of list to accept this command, Lingo will just present an alert 'Script error: Handler not defined' and show the Lingo list command with a symbol sign in front. This means that Lingo thinks that you are calling your own user-defined handler called 'on add' or 'on addProp' etc, because the thing you are using that command on does not prove to accept it. But Lingo leaves it up to you to find out for yourself what's wrong in each case... Best to use the 'listP()' list validation function to check your specific variable or expression which doesn't accept Lingo's list commands. It might even be that you are using a list command on a valid list variable, but forgot to declare it as 'global'.
3. TIP: For property lists: Instead of using one of the different flavors of the 'getProp()' and 'setProp()' functions, you can test AND set their entries by using the keyword 'the' like you do with the property variables of any other object, like: 'set the aPropertyName of aPropList = 999'.
4. TIP: You can use some (property) list commands on scripts, like 'count(script memberNameOrNumber)' or 'getAt(script memberNameOrNumber, 1)', as well as on objects: 'count(object)' or 'getAt(goMyObject, 1)'.

[index] _ D5/601 _ 971210:

add()

linearList entry adding command
6.0 Dictionary Errors, same in 5.0:
"[1, 4, 5] ... add bids, 2"
= Example 2 misses info:
"The resulting list is '[1, 2, 4, 5]'."

= Missing:
"See Also: addAt, append,
 [ ] (list brackets), list(), listP(), ilk(#linearList)"
 --
[index] _ D5/601 _ 971210:

addAt()

linearList entry adding command
6.0 Dictionary Errors, same in 5.0:
"Syntax:  addAt list, position, value"
= Should read:
"Syntax:  addAt linearList, position, value"

"This command adds a value to the list at the position..."
= Repeated error; should read:
"This command adds a value to the LINEAR list at the position..."

"...list named 'bids', which is [3,2,4, 3, 6,7]:
    set bids = [3,2,4, 5, 6,7]"
= The forth entry mis-matches; should read:
"...list named 'bids', which is [3,2,4, 5, 6,7]: ..."

= Missing:
"See Also: add, append, list(), listP(), ilk(#linearList)"
 --
1. TIP: If you use 'addAt(aLinearList, aPosition, aValue)' on a linear list that contains fewer entries than the given position, the list is expanded with blank entries of 0 before the new entry position, delimited by commas.
2. TIP: You can use 'addAt(aLinearList, 5, anyValue)' on points and rects to add more entries into them than they actually have (a point has 2 and a rect has 4 entries). This might be a useful way to store 'hidden' data at the end of point and rect variables... ;-)
3. TIP: See ''setAt()' for EXAMPLEs.

[index] _ D5/601 _ 971210:

addProp()

propertyList adding command
6.0 Dictionary Errors, same in 5.0:
"Syntax:  addProp list, position, value"
= Should read:
"Syntax:  addProp propList, position, value"

"...to the property list specified by 'list'."
= Should read:
"...to the property list specified by 'propList'."

= Missing:
"See Also: setaProp, listP(), ilk(#propList)"
 --

"The 'addProp' command works with linear lists only."
= The 5.0 Dictionary should read:
"The 'addProp' command works with PROPERTY lists only."
 --
1. TIP: All of Lingo's list commands work much faster on sorted lists, so whenever you can, use the 'sort(aLinearOrPropertyList)' function after initializing a list (see EXAMPLEs at 'setAt()').
2. TIP: If you add a (second) property to a list in which a property by this name already exists, and if the name is a symbol, then the newly added doublet will take on the (case-specific) writing of the first used property name: 'set propList = [#LINgo:1] .. addProp(propList, #linGO, 2) .. propList = [#LINgo:1,#LINgo:2]'.
3. TIP: The 'addProp()' command does NOT work on scripts and child objects. Use ''setAt()' instead.

[index] _ D5/601 _ 971210:

append()

linearList adding command
6.0 Dictionary Errors, same in 5.0:
"Syntax:  append list, value"
= Should read:
"Syntax:  append linearList, value"

"...'add' command, which adds a value to a sorted list..."
= Should read:
"...'add' command, which in case a list has been sorted
    adds a value..."

"set bids = [1, 3, 4]
 append bids, 2"
= The Example misses an important line:
"set bids = [1, 3, 4]
 sort(bids)
 append bids, 2"

...but it seems to be faster to first append, and then sort!

= Missing:
"See Also: ... addAt, listP(), ilk(#linearList)"
 --
[index] _ D5/601 _ 971210:

count()

counting command for lists entries and script/object properties
NEW for Director 4.0 - 6.0:
"Syntax:  count(theObject)
 This function returns...the number of properties in a parent script."
 --
TIP: The 'count()' command also works on child objects and scripts, as well as some other (property) list commands do, see EXAMPLE at 'debug(myObj)')

[index] _ D5/601 _ 971210:

deleteAll()

list emptying function, new in 6.0, works also in 5.0
6.0 Dictionary Errors:
"This command deletes all items in the specified list."
= Repeated error; should read:
"This command deletes all ENTRIES in the specified list."
...'item' is a Lingo chunk term for strings!

= Missing:
"See Also: ... deleteAt, deleteOne, deleteProp,
 [ ] (list brackets), listP(), ilk(#list)"
 --
TIP: The list command 'deleteAll()' is revealed in 6.0, but also works in 5.0. It deletes ALL entries in the specified LINEAR or PROPERTY list, but the emptied list will keep its list type, i.e. 'deleteAll(aLinearList)' results in the linear list being '[ ]', and 'deleteAll(aPropList)' results in the property list being '[:]'. It has the same function as the Lingo expressions: 'set linearList = [ ]' or 'set propList = [:]', except you don't have to specify the type of your list.

[index] _ D5/601 _ 971210:

deleteAt()

list entry deleting function
6.0 Dictionary Errors, same in 5.0:
"This command deletes the item in the position..."
= Repeated error; should read:
"This command deletes the ENTRY in the position..."
...'item' is a Lingo chunk term for strings!

"If you try to delete an object that isn't in the list...
 checking wether the item is in the list."
= Should read:
"If you try to delete a POSITION that isn't in the list...
 checking wether the list contains that NUMBER of entries."

"This handler checks wether an object is in the list..."
= Repeated error; the Example should read:
"This handler checks wether the list CONTAINS as many entries..."

= Missing:
"See Also: ... deleteAll, deleteOne,
 deleteProp, [ ] (list brackets), listP(), ilk(#list)"
 --
[index] _ D5/601 _ 971210:

deleteOne()

list entry deleting function
5.0 Dictionary Error, cleared in 6.0:
"The deleteOne command works with linear lists only."
= Should read:
"The deleteOne command works with LINEAR and PROPERTY lists."

= Missing:
"See Also: deleteAll, deleteAt, deleteProp,
 [ ] (list brackets), listP(), ilk(#linearList), ilk(#propList)"
 --
1. TIP: The second argument for 'deleteOne(aList, value)' must be the value or string of the list entry, NOT its position.
2. TIP: If you surround the arguments for 'deleteOne()' with parenthesis, you get undocumented return values of: 1 = the value was found and the list entry deleted, or 0 = the value was not found.

3. TIP: All of Lingo's list commands work much faster on sorted lists, so whenever you can, use the 'sort(aLinearOrPropertyList)' function after initializing a list (see EXAMPLEs at 'setAt()').

--
EXAMPLEs:
You can test 'the result' of the 'deleteOne()' function by putting it into a variable:
set myList = ["Delete this", "Don't delete this!"]
--
set x = deleteOne(myList, "Delete this")

if (x=1) then put ("Value found & deleted!")
-- "Value found & deleted!"
put mylist
-- ["Don't delete this!"]
--
put NOT deleteOne(myList, "Delete this")
-- 1
[index] _ D5/601 _ 971210:

deleteProp()
property list entry deleting command

6.0 Dictionary Errors, same in 5.0:
"Syntax:  deleteProp list, item"
= Repeated errors; should read:
"Syntax:  deleteProp propList, entry"

...and just forget what the Dictionary says about using
   this command for linear lists: It's name has PROP in it!

= Missing:
"See Also: ... deleteAll, deleteOne, listP(), ilk(#propList)"
 --
TIP: The 'deleteProp()' command, like all list 'delete' commands, does NOT work on child objects and scripts. Carrying the name "Prop" in it, the 'deleteProp()' command is specialized for property lists, and should stay that way; just forget about using it with linear lists, for those use the 'deleteAt()' command!

[index] _ D5/601 _ 971210:

getProp()

propList reading function
6.0 Dictionary Errors, same in 5.0:
"Syntax:  getProp(list, property)"
= Should read:
"Syntax:  getProp(propList, propertyName)"

= Missing:
"See Also: ... getaProp, getAt, getPos, getPropAt,
 listP(), ilk(#propList)"
 --

The 5.0 Dictionary even uses a linear list example,
but that does NOT work with the 'getProp()' command!
--
1. TIP: For property lists: Instead of using one of the different flavors of the 'getProp()' and 'setProp()' functions, you can test AND set their entries like you do with the property variables of a child object: 'set the aPropertyName of aPropList = 999' (see the 'property' keyword 'the').
2. TIP: All of Lingo's list commands work much faster on sorted lists, so whenever you can, use the 'sort(aLinearOrPropertyList)' function after initializing a list (see EXAMPLEs at 'setAt()').
3. TIP: The 'getProp()' command also works on scripts and child objects (same as other list commands do, see EXAMPLE at 'debug(myObj)'), but prefer to use 'getaProp()' because it will NOT produce an error alert when it doesn't find the entry.

[index] _ D5/601 _ 971210:

setaProp()

propList editing command
6.0 Dictionary Errors, same in 5.0:
"Syntax:  setaProp list, property, newValue"
= Should read:
"Syntax:  setaProp propList, propertyName, newValue"

"...and then add the item #c:10 to the list: ..."
= Repeated error; the Example should read:
"...and then add the ENTRY #c:10 to the list: ..."
...'item' is a Lingo chunk term for strings!

= Missing:
"See Also: ... setAt, setProp, listP(), ilk(#propList)"
 --

"setaProp x, #c, 10"
= The 5.0 Dictionary should read:
"setaProp NEWLIST, #c, 10"
 --
1. TIP: Remember: Use the 'setaProp()' command if you're NOT sure if the property is already in your propList, because 'setaProp()' does its own checking and will add the property if its not already there, whereas 'setProp()' produces an error alert if it can't find the entry.
2. TIP: All of Lingo's list commands work much faster on sorted lists, so whenever you can, use the 'sort(aLinearOrPropertyList)' function after initializing a list (see EXAMPLEs at 'setAt()').
3. TIP: Instead of using 'setProp()' or 'setaProp()' to change entries in property lists, child objects, or scripts, you can test AND set 'the aPropertyName of aPropList' (see the 'property' keyword 'the').
4. TIP: The 'setaProp()' command also works on scripts and child objects (same as other list commands do, see EXAMPLE at 'debug(myObj)') and will either set a script property or add (initialize) the property if it's not already used in the script or global object.

[index] _ D5/601 _ 971210:

setAt()
list changing command

6.0 Dictionary Errors, same in 5.0:
"This command replaces the item specified..."
= Repeated error; should read:
"This command replaces the ENTRY specified..."
...'item' is a Lingo chunk term for strings!

"...Director expands the list's blank entries
    to provide the number of places..."
= Not exactly; should read:
"...Director expands the linearList with integer entries of '0'
    to provide the number of places..."

= Missing:
"See Also: setaProp, setProp,
 listP(), ilk(#linearList), ilk(#propList)"
 --

"If the list contains fewer items...Lingo gives a script error"
= The 5.0 Dictionary should read:
"If the PROPERTY list contains fewer items...script error"
 --
1. TIP: The 'setAt()'command seems to be the ONLY list command that does NOT work faster on sorted lists -- it works fast as lightning on both list types... ;-)
2. TIP: For property lists, instead of using 'setAt()' to change their entries, you can test AND set 'the aPropertyName of aPropList' (see the 'property' keyword 'the').
3. TIP: For nested lists (lists containing sublists), the 'setAt()' command can work on the result of nested 'getAt()' commands and thus change the sublist's content. If the variable 'myList' contains '[ [1,2], [1,2] ]', then 'setAt( getAt(myList, 2), 1, 999 )' will get the second sublist from the main list, and put 999 into its first position, whereas: 'getAt( getAt(myList, 2), 1 )' returns the value at the first position of the list's second sublist. Remember: If you make a copy of the original list or put any of its contents into a new varibale by using 'getAt()', and then change any of the list contents of the new variable, you will ALSO change the original list -- if you didn't make a true copy of it using the 'duplicate(aList)' function. Easy, eye... 8-)
4. TIP: You can use 'setAt(aList, entryPosition, value)' on points and rects, and you can even use the 'setAt()' or 'addAt()' command to add more entries into them than they actually have (a point has 2 and a rect has 4 entries). This might be a useful way to store 'hidden' data at the end of points and rects... ;)
5. TIP: The 'setAt()' command does NOT work on scripts and child objects.

--
EXAMPLEs:
Here are some times of repeated list commands on the first entry of a property list with 9 entries (Mac 68K):
--> Time for 20,000 x SET commands on an unsorted propList:
--> setAt:     129 ticks
--> setProp:   677 ticks
--> setaProp:  679 ticks
--> set the :  702 ticks.

--> Time for 20,000 x SET commands on a SORTED propList:
--> setAt:     129 ticks
--> setProp:   364 ticks
--> setaProp:  362 ticks
--> set the :  388 ticks.

-->  Now lets deal with hidden areas :-)
--
set x = point(1,2)
put x
-- point(1, 2)
put the locH of x
-- 1
put the locV of x
-- 2
setAt(x, 2, 222)
put x
-- point(1, 222)
setAt(x, 4, 4444)
put x
-- point(1, 222, 0, 4444)

put ilk(x)
-- #point
put ilk(x, #list)
-- 1
put ilk(x, #rect)
-- 0
--
-->  The point is still a point!
-->  Now let's use 'setAt' on rects:
--
set x = the rect of the stage
put x
-- rect(0, 0, 640, 480)

setAt(x, 3, 3333)
put x
-- rect(0, 0, 3333, 400)
setAt(x, 7, 777)
put x
-- rect(0, 0, 640, 3333, 0, 0, 777)

put ilk(x)
-- #rect
put ilk(x, #list)
-- 1
put value(x)
-- rect(0, 0, 640, 3333, 0, 0, 777)
set x = x + 1
put x
-- rect(1, 1, 641, 3334, 1, 1, 778)

put ilk(x, #rect)
-- 1
[index] _ D5/601 _ 971210:

setProp()

propList editing command
6.0 Dictionary Errors, same in 5.0:
"Syntax:  setProp list, property, newValue"
= Should read:
"Syntax:  setProp propList, propertyName, newValue"

...The Example has the property list 'x' missing!

= Missing:
"See Also: ... setAt, listP(), ilk(#propList)"
 --

(Top)

URL = "http://www.a3w.de/Lingo/Ldoc_Lists.html" (971210)

Ldoc+ Lingo Group: LISTs

[ ] and [:]

add()

addAt()

addProp()

append()

count()

deleteAll()

deleteAt()

deleteOne()

EXAMPLEs:

deleteProp()

getProp()

setaProp()

setAt()

EXAMPLEs:

setProp()

Ldoc+ Lingo Group:
LISTs