usps_intelligent_barcode 0.3.0

data/lib/usps_intelligent_barcode/crc.rb

@@ -0,0 +1,52 @@
+require 'usps_intelligent_barcode/numeric_conversions'
+
+module Imb
+
+  # @!group Internal
+
+  # Calculates the Intelligent Mail Barcode CRC.
+
+  class Crc
+
+    include NumericConversions
+
+    # Calculate a CRC.
+    # @param [Integer] binary_data A 102-bit integer
+    # @return [Integer] An 11-bit CRC
+
+    def crc(binary_data)
+      crc = MASK
+      bytes = numeric_to_bytes(binary_data, NUM_INPUT_BYTES)
+      crc = crc_byte(crc, bytes.first, LEADING_BITS_TO_IGNORE)
+      for byte in bytes[1...NUM_INPUT_BYTES]
+        crc = crc_byte(crc, byte, 0)
+      end
+      crc
+    end
+
+    private
+
+    LEADING_BITS_TO_IGNORE = 2
+    CRC_BITS = 11
+    CRC_MSB_MASK = 1 << (CRC_BITS - 1)
+    BITS_PER_BYTE = 8
+    POLYNOMIAL = 0x0F35
+    MASK = (1 << CRC_BITS) - 1
+    NUM_INPUT_BYTES = 13
+
+    def crc_byte(crc, byte, leading_bits_to_ignore)
+      num_bits = BITS_PER_BYTE - leading_bits_to_ignore
+      data = byte << CRC_BITS - BITS_PER_BYTE + leading_bits_to_ignore
+      num_bits.times do
+        use_polynomial = (crc ^ data) & CRC_MSB_MASK
+        crc <<= 1 
+        crc ^= POLYNOMIAL if use_polynomial != 0
+        crc &= MASK
+        data <<= 1
+      end
+      crc
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/mailer_id.rb

@@ -0,0 +1,105 @@
+module Imb
+
+  # This class represents a mailer ID.
+
+  class MailerId
+
+    # The allowable range for a short (6-digit) mailer ID
+    SHORT_RANGE = 0..899_999
+
+    # The allowable range for a long (9-digit) mailer ID
+    LONG_RANGE = 900_000_000..999_999_999
+
+    # The list of all allowable ranges for a mailer ID
+    RANGES = [SHORT_RANGE, LONG_RANGE]
+
+    # Turn the argument into a MailerID if possible.  Accepts:
+    # * {MailerId}
+    # * String
+    # * Integer
+    # @return [MailerId]
+    # @raise [ArgumentError] If the argument cannot be coerced
+
+    def self.coerce(o)
+      case o
+      when MailerId
+        o
+      when String
+        new(o.to_i)
+      when Integer
+        new(o)
+      else
+        raise ArgumentError, 'Cannot coerce to MailerId'
+      end
+    end
+
+    # @param [Integer] value
+
+    def initialize(value)
+      @value = value
+    end
+
+    # Return true if this object is equal to o
+    # @param [Object] o Any object acceptable to {.coerce}
+
+    def ==(o)
+      MailerId.coerce(o).to_i == to_i
+    rescue ArgumentError
+      false
+    end
+
+    # @return [Integer] The value of the mailer ID
+
+    def to_i
+      @value
+    end
+
+    # @!group Internal
+
+    # Return true if this is a long (9 digit) mailer ID
+
+    def long?
+      LONG_RANGE === @value
+    end
+
+    # Validate the value.
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @raise ArgumentError if invalid
+
+    def validate(long_mailer_id)
+      unless in_range?
+        raise ArgumentError, "Must be #{RANGES.join(' or ')}"
+      end
+    end
+    
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+    # @param [Integer] target The target to be shifted and added to
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @return [Integer] The new value of the target
+
+    def shift_and_add_to(target, long_mailer_id)
+      target * 10 ** num_digits + to_i
+    end
+
+    # @!endgroup
+
+    private
+
+    def in_range?
+      RANGES.any? do |range|
+        range === @value
+      end
+    end
+
+    def num_digits
+      if long?
+        9
+      else
+        6
+      end
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/numeric_conversions.rb

@@ -0,0 +1,22 @@
+module Imb
+
+  # @!group Internal
+
+  # Numeric conversions
+
+  module NumericConversions
+
+    # Convert a numeric to an array of at least +min_bytes+ bytes.
+    # @param [Numeric] n
+    # @param [Integer] min_bytes
+    # @return [[Integer]] Array of bytes
+
+    def numeric_to_bytes(n, min_bytes=0)
+      n.to_s(16).rjust(2 * min_bytes, '0').scan(/../).map do |s|
+        s.to_i(16)
+      end
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/routing_code.rb

@@ -0,0 +1,134 @@
+module Imb
+
+  # Represents a routing code
+
+  class RoutingCode
+
+    # Turn the argument into a RoutingCode if possible.  Accepts:
+    # * {RoutingCode}
+    # * nil (no routing code)
+    # * String of length:
+    #   * 0 - no routing code
+    #   * 5 - zip
+    #   * 9 - zip + plus4
+    #   * 11 - zip + plus4 + delivery point
+    # * Array of [zip, plus4, delivery point]
+    # @return [RoutingCode]
+
+    def self.coerce(o)
+      case o
+      when nil
+        coerce('')
+      when RoutingCode
+        o
+      when Array
+        RoutingCode.new(*o)
+      when String
+        RoutingCode.new(*string_to_array(o))
+      else
+        raise ArgumentError, 'Cannot coerce to RoutingCode'
+      end
+    end
+
+    # @return [Integer] The ZIP (or nil)
+    attr_accessor :zip
+
+    # @return [Integer] The plus4 (or nil)
+    attr_accessor :plus4
+
+    # @return [Integer] The delivery point (or nil)
+    attr_accessor :delivery_point
+    
+    # Create a RoutingCode.  Arguments are:
+    # * +zip+ - Integer zip (or nil)
+    # * +plus4+ - Integer plus4 (or nil)
+    # * +delivery_point+ - Integer delivery poitn (or nil)
+
+    def initialize(zip, plus4, delivery_point)
+      @zip = arg_to_i(zip)
+      @plus4 = arg_to_i(plus4)
+      @delivery_point = arg_to_i(delivery_point)
+    end
+
+    # Return true if this object is equal to o
+    # @param [Object] o Any object acceptable to {.coerce}
+
+    def ==(o)
+      RoutingCode.coerce(o).to_a == to_a
+    rescue ArgumentError
+      false
+    end
+
+    # @!group Internal
+
+    # Convert a string representation of a routing code into
+    # an array that can be passed to the constructor.
+    # +s+ is a string of length:
+    # * 0 - no routing code
+    # * 5 - zip
+    # * 9 - zip + plus4
+    # * 11 - zip + plus4 + delivery point
+    # The result is an array of [zip, zip4, delivery point]
+
+    def self.string_to_array(s)
+      s = s.gsub(/[\D]/, '')
+      match = /^(?:(\d{5})(?:(\d{4})(\d{2})?)?)?$/.match(s)
+      unless match
+        raise ArgumentError, "Bad routing code: #{s.inspect}"
+      end
+      zip, plus4, delivery_point = match.to_a[1..-1]
+      [zip, plus4, delivery_point]
+    end
+
+    # Validate the value.
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @raise ArgumentError if invalid
+
+    def validate(long_mailer_id)
+    end
+
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+    # @param [Integer] target The target to be shifted and added to
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @return [Integer] The new value of the target
+
+    def shift_and_add_to(target, long_mailer_id)
+      target * 10 ** NUM_DIGITS + convert
+    end
+
+    # @!endgroup
+
+    protected
+
+    # Convert to an array of [zip, plus4, delivery point]
+
+    def to_a
+      [@zip, @plus4, @delivery_point]
+    end
+
+    private
+
+    NUM_DIGITS = 11 #:nodoc:
+
+    def arg_to_i(o)
+      o.andand.to_i
+    end
+    
+    # Convert to an integer value
+
+    def convert
+      if @zip && @plus4 && @delivery_point
+        @zip * 1000000 + @plus4 * 100 + @delivery_point + 1000100001
+      elsif @zip && @plus4
+        @zip * 10000 + @plus4 + 100001
+      elsif @zip
+        @zip + 1
+      else
+        0
+      end
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/serial_number.rb

@@ -0,0 +1,88 @@
+module Imb
+
+  # This class represents the mail piece's serial number.
+
+  class SerialNumber
+
+    # Turn the argument into a SerialNumber if possible.  Accepts:
+    # * {SerialNumber}
+    # * String
+    # * Integer
+    # @return [SerialNumber]
+
+    def self.coerce(o)
+      case o
+      when SerialNumber
+        o
+      when String
+        new(o.to_i)
+      when Integer
+        new(o)
+      else
+        raise ArgumentError, 'Cannot coerce to SerialNumber'
+      end
+    end
+
+    # @param [Integer] value
+
+    def initialize(value)
+      @value = value
+    end
+
+    # Return true if this object is equal to o
+    # @param [Object] o Any object acceptable to {.coerce}
+
+    def ==(o)
+      SerialNumber.coerce(o).to_i == to_i
+    rescue ArgumentError
+      false
+    end
+
+    # @return [Integer] The value of the serial number
+
+    def to_i
+      @value
+    end
+
+    # @!group Internal
+
+    # Validate the value.
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @raise ArgumentError if invalid
+
+    def validate(long_mailer_id)
+      range = 0..max_value(long_mailer_id)
+      unless range === @value
+        raise ArgumentError, "Must be #{range}"
+      end
+    end
+
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+    # @param [Integer] target The target to be shifted and added to
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @return [Integer] The new value of the target
+
+    def shift_and_add_to(target, long_mailer_id)
+      target * 10 ** num_digits(long_mailer_id) + to_i
+    end
+
+    # @!endgroup
+
+    private
+
+    def max_value(long_mailer_id)
+      max_value = 10 ** num_digits(long_mailer_id) - 1
+    end
+
+    def num_digits(long_mailer_id)
+      if long_mailer_id
+        6
+      else
+        9
+      end
+    end
+
+  end
+
+end

data/lib/usps_intelligent_barcode/service_type.rb

@@ -0,0 +1,79 @@
+module Imb
+
+  # This class represents a service type.
+
+  class ServiceType
+
+    # The valid range of a service type
+    RANGE = 0..999
+
+    # Turn the argument into a ServiceType if possible.  Accepts:
+    # * {ServiceType}
+    # * String
+    # * Integer
+
+    def self.coerce(o)
+      case o
+      when ServiceType
+        o
+      when String
+        new(o.to_i)
+      when Integer
+        new(o)
+      else
+        raise ArgumentError, 'Cannot coerce to ServiceType'
+      end
+    end
+
+    # @param [Integer] value
+
+    def initialize(value)
+      @value = value
+    end
+
+    # Return true if this object is equal to o
+    # @param [Object] o Any object acceptable to {.coerce}
+
+    def ==(o)
+      ServiceType.coerce(o).to_i == to_i
+    rescue ArgumentError
+      false
+    end
+
+    # @return [Integer] The value of the service type
+
+    def to_i
+      @value
+    end
+
+    # @!group Internal
+
+    # Validate the value.
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @raise ArgumentError if invalid
+
+    def validate(long_mailer_id)
+      unless (RANGE) === @value
+        raise ArgumentError, "Must be #{RANGE}"
+      end
+    end
+
+    # Add this object's value to target, shifting it left as many
+    # digts as are needed to make room.
+    # @param [Integer] target The target to be shifted and added to
+    # @param long_mailer_id truthy if the mailer ID is long (9 digits).
+    # @return [Integer] The new value of the target
+
+    def shift_and_add_to(target, long_mailer_id)
+      target * 10 ** NUM_DIGITS + to_i
+    end
+
+    # @!endgroup
+
+    private
+
+    NUM_DIGITS = 3 #:nodoc:
+
+  end
+
+end