# Hurricane VLSI Database

List of all members | Public Member Functions
Hurricane::Collection< Type > Class Template Referenceabstract

Collection description (API) More...

Inheritance diagram for Hurricane::Collection< Type >:
[legend]

## Public Member Functions
virtual | ~Collection ()
virtual Collection< Type > * | getClone () const =0
virtual Locator< Type > * | getLocator () const =0
virtual unsigned | getSize () const
Type | getFirst () const
GenericCollection< Type > | getSubSet (const Filter< Type > &filter) const
template<class SubType >
GenericCollection< SubType > | getSubSet () const
template<class SubType >
GenericCollection< SubType > | getSubSet (const Filter< SubType > &filter) const

## Detailed Description

### template<class Type>
class Hurricane::Collection< Type >

Collection description (API)

# Introduction

Collections introduce the concept of set of elements.

Strictly speaking collections are not containers (in the STL way) but indeed set descriptors. For example, the set of instances called by a cell, which are located within a given rectangular area, will be a subtype of Collection<Instance*> whose first attribute will be a pointer to the cell and a second attribute the rectangular area.

Main characteristics of Collections:

- Collections do not own their elements (they remains when the Collection is deleted).
- They can only be iterated forward. Once an element is consumed you cannot go back to it. You must restart the collection walktrough instead.
- Collections are very light objects which are built, copied or destroyed very rapidly.

# STL Iterator Support

The Collections now provides a basic iterator support to allow the C++11 `for` contruct:

Cell* cell = ...; // Get a Cell from somewhere.
for( Net* inet : cell->getNets() ) {
cout << "This is " << inet;
if (inet->isExternal())
cout << " [external net].";
cout << endl;
}

Although the `forEach` macro is still retained for backward compatibility, it is advisable to use the C++11 way.

# The forEach Macro (obsoleted)

Collections are to be used in conjunction with the `forEach` macro which allows to easily iterate over the elements. Iteration is done through a simplistic iterator which have overload for the `operator*()` and `operator->()`

The `forEach` macro takes three arguments:

`forEach(type,iterator,collection)`
`type` | Element's type of the collection.
`iterator` | Name of the iterator's variable.
`collection` | An appropriate collection to iterate over, that is, built over `type` elements.

To use the forEach macro outside the Hurricane namespace, the following statement is necessary:

using Hurricane::ForEachIterator

Here is a small example of a loop:

using Hurricane::ForEachIterator;
Cell* cell = ...; // Get a Cell from somewhere.
forEach( Net*, inet, cell->getNets() ) {
cout << "This is " << (*inet);
if (inet->isExternal())
cout << " [external net].";
cout << endl;
}

# The Generic getCollection

The collections provide the generic `getCollection()` function which allows to convert its argument into a generic collection. It has no specific interest for Hurricane collections, but this function is overloaded for STL containers.

This allows to handle a STL containers like a normal collection as shown in the following example:

set<Instance*> instanceSet;
// here we fill the set with the desired instances...
forEach(Instance*, iinstance, getCollection(instanceSet)) {
// process here each instance of the set
// (the elements are visited according to the set ordering)
}

Remark: This approach is a little bit less efficient than the use of
  STL iterators, not much indeed, but has the advantage to be homogeneous with the remaining code (recall: the created collection doesn't make a copy of the STL container and its creation time is negligible).

Caution: The returned collection is valid whenever the STL container
  is valid. Then you should not do the following:
  GenericCollection<Instance*> getInstances(...)
  {
  set<Instance*> instanceSet;
  // we fill the container with the appropriate instances
  return getCollection(instanceSet); // instanceSet deleted after return
  }

The same will occur anyway if you do:

Cell* cell = ...; // we get the cell
Nets nets = cell->getNets();
cell->destroy();
forEach(Net*, inet, nets) {
...
}

# Locators

Each type of collection provides an associated Locator for tracing through the corresponding set of elements.

Each locator moves efficiently through the data structure without building (in the form of a list or any other container type) the set of elements defined by the collection (it may however use a stack (or something else) to manage recursive traces).

The elements are therefore visited in the order with which they are internally stored. No assumptions must be made about this ordering. However, collections representing an STL container are visited in the same order than the container's one.

If you need to visit the objects in a given order, you must first fill a STL container: either a vector to be sorted accordingly or a set with the given sort criteria (see the Fill method below).

## Constructor & Destructor Documentation

## ◆ ~Collection()

template<class Type>

Hurricane::Collection< Type >::~Collection< Type > | ( |  | ) |
| inline virtual

Destroys the collection but doesn't acts on elements refered by this collection.

## Member Function Documentation

## ◆ getClone()

template<class Type>

Collection< Type > * Hurricane::Collection< Type >::getClone | ( |  | ) | const
| pure virtual

Allocates and returns a clone (copy) of the collection (whatever be its type).

Remark: In principle there is no need to use this function. However,
  if you do so, don't forget to delete the clone after use. It is indeed much easier to use generic collections which do that for you, as we will see later.

## ◆ getLocator()

template<class Type>

Locator< Type > * Hurricane::Collection< Type >::getLocator | ( |  | ) | const
| pure virtual

Allocates and returns a locator adapted to visit the elements of the collection.

Remark: In principle there is no need to use this function. Use
  preferably the macro for_each described below. However, if you do so, don't forget to delete this locator after use, else use generic locators, which do that for you, as we will see later.

Referenced by Hurricane::Collection< SubType >::getFirst(), and Hurricane::Collection< SubType >::getSize().

## ◆ getSize()

template<class Type>

unsigned Hurricane::Collection< Type >::getSize | ( |  | ) | const
| inline virtual

Returns: the number of objects identified within the collection.

Remark: Very fast in some cases, but may need to visit the collection
  in most ones.

## ◆ getFirst()

template<class Type>

Type Hurricane::Collection< Type >::getFirst | ( |  | ) | const
| inline

Returns: the first element of the collection.

Remark: The result is meaningful only when the collection is non
  empty.

## ◆ getSubSet() [1/3]

template<class Type>

GenericCollection< Type > Hurricane::Collection< Type >::getSubSet | ( | const Filter< Type > & | filter | ) | const
| inline

Returns: the collection representing the subset of elements accepted by the filter.

Nets Cell::getExternalNets() const
{
return getNets().getSubSet(Net::getIsExternalFilter());
}

## ◆ getSubSet() [2/3]

template<class Type>
template<class SubType >

GenericCollection< SubType > Hurricane::Collection< Type >::getSubSet< SubType > | ( |  | ) | const
| inline

Returns: the collection corresponding to the subset of elements of type `<SubType>`.

Remark: The returned collection is a collection of objects of type
  SubType and not of type Type.

Contacts Net::getContacts() const
{
return getComponents().getSubSet<Contact*>();
}

Referenced by Hurricane::Collection< SubType >::getSubSet().

## ◆ getSubSet() [3/3]

template<class Type>
template<class SubType >

GenericCollection< SubType > Hurricane::Collection< Type >::getSubSet< SubType > | ( | const Filter< SubType > & | filter | ) | const
| inline

Returns: the collection representing the subset of elements of type `<SubType>` accepted by the filter.

Remark: The returned collection is a collection of elements of type
  SubType and not of type Type and the filter must be a filter of elements of type SubType.

Sample: Filter Hurricane::Segment according to their Layer.
  class IsOnLayer : public Filter<Segment*> {
  public:
  Layer* _layer;
  public:
  IsOnLayer(Layer* layer)
  : _layer(layer)
  {
  if (!_layer) throw Error("Can't create IsOnLayer filter : null layer");
  };
  IsOnLayer(const IsOnLayer& isOnLayer)
  : _layer(isOnLayer._layer)
  { };
  IsOnLayer& operator=(const IsOnLayer& isOnLayer)
  {
  _layer = isOnLayer._layer;
  return *this;
  };
  virtual Filter<Net*>* getClone() const
  {
  return new IsOnLayer(*this);
  };
  virtual bool Accept(Segment* segment) const
  {
  return (segmentgetLayer() == _layer);
  };
  };

And somewher later:

Layer* metal = getDataBase()->getTechnology()->getLayer("metal");
Segments segments = net->getComponents()->getSubSet<Segment*>(IsOnLayer(metal));
// segments represents here the subset of net components
// which are of type Segment and located on layer metal

The documentation for this class was generated from the following files:

- Collection.h
- Collection.dox

Generated by doxygen 1.8.14 on Sun Mar 8 2020 | Return to top of page

Hurricane VLSI Database | Copyright © 2000-2016 Bull S.A. All rights reserved