[ANN] arrayfields-3.7.0

[ara.t.howard]

NAME
arrayfields.rb

URIS
http://rubyforge.org/projects/arrayfields/
http://www.codeforpeople.com/lib/ruby/arrayfields/
http://raa.ruby-lang.org/project/arrayfields/

SYNOPSIS
require 'arrayfields'

fields = 'name', 'age'
a = [ 'zaphod', 42 ]

a.fields = fields

a[ 'name' ] #=> 'zaphod'
a[ :name ] #=> 'zaphod'
a.indices 'name', 'age' #=> [ 'zaphod', 42 ]

DESCRIPTION
allow keyword access to array instances. arrayfields works by adding only a
few methods to arrays, namely #fields= and fields, but the #fields= method
is hooked to extend arrays on a per object basis. in otherwords __only__
those arrays whose fields are set will have auto-magical keyword access
bestowed on them - all other arrays remain unaffected. arrays with keyword
access require much less memory when compared to hashes/objects and yet
still provide fast lookup.

LIST OF OVERRIDDEN METHODS
Array#[]
Array#slice
Array#[]=
Array#at
Array#delete_at
Array#fill
Array#values_at
Array#indices
Array#indexes
Array#slice!

LIST OF HASH-LIKE METHODS
Array#each_with_field
Array#each_pair
Array#each_key
Array#each_value
Array#fetch
Array#has_key?
Array#member?
Array#key?
Array#has_value?
Array#value?
Array#keys
Array#store
Array#values
Array#to_hash
Array#to_h
Array#update
Array#replace
Array#invert

LIST OF ADDED Array METHODS
Array#fields=
Array#fields

LIST OF ADDED Array CLASS METHODS
Array.fields/Array.struct

SAMPLES

<========< sample/a.rb >========>

~ > cat sample/a.rb

require 'arrayfields'
#
# the class Array has only a few added method, one is for setting the fields,
# when the fields are set for an array THIS INSTANCE ONLY will be modified to
# allow keyword access. other arrays will not be affected!
#
a = [0,1,2]
fields = ['zero', 'one', 'two']
a.fields = fields # ONLY the Array 'a' is affected!
#
# keyword access is now allowed for many methods
#
p a['zero'] #=> 0
p a['one'] #=> 1
p a['two'] #=> 2
p a.at('one') #=> 1
p a.values_at('zero', 'two') #=> [0, 2]
#
# assigmnet is allowed
#
a['zero'] = 42
p a['zero'] #=> 0
a['zero'] = 0
#
# assignment to non-fields results in the element being appended and the field
# being added for future use (also appended)
#
p(a.fields.join(',')) #=> "zero, one, two"
p a['three'] #=> nil
a['three'] = 3
p(a.fields.join(',')) #=> "zero, one, two, three"
p a['three'] #=> 3
#
# other detructive methods are also keyword enabled
#
a.fill 42, 'zero', len = a.size
p(a.values_at(a.fields)) #=> [42, 42, 42, 42]
a.replace [0,1,2,3]

a.slice! 'two', 2
p a #=> [0,1]

~ > ruby sample/a.rb

0
1
2
1
[0, 2]
42
"zero,one,two"
nil
"zero,one,two,three"
3
[42, 42, 42, 42]
[0, 1]


<========< sample/b.rb >========>

~ > cat sample/b.rb

require 'arrayfields'
#
# the struct/fields factory method can be used in much the same way as ruby's
# own struct generators and is useful when the fields for a set of arrays is
# known apriori
#
c = Array.fields :a, :b, :c # same as Array.struct
a = c.new [42, nil, nil]
a[:c] = 42
p a #=> [42, nil, 42]
#
# of course we can append too
#
a[:d] = 42.0
p a[:d] #=> 42.0
p a #=> [42, nil, 42, 42.0]

~ > ruby sample/b.rb

[42, nil, 42]
42.0
[42, nil, 42, 42.0]


AUTHOR
(e-mail address removed)

HISTORY
3.7.0:
- multiton pattern clean up, thanks gavin kistner!
- mods for ruby 1.8.6 (alias bug in 1.8.6 i think)
- added PseudoHash class
- added Array.struct/fields class generator


enjoy.

-a