fixed_point_field 1.0

data/README

@@ -0,0 +1,62 @@
+FixedPointField
+===============
+
+Stores floating point values in an integer database column.
+
+Most useful for currency, fixed_point_field is a library that lets you tell your
+active record classes that some numeric column needs to be upscaled when saved
+and downscaled when loaded, by some known number of decimal places.  It also
+generates stubs to directly access the fixed point version of the number, if
+you need to use mathematics and remain exact, you can multiply the fixed width
+version of your number by another integer and then down convert the result
+manually. The formula for this is:
+  fixed_num.to_f / (base ** width)
+
+
+Usage
+=====
+
+class Product < ActiveRecord::Base
+  fixed_point_field :price
+end
+
+prod = Product.new(:price => 12.75)
+prod.price                          # => 12.75
+prod.price_fixed                    # => 1275
+
+# it is stored as an int
+prod.send(:read_attribute, :price)  # => 1275
+
+# fixed point setter
+prod.price_fixed = 1999
+prod.price                          # => 19.99
+
+
+Other widths and bases
+======================
+
+This library was designed to be used to store American currency (USD), but may
+be useful in other situations as well.  To store a number with a fixed point
+width of 10, use:
+
+fixed_point_field :very_precise_column, :width => 10
+
+You can also store numbers in other bases other than decimal numbers, but any
+base that is not evenly divisible by 10 will give you rounding errors, negating
+the value of the plugin.  I'm not sure why you'd need this, but here it is:
+
+fixed_point_field :base_twenty_column, :base => 20
+
+
+Installation
+============
+
+The preferred method of installation is through Rubygems.  You can use
+config.gem, bundler, or manually install the fixed_point_field gem, depending
+on your version of Rails and desired usage.
+
+
+Feedback
+========
+
+powerup@rubidine.com

data/Rakefile

@@ -0,0 +1,27 @@
+begin
+  require File.join(File.dirname(__FILE__), '..', '..', '..', 'config', 'environment')
+rescue LoadError
+  raise "Please test from within your rails application: Unable to load environment.rb"
+end
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the fixed_point_field plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the fixed_point_field plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'FixedPointField'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/init.rb

@@ -0,0 +1,2 @@
+require 'fixed_point_field'
+ActiveRecord::Base.send :include, FixedPointField

data/lib/fixed_point_field.rb

@@ -0,0 +1,123 @@
+# The MIT License
+# 
+# Copyright (c) 2009 Rubidine <powerup@rubidine.com>
+# 
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+# 
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+# 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+# Fixed Point Field specifies that a field that is accessed like a float from
+# a rails script should be stored as an integer in the database.  This is only
+# practical when the field always has a fixed number of digits after the
+# decimal place, like how US Dollars have 2 digits of cents after the decimal.
+# More information and examples are available in the README.
+module FixedPointField
+
+  # When the module is included, in addition to adding the methods to instances
+  # of the class, we need to add methods to the class object, do this
+  # with extend.
+  def self.included kls
+    kls.send :extend, ClassMethods
+  end
+
+  # Set a fixed point column to the specificed value (fixed).  This
+  # is wrapped behind a conversion for the default assignment operator,
+  # such that if you had called:
+  # <code>fixed_point_field :price</code>
+  # the method price= would convert and then call this function.
+  def set_fixed_point(column_name, value)
+    write_attribute(column_name, value)
+  end
+
+  # Set a column using a floating point column.  This calls
+  # set_fixed_point after it has up-scaled the value to the specified
+  # number of digits.  By default the width is 2 and base is 10, to
+  # work with USD currency.
+  # If you had called:
+  # <code>fixed_point_field :price</code>
+  # the method price= would be a direct call to this function.
+  def set_floating_point(column_name, value, width = 2, base = 10)
+    return if value == ''
+    set_fixed_point(column_name, (value.to_f * (base**width)).round)
+  end
+
+  # Retrieve the raw value of the field, which will be a Fixnum.
+  # This is wrapped behind the default getter, so it is fetched with this
+  # function, then down-converted and returned.
+  def read_fixed_point(column_name)
+    read_attribute(column_name)
+  end
+
+  # Reads the fixed point version and converts.  Will return nil if the column
+  # value is nil.  If you had called:
+  # <code>fixed_point_field :price</code>
+  # the method price would be a direct call to this function.
+  def read_floating_point(column_name, width = 2, base = 10)
+    (rv = read_fixed_point(column_name)) ? (rv.to_f / (base**width)) : nil
+  end
+
+  module FixedPointField::ClassMethods
+
+    # Calling this in an active record class will make getters / setters
+    # available for in integer field that return / accept values that are
+    # floating point.  It will convert them to integer values by up-scaling
+    # the number by a certain number of decimal places.  This is most useful
+    # for working with money, when the values can be stored as cents, but
+    # will most often be working with dollars, which always has two places
+    # after the decimal reserved for cents.
+    #
+    # Takes any number of field names to be converted, and an optional
+    # hash as the last argument.  The hash can have keys of :width, which
+    # is the number of places beyond the decimal to use (default 2), and
+    # :base, which is the number system to use (default 10 [decimal]).
+    #
+    # This for a field named my_field, this will generate the methods
+    #   * my_field - returns the value as a float
+    #   * my_field_fixed - returns the value as it is stored (Fixnum)
+    #   * my_field= - takes a floating point number and scales it appropriately
+    #   * my_field_fixed= - direct setter for fixed point number
+    def fixed_point_field *fields
+      opts = (fields.pop if fields.last.is_a?(Hash)) || {}
+      opts[:width] ||= 2
+      opts[:base] ||= 10
+      fields.each do |field|
+        read_fixed_method = "#{field}_fixed"
+        read_float_method = "#{field}"
+        set_float_method = "#{field}="
+        set_fixed_method = "#{field}_fixed="
+
+        define_method(read_fixed_method) do
+          read_fixed_point(field)
+        end
+
+        define_method(read_float_method) do
+          read_floating_point(field, opts[:width], opts[:base])
+        end
+
+        define_method(set_float_method) do |value|
+          set_floating_point(field, value, opts[:width], opts[:base])
+        end
+
+        define_method(set_fixed_method) do |value|
+          set_fixed_point(field, value)
+        end
+
+      end
+    end
+  end
+
+end

data/tasks/fixed_point_field_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :fixed_point_field do
+#   # Task goes here
+# end

data/test/fixed_point_field_test.rb

@@ -0,0 +1,221 @@
+# this doesn't stand alone, load rails
+unless defined?(RAILS_ROOT)
+  ENV['RAILS_ENV'] = 'test'
+  begin
+    require File.join(File.dirname(__FILE__), '..', '..', '..', '..', 'config', 'environment')
+  rescue
+    raise "Please test from within your rails app vendor/plugins/THISPLUGIN: Unable to load config/environment.rb"
+  end
+end
+
+begin
+  require 'mocha'
+rescue LoadError
+  raise "Please install the mocha gem to test fixed_point_column."
+end
+
+require 'test/unit'
+
+class FixedPointFieldTest < Test::Unit::TestCase
+
+  class Sentinel < RuntimeError
+  end
+
+  class TestRecord < ActiveRecord::Base
+    def self.columns
+      [
+        ActiveRecord::ConnectionAdapters::Column.new(
+          'a', #name
+          nil, #default
+          'int(11)', # sql type
+          true #null
+        ),
+        ActiveRecord::ConnectionAdapters::Column.new(
+          'b', #name
+          nil, #default
+          'int(11)', # sql type
+          true #null
+        )
+      ]
+    end
+  end
+
+  def test_mixin_works
+    TestRecord.send(:fixed_point_field, :a)
+    instance = TestRecord.new
+
+    assert instance.respond_to?(:set_fixed_point)
+    assert instance.respond_to?(:set_floating_point)
+    assert instance.respond_to?(:read_fixed_point)
+    assert instance.respond_to?(:read_floating_point)
+
+    assert instance.respond_to?(:a_fixed)
+    assert instance.respond_to?(:a)
+    assert instance.respond_to?(:a_fixed=)
+    assert instance.respond_to?(:a=)
+  end
+
+  def test_sane_defaults
+    TestRecord.send(:fixed_point_field, :a)
+    instance = TestRecord.new
+
+    # make sure it works before the stub
+    instance.a = 10.3
+
+    # 2, 10 are our default width and base
+    instance.stubs(:set_floating_point).with(:a, 10.3, 2, 10).raises(Sentinel)
+    assert_raises(Sentinel) do
+      instance.a = 10.3
+    end
+  end
+
+  def test_mixin_works_with_options
+    TestRecord.send(:fixed_point_field, :a, {:width => 1})
+    instance = TestRecord.new
+
+    assert instance.respond_to?(:set_fixed_point)
+    assert instance.respond_to?(:set_floating_point)
+    assert instance.respond_to?(:read_fixed_point)
+    assert instance.respond_to?(:read_floating_point)
+
+    assert instance.respond_to?(:a_fixed)
+    assert instance.respond_to?(:a)
+    assert instance.respond_to?(:a_fixed=)
+    assert instance.respond_to?(:a=)
+  end
+
+  def test_options_are_followed
+    TestRecord.send(:fixed_point_field, :a, {:width => 1})
+    instance = TestRecord.new
+
+    # make sure it works before the stub
+    instance.a = 10.3
+
+    # third argument = width
+    instance.stubs(:set_floating_point).with(:a, 10.3, 1, 10).raises(Sentinel)
+    assert_raises(Sentinel) do
+      instance.a = 10.3
+    end
+
+    # make sure it works before the stub
+    instance.a
+
+    # second argument = width
+    instance.stubs(:read_floating_point).with(:a, 1, 10).raises(Sentinel)
+    assert_raises(Sentinel) do
+      instance.a
+    end
+  end
+
+  def test_set_float
+    TestRecord.send(:fixed_point_field, :a)
+    instance = TestRecord.new
+    instance.a = 10.3
+    assert_equal 1030, instance.send(:read_attribute, :a)
+  end
+
+  def test_set_fixed
+    TestRecord.send(:fixed_point_field, :a)
+    instance = TestRecord.new
+    instance.a_fixed = 103
+    assert_equal 103, instance.send(:read_attribute, :a)
+  end
+
+  def test_read_float
+    TestRecord.send(:fixed_point_field, :a)
+    instance = TestRecord.new
+    instance.send(:write_attribute, :a, 103)
+    assert_equal 1.03, instance.a
+  end
+
+  def test_read_fixed
+    TestRecord.send(:fixed_point_field, :a)
+    instance = TestRecord.new
+    instance.send(:write_attribute, :a, 103)
+    assert_equal 103, instance.a_fixed
+  end
+
+  def test_write_and_read_paring
+    TestRecord.send(:fixed_point_field, :a)
+    instance = TestRecord.new
+
+    instance.a = 10.3
+    assert_equal 10.3, instance.a
+    assert_equal 1030, instance.a_fixed
+
+    instance.a_fixed = 1310
+    assert_equal 13.10, instance.a
+    assert_equal 1310, instance.a_fixed
+  end
+
+  def test_multiple_fields_mixin
+    TestRecord.send(:fixed_point_field, :a, :b)
+    instance = TestRecord.new
+
+    assert instance.respond_to?(:set_fixed_point)
+    assert instance.respond_to?(:set_floating_point)
+    assert instance.respond_to?(:read_fixed_point)
+    assert instance.respond_to?(:read_floating_point)
+
+    assert instance.respond_to?(:a_fixed)
+    assert instance.respond_to?(:a)
+    assert instance.respond_to?(:a_fixed=)
+    assert instance.respond_to?(:a=)
+
+    assert instance.respond_to?(:b_fixed)
+    assert instance.respond_to?(:b)
+    assert instance.respond_to?(:b_fixed=)
+    assert instance.respond_to?(:b=)
+  end
+
+  def test_multiple_fields_read_write_pairing_without_collision
+    TestRecord.send(:fixed_point_field, :a, :b)
+    instance = TestRecord.new
+
+    instance.a = 10.3
+    instance.b = 1.1
+    assert_equal 10.3, instance.a
+    assert_equal 1030, instance.a_fixed
+    assert_equal 1.1, instance.b
+    assert_equal 110, instance.b_fixed
+
+    instance.a_fixed = 1310
+    instance.b_fixed = 570
+    assert_equal 13.10, instance.a
+    assert_equal 1310, instance.a_fixed
+    assert_equal 5.70, instance.b
+    assert_equal 570, instance.b_fixed
+  end
+
+  def test_multiple_fields_mixin_with_options
+    TestRecord.send(:fixed_point_field, :a, :b, {:width => 1})
+    instance = TestRecord.new
+
+    assert instance.respond_to?(:set_fixed_point)
+    assert instance.respond_to?(:set_floating_point)
+    assert instance.respond_to?(:read_fixed_point)
+    assert instance.respond_to?(:read_floating_point)
+
+    assert instance.respond_to?(:a_fixed)
+    assert instance.respond_to?(:a)
+    assert instance.respond_to?(:a_fixed=)
+    assert instance.respond_to?(:a=)
+
+    assert instance.respond_to?(:b_fixed)
+    assert instance.respond_to?(:b)
+    assert instance.respond_to?(:b_fixed=)
+    assert instance.respond_to?(:b=)
+  end
+
+  def test_base_twenty
+    TestRecord.send(:fixed_point_field, :a, :b, {:base => 20})
+    instance = TestRecord.new
+
+    instance.a = 10.3
+    assert_equal (10.3 * (20 ** 2)), instance.send(:read_attribute, :a)
+
+    # make sure it loads back okay as well
+    assert_equal 10.3, instance.a
+  end
+
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+name: fixed_point_field
+version: !ruby/object:Gem::Version 
+  version: "1.0"
+platform: ruby
+authors: 
+- Todd Willey <todd@rubidine.com>
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-05 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Store numeric amounts with a known number of decial points, such as currency, as a whole number, for more precise (non-floating point) operations.
+email: powerup@rubidine.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- README
+- Rakefile
+- init.rb
+- lib/fixed_point_field.rb
+- tasks/fixed_point_field_tasks.rake
+- test/fixed_point_field_test.rb
+has_rdoc: true
+homepage: http://github.com/rubidine/fixed_point_field
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 1.3.1
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: ActiveRecord plugin for dealing with currency
+test_files: 
+- test/fixed_point_field_test.rb