AitCS - Array in the Command's Shadow

Found at: https://chiselapp.com/user/stwo/repository/aitcs

[Stu] 2022-08-22 Version 2.0b1.

[Stu] 2020-03-17 Version 1.2.

[Stu] 2018-05-16 Created page. Version 1.0.

An Array in the Command's Shadow is an array with an associated set of commands that each provide access to or allow certain useful manipulations of the array.

An AitCS may be used where a program would normally use global or namespace variables to hold configuration, state, widget paths, temp values, etc.

Using AitCS is not as fast as using straight Tcl or Jim.
The desire for convenience vs the need for speed should
be taken into account when deciding to use AitCS.
See the Speed section following the Examples section.


***Examples***
======none
# Set/Get/Variable Reference
# Save a widget and link a textvariable
aitcs new rec
aitcs new gui   
set fld preference
rec $fld Tcl
gui $fld [entry .e -textvariable [rec& $fld]]
[gui $fld] insert end /Tk
string length [rec preference]; # 6

# Get/Set  
aitcs new things
things a 3
things b [expr {[things a] + 2}]
things c [expr {[things b] * [things a]}]
things c; # 15

# Setto/Exists/Unset/Variable Reference
aitcs new fruits
fruits= apple orange pear apricot 0
if {![fruits? peach]} {
   fruits= peach 0
}                
array names [fruits&]; # {apple orange pear apricot peach}
fruits- p* a*
array names [fruits&]; # {orange}

# Get With Default
aitcs new things
things are good
things^ are ok; # good
things^ be ok; # ok

# Lappend       
aitcs new store
store this one  
store+ this two three four five
store this; # {one two three four five}

# Incr
aitcs new counters
counters cycles 0  
counters+= cycles
counters+= cycles 2
counters+= cycles -1
counters cycles; # 2

# Make Exist/Exists
aitcs new cow   
cow!
set cow(sound) moo
if {[cow? sound] && $cow(sound) eq "moo"} {
   puts "Standard English Cow"
}

# Command Reference/Variable Reference/Incr
aitcs new callback
callback count 0
after 1000 [list [callback&&]+= count]
vwait [callback& count]
callback count; # 1

# Destroy
aitcs new tmp
tmp count 5
tmp+= count -1
tmp count; # 4
set fqarr [tmp&]
info exists $fqarr; # 1
tmp---
info exists $fqarr; # 0
tmp count; # <error>
======

***Speed***
======none
Using AitCS is not as fast as using straight Tcl or Jim.

The decision to use AitCS is a question of convenience vs speed.
See the README for more info about speed and test targets.

AitCS is command-based and so will always be slower than
any variable a byte-compiler can touch directly.

These are the results of the "vs" tests (also in the doc dir)
run on my machine. AitCS is disappointingly slower than Tcl
but not that much slower than Jim.
This may change with future versions of Tcl or Jim.

2022-08-22 Running vs tests with Tcl 8.6.12
LD_LIBRARY_PATH=".:" TCLLIBPATH="." TCL8_5_TM_PATH='.' TCL8_6_TM_PATH='.' tclsh8.6 ../tests/vs.tcl
Operation                 AitCS        Tcl    Change
exists z               3.404100   2.022600   168.30%
set z 1                4.828000   2.080700   232.04%
exists z               3.686600   2.049600   179.87%
get z                  4.068900   2.018800   201.55%
set l {}               4.829400   2.067500   233.59%
lappend l a b c        8.843100   6.530700   135.41%
unset l                5.526700   2.573500   214.75%
incr z                 5.139800   2.445300   210.19%
mkexist                6.296000   1.894800   332.28%
gwd z                  4.017400   2.381600   168.68%
gwd q 3                3.805900   2.158400   176.33%
setto a b c d e 0      8.348600   4.626400   180.46%
eref z                 3.269800   2.650900   123.35%
aref                   2.588700   2.156700   120.03%
cref                   2.464000   5.420700    45.46%


2022-08-22 Running vs tests with Jim 0.80
JIMLIB="." jimsh ../tests/vs.tcl
Operation            AitCS   Jim    Change
exists z               8.6   8.4   103.29%
set z 1                8.4   6.2   134.28%
exists z               6.0   5.1   117.08%
get z                  5.6   4.3   131.69%
set l {}               8.3   6.3   132.53%
lappend l a b c        7.1   7.2    97.98%
unset l                6.1   6.1   100.34%
incr z                 6.5   5.3   122.67%
mkexist                2.5   2.5    99.08%
gwd z                  9.3   7.3   127.43%
gwd q 3               12.0  10.0   120.00%
setto a b c d e 0     19.0  15.0   126.67%
eref z                 3.9   3.4   114.62%
aref                   2.2   2.1   102.86%
======

<<categories>>Array