/ 
TUI-Vision-v2.0.1
/ TUI::Objects::SortedCollection

NAME

TUI::Objects::SortedCollection - sorted collection base class

HIERARCHY

TObject
  TCollection
    TSortedCollection
      TStringCollection

SYNOPSIS

package MySortedCollection;
use Moo;
use TUI::Objects;
extends TSortedCollection;

sub keyOf {
  my ( $self, $item ) = @_;
  return $item->{name};
}

sub compare {
  my ( $self, $key1, $key2 ) = @_;
  return lc($key1) cmp lc($key2);
}

package main;

my $coll = MySortedCollection->new(
  limit => 10,
  delta => 5
);

$coll->insert({ name => 'Gamma' });
$coll->insert({ name => 'alpha' });
$coll->insert({ name => 'Beta'  });

# Sorted automatically via keyOf + compare.
my $second = $coll->at(1);   # { name => 'Beta' }

my $index;
my $found = $coll->search('beta', \$index);
my $pos   = $coll->indexOf($second);

DESCRIPTION

TSortedCollection implements a collection that automatically maintains its elements in sorted order. Items inserted into the collection are placed at the appropriate position based on a comparison function supplied by derived classes.

The class itself does not define how items are compared or which part of an item constitutes the sort key. Subclasses must override keyOf to extract a key from an item and compare to define the ordering of those keys.

Duplicate handling is configurable via the duplicates attribute. By default, items with identical keys are rejected. When duplicates are enabled, items with equal keys are inserted adjacent to existing entries.

TSortedCollection is typically used as a base class for domain-specific collections such as string collections.

Commonly Used Features

Typical usage follows a short cycle: create the collection, insert items, and use search or indexOf for lookup. For subclasses, the practical requirements are to implement keyOf and compare; duplicate handling is then adjusted as needed through duplicates.

ATTRIBUTES

duplicates

Boolean flag controlling whether duplicate keys are permitted. If false (the default), duplicate items are rejected. If true, duplicate items are inserted next to existing items with the same key.

CONSTRUCTOR

new

my $coll = TSortedCollection->new(
  limit => $limit,
  delta => $delta
);

Creates a new sorted collection with the specified initial capacity and growth policy.

limit

Initial capacity of the collection (Int).

delta

Growth increment of the collection (Int). A value of zero disables automatic growth.

new_TSortedCollection

my $coll = new_TSortedCollection($limit, $delta);

Factory-style constructor using positional arguments.

This constructor is equivalent to calling new with named parameters and is provided for compatibility with traditional Turbo Vision construction patterns.

METHODS

compare

my $cmp = $coll->compare($key1, $key2);

Compares two keys and returns an integer indicating their relative order.

The return value follows the standard convention:

  • negative value if $key1 is less than $key2

  • zero if both keys are equal

  • positive value if $key1 is greater than $key2

Subclasses must override this method.

indexOf

my $index = $coll->indexOf($item | undef);

Returns the index of the specified item, or -1 if the item is not present in the collection.

insert

my $index = $coll->insert($item | undef);

Inserts an item into the collection at the position determined by its sort key.

If an item with an identical key already exists, the behavior depends on the value of the duplicates attribute.

keyOf

my $key = $coll->keyOf($item | undef);

Returns the sort key associated with the specified item.

Subclasses must override this method.

my $found = $coll->search($key | undef, \$index);

Searches for an item with the specified key.

Returns true if the key is found. If found, $index contains the position of the matching item. Otherwise, $index indicates the position where such an item would be inserted.

AUTHORS

  • Borland International (original Turbo Vision design)

  • J. Schneider <brickpool@cpan.org> (Perl implementation and maintenance)

COPYRIGHT AND LICENSE

Copyright (c) 1990-1994, 1997 by Borland International

Copyright (c) 2024-2026 the "AUTHORS" as listed above.

This software is licensed under the MIT license (see the LICENSE file, which is part of the distribution).