/ 
TUI-Vision-2.000_001
/ TUI::Objects::Collection

NAME

TUI::Objects::Collection - dynamic container for managing collections of items

HIERARCHY

TObject
  TNSCollection
    TCollection
      TStringCollection

SYNOPSIS

use TUI::Objects;

my $col = TCollection->new(
  limit => 10,
  delta => 5
);

$col->insert('alpha');
$col->insert('beta');
$col->atInsert(1, 'between');

my $idx = $col->indexOf('beta');
my $first = $col->at(0);

my $found = $col->firstThat(
  sub { index($_, 'bet') == 0 },
  undef
);

$col->forEach(sub {
  my $item = $_;
  # ... process each item
}, undef);

DESCRIPTION

TCollection provides a dynamically sizable container for storing and accessing arbitrary items. It behaves similarly to a resizable array and is used throughout the Turbo Vision framework as the base class for specialized collection types.

The collection automatically grows when its capacity is exceeded. Growth behavior is controlled by the limit and delta attributes.

Several specialized collections derive from TCollection, including sorted collections, string collections, and resource collections.

TNSCollection represents the non-storable base variant used internally, while TCollection provides the public, reusable collection interface.

Commonly Used Features

TCollection is both a base class and a practical general-purpose container for application code. In day-to-day usage, the most common operations are construction with limit/delta, insertion with insert() or atInsert(), random access with at(), replacement with atPut(), and removal with remove(), atRemove(), or atFree().

Search and traversal are typically done with indexOf(), firstThat(), lastThat(), and forEach(). For lifecycle and cleanup, removeAll(), freeAll(), and pack() are frequently used to reset state or compact the collection.

Specialized containers like TStringCollection and TSortedCollection build on this behavior, so understanding TCollection methods is directly useful even when working with derived classes.

CONSTRUCTOR

new

my $collection = TCollection->new(
  limit => $limit,
  delta => $delta
);

Creates a new collection.

limit

Initial capacity of the collection.

delta

Growth increment used when the collection exceeds its current capacity.

new_TCollection

my $collection = new_TCollection($limit | undef, $delta | undef);

Factory-style constructor using positional arguments.

ATTRIBUTES

The following attributes represent the internal state of the collection.

items

Array reference holding the items in the collection.

count

Current number of items stored in the collection.

limit

The current capacity of the collection. When the number of elements reaches this value, the collection grows according to delta.

delta

Growth increment used when the collection needs to expand. Increasing the limit by larger deltas reduces the frequency of reallocations.

shouldDelete

Boolean flag indicating whether items should be freed when removed from the collection.

METHODS

at

my $item = $collection->at($index);

Returns the item at the specified index.

atFree

$collection->atFree($index);

Removes the item at the specified index and frees it.

atInsert

$collection->atInsert($index, $item | undef);

Inserts an item at the specified index, shifting subsequent items.

atPut

$collection->atPut($index, $item | undef);

Replaces the item at the specified index.

atRemove

$collection->atRemove($index);

Removes the item at the specified index without freeing it.

dataSize

my $size = $collection->dataSize();

Returns the number of scalar values transferred via getData and setData.

For collections, this value is always 1.

error

$collection->error($code, $info);

Handles collection errors.

All bounds and consistency checks in collection methods route errors through this method. Subclasses may override error to implement custom error handling instead of terminating execution.

firstThat

my $item = $collection->firstThat(\&test, $arg | undef);

Returns the first item (scanning forward) for which the test function returns true.

forEach

$collection->forEach(\&action, $arg | undef);

Invokes the action for each item in the collection.

free

$collection->free($item);

Removes the specified item from the collection and frees it.

freeAll

$collection->freeAll();

Frees all items in the collection and clears it.

freeItem

$collection->freeItem($item);

Frees a single item. This method may be overridden by subclasses to customize item disposal.

indexOf

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

Returns the index of the specified item, or -1 if not found.

insert

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

Inserts an item at the end of the collection and returns its index.

lastThat

my $item = $collection->lastThat(\&test, $arg | undef);

Returns the last matching item by scanning the collection in reverse order.

pack

$collection->pack();

Removes undefined gaps from the collection.

remove

$collection->remove($item);

Removes the specified item from the collection without freeing it.

removeAll

$collection->removeAll();

Removes all items from the collection without freeing them.

setLimit

$collection->setLimit($limit);

Sets a new capacity limit for the collection and reallocates internal storage as needed.

shutDown

$collection->shutDown();

Performs shutdown processing for the collection.

SEE ALSO

TUI::Objects::SortedCollection, TUI::Objects::StringCollection, TUI::Objects::Object

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) 2021-2026 the "AUTHORS" as listed above.

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