Class: Dictionary

Class | Dictionary
In: | lib/more/facets/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 has_key? insert inspect invert key? keys last length merge merge! new new_by order order_by order_by_key order_by_value pop push reject reject! reorder replace reverse reverse! select shift size store to_a to_h to_hash to_s unshift update values

### Included Modules

Enumerable

### Public Class methods

[](*args)

[Source]

    # File lib/more/facets/dictionary.rb, line 128
        def [](*args)
          hsh = new
          if Hash === args[0]
            hsh.replace(args[0])
          elsif (args.size % 2) != 0
            raise ArgumentError, "odd number of elements for Hash"
          else
            while !args.empty?
              hsh[args.shift] = args.shift
            end
          end
          hsh
        end

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 }

[Source]

    # File lib/more/facets/dictionary.rb, line 160
        def alpha(*args, &block)
          new(*args, &block).order_by_key
        end

auto(*args)

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

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

[Source]

    # File lib/more/facets/dictionary.rb, line 169
        def auto(*args)
          #AutoDictionary.new(*args)
          leet = lambda { |hsh, key| hsh[key] = new(&leet) }
          new(*args, &leet)
        end

new(*args, &blk)

New Dictiionary.

[Source]

    # File lib/more/facets/dictionary.rb, line 178
      def initialize(*args, &blk)
        @order = []
        @order_by = nil
        if blk
          dict = self                                  # This ensure autmatic key entry effect the
          oblk = lambda{ |hsh, key| blk[dict,key] }    # dictionary rather then just the interal hash.
          @hash = Hash.new(*args, &oblk)
        else
          @hash = Hash.new(*args)
        end
      end

new_by(*args, &blk)

Like new but the block sets the order.

[Source]

    # File lib/more/facets/dictionary.rb, line 144
        def new_by(*args, &blk)
          new(*args).order_by(&blk)
        end

### Public Instance methods

<<(kv)

[Source]

    # File lib/more/facets/dictionary.rb, line 381
      def <<(kv)
        push(*kv)
      end

==(hsh2)

def ==( hsh2 )

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

end

[Source]

    # File lib/more/facets/dictionary.rb, line 255
      def ==(hsh2)
        if hsh2.is_a?( Dictionary )
          @order == hsh2.order &&
          @hash  == hsh2.instance_variable_get("@hash")
        else
          false
        end
      end

[](k)

[Source]

    # File lib/more/facets/dictionary.rb, line 264
      def [] k
        @hash[ k ]
      end

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

Store operator.

      h[key] = value

Or with additional index.

     h[key,index] = value

[Source]

    # File lib/more/facets/dictionary.rb, line 280
      def []=(k, i=nil, v=nil)
        if v
          insert(i,k,v)
        else
          store(k,i)
        end
      end

clear()

[Source]

    # File lib/more/facets/dictionary.rb, line 298
      def clear
        @order = []
        @hash.clear
      end

delete( key )

[Source]

    # File lib/more/facets/dictionary.rb, line 303
      def delete( key )
        @order.delete( key )
        @hash.delete( key )
      end

delete_if() {|k,@hash[k]| ...}

[Source]

    # File lib/more/facets/dictionary.rb, line 324
      def delete_if
        order.clone.each { |k| delete k if yield(k,@hash[k]) }
        self
      end

dup()

[Source]

    # File lib/more/facets/dictionary.rb, line 406
      def dup
        a = []
        each{ |k,v| a << k; a << v }
        self.class[*a]
      end

each() {|k,@hash[k]| ...}

[Source]

    # File lib/more/facets/dictionary.rb, line 318
      def each
        order.each { |k| yield( k,@hash[k] ) }
        self
      end

each_key() {|k| ...}

[Source]

    # File lib/more/facets/dictionary.rb, line 308
      def each_key
        order.each { |k| yield( k ) }
        self
      end

each_pair()

Alias for each

each_value() {|@hash[k]| ...}

[Source]

    # File lib/more/facets/dictionary.rb, line 313
      def each_value
        order.each { |k| yield( @hash[k] ) }
        self
      end

empty?()

[Source]

    # File lib/more/facets/dictionary.rb, line 455
      def empty?
        @hash.empty?
      end

fetch(k, *a, &b)

[Source]

    # File lib/more/facets/dictionary.rb, line 268
      def fetch(k, *a, &b)
        @hash.fetch(k, *a, &b)
      end

first(x=nil)

[Source]

    # File lib/more/facets/dictionary.rb, line 439
      def first(x=nil)
        return @hash[order.first] unless x
        order.first(x).collect { |k| @hash[k] }
      end

has_key?(key)

[Source]

    # File lib/more/facets/dictionary.rb, line 459
      def has_key?(key)
        @hash.has_key?(key)
      end

insert( i,k,v )

[Source]

    # File lib/more/facets/dictionary.rb, line 288
      def insert( i,k,v )
        @order.insert( i,k )
        @hash.store( k,v )
      end

inspect()

[Source]

    # File lib/more/facets/dictionary.rb, line 400
      def inspect
        ary = []
        each {|k,v| ary << k.inspect + "=>" + v.inspect}
        '{' + ary.join(", ") + '}'
      end

invert()

[Source]

    # File lib/more/facets/dictionary.rb, line 339
      def invert
        hsh2 = self.class.new
        order.each { |k| hsh2[@hash[k]] = k }
        hsh2
      end

key?(key)

[Source]

    # File lib/more/facets/dictionary.rb, line 463
      def key?(key)
        @hash.key?(key)
      end

keys()

[Source]

    # File lib/more/facets/dictionary.rb, line 335
      def keys
        order
      end

last(x=nil)

[Source]

    # File lib/more/facets/dictionary.rb, line 445
      def last(x=nil)
        return @hash[order.last] unless x
        order.last(x).collect { |k| @hash[k] }
      end

length()

[Source]

    # File lib/more/facets/dictionary.rb, line 450
      def length
        @order.length
      end

merge( hsh2 )

[Source]

    # File lib/more/facets/dictionary.rb, line 419
      def merge( hsh2 )
        self.dup.update(hsh2)
      end

merge!( hsh2 )

Alias for update

order()

[Source]

    # File lib/more/facets/dictionary.rb, line 190
      def order
        reorder if @order_by
        @order
      end

order_by( &block )

Keep dictionary sorted by a specific sort order.

[Source]

    # File lib/more/facets/dictionary.rb, line 197
      def order_by( &block )
        @order_by = block
        order
        self
      end

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.

[Source]

    # File lib/more/facets/dictionary.rb, line 217
      def order_by_key
        @order_by = lambda { |k,v| k }
        order
        self
      end

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 }

[Source]

    # File lib/more/facets/dictionary.rb, line 235
      def order_by_value
        @order_by = lambda { |k,v| v }
        order
        self
      end

pop()

[Source]

    # File lib/more/facets/dictionary.rb, line 395
      def pop
        key = order.last
        key ? [key,delete(key)] : nil
      end

push( k,v )

[Source]

    # File lib/more/facets/dictionary.rb, line 385
      def push( k,v )
        unless @hash.include?( k )
          @order.push( k )
          @hash.store( k,v )
          true
        else
          false
        end
      end

reject(&block)

[Source]

    # File lib/more/facets/dictionary.rb, line 345
      def reject(&block)
        self.dup.delete_if(&block)
      end

reject!( &block )

[Source]

    # File lib/more/facets/dictionary.rb, line 349
      def reject!( &block )
        hsh2 = reject(&block)
        self == hsh2 ? nil : hsh2
      end

reorder()

[Source]

    # File lib/more/facets/dictionary.rb, line 242
      def reorder
        if @order_by
          assoc = @order.collect{ |k| [k,@hash[k]] }.sort_by(&@order_by)
          @order = assoc.collect{ |k,v| k }
        end
        @order
      end

replace(hsh2)

[Source]

    # File lib/more/facets/dictionary.rb, line 354
      def replace(hsh2)
        case hsh2
        when Hash
          @order = hsh2.keys
          @hash  = hsh2
        else
          @order = hsh2.order
          @hash  = hsh2.hash
        end
        reorder
      end

reverse()

[Source]

    # File lib/more/facets/dictionary.rb, line 434
      def reverse
        dup.reverse!
      end

reverse!()

[Source]

    # File lib/more/facets/dictionary.rb, line 429
      def reverse!
        @order.reverse!
        self
      end

select() {|k,v| ...}

[Source]

    # File lib/more/facets/dictionary.rb, line 423
      def select
        ary = []
        each { |k,v| ary << [k,v] if yield k,v }
        ary
      end

shift()

[Source]

    # File lib/more/facets/dictionary.rb, line 366
      def shift
        key = order.first
        key ? [key,delete(key)] : super
      end

size()

Alias for length

store( a,b )

[Source]

    # File lib/more/facets/dictionary.rb, line 293
      def store( a,b )
        @order.push( a ) unless @hash.has_key?( a )
        @hash.store( a,b )
      end

to_a()

[Source]

    # File lib/more/facets/dictionary.rb, line 467
      def to_a
        ary = []
        each { |k,v| ary << [k,v] }
        ary
      end

to_h()

[Source]

    # File lib/more/facets/dictionary.rb, line 481
      def to_h
        @hash.dup
      end

to_hash()

[Source]

    # File lib/more/facets/dictionary.rb, line 477
      def to_hash
        @hash.dup
      end

to_s()

[Source]

    # File lib/more/facets/dictionary.rb, line 473
      def to_s
        self.to_a.to_s
      end

unshift( k,v )

[Source]

    # File lib/more/facets/dictionary.rb, line 371
      def unshift( k,v )
        unless @hash.include?( k )
          @order.unshift( k )
          @hash.store( k,v )
          true
        else
          false
        end
      end

update( hsh2 )

[Source]

    # File lib/more/facets/dictionary.rb, line 412
      def update( hsh2 )
        hsh2.each { |k,v| self[k] = v }
        reorder
        self
      end

values()

[Source]

    # File lib/more/facets/dictionary.rb, line 329
      def values
        ary = []
        order.each { |k| ary.push @hash[k] }
        ary
      end

[Validate]