Class | Dictionary
In: | lib/facets/more/dictionary.rb
Parent: | Object

# Dictionary

The Dictionary class is a Hash that preserves order. So it has some array-like extensions also. By defualt a Dictionary object preserves insertion order, but any order can be specified including alphabetical key order.

## Usage

Just require this file and use Dictionary instead of Hash.

      # You can do simply
      hsh = Dictionary.new
      hsh['z'] = 1
      hsh['a'] = 2
      hsh['c'] = 3
      p hsh.keys     #=> ['z','a','c']

      # or using Dictionary[] method
      hsh = Dictionary['z', 1, 'a', 2, 'c', 3]
      p hsh.keys     #=> ['z','a','c']

      # but this don't preserve order
      hsh = Dictionary['z'=>1, 'a'=>2, 'c'=>3]
      p hsh.keys     #=> ['a','c','z']

      # Dictionary has useful extensions: push, pop and unshift
      p hsh.push('to_end', 15)       #=> true, key added
      p hsh.push('to_end', 30)       #=> false, already - nothing happen
      p hsh.unshift('to_begin', 50)  #=> true, key added
      p hsh.unshift('to_begin', 60)  #=> false, already - nothing happen
      p hsh.keys                     #=> ["to_begin", "a", "c", "z", "to_end"]
      p hsh.pop                      #=> ["to_end", 15], if nothing remains, return nil
      p hsh.keys                     #=> ["to_begin", "a", "c", "z"]
      p hsh.shift                    #=> ["to_begin", 30], if nothing remains, return nil

## Usage Notes

- You can use order_by to set internal sort order.
- #<< takes a two element [k,v] array and inserts.
- Use ::auto which creates Dictionay sub-entries as needed.
- And ::alpha which creates a new Dictionary sorted by key.

### Methods

<< == [] [] []= alpha auto clear delete delete_if dup each each_key each_pair each_value empty? fetch first insert inspect invert keys last length merge merge! new new_by order order_by order_by_key order_by_value pop push reject reject! reorder replace select shift size store to_a to_s unshift update values

### Public Class methods

[]( *args )
alpha( *args, &block )

Alternate to new which creates a dictionary sorted by key.

      d = Dictionary.alpha
      d["z"] = 1
      d["y"] = 2
      d["x"] = 3
      d  #=> {"x"=>3,"y"=>2,"z"=>2}

This is equivalent to:

      Dictionary.new.order_by { |key,value| key }

auto( *args )

Alternate to new which auto-creates sub-dictionaries as needed.

      d = Dictionary.auto
      d["a"]["b"]["c"] = "abc"  #=> { "a"=>{"b"=>{"c"=>"abc"}}}

new( *args, &blk )
new_by( *args, &blk )

Like new but the block sets the order.

### Public Instance methods

<<(kv)
==( hsh2 )

def ==( hsh2 )

      return false if @order != hsh2.order
      super hsh2

end

[](k)
[]=(k, i=nil, v=nil)

Store operator.

      h[key] = value

Or with additional index.

     h[key,index] = value

clear()
delete( key )
delete_if() {|| ...}
dup()
each() {|k,@hash[k]| ...}
each_key() {|k| ...}
each_pair()

Alias for each

each_value() {|@hash[k]| ...}
empty?()
fetch( k )
first()
insert( i,k,v )
inspect()
invert()
keys()
last()
length()
merge( hsh2 )
merge!( hsh2 )

Alias for update

order()
order_by( &block )

Keep dictionary sorted by a specific sort order.

order_by_key()

Keep dictionary sorted by key.

      d = Dictionary.new.order_by_key
      d["z"] = 1
      d["y"] = 2
      d["x"] = 3
      d  #=> {"x"=>3,"y"=>2,"z"=>2}

This is equivalent to:

      Dictionary.new.order_by { |key,value| key }

The initializer Dictionary#alpha also provides this.

order_by_value()

Keep dictionary sorted by value.

      d = Dictionary.new.order_by_value
      d["z"] = 1
      d["y"] = 2
      d["x"] = 3
      d  #=> {"x"=>3,"y"=>2,"z"=>2}

This is equivalent to:

      Dictionary.new.order_by { |key,value| value }

pop()
push( k,v )
reject( &block )
reject!( &block )
reorder()
replace( hsh2 )
select() {|k,v| ...}
shift()
size()

Alias for length

store( a,b )
to_a()
to_s()
unshift( k,v )
update( hsh2 )
values()

[Validate]