API reference - Class CellInstArray

Notation used in Ruby API documentation

Module: db

Description: A single or array cell instance

This object represents either single or array cell instances. A cell instance array is a regular array, described by two displacement vectors (a, b) and the instance count along that axes (na, nb).

In addition, this object represents either instances with simple transformations or instances with complex transformations. The latter includes magnified instances and instances rotated by an arbitrary angle.

The cell which is instantiated is given by a cell index. The cell index can be converted to a cell pointer by using Layout#cell. The cell index of a cell can be obtained using Cell#cell_index.

See The Database API for more details about the database objects.

Public constructors

new CellInstArray ptrnewCreates en empty cell instance with size 0
new CellInstArray ptrnew(unsigned int cell_index,
const Trans trans)
Creates a single cell instance
new CellInstArray ptrnew(const Cell ptr cell,
const Trans trans)
Creates a single cell instance
new CellInstArray ptrnew(unsigned int cell_index,
const Vector disp)
Creates a single cell instance
new CellInstArray ptrnew(const Cell ptr cell,
const Vector disp)
Creates a single cell instance
new CellInstArray ptrnew(unsigned int cell_index,
const ICplxTrans trans)
Creates a single cell instance with a complex transformation
new CellInstArray ptrnew(const Cell ptr cell,
const ICplxTrans trans)
Creates a single cell instance with a complex transformation
new CellInstArray ptrnew(unsigned int cell_index,
const Trans trans,
const Vector a,
const Vector b,
unsigned long na,
unsigned long nb)
Creates a single cell instance
new CellInstArray ptrnew(const Cell ptr cell,
const Trans trans,
const Vector a,
const Vector b,
unsigned long na,
unsigned long nb)
Creates a single cell instance
new CellInstArray ptrnew(unsigned int cell_index,
const Vector disp,
const Vector a,
const Vector b,
unsigned long na,
unsigned long nb)
Creates a single cell instance
new CellInstArray ptrnew(const Cell ptr cell,
const Vector disp,
const Vector a,
const Vector b,
unsigned long na,
unsigned long nb)
Creates a single cell instance
new CellInstArray ptrnew(unsigned int cell_index,
const ICplxTrans trans,
const Vector a,
const Vector b,
unsigned long na,
unsigned long nb)
Creates a single cell instance with a complex transformation
new CellInstArray ptrnew(const Cell ptr cell,
const ICplxTrans trans,
const Vector a,
const Vector b,
unsigned long na,
unsigned long nb)
Creates a single cell instance with a complex transformation

Public methods

[const]bool!=(const CellInstArray other)Compares two arrays for inequality
[const]bool<(const CellInstArray other)Compares two arrays for 'less'
[const]bool==(const CellInstArray other)Compares two arrays for equality
[const]CellInstArray ptr_const_castReturns a non-const reference to self.
void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
[const]VectoraGets the displacement vector for the 'a' axis
voida=(const Vector vector)Sets the displacement vector for the 'a' axis
voidassign(const CellInstArray other)Assigns another object to self
[const]VectorbGets the displacement vector for the 'b' axis
voidb=(const Vector vector)Sets the displacement vector for the 'b' axis
[const]Boxbbox(const Layout layout,
unsigned int layer_index)
Gets the bounding box of the array with respect to one layer
[const]Boxbbox(const Layout layout)Gets the bounding box of the array
voidcell=(Cell ptr cell)Sets the cell this instance refers to
[const]unsigned intcell_indexGets the cell index of the cell instantiated
voidcell_index=(unsigned int index)Sets the index of the cell this instance refers to
[const]ICplxTranscplx_transGets the complex transformation of the first instance in the array
voidcplx_trans=(const ICplxTrans trans)Sets the complex transformation of the instance or the first instance in the array
[const]new CellInstArray ptrdupCreates a copy of self
[const,iter]ICplxTranseach_cplx_transGets the complex transformations represented by this instance
[const,iter]Transeach_transGets the simple transformations represented by this instance
[const]unsigned longhashComputes a hash value
voidinvertInverts the array reference
[const]boolis_complex?Gets a value indicating whether the array is a complex array
[const]boolis_regular_array?Gets a value indicating whether this instance is a regular array
[const]unsigned longnaGets the number of instances in the 'a' axis
voidna=(unsigned long n)Sets the number of instances in the 'a' axis
[const]unsigned longnbGets the number of instances in the 'b' axis
voidnb=(unsigned long n)Sets the number of instances in the 'b' axis
[const]unsigned longsizeGets the number of single instances in the array
[const]stringto_sConverts the array to a string
[const]TranstransGets the transformation of the first instance in the array
voidtrans=(const Trans t)Sets the transformation of the instance or the first instance in the array
voidtransform(const Trans trans)Transforms the cell instance with the given transformation
voidtransform(const ICplxTrans trans)Transforms the cell instance with the given complex transformation
[const]CellInstArraytransformed(const Trans trans)Gets the transformed cell instance
[const]CellInstArraytransformed(const ICplxTrans trans)Gets the transformed cell instance (complex transformation)

Deprecated methods (protected, public, static, non-static and constructors)

[const]Boxbbox_per_layer(const Layout layout,
unsigned int layer_index)
Use of this method is deprecated. Use bbox instead
voidcreateUse of this method is deprecated. Use _create instead
voiddestroyUse of this method is deprecated. Use _destroy instead
[const]booldestroyed?Use of this method is deprecated. Use _destroyed? instead
[const]boolis_const_object?Use of this method is deprecated. Use _is_const_object? instead

Detailed description

!=

Signature: [const] bool != (const CellInstArray other)

Description: Compares two arrays for inequality

<

Signature: [const] bool < (const CellInstArray other)

Description: Compares two arrays for 'less'

The comparison provides an arbitrary sorting criterion and not specific sorting order. It is guaranteed that if an array a is less than b, b is not less than a. In addition, it a is not less than b and b is not less than a, then a is equal to b.

==

Signature: [const] bool == (const CellInstArray other)

Description: Compares two arrays for equality

_const_cast

Signature: [const] CellInstArray ptr _const_cast

Description: Returns a non-const reference to self.

Basically, this method allows turning a const object reference to a non-const one. This method is provided as last resort to remove the constness from an object. Usually there is a good reason for a const object reference, so using this method may have undesired side effects.

This method has been introduced in version 0.29.6.

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

a

Signature: [const] Vector a

Description: Gets the displacement vector for the 'a' axis

Starting with version 0.25 the displacement is of vector type.

Python specific notes:
The object exposes a readable attribute 'a'. This is the getter.

a=

Signature: void a= (const Vector vector)

Description: Sets the displacement vector for the 'a' axis

If the instance was not regular before this property is set, it will be initialized to a regular instance.

This method was introduced in version 0.22. Starting with version 0.25 the displacement is of vector type.

Python specific notes:
The object exposes a writable attribute 'a'. This is the setter.

assign

Signature: void assign (const CellInstArray other)

Description: Assigns another object to self

b

Signature: [const] Vector b

Description: Gets the displacement vector for the 'b' axis

Starting with version 0.25 the displacement is of vector type.

Python specific notes:
The object exposes a readable attribute 'b'. This is the getter.

b=

Signature: void b= (const Vector vector)

Description: Sets the displacement vector for the 'b' axis

If the instance was not regular before this property is set, it will be initialized to a regular instance.

This method was introduced in version 0.22. Starting with version 0.25 the displacement is of vector type.

Python specific notes:
The object exposes a writable attribute 'b'. This is the setter.

bbox

(1) Signature: [const] Box bbox (const Layout layout, unsigned int layer_index)

Description: Gets the bounding box of the array with respect to one layer

The bounding box incorporates all instances that the array represents. It needs the layout object to access the actual cell from the cell index.

'bbox' is the preferred synonym since version 0.28.

(2) Signature: [const] Box bbox (const Layout layout)

Description: Gets the bounding box of the array

The bounding box incorporates all instances that the array represents. It needs the layout object to access the actual cell from the cell index.

bbox_per_layer

Signature: [const] Box bbox_per_layer (const Layout layout, unsigned int layer_index)

Description: Gets the bounding box of the array with respect to one layer

Use of this method is deprecated. Use bbox instead

The bounding box incorporates all instances that the array represents. It needs the layout object to access the actual cell from the cell index.

'bbox' is the preferred synonym since version 0.28.

cell=

Signature: void cell= (Cell ptr cell)

Description: Sets the cell this instance refers to

This is a convenience method and equivalent to 'cell_index = cell.cell_index()'. There is no getter for the cell pointer because the CellInstArray object only knows about cell indexes.

This convenience method has been introduced in version 0.28.

Python specific notes:
The object exposes a writable attribute 'cell'. This is the setter.

cell_index

Signature: [const] unsigned int cell_index

Description: Gets the cell index of the cell instantiated

Use Layout#cell to get the Cell object from the cell index.

Python specific notes:
The object exposes a readable attribute 'cell_index'. This is the getter.

cell_index=

Signature: void cell_index= (unsigned int index)

Description: Sets the index of the cell this instance refers to

Python specific notes:
The object exposes a writable attribute 'cell_index'. This is the setter.

cplx_trans

Signature: [const] ICplxTrans cplx_trans

Description: Gets the complex transformation of the first instance in the array

This method is always applicable, compared to trans, since simple transformations can be expressed as complex transformations as well.

Python specific notes:
The object exposes a readable attribute 'cplx_trans'. This is the getter.

cplx_trans=

Signature: void cplx_trans= (const ICplxTrans trans)

Description: Sets the complex transformation of the instance or the first instance in the array

This method was introduced in version 0.22.

Python specific notes:
The object exposes a writable attribute 'cplx_trans'. This is the setter.

create

Signature: void create

Description: Ensures the C++ object is created

Use of this method is deprecated. Use _create instead

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

destroy

Signature: void destroy

Description: Explicitly destroys the object

Use of this method is deprecated. Use _destroy instead

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

destroyed?

Signature: [const] bool destroyed?

Description: Returns a value indicating whether the object was already destroyed

Use of this method is deprecated. Use _destroyed? instead

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

dup

Signature: [const] new CellInstArray ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__' and '__deepcopy__'.

each_cplx_trans

Signature: [const,iter] ICplxTrans each_cplx_trans

Description: Gets the complex transformations represented by this instance

For a single instance, this iterator will deliver the single, complex transformation. For array instances, the iterator will deliver each complex transformation of the expanded array. This iterator is a generalization of each_trans for general complex transformations.

This method has been introduced in version 0.25.

each_trans

Signature: [const,iter] Trans each_trans

Description: Gets the simple transformations represented by this instance

For a single instance, this iterator will deliver the single, simple transformation. For array instances, the iterator will deliver each simple transformation of the expanded array.

This iterator will only deliver valid transformations if the instance array is not of complex type (see is_complex?). A more general iterator that delivers the complex transformations is each_cplx_trans.

This method has been introduced in version 0.25.

hash

Signature: [const] unsigned long hash

Description: Computes a hash value

Returns a hash value for the given cell instance. This method enables cell instances as hash keys.

This method has been introduced in version 0.25.

Python specific notes:
This method is also available as 'hash(object)'.

invert

Signature: void invert

Description: Inverts the array reference

The inverted array reference describes in which transformations the parent cell is seen from the current cell.

is_complex?

Signature: [const] bool is_complex?

Description: Gets a value indicating whether the array is a complex array

Returns true if the array represents complex instances (that is, with magnification and arbitrary rotation angles).

is_const_object?

Signature: [const] bool is_const_object?

Description: Returns a value indicating whether the reference is a const reference

Use of this method is deprecated. Use _is_const_object? instead

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

is_regular_array?

Signature: [const] bool is_regular_array?

Description: Gets a value indicating whether this instance is a regular array

na

Signature: [const] unsigned long na

Description: Gets the number of instances in the 'a' axis

Python specific notes:
The object exposes a readable attribute 'na'. This is the getter.

na=

Signature: void na= (unsigned long n)

Description: Sets the number of instances in the 'a' axis

If the instance was not regular before this property is set to a value larger than zero, it will be initialized to a regular instance. To make an instance a single instance, set na or nb to 0.

This method was introduced in version 0.22.

Python specific notes:
The object exposes a writable attribute 'na'. This is the setter.

nb

Signature: [const] unsigned long nb

Description: Gets the number of instances in the 'b' axis

Python specific notes:
The object exposes a readable attribute 'nb'. This is the getter.

nb=

Signature: void nb= (unsigned long n)

Description: Sets the number of instances in the 'b' axis

If the instance was not regular before this property is set to a value larger than zero, it will be initialized to a regular instance. To make an instance a single instance, set na or nb to 0.

This method was introduced in version 0.22.

Python specific notes:
The object exposes a writable attribute 'nb'. This is the setter.

new

(1) Signature: [static] new CellInstArray ptr new

Description: Creates en empty cell instance with size 0

Python specific notes:
This method is the default initializer of the object.

(2) Signature: [static] new CellInstArray ptr new (unsigned int cell_index, const Trans trans)

Description: Creates a single cell instance

cell_index:The cell to instantiate
trans:The transformation by which to instantiate the cell

Python specific notes:
This method is the default initializer of the object.

(3) Signature: [static] new CellInstArray ptr new (const Cell ptr cell, const Trans trans)

Description: Creates a single cell instance

cell:The cell to instantiate
trans:The transformation by which to instantiate the cell

This convenience variant takes a Cell pointer and is equivalent to using 'cell.cell_index()'. It has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

(4) Signature: [static] new CellInstArray ptr new (unsigned int cell_index, const Vector disp)

Description: Creates a single cell instance

cell_index:The cell to instantiate
disp:The displacement

This convenience initializer has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

(5) Signature: [static] new CellInstArray ptr new (const Cell ptr cell, const Vector disp)

Description: Creates a single cell instance

cell:The cell to instantiate
disp:The displacement

This convenience variant takes a Cell pointer and is equivalent to using 'cell.cell_index()'. It has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

(6) Signature: [static] new CellInstArray ptr new (unsigned int cell_index, const ICplxTrans trans)

Description: Creates a single cell instance with a complex transformation

cell_index:The cell to instantiate
trans:The complex transformation by which to instantiate the cell

Python specific notes:
This method is the default initializer of the object.

(7) Signature: [static] new CellInstArray ptr new (const Cell ptr cell, const ICplxTrans trans)

Description: Creates a single cell instance with a complex transformation

cell:The cell to instantiate
trans:The complex transformation by which to instantiate the cell

This convenience variant takes a Cell pointer and is equivalent to using 'cell.cell_index()'. It has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

(8) Signature: [static] new CellInstArray ptr new (unsigned int cell_index, const Trans trans, const Vector a, const Vector b, unsigned long na, unsigned long nb)

Description: Creates a single cell instance

cell_index:The cell to instantiate
trans:The transformation by which to instantiate the cell
a:The displacement vector of the array in the 'a' axis
b:The displacement vector of the array in the 'b' axis
na:The number of placements in the 'a' axis
nb:The number of placements in the 'b' axis

Starting with version 0.25 the displacements are of vector type.

Python specific notes:
This method is the default initializer of the object.

(9) Signature: [static] new CellInstArray ptr new (const Cell ptr cell, const Trans trans, const Vector a, const Vector b, unsigned long na, unsigned long nb)

Description: Creates a single cell instance

cell:The cell to instantiate
trans:The transformation by which to instantiate the cell
a:The displacement vector of the array in the 'a' axis
b:The displacement vector of the array in the 'b' axis
na:The number of placements in the 'a' axis
nb:The number of placements in the 'b' axis

This convenience variant takes a Cell pointer and is equivalent to using 'cell.cell_index()'. It has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

(10) Signature: [static] new CellInstArray ptr new (unsigned int cell_index, const Vector disp, const Vector a, const Vector b, unsigned long na, unsigned long nb)

Description: Creates a single cell instance

cell_index:The cell to instantiate
disp:The basic displacement of the first instance
a:The displacement vector of the array in the 'a' axis
b:The displacement vector of the array in the 'b' axis
na:The number of placements in the 'a' axis
nb:The number of placements in the 'b' axis

This convenience initializer has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

(11) Signature: [static] new CellInstArray ptr new (const Cell ptr cell, const Vector disp, const Vector a, const Vector b, unsigned long na, unsigned long nb)

Description: Creates a single cell instance

cell:The cell to instantiate
disp:The basic displacement of the first instance
a:The displacement vector of the array in the 'a' axis
b:The displacement vector of the array in the 'b' axis
na:The number of placements in the 'a' axis
nb:The number of placements in the 'b' axis

This convenience variant takes a Cell pointer and is equivalent to using 'cell.cell_index()'. It has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

(12) Signature: [static] new CellInstArray ptr new (unsigned int cell_index, const ICplxTrans trans, const Vector a, const Vector b, unsigned long na, unsigned long nb)

Description: Creates a single cell instance with a complex transformation

cell_index:The cell to instantiate
trans:The complex transformation by which to instantiate the cell
a:The displacement vector of the array in the 'a' axis
b:The displacement vector of the array in the 'b' axis
na:The number of placements in the 'a' axis
nb:The number of placements in the 'b' axis

Starting with version 0.25 the displacements are of vector type.

Python specific notes:
This method is the default initializer of the object.

(13) Signature: [static] new CellInstArray ptr new (const Cell ptr cell, const ICplxTrans trans, const Vector a, const Vector b, unsigned long na, unsigned long nb)

Description: Creates a single cell instance with a complex transformation

cell:The cell to instantiate
trans:The complex transformation by which to instantiate the cell
a:The displacement vector of the array in the 'a' axis
b:The displacement vector of the array in the 'b' axis
na:The number of placements in the 'a' axis
nb:The number of placements in the 'b' axis

This convenience variant takes a Cell pointer and is equivalent to using 'cell.cell_index()'. It has been introduced in version 0.28.

Python specific notes:
This method is the default initializer of the object.

size

Signature: [const] unsigned long size

Description: Gets the number of single instances in the array

If the instance represents a single instance, the count is 1. Otherwise it is na*nb. Starting with version 0.27, there may be iterated instances for which the size is larger than 1, but is_regular_array? will return false. In this case, use each_trans or each_cplx_trans to retrieve the individual placements of the iterated instance.

Python specific notes:
This method is also available as 'len(object)'.

to_s

Signature: [const] string to_s

Description: Converts the array to a string

This method was introduced in version 0.22.

Python specific notes:
This method is also available as 'str(object)'.

trans

Signature: [const] Trans trans

Description: Gets the transformation of the first instance in the array

The transformation returned is only valid if the array does not represent a complex transformation array

Python specific notes:
The object exposes a readable attribute 'trans'. This is the getter.

trans=

Signature: void trans= (const Trans t)

Description: Sets the transformation of the instance or the first instance in the array

This method was introduced in version 0.22.

Python specific notes:
The object exposes a writable attribute 'trans'. This is the setter.

transform

(1) Signature: void transform (const Trans trans)

Description: Transforms the cell instance with the given transformation

This method has been introduced in version 0.20.

(2) Signature: void transform (const ICplxTrans trans)

Description: Transforms the cell instance with the given complex transformation

This method has been introduced in version 0.20.

transformed

(1) Signature: [const] CellInstArray transformed (const Trans trans)

Description: Gets the transformed cell instance

This method has been introduced in version 0.20.

(2) Signature: [const] CellInstArray transformed (const ICplxTrans trans)

Description: Gets the transformed cell instance (complex transformation)

This method has been introduced in version 0.20.