1.1 - Flat Bags: much more than dictionaries and lists

First of all a flat Bag can be considered simply as a dictionary which items are ordered and keys may be duplicated.

1.1.1 - How to instantiate a Bag

To instantiate a bag, you pass a list composed of tuples or a dict, to the constructor. If you don't pass any argument you obtain an empty bag.

from gnr.core.gnrbag import Bag
mybag= Bag()
mybag = Bag([('a',1),('b',2)])
mybag = Bag({'a': 1, 'b':2})

1.1.2 - Setting and Getting items

You can read/write a bag's item using the methods getItem(path), setItem(path,value). When considering flat bags, the path is called a label and represent the item's identifier among the bag's children.

mybag = Bag()
mybag.setItem('a',1)
first= mybag.getItem('a')

A more compact way to access to bag's items is the square-brackets notation, which is a typical feature of dictionaries.

mybag['b']=2
second = mybag['b']

1.1.3 - Duplicated labels

It is evident that there are several analogies between a bag's label and dictionary key, but there are also some fundamental differences.

• A bag's label must be a string: numbers or complex types are not valid labels.
• Unlike dictionaries, whose keys must be unique, bags can have different items tagged with the same label.
• If you try to get an item that is not present within the bag, python doesn't raise an exception, but the method getItem returns None

IMPORTANT - It is possible to insert different values with the same label, but in order to do this you have to use the method addItem(label,value) because setItem(label,value) would set a new value on the old item.

beatles= Bag()
beatles. addItem('member', 'John') # you could also use ''setitem'' to add the first item to the bag
beatles. addItem('member', 'Paul')
beatles. addItem('member', 'George')
beatles. addItem('member', 'Ringo')

1.1.4 - Accessing to items by index

A bag is an ordered container, in fact a Bag remembers the order of insertion of its children. This makes a Bag similar to a list, allowing it to get its items with a numeric index that represents an element's position. If you want to access data by its position, you have to use a particular label composed by # followed by the item's index.

first= mybag.getItem('#1')
second= mybag['#2']

This feature is very useful when a bag has several items with the same label, because the method getItem(label) returns only the first item tagged with the argument label. This means that the only way to access items with a duplicated label is by index.

lennon= beatles.getItem('member')
lennon= beatles.getItem('#0')
mccartney=beatles.getItem('#1')
harrison=beatles['#2']

If you need to know the ordinal position of an item you can use the method index(label). But remember that unlike a list's index method, returns the element position using its label and not its value. A bag's label can be duplicated and in this case the method index(label) returns the position of the first occurrence of the label.

n= beatles.index('member')
lennon= beatles['#%i' %n']

1.1.5 - Setting item's position

It is possible to set a new item at a particular position among its brothers, using the optional argument _position of the method setItem(label,value). The default behaviour of setItem is to add the new item as the last element of a list, but the _position argument provides a compact syntax to insert any item at it's desired place. _position must be a string of the following types:

'<'	set as first item
'<label'	set before the element with label
'<#index '	set before the element with index
'>'	set as last item
'>label'	set after the element with label
'>#index '	set after the element with index
'#index'	set at position

mybag=Bag({'a':1,'b':2,'c':3,'d':4})
mybag.setItem('e',5, _position= '<')
mybag.setItem('f',6, _position= '<c')
mybag.setItem('g',7, _position= '<#3')

1.1.6 - How to display a bag

If you want to display a bag in your python shell you can use the built-in function print. If you need a bag's representation as a string use the method asString

>>> print mybag

0 - (int) e: 5  
1 - (int) a: 1  
2 - (int) g: 7  
3 - (int) f: 6  
4 - (int) c: 3  
5 - (int) b: 2  
6 - (int) d: 4

>>> mystring= mybag.asString()
>>> mystring

0 - (int) e: 5  
1 - (int) a: 1  
2 - (int) g: 7  
3 - (int) f: 6  
4 - (int) c: 3  
5 - (int) b: 2  
6 - (int) d: 4

Bag representation makes a line for each item. The line is structured:

item's index

item's type

label

value

1.1.7 - Other similarities between bags, dictionaries and lists

1.1.7.1 - Dictionary methods

• bag.keys()
• bag.items()
• bag.values()
• bag.has_key()

1.1.7.2 - List methods

• index()
• pop()

1.1.7.3 - The operator 'in'

Bag also supports the operator in exactly like a dictionary or list.

>>>'a' in mybag
True

1.1.7.4 - Transform a flat bag in a dictionary

A bag can be transformed into a dict with the method asDict()

d=b.asDict()

If you attempt to transform a bag that is hierarchical, to a dictionary, you will not generate an error but the resulting dictionary will contain only the first level of the bag.

---

Error: Failed to load processor FooterNavLinks

No macro or processor named 'FooterNavLinks' found