NAME

Math::PartialOrder::CMasked - class for compiled type hierarches using the Bit::Vector module.

SYNOPSIS

use Math::PartialOrder::CMasked;

...

REQUIRES

Carp, Exporter, Math::PartialOrder::Base, Bit::Vector.

DESCRIPTION

Math::PartialOrder::CMasked is a compiling Math::PartialOrder implementation for compiled datatype hierarchies using the Bit::Vector module for hierarchy operations and an internal representation of immediate hierarchy information as 'Enum' strings. It inherits directly from Math::PartialOrder::Base.

This package implements the methods required by Math::PartialOrder::Base for datatype hierarchies. See Math::PartialOrder::Base for details.

METHODS

Construction & Initialization

• new( {root=>$r} )

  Creates and returns a new Math::PartialOrder::CMasked object rooted at $r, which defaults to 'BOTTOM'.

Compilation Methods

• compile()

  Forces compilation of the hierarhcy. Note that the hierarchy is automatically compiled on any call of a method involving inheritance relations other than direct parent/child relations, and is automatically de-compiled on destructive hierarchy operations such as add(), move() or remove(). Returns a true value on success, false otherwise.

• decompile, uncompile

  Forces de-compilation of the hierarchy. Really just sets an internal flag -- if you want to free up memory, use the _release_compiled() method.

• _release_compiled()

  Forces de-compilation of the hierarchy and eliminates references to the Bit::Vector objects in which the compiled information (if any) was stored.

Additional Hierarchy Manipulation Methods

Additional Hierarchy Information Methods

• has_ancestor_index($i1,$i2)

  Like has_ancestor(), but $i1 and $i2 are type-indices.

• has_descendant_index($i1,$i2)

  Like has_descendant(), but $i1 and $i2 are type-indices.

• ancestors_mask($i)

  Returns the compiled bitmask of all ancestors of the type with index $i as a new Bit::Vector object, or undef if the hierarchy contains no type with the index $i.

• descendants_mask($i)

  Returns the bitmask of all descendants of the type with index $i as a new Bit::Vector object, or undef if the hierarchy contains no type with index $i.

Additional Sorting and Comparison Methods

• _compare_index($i1,$i2)

  Like _compare(), but $i1 and $i2 are type-indices.

• _minimize($bv)

  Destructively minimizes the Bit::Vector object $bv, returns $bv.

• _maximize($bv)

  Destructively maximizes the Bit::Vector object $bv, returns $bv.

Additional Type Operations

Additional Iteration Methods

• iterate_i(\&next,\&callback,\%args)

  Like iterate(\&next,\&callback,\%args), but &next is called with arguments ($h,$i), where $i is a type-index, and is expected to return a list of type indices. Similarly, &callback is called with arguments ($h, $i, \%args) for each type-index $i over which it iterates. $args{start} is also expected to be a type-index.

• iterate_pc_i(\&callback,\%args)

  Like iterate_pc(\&callback,\%args), but $callback is called with arguments ($h, $i, \%args) for each type-index $i over which it iterates. $args{start} is also expected to be a type-index.

• iterate_cp_i(\&callback,\%args)

  Like iterate_cp(\%args), but &callback is called with arguments ($h, $i, \%args) for each type-index $i the hierarchy. $args{start} is also expected to be a type-index.

Low-Level Access

* _indices()

Return the hashref of type-indices keyed by type-names.

* _types()

Return a reference to an array of currently-defined types keyed by type-index.

* _root(), _root($type)

Get/set root type.

* _set_root($root)

Sets the root type without any additional checking.

* _parents()

Returns reference to an array of Enum-strings indexed by type-index.

* _parents_enum($type)

Returns the enum-string representing the direct parents of $type.

* _parents_mask($type)

Returns a temporary Bit::Vector representing the parents of $type, or undef if none exists. If you need to save this data, use the Bit::Vector::Clone() method on the result.

* _parents_indices($type)

Returns a list of the indices of $type's parents.

* _children()

Returns reference to an array of Enum-strings objects indexed by type-index.

* _children_enum($type)

Returns the enum-string representing the direct children of $type.

* _children_mask($type)

Returns a Bit::Vector representing the children of $type. Same caveats as for _parents_mask().

* _children_indices($type)

Returns a list of the indices of $type's children.

* _ancestors()

Returns a reference to an array of Bit::Vector objects encoding the ancestors of each type, keyed by type-index. Compiled hierarchies only.

* _descendants()

Returns a reference to an array of Bit::Vector objects encoding the descendants of each type, keyed by type-index. Compiled hierarchies only.

* _types2mask($bv,@types)

Stores the bitmask for @types in $bv, returns $bv. $bv should already be large enough to accomodate @types.

* types2mask($bv,@types)

Like _types2mask(), but checks for undefined types.

* _types2enum(@types)

Returns an Enum-string containing all and only the indices of @types. Assumes that @types exist in the hierarchy. Nothing fancy, just a join.

* types2enum(@types)

Like _types2enum(), but checks for undefined types.

* _enum2types($enum,$bv)

Returns a list of types corresponding to the indices set in the enum-string $enum by first reading $enum into the Bit::Vector object $bv, which should already be large enough to accomodate it. A value of undef in the returned list indicates an undefined type.

* enum2types($enum,$bv)

Like _enum2types(), but weeds out undef values from the returned list.

* _vectors(), _vectors($num,...)

Without arguments, returns the internal bit-vectors for the hierarchy as an array-reference. With arguments, returns a list containing the internal vectors at indices $num,....

Non-Method Bit::Vector Utilities

The following exportable subroutines can be imported together by specifying the :bvutils tag to the use directive.

• _bv_ensure_size($bv,$size)

  Ensures that the Bit::Vector $bv is at least $size bits long, resizing it if necessary.

• _bv_make_comparable($bv1,$bv2)

  Ensures that $bv1 and $bv2 are the same size by resizing the smaller of the two if they are not already of the same size. Returns the new size of both vectors.

• _bv_bit_test($bv,$bit)

  Checks whether bit number $bit is set in the Bit::Vector $bv, performing a preliminary size-check. No resize is performed.

• _bv_bit_on($bv,$idx)

  Sets bit at index $idx in the Bit::Vector $bv to 1, resizing $bv if necessary.

• _bv_bit_off($bv,$idx)

  Sets bit at index $idx in the Bit::Vector $bv to 0.

• _bv_union_d($bv1,$bv2)

  Destructive Bit::Vector union operation: sets $bv1 to be the union of itself and $bv2, making them comparable first.

• _bv_intersection_d($bv1,$bv2)

  Destructive Bit::Vector intersection operation: sets $bv1 to be the intersection of itself and $bv2, making them comparable first.

• _bv_difference_d($bv1,$bv2)

  Destructive Bit::Vector difference operation: sets $bv1 to be the difference of itself and $bv2, making them comparable first.

Non-Method Enum-string Utilities

The following exportable subroutines can be imported together by specifying the :enumutils tag to the use directive.

• _enum2indices($enum,$bv)

  Returns a list of indices set in $enum by first reading it into the Bit::Vector $bv, which should already be large enough to accomodate it.

• _enum_bit_test($enum,$bit,$bv)

  Tests whether $bit is set in the enum-string $enum using the Bit::Vector $bv for the test. $bv should be large enough to accomodata $enum.

• _enum_bit_on($enum,$bit,$bv)

  Returns the result of setting bit $bit in $enum by converting $enum to and from the Bit::Vector $bv, which is assumed to already be large enough to accomodate $enum, although it may not yet be large enough to accomodate $bit -- if this is the case, it will be resized.

• _enum_bit_off($enum,$bit,$bv)

  Like _enum_bit_on(), but clears bit $bit.

• _enum_union($enum1,$enum2,$bv1,$bv2)

  Returns the union of $enum1 and $enum2 as an enum-string, using the Bit::Vector objects $bv1 and $bv2 to perform the calculation. $bv1 and $bv2 should already be large enough to accomodate $enum1 and $enum2, respectively

• _enum_intersection($enum1,$enum2,$bv1,$bv2)

  Like _enum_union(), but returns the intersection of $enum1 and $enum2.

• _enum_difference($enum1,$enum2,$bv1,$bv2)

  Like _enum_union(), but returns the difference of $enum1 and $enum2.

ACKNOWLEDGEMENTS

perl by Larry Wall.

Bit::Vector by Steffen Beyer.

AUTHOR

Bryan Jurish <jurish@ling.uni-potsdam.de>

COPYRIGHT

Copyright (c) 2001, Bryan Jurish. All rights reserved.

This package is free software. You may redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1). Math::PartialOrder(3pm). Math::PartialOrder::Base(3pm). Math::PartialOrder::CEnum(3pm). Math::PartialOrder::Std(3pm). Math::PartialOrder::Caching(3pm). Math::PartialOrder::LRUCaching(3pm). Math::PartialOrder::Loader(3pm). Bit::Vector(3pm).

cpanm Math::PartialOrder

perl -MCPAN -e shell
install Math::PartialOrder