API reference - Class Texts

&

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

+

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

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

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

The 'join' alias has been introduced in version 0.28.12.

+=

Signature: Texts += (const Texts other)

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

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

Note that in Ruby, the '+=' operator actually does not exist, but is emulated by '+' followed by an assignment. This is less efficient than the in-place operation, so it is recommended to use 'join_with' instead.

The 'join_with' alias has been introduced in version 0.28.12.

-

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

[]

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.

_const_cast

Signature: [const] Texts 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.

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__' and '__deepcopy__'.

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

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.

enable_properties

Signature: void enable_properties

Description: Enables properties for the given container.

This method has an effect mainly on original layers and will import properties from such layers. By default, properties are not enabled on original layers. Alternatively you can apply filter_properties or map_properties to enable properties with a specific name key.

This method has been introduced in version 0.28.4.

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.

filter

Signature: void filter (const TextFilter ptr filter)

Description: Applies a generic filter in place (replacing the texts from the Texts collection)

See TextFilter for a description of this feature.

This method has been introduced in version 0.29.

filter_properties

Signature: void filter_properties (variant[] keys)

Description: Filters properties by certain keys.

Calling this method on a container will reduce the properties to values with name keys from the 'keys' list. As a side effect, this method enables properties on original layers.

This method has been introduced in version 0.28.4.

filtered

Signature: [const] Texts filtered (const TextFilter ptr filtered)

Description: Applies a generic filter and returns a filtered copy

See TextFilter for a description of this feature.

This method has been introduced in version 0.29.

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

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

join

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

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

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

The 'join' alias has been introduced in version 0.28.12.

join_with

Signature: Texts join_with (const Texts other)

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

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

Note that in Ruby, the '+=' operator actually does not exist, but is emulated by '+' followed by an assignment. This is less efficient than the in-place operation, so it is recommended to use 'join_with' instead.

The 'join_with' alias has been introduced in version 0.28.12.

map_properties

Signature: void map_properties (map<variant,variant> key_map)

Description: Maps properties by name key.

Calling this method on a container will reduce the properties to values with name keys from the 'keys' hash and renames the properties. Properties not listed in the key map will be removed. As a side effect, this method enables properties on original layers.

This method has been introduced in version 0.28.4.

move

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

Description: Moves the text collection

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

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)

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)

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

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.

process

Signature: void process (const TextOperator ptr process)

Description: Applies a generic text processor in place (replacing the texts from the text collection)

See TextProcessor for a description of this feature.

This method has been introduced in version 0.29.

processed

(1) Signature: [const] Texts processed (const TextOperator ptr processed)

Description: Applies a generic text processor and returns a processed copy

See TextProcessor for a description of this feature.

This method has been introduced in version 0.29.

(2) Signature: [const] Region processed (const TextToPolygonOperator ptr processed)

Description: Applies a generic text-to-polygon processor and returns a region with the results

See TextToPolygonProcessor for a description of this feature.

This method has been introduced in version 0.29.

pull_interacting

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

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

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.

remove_properties

Signature: void remove_properties

Description: Removes properties for the given container.

This will remove all properties on the given container.

This method has been introduced in version 0.28.4.

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

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

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.

transform

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

Description: Transform the text collection (modifies self)

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)

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)

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

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

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

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.

write

Signature: [const] void write (string filename)

Description: Writes the region to a file

This method is provided for debugging purposes. It writes the object to a flat layer 0/0 in a single top cell.

This method has been introduced in version 0.29.