container.html

xowiki
- Documentation
  - Next Scripting Language (NX)
  - Miscellaneous
    - thread-mallocs
    - naviserver-connthreadqueue

This example is a small design study to implement container classes with different features, namely a SimpleContainer, an OrderedContainer and a SortedContainer. First of all, we require NX:

package req nx
nx::test configure -count 1

Simple Container

The first container class presented here is called SimpleContainer, which manages its contained items. As all container classes presented here, the items are created as child objects embedded in the container. If the container is deleted, all items are deleted as well. The items, which will be put into the container, should be instances of a certain class. We define here for this purpose an arbitrary class C:

nx::Class create C

The class SimpleContainer keeps and manages items added to it. Every instance of this class might have different item classes. We might provide a prefix for naming the items, otherwise the default is member.

nx::Class create SimpleContainer {
  :property {memberClass ::MyItem}
  :property {prefix member}

  # Require the method "autoname" for generating nice names
  :require method autoname

  # The method new is responsible for creating a child of the current
  # container.
  :public method new {args} {
    set item [${:memberClass} create [:]::[:autoname ${:prefix}] {*}$args]
    return $item
  }
}

Create and instance of the class SimpleContainer …

% SimpleContainer create container1 -memberClass ::C
::container1

and add a few items:

% container1 new
::container1::member1

% container1 new
::container1::member2

% container1 new
::container1::member3

The elements of the container can be obtained via info children:

% container1 info children
::container1::member1 ::container1::member2 ::container1::member3

Ordered Container

In the example with SimpleContainer, the order of the results of info children just happens to be in the order of the added items, but in general, this order is not guaranteed, but depends on the population of the hash tables. In the next step, we extend the example above by preserving the order of the elements.

The class OrderedContainer is similar to SimpleContainer, but keeps a list of items that were added to the container. The item list is managed in a property items which is defined as incremental to make use of the add and delete methods provided by the slots.

nx::Class create OrderedContainer -superclass SimpleContainer {
  :property -incremental {items:0..n {}}

  :public method new {args} {
    set item [${:memberClass} create [:]::[:autoname ${:prefix}] {*}$args]
    :items add $item end
    return $item
  }

  # Since we keep the list of items, we have to maintain it in case
  # items are deleted.
  :public method delete {item:object} {
    :items delete $item
    $item destroy
  }

}

Create an instance of OrderedContainer …

% OrderedContainer create container2 -memberClass ::C
::container2

and add a few items:

% container2 new
::container2::member1

% container2 new
::container2::member2

% container2 new
::container2::member3

The elements of the container are obtained via the method items.

% container2 items get
::container2::member1 ::container2::member2 ::container2::member3

When we delete an item in the container …

% container2 delete ::container2::member2

the item is as well removed from the items list.

% container2 items get
::container2::member1 ::container2::member3

Sorted Container

In the next step, we define a SortedContainer, that keeps additionally a sorted list for iterating through the items without needing to sort the items when needed. The implementation maintains an additional sorted list. The implementation of the SortedContainer depends on "lsearch -bisect" which requires Tcl 8.6. Therefore, if we have no Tcl 8.6, just return here.

if {[info command yield] eq ""} return

For sorting, we require the item class to have a key, that can be freely specified. We use there the property name of Class D:

nx::Class create D {
  :property name:required
}

nx::Class create SortedContainer -superclass OrderedContainer {

  # In order to keep the index consisting of just the objects and to
  # ease sorting, we maintain two list, one list of values and one
  # list of objects. We assume for the time being, that the keys are
  # not changing.

  :variable values {}
  :variable index {}
  :property key

  :public method index {} { return ${:index}}

  :public method new {args} {
    set item [${:memberClass} create [:]::[:autoname ${:prefix}] {*}$args]
    if {[info exists :key]} {
      set value [$item cget -${:key}]
      set pos [lsearch -bisect ${:values} $value]
      set :values [linsert ${:values} [expr {$pos + 1}] $value]
      set :index  [linsert ${:index}  [expr {$pos + 1}] $item]
    }
    lappend :items $item
    return $item
  }

  # Since we keep the list of items, we have to maintain it in case
  # items are deleted.
  :public method delete {item:object} {
    set pos [lsearch ${:index} $item]
    if {$pos == -1} {error "item $item not found in container; items: ${:index}"}
    set :values [lreplace ${:values} $pos $pos]
    set :index  [lreplace ${:index}  $pos $pos]
    next
  }
}

Create a container for class D with key name:

SortedContainer create container3 -memberClass ::D -key name

Add a few items

% container3 new -name victor
::container3::member1

% container3 new -name stefan
::container3::member2

% container3 new -name gustaf
::container3::member3

The method items returns the items in the order of insertion (as before):

% container3 items get
::container3::member1 ::container3::member2 ::container3::member3

The method index returns the items in sorting order (sorted by the name member):

% container3 index
::container3::member3 ::container3::member2 ::container3::member1

Now we delete an item:

% container3 delete ::container3::member2

The item is as well removed from the result lists

% container3 items get
::container3::member1 ::container3::member3

% container3 index
::container3::member3 ::container3::member1

container.html

Listing of doc/example-scripts/container.tcl

Simple Container

Ordered Container

Sorted Container