6.7. The bracket operator

6.7. The bracket operator
	Chapter 6. YCP Operators

6.7.1. Introduction

The bracket operator is the use of '[' and ']' like accessing arrays in C.

In YCP, this operator is used to ease handling with (possibly nested) lists and maps.

The bracket operator can be applied to any list or map variable and should be used in favour of (deeply) nested lookup() and select() cascades.

6.7.2. Access variant

The access variant of the bracket operator is used for accessing elements of a list or a map. It effectively replaces select for lists and lookup for maps.

6.7.2.1. Accessing lists

General syntax:

for simple lists:

<list-var>[<index>]:<default-value>

for nested lists:

<list-var>[<index>,<index> <, ...>]:<default-value>

index must be an integer and counts from 0 up to the number of elements-1.

It will return the default-value if you try to access an out-of-bounds element.

	Important
	Note that there must be no space between the closing bracket and the colon.

Examples:

{
    list list_of_numbers = [1, 2, 3];

    // value of element with index 2 is 3
    integer three = list_of_numbers[2]:0;

    // evaluates to the default value 0,
    // because list element with index 42 doesn't exist
    integer zero = list_of_numbers[42]:0;

    // evaluates to 4
    integer number = [3, 4, 5][1]:8;

    list list_of_lists = [[1,2], [3,4], [5,6]];

    // list_of_lists[1] -> [3,4]
    // [3,4][0] -> 3
    //
    // returns true because the left side evaluates to 3
    // just as the right side does (three == 3)
    return (list_of_lists[1,0]:0 == three);
}

6.7.2.2. Accessing maps

General syntax:

for simple maps:

<map-var>[<key>]:<default-value>

Examples:

{
    // map with string as a key, integer as a value
    map simple_map = $["a":1, "b":2, "c":3];

    // evaluates to 3
    integer three = simple_map["c"]:0;

    // evaluates to 0
    integer zero = simple_map["notthere"]:0;
}

{
    // map with string as a key, integer as a value
    // this example also defines the data-types
    map <string, integer> simple_map = $["a":1, "b":2, "c":3];

    // evaluates to 3
    integer three = simple_map["c"]:0;

    // evaluates to 0
    integer zero = simple_map["notthere"]:0;
}

for nested lists:

<map-var>[<key>,<key> <, ...>]:<default-value>

key must have an allowed type for maps, integer, string, or symbol.

It will return default-value if you try to access an non existing key.

	Important
	Note that there must be no space between the closing bracket and the colon.

Examples:

{
    // map with string as a key and another map as a value
    map nested_map = $[
	"a":$[1:2],
	"b":$[3:4],
	"c":$[5:6]
    ];

    // nested_map["b"] -> $[3:4] ("b" is a key of the map)
    // $[3:4][3] -> 4            ( 3  is a key of the map)
    //
    // returns true
    return (nested_map["b",3]:0 == 4);
}

{
    // map with string as a key and another map as a value
    // this map has a defined data-type
    map <string, map <integer, integer> > nested_map = $[
	"a":$[1:2],
	"b":$[3:4],
	"c":$[5:6]
    ];

    // returns true
    return (nested_map["b", 3]:0 == 4);
}

6.7.2.3. Mixed map/list access

Since the bracket operator applies to list and maps, you can use it to access nested lists and maps. But be careful not to mix up the index/key types.

Examples:

{
    map <string, list <integer> > map_of_lists = $[
	"a":[1, 2, 3, 4],
	"b":[5, 6],
	"c":[7, 8, 9]
    ];
    // evaluates to 3
    integer three = map_of_lists["a", 2]:0;

    list <map <integer, integer> > list_of_maps = [
	$[0:1],
	$[2:3],
	$[4:5]
    ];
    // returns true
    return (list_of_maps[1,2]:0 == three);
}

6.7.3. Assign variant

The bracket operator can also be used on the left side of an assignment (lvalue). This changes the list or map element in place (!!) and must be used with care.

If the map or list element does not exist, it will be created. The bracket operator can therefore replace add and change.

Creating a new list element will extend the size of the list. Holes will be filled with nil. See the examples below.

If used as an lvalue, the default value is not allowed.

Examples:

{
    list numbers = [1, 2, 3];

    // changes the second element
    // numbers == [1, 25, 3] now
    numbers[1] = 25;

    // extends the list to 7 elements (0-6)
    // numbers == [1, 25, 3, nil, nil, nil, 6] now
    numbers[6] = 6;

    // remove an element item with index 2
    // numbers == [1, 25, nil, nil, nil, 6] now
    numbers = remove (numbers, 2);
}

{
    map <string, integer> new_map = $["a":1, "b":2, "c":3];
    // changes the "c" element
    // new_map == $["a":1, "b":2, "c":42] now
    new_map["c"] = 42;

    // add a new element to m
    new_map["zz"] = 13;

    // remove an elment "a"
    // new_map == $["b":2, "c":42, "zz":13] now
    new_map = remove (new_map, "a");

    // returns $["b":2, "c":42, "zz":13]
    return (new_map);
}


6.6. Operators Precedence		Chapter 7. Data Type locale