API reference - Class Texts

Notation used in Ruby API documentation

Module: db

Description: Texts (a collection of texts)

Class hierarchy: Texts » ShapeCollection

Text objects are useful as labels for net names, to identify certain regions and to specify specific locations in general. Text collections provide a way to store - also in a hierarchical fashion - and manipulate a collection of text objects.

Text objects can be turned into polygons by creating small boxes around the texts (polygons). Texts can also be turned into dot-like edges (edges). Texts can be filtered by string, either by matching against a fixed string (with_text) or a glob-style pattern (with_match).

Text collections can be filtered geometrically against a polygon Region using interacting or non-interacting. Vice versa, texts can be used to select polygons from a Region using pull_interacting.

Beside that, text collections can be transformed, flattened and combined, similar to EdgePairs.

This class has been introduced in version 0.27.

Public constructors

new Texts ptrnewDefault constructor
new Texts ptrnew(Text[] array)Constructor from an text array
new Texts ptrnew(const Text text)Constructor from a single edge pair object
new Texts ptrnew(const Shapes shapes)Shapes constructor
new Texts ptrnew(const RecursiveShapeIterator shape_iterator)Constructor from a hierarchical shape set
new Texts ptrnew(const RecursiveShapeIterator shape_iterator,
const ICplxTrans trans)
Constructor from a hierarchical shape set with a transformation
new Texts ptrnew(const RecursiveShapeIterator shape_iterator,
DeepShapeStore dss)
Creates a hierarchical text collection from an original layer
new Texts ptrnew(const RecursiveShapeIterator shape_iterator,
DeepShapeStore dss,
const ICplxTrans trans)
Creates a hierarchical text collection from an original layer with a transformation

Public methods

[const]Texts&(const Region other)Returns the texts from this text collection which are inside or on the edge of polygons from the given region
[const]Texts+(const Texts other)Returns the combined text collection of self and the other one
Texts+=(const Texts other)Adds the texts of the other text collection to self
[const]Texts-(const Region other)Returns the texts from this text collection which are not inside or on the edge of polygons from the given region
[const]const Text ptr[](unsigned long n)Returns the nth text
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.
voidassign(const Texts other)Assigns another object to self
[const]BoxbboxReturn the bounding box of the text collection
voidclearClears the text collection
[const]unsigned longcountReturns the (flat) number of texts in the text collection
[const]unsigned longdata_idReturns the data ID (a unique identifier for the underlying data storage)
voiddisable_progressDisable progress reporting
[const]new Texts ptrdupCreates a copy of self
[const,iter]TexteachReturns each text of the text collection
[const]EdgesedgesReturns dot-like edges for the texts
voidenable_progress(string label)Enable progress reporting
[const]Regionextents(int d = 1)Returns a region with the enlarged bounding boxes of the texts
[const]Regionextents(int dx,
int dy)
Returns a region with the enlarged bounding boxes of the texts
voidflattenExplicitly flattens an text collection
[const]boolhas_valid_texts?Returns true if the text collection is flat and individual texts can be accessed randomly
[const]unsigned longhier_countReturns the (hierarchical) number of texts in the text collection
voidinsert(const Text text)Inserts a text into the collection
voidinsert(const Texts texts)Inserts all texts from the other text collection into this collection
[const]voidinsert_into(Layout ptr layout,
unsigned int cell_index,
unsigned int layer)
Inserts this texts into the given layout, below the given cell and into the given layer.
[const]voidinsert_into_as_polygons(Layout ptr layout,
unsigned int cell_index,
unsigned int layer,
int e)
Inserts this texts into the given layout, below the given cell and into the given layer.
[const]Textsinteracting(const Region other)Returns the texts from this text collection which are inside or on the edge of polygons from the given region
[const]boolis_deep?Returns true if the edge pair collection is a deep (hierarchical) one
[const]boolis_empty?Returns true if the collection is empty
Textsmove(const Vector p)Moves the text collection
Textsmove(int x,
int y)
Moves the text collection
[const]Textsmoved(const Vector p)Returns the moved text collection (does not modify self)
[const]Textsmoved(int x,
int y)
Returns the moved edge pair collection (does not modify self)
[const]Textsnot_interacting(const Region other)Returns the texts from this text collection which are not inside or on the edge of polygons from the given region
[const]Regionpolygons(int e = 1)Converts the edge pairs to polygons
[const]Regionpull_interacting(const Region other)Returns all polygons of "other" which are including texts of this text set
Textsselect_interacting(const Region other)Selects the texts from this text collection which are inside or on the edge of polygons from the given region
Textsselect_not_interacting(const Region other)Selects the texts from this text collection which are not inside or on the edge of polygons from the given region
voidswap(Texts other)Swap the contents of this collection with the contents of another collection
[const]stringto_sConverts the text collection to a string
[const]stringto_s(unsigned long max_count)Converts the text collection to a string
Textstransform(const Trans t)Transform the text collection (modifies self)
Textstransform(const ICplxTrans t)Transform the text collection with a complex transformation (modifies self)
[const]Textstransformed(const Trans t)Transform the edge pair collection
[const]Textstransformed(const ICplxTrans t)Transform the text collection with a complex transformation
[const]Textswith_match(string pattern,
bool inverse)
Filter the text by glob pattern
[const]Textswith_text(string text,
bool inverse)
Filter the text by text string

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

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
[const]unsigned longsizeUse of this method is deprecated. Use count instead
Textstransform_icplx(const ICplxTrans t)Use of this method is deprecated. Use transform instead
[const]Textstransformed_icplx(const ICplxTrans t)Use of this method is deprecated. Use transformed instead

Detailed description

&

Signature: [const] Texts & (const Region other)

Description: Returns the texts from this text collection which are inside or on the edge of polygons from the given region

Returns:A new text collection containing the texts inside or on the edge of polygons from the region

+

Signature: [const] Texts + (const Texts other)

Description: Returns the combined text collection of self and the other one

Returns:The resulting text collection

This operator adds the texts of the other collection to self and returns a new combined set.

+=

Signature: Texts += (const Texts other)

Description: Adds the texts of the other text collection to self

Returns:The text collection after modification (self)

This operator adds the texts of the other collection to self.

-

Signature: [const] Texts - (const Region other)

Description: Returns the texts from this text collection which are not inside or on the edge of polygons from the given region

Returns:A new text collection containing the texts not inside or on the edge of polygons from the region

[]

Signature: [const] const Text ptr [] (unsigned long n)

Description: Returns the nth text

This method returns nil if the index is out of range. It is available for flat texts only - i.e. those for which has_valid_texts? is true. Use flatten to explicitly flatten an text collection.

The each iterator is the more general approach to access the texts.

_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.

assign

Signature: void assign (const Texts other)

Description: Assigns another object to self

bbox

Signature: [const] Box bbox

Description: Return the bounding box of the text collection

The bounding box is the box enclosing all origins of all texts.

clear

Signature: void clear

Description: Clears the text collection

count

Signature: [const] unsigned long count

Description: Returns the (flat) number of texts in the text collection

The count is computed 'as if flat', i.e. texts inside a cell are multiplied by the number of times a cell is instantiated.

Starting with version 0.27, the method is called 'count' for consistency with Region. 'size' is still provided as an alias.

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

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.

data_id

Signature: [const] unsigned long data_id

Description: Returns the data ID (a unique identifier for the underlying data storage)

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.

disable_progress

Signature: void disable_progress

Description: Disable progress reporting

Calling this method will disable progress reporting. See enable_progress.

dup

Signature: [const] new Texts ptr dup

Description: Creates a copy of self

Python specific notes:
This method also implements '__copy__'

each

Signature: [const,iter] Text each

Description: Returns each text of the text collection

Python specific notes:
This method enables iteration of the object

edges

Signature: [const] Edges edges

Description: Returns dot-like edges for the texts

Returns:An edge collection containing the individual, dot-like edges

enable_progress

Signature: void enable_progress (string label)

Description: Enable progress reporting

After calling this method, the text collection will report the progress through a progress bar while expensive operations are running. The label is a text which is put in front of the progress bar. Using a progress bar will imply a performance penalty of a few percent typically.

extents

(1) Signature: [const] Region extents (int d = 1)

Description: Returns a region with the enlarged bounding boxes of the texts

Text bounding boxes are point-like boxes which vanish unless an enlargement of >0 is specified. The bounding box is centered at the text's location. The boxes will not be merged, so it is possible to determine overlaps of these boxes for example.

(2) Signature: [const] Region extents (int dx, int dy)

Description: Returns a region with the enlarged bounding boxes of the texts

This method acts like the other version of extents, but allows giving different enlargements for x and y direction.

flatten

Signature: void flatten

Description: Explicitly flattens an text collection

If the collection is already flat (i.e. has_valid_texts? returns true), this method will not change the collection.

has_valid_texts?

Signature: [const] bool has_valid_texts?

Description: Returns true if the text collection is flat and individual texts can be accessed randomly

hier_count

Signature: [const] unsigned long hier_count

Description: Returns the (hierarchical) number of texts in the text collection

The count is computed 'hierarchical', i.e. texts inside a cell are counted once even if the cell is instantiated multiple times.

This method has been introduced in version 0.27.

insert

(1) Signature: void insert (const Text text)

Description: Inserts a text into the collection

(2) Signature: void insert (const Texts texts)

Description: Inserts all texts from the other text collection into this collection

insert_into

Signature: [const] void insert_into (Layout ptr layout, unsigned int cell_index, unsigned int layer)

Description: Inserts this texts into the given layout, below the given cell and into the given layer.

If the text collection is a hierarchical one, a suitable hierarchy will be built below the top cell or and existing hierarchy will be reused.

insert_into_as_polygons

Signature: [const] void insert_into_as_polygons (Layout ptr layout, unsigned int cell_index, unsigned int layer, int e)

Description: Inserts this texts into the given layout, below the given cell and into the given layer.

If the text collection is a hierarchical one, a suitable hierarchy will be built below the top cell or and existing hierarchy will be reused.

The texts will be converted to polygons with the enlargement value given be 'e'. See polygon or extents for details.

interacting

Signature: [const] Texts interacting (const Region other)

Description: Returns the texts from this text collection which are inside or on the edge of polygons from the given region

Returns:A new text collection containing the texts inside or on the edge of polygons from the region

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_deep?

Signature: [const] bool is_deep?

Description: Returns true if the edge pair collection is a deep (hierarchical) one

is_empty?

Signature: [const] bool is_empty?

Description: Returns true if the collection is empty

move

(1) Signature: Texts move (const Vector p)

Description: Moves the text collection

p:The distance to move the texts.
Returns:The moved texts (self).

Moves the texts by the given offset and returns the moved text collection. The text collection is overwritten.

(2) Signature: Texts move (int x, int y)

Description: Moves the text collection

x:The x distance to move the texts.
y:The y distance to move the texts.
Returns:The moved texts (self).

Moves the edge pairs by the given offset and returns the moved texts. The edge pair collection is overwritten.

moved

(1) Signature: [const] Texts moved (const Vector p)

Description: Returns the moved text collection (does not modify self)

p:The distance to move the texts.
Returns:The moved texts.

Moves the texts by the given offset and returns the moved texts. The text collection is not modified.

(2) Signature: [const] Texts moved (int x, int y)

Description: Returns the moved edge pair collection (does not modify self)

x:The x distance to move the texts.
y:The y distance to move the texts.
Returns:The moved texts.

Moves the texts by the given offset and returns the moved texts. The text collection is not modified.

new

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

Description: Default constructor

This constructor creates an empty text collection.

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

(2) Signature: [static] new Texts ptr new (Text[] array)

Description: Constructor from an text array

This constructor creates an text collection from an array of Text objects.

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

(3) Signature: [static] new Texts ptr new (const Text text)

Description: Constructor from a single edge pair object

This constructor creates an text collection with a single text.

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

(4) Signature: [static] new Texts ptr new (const Shapes shapes)

Description: Shapes constructor

This constructor creates an text collection from a Shapes collection.

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

(5) Signature: [static] new Texts ptr new (const RecursiveShapeIterator shape_iterator)

Description: Constructor from a hierarchical shape set

This constructor creates a text collection from the shapes delivered by the given recursive shape iterator. Only texts are taken from the shape set and other shapes are ignored. This method allows feeding the text collection from a hierarchy of cells.

layout = ... # a layout
cell   = ... # the index of the initial cell
layer  = ... # the index of the layer from where to take the shapes from
r = RBA::Texts::new(layout.begin_shapes(cell, layer))

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

(6) Signature: [static] new Texts ptr new (const RecursiveShapeIterator shape_iterator, const ICplxTrans trans)

Description: Constructor from a hierarchical shape set with a transformation

This constructor creates a text collection from the shapes delivered by the given recursive shape iterator. Only texts are taken from the shape set and other shapes are ignored. The given transformation is applied to each text taken. This method allows feeding the text collection from a hierarchy of cells. The transformation is useful to scale to a specific database unit for example.

layout = ... # a layout
cell   = ... # the index of the initial cell
layer  = ... # the index of the layer from where to take the shapes from
dbu    = 0.1 # the target database unit
r = RBA::Texts::new(layout.begin_shapes(cell, layer), RBA::ICplxTrans::new(layout.dbu / dbu))

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

(7) Signature: [static] new Texts ptr new (const RecursiveShapeIterator shape_iterator, DeepShapeStore dss)

Description: Creates a hierarchical text collection from an original layer

This constructor creates a text collection from the shapes delivered by the given recursive shape iterator. This version will create a hierarchical text collection which supports hierarchical operations.

dss    = RBA::DeepShapeStore::new
layout = ... # a layout
cell   = ... # the index of the initial cell
layer  = ... # the index of the layer from where to take the shapes from
r = RBA::Texts::new(layout.begin_shapes(cell, layer))

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

(8) Signature: [static] new Texts ptr new (const RecursiveShapeIterator shape_iterator, DeepShapeStore dss, const ICplxTrans trans)

Description: Creates a hierarchical text collection from an original layer with a transformation

This constructor creates a text collection from the shapes delivered by the given recursive shape iterator. This version will create a hierarchical text collection which supports hierarchical operations. The transformation is useful to scale to a specific database unit for example.

dss    = RBA::DeepShapeStore::new
layout = ... # a layout
cell   = ... # the index of the initial cell
layer  = ... # the index of the layer from where to take the shapes from
dbu    = 0.1 # the target database unit
r = RBA::Texts::new(layout.begin_shapes(cell, layer), RBA::ICplxTrans::new(layout.dbu / dbu))

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

not_interacting

Signature: [const] Texts not_interacting (const Region other)

Description: Returns the texts from this text collection which are not inside or on the edge of polygons from the given region

Returns:A new text collection containing the texts not inside or on the edge of polygons from the region

polygons

Signature: [const] Region polygons (int e = 1)

Description: Converts the edge pairs to polygons

This method creates polygons from the texts. This is equivalent to calling extents.

pull_interacting

Signature: [const] Region pull_interacting (const Region other)

Description: Returns all polygons of "other" which are including texts of this text set

Returns:The region after the polygons have been selected (from other)

The "pull_..." method is similar to "select_..." but works the opposite way: it selects shapes from the argument region rather than self. In a deep (hierarchical) context the output region will be hierarchically aligned with self, so the "pull_..." method provide a way for re-hierarchization.

Merged semantics applies for the polygon region.

select_interacting

Signature: Texts select_interacting (const Region other)

Description: Selects the texts from this text collection which are inside or on the edge of polygons from the given region

Returns:A text collection after the texts have been selected (self)

In contrast to interacting, this method will modify self.

select_not_interacting

Signature: Texts select_not_interacting (const Region other)

Description: Selects the texts from this text collection which are not inside or on the edge of polygons from the given region

Returns:A text collection after the texts have been selected (self)

In contrast to interacting, this method will modify self.

size

Signature: [const] unsigned long size

Description: Returns the (flat) number of texts in the text collection

Use of this method is deprecated. Use count instead

The count is computed 'as if flat', i.e. texts inside a cell are multiplied by the number of times a cell is instantiated.

Starting with version 0.27, the method is called 'count' for consistency with Region. 'size' is still provided as an alias.

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

swap

Signature: void swap (Texts other)

Description: Swap the contents of this collection with the contents of another collection

This method is useful to avoid excessive memory allocation in some cases. For managed memory languages such as Ruby, those cases will be rare.

to_s

(1) Signature: [const] string to_s

Description: Converts the text collection to a string

The length of the output is limited to 20 texts to avoid giant strings on large collections. For full output use "to_s" with a maximum count parameter.

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

(2) Signature: [const] string to_s (unsigned long max_count)

Description: Converts the text collection to a string

This version allows specification of the maximum number of texts contained in the string.

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

transform

(1) Signature: Texts transform (const Trans t)

Description: Transform the text collection (modifies self)

t:The transformation to apply.
Returns:The transformed text collection.

Transforms the text collection with the given transformation. This version modifies the text collection and returns a reference to self.

(2) Signature: Texts transform (const ICplxTrans t)

Description: Transform the text collection with a complex transformation (modifies self)

t:The transformation to apply.
Returns:The transformed text collection.

Transforms the text collection with the given transformation. This version modifies the text collection and returns a reference to self.

transform_icplx

Signature: Texts transform_icplx (const ICplxTrans t)

Description: Transform the text collection with a complex transformation (modifies self)

t:The transformation to apply.
Returns:The transformed text collection.

Use of this method is deprecated. Use transform instead

Transforms the text collection with the given transformation. This version modifies the text collection and returns a reference to self.

transformed

(1) Signature: [const] Texts transformed (const Trans t)

Description: Transform the edge pair collection

t:The transformation to apply.
Returns:The transformed texts.

Transforms the texts with the given transformation. Does not modify the edge pair collection but returns the transformed texts.

(2) Signature: [const] Texts transformed (const ICplxTrans t)

Description: Transform the text collection with a complex transformation

t:The transformation to apply.
Returns:The transformed texts.

Transforms the text with the given complex transformation. Does not modify the text collection but returns the transformed texts.

transformed_icplx

Signature: [const] Texts transformed_icplx (const ICplxTrans t)

Description: Transform the text collection with a complex transformation

t:The transformation to apply.
Returns:The transformed texts.

Use of this method is deprecated. Use transformed instead

Transforms the text with the given complex transformation. Does not modify the text collection but returns the transformed texts.

with_match

Signature: [const] Texts with_match (string pattern, bool inverse)

Description: Filter the text by glob pattern

"pattern" is a glob-style pattern (e.g. "A*" will select all texts starting with a capital "A"). If "inverse" is false, this method returns the texts matching the pattern. If "inverse" is true, this method returns the texts not matching the pattern.

with_text

Signature: [const] Texts with_text (string text, bool inverse)

Description: Filter the text by text string

If "inverse" is false, this method returns the texts with the given string. If "inverse" is true, this method returns the texts not having the given string.