List expansion (*.)

Gosu includes a special operator for array expansion and list expansion. The expansion operator is an asterisk followed by a period. Array expansion is valuable if you need a single one-dimensional array or list through which you can iterate.

The return value is as follows:

  • If you use the expansion operator on an array, Gosu gets a property from every item in the array and returns all instances of that property in a new, single-dimensional, read-only array.
  • If you use the expansion operator on a list, Gosu gets a property from every item in the list and returns all instances of that property in a new, single-dimensional, read-only list.

You can access elements in the new array or list individually with index notation, and you can iterate through the elements in a for loop. You cannot modify the elements of the new array or list.

The following code creates a String array. String objects in Gosu have a length property that contains the number of characters. The code uses the expansion operator on the array to create an array of string lengths for elements of the original array. Because the length property is of type int, the expansion array also is of type int. 

var stringArray = new String[] {"one", "two", "three", "four"} 
var lengthArray = stringArray*.length 

for (element in lengthArray) { 
  print(element) 
}

The output from this code is:

3
3
5
4

Suppose you have an array of Book objects, each of which has a String property Name. You could use array expansion to extract the Name property from each item in the array. Array expansion creates a new array containing just the Name properties of all books in the array.

If a variable named myArrayOfBooks holds your array, use the following code to extract the Name properties:

var nameArray = myArrayOfBooks*.Name

The nameArray variable contains an array whose length is exactly the same as the length of myArrayofBooks. The first item is the value myArrayofBooks[0].Name, the second item is the value of myArrayofBooks[1].Name, and so on.

Suppose you wanted to get a list of the groups to which a user belongs so that you can display the display name property of each group. Suppose a User object contains a MemberGroups property that returns a read-only array of groups to which the user belongs. In this case, the Gosu syntax user.MemberGroups returns an array of Group objects, each one of which has a DisplayName property. To get the display name property from each group, use the following Gosu code 

user.MemberGroups*.DisplayName

Because MemberGroups is an array, Gosu expands the array by the DisplayName property on the Group component type. The result is an array of the names of all the Groups to which the user belongs. The type is String[].

The result might look like the following:

["GroupName1", "GroupName2", "GroupName14", "GroupName22"]

The expansion operator also applies to methods. Gosu uses the type on which the method runs to determine how to expand the type:

  • If the original object is an array, Gosu creates an expanded array.
  • If the original object is a list, Gosu creates an expanded list.

The following example calls a method on the String component of the List of String objects. Gosu generates a list of initials by extracting the first character in each String.

var s = {"Fred", "Garvin"}

// Generate the character list [F, G]
var charList = s*.charAt( 0 )

Important notes about the expansion operator:

  • The generated array or list itself is always read-only from Gosu. You cannot assign values to elements of the array, such as setting nameArray[0].
  • The expansion operator *. applies only to array expansion, not for standard property accessing.
  • When using the *. expansion operator, only component type properties are accessible.
  • When using the *. expansion operator, array properties are not accessible.
  • The expansion operator applies to arrays and to any Iterable type and all Iterator types. The operator preserves the type of the array or list. For instance, if you apply the *. operator to a List, the result is a List. All other expansion behavior is the same as for arrays.

See also