nth

Nth

The Nth gem is a collection of utilities that use named numbers and ordinals to represent or access data. If you starting singing eight quintillion bottles of beer on the wall at the start of the big bang, you would still be signing it today! The gem supports numbers bigger than a milliquadragintillion (over 3000 zeros). A way smaller number septemvigintillion is more than the number of atoms in the Universe; it only has 84 zeros. Asside from ridiculously large numbers, there are also some useful utilities using named numbers. As an example we can access the #twelfth character of a string. Cookbook applications might like to use named measurements such as 'five and three quarters'.

Installation

Add this line to your application's Gemfile:

gem 'nth'

And then execute:

$ bundle

Or install it yourself as:

$ gem install nth

Usage

The Nth gem has methods that can be used out of the box. Instead you can install these methods to base classes such as Integer or String. This document will first explain how to install various utilities or a subset of available utilities to base classes. The last part of the document shows how to use some of the utilities without installing methods to base classes. Note that access methods must be installed.

Access Methods

Instead of using the [] and []= operators, on Arrays or Strings we can access elements using ordinals. This can also be applied to custom objects provided certain methods have been implemented. There are two mechanisms that can applied in order to endow a class with ordinal access. The preferred means utilizes a generator that defines a subset of ordinal access methods. The other uses the method_missing dynamic system of ghost methods which is less performant. As you only get to override method_missing once, you should be careful that some other library has not already done this. Note that both can be used at the same time; this allows for the more common ordinals to provide faster access. These access methods must be installed on a base class before they become active. Such installation should only be placed in your startup code. This is best seen by example as follows:

require 'Nth'
"".respond_to? :first  # false ... ordinal access not installed yet
"".respond_to? :last   # false

Nth::install(:AccessOrdinals, String, 5) 
# above installs: #first, #second, #third, #fourth, #fifth, and #last  methods

str = "This is a test!"
str.first   #  'T'
str.last    #  '!'
str.fourth  #  's'
str.fifth   #  ' '
str.sixth   #  error not defined
str.fifth = '_'  # str == "This_is a test!"

# add more ordinals ...
Nth::install(:AccessOrdinals, String, 25, '.')  # '.' is the fill parameter ... ' ' is the default

str.methods.include? :twenty_fifth   # true
str.methods.include? :twenty_fifth=  # true

str = "testing "
str.twenty_fifth = " 1,2,3"  # str == "testing ................ 1,2,3"

# add all ordinals using method missing ...
Nth::install(:AccessAllOrdinals, String, '?')

str.methods.include? :thirtieth  # false  ... not a real method
str.respond_to? :thirtieth       # true   ... but will respond to call

str.fourtieth = "$"  # str == "testing ................ 1,2,3?????????$"       

From the above we have the first 25 ordinals defined with actual methods, with the remaining ordinals defined using ghost methods. Now if you were to access the ordinal str.tresvigintillionth = "oops!", your computer would run out of memory! You can change the fill character by calling: String.instance_variable_set :@default_insert, ' '. Now we can do the same thing with Arrays as follows:

require 'Nth'
Nth::install(:AccessOrdinals, Array, 15, "nada")  # defaults to nil if no fill specified
array = [1,2,3]
array.fifth = 500  # [1, 2, 3, "nada", 500]
Nth::install(:AccessAllOrdinals, Array, nil)
array.tenth = "pi"  # [1, 2, 3, "nada", 500, nil, nil, nil, nil, "pi"]

From the above we have 15 actual ordinal methods, with the remainder implemented using ghost methods. Note that you only get one ghost method per class so be judicious. Custom objects call also install ordinal access provided that they implement the following methods: :[], :[]=, size. Note that Hash objects don't behave well as they are not ordered numerically like Array or String objects are.

Integer Methods

Integer methods must be installed before they become available. Each method creates a string which represents the number in some way. Integer methods are installed as follows: Nth::install(:IntMethods). Each method is documented in the following subsections.

Instance Method nth

This method creates a string comprising the number followed by a 2-letter suffix. Larger numbers are grouped in 3 and delimited by a comma. See the examples below:

require 'Nth'         
Nth::install(:IntMethods)

5.nth  # "5th"
1.nth  # "1st"
22.nth # "22nd"
63.nth # "63rd"
11.nth # "11th"
0.nth  # "0th"
-12345673.nth  # "-12,345,673rd"

Instance Method to_number

This method creates a string name that represents the number. See the examples below:

require 'Nth'         
Nth::install(:IntMethods)

123456789.to_number # "one hundred twenty-three million four hundred fifty-six thousand seven hundred eighty-nine"
600013417.to_number # "six hundred million thirteen thousand four hundred seventeen"
(10**105).to_number # "one quattuortrigintillion" 

Instance Method to_ordinal

This method creates a string name that represents the ordinal name of the number. See the examples below:

require 'Nth'         
Nth::install(:IntMethods)

123456783.to_ordinal # "one hundred twenty-three million four hundred fifty-six thousand seven hundred eighty-third"
600013412.to_ordinal # "six hundred million thirteen thousand four hundred twelfth"
(10**105).to_ordinal # "one quattuortrigintillionth" 

Instance Method cents_to_dollars

This method creates a string money name that could be used to print checks. The integer represents the number of pennies. See the examples below:

require 'Nth'         
Nth::install(:IntMethods)

1458312.cents_to_dollars  # "fourteen thousand five hundred eighty-three dollars and twelve cents"
101.cents_to_dollars      # "one dollar and one cent"
56.cents_to_dollars       # "zero dollars and fifty-six cents"
200.cents_to_dollars      # "two dollars and zero cents"

Instance Method pence_to_pounds

This method creates a string money name that could be used to print checks. The integer represents the number of pence. This is the British version of cents_to_dollars. See the examples below:

require 'Nth'         
Nth::install(:IntMethods)

1458312.pence_to_pounds  # "fourteen thousand five hundred eighty-three pounds and twelve pence"
101.pence_to_pounds      # "one pound and one penny"
56.pence_to_pounds       # "zero pounds and fifty-six pence"
200.pence_to_pounds      # "two pounds and zero pence"

Float Methods

Float methods must be installed before they become available. There are a variety of methods that implement a variety of utilities. Float methods are installed as follows: Nth::install(:FloatMethods). Each method is documented in the following subsections.

Instance Method to_fractional_unit(unit_name, mode = :descriptive, tar=0.01)

This method converts a floating point number to a unit based fraction with a multiplicity of formats. The unit_name parameter use use the singular noun; the method will pluralized the noun when appropriate. The mode parameter formats the resulting string; this will be explained by example later. The tar parameter defines the target resolution of the fraction; it is the percent error of the fraction. This routine is most useful for cookbook applications. See example below:

require 'Nth'         
Nth::install(:FloatMethods)  # do this once in the initialization section of your code

cups = 4.333333
cups.to_fractional_unit('cup')             #  "four and one third cups"
cups.to_fractional_unit('cup', :numeric)   #  "4 1/3 cups"
(1.0).to_fractional_unit('cup', :numeric)  #  "1 cup"

#  mode :utf    uses fraction glyphs if available ... uses digits for whole numbers
#  mode :html   uses fraction glyphs via html ampersand semicolon syntax

Instance Method inches_to_feet(mode = :descriptive, denom=16)

This method converts floating point inches to a string comprising feet and inches. The parameter mode defines how the resulting string is formatted. The denom parameter specifies the target resolution; for proper tape measure formate, this should be a power of 2. See the examples below:

require 'Nth'         
Nth::install(:FloatMethods)

data = 123.4567
data.inches_to_feet                     #  "ten feet three and seven sixteenth inches"
data.inches_to_feet(:numeric_long)      # "10 feet 3 7/16 inches"
data.inches_to_feet(:numeric_short)     # "10ft 3 7/16in"
data.inches_to_feet(:numeric_short,32)  # "10ft 3 15/32in"
(13.0).inches_to_feet                   # "one foot one inch"
# mode == :tics_utf  uses utf tic marks
# mode == :tics_html same as above but uses html entities to represent tic marks
# FYI:: love to show you an example, but can't display UTF chars in *.md document

Instance Method inches_to_yards(mode = :descriptive, denom=16)

Similar to inches_to_feet, but instead separates number into three fields: yards, feet, inches. This uses the same parameters as inches_to_feet, except tics_utf and tics_html are not supported.

Instance Method to_dms(frac_sec==2)

This turns geographical floating point numbers into degrees, minutes, and seconds. The routine produces utf chars that include degree glyphs as well as tic marks. The parameter frac_sec defines the number of displayed fractional digits in the seconds field.

Nth Module direct methods

This section details various methods that can be used without having to perform an installation to a class. There are several utility methods that are not documented as they are called by more useful methods. There are also methods that are not available in the installed section that have some utility.

Nth::pluralize(str)

This seemingly unrelated method is used to pluralize unit names; but it can be used on other nouns as well. This routine also handles most exceptions. See the example below:

require 'Nth' 

Nth::pluralize('foot')     # 'feet'
Nth::pluralize('octopus')  # "octopi"
Nth::pluralize('box')      # "boxes"
Nth::pluralize('wife')     # "wives"
Nth::pluralize('kiss')     # "kisses"
Nth::pluralize('fish')     # "fish"
Nth::pluralize('die')      # "dice"

Nth::get_number_name(int, *flags)

This converts an integer to a named number. The flags parameter list defines the final string formatting. This is best seen by example as follows:

require 'Nth' 
# flags are as follows:
# :-_                 separate each word with an underscore
# :-                  use dashes on some word combinations such as: twenty-six
# :plus_minus         prefix number with 'plus' or 'minus'  (default 'minus' if negative else '')
# :positive_negative  prefix number with 'positive' or 'negative' 

Nth::get_number_name(-13453)     # "minus thirteen thousand four hundred fifty three"
Nth::get_number_name(13453, :-)  # "thirteen thousand four hundred fifty-three"
Nth::get_number_name(13453, :_)  # "thirteen_thousand_four_hundred_fifty_three"
Nth::get_number_name(17, :plus_minus)  # "plus seventeen"
Nth::get_number_name(17, :positive_negative)  # "positive seventeen"
Nth::get_number_name(-17, :_, :positive_negative)  # "negative_seventeen"

Nth::get_ordinal_name(int, *flags)

This routine uses the same flags as get_number_name, but instead produces ordinal names. See the example below:

Nth::get_ordinal_name(-13453)  # "minus thirteen thousand four hundred fifty third"
Nth::get_ordinal_name(-17, :_, :positive_negative)  "negative_seventeenth"

Integer Methods without installation

We can access without installation integer methods as follows:

  Nth::IntMethods::to_nth_string(12345)        # "12,345th"
  Nth::IntMethods::to_nth_string(12345,false)  # "12345th"
  Nth::IntMethods::penny_to_dollar(12345)  # "one hundred twenty-three dollars and forty-five cents"
  Nth::IntMethods::pence_to_pound(12345)   # "one hundred twenty-three pounds and forty-five pence"

Float Methods without installation

We can access without installation float methods as follows:

  Nth::FloatMethods::to_fractional_unit(3.666666, 'cup', :descriptive, 0.01)  #  "three and two third cups"
  Nth::FloatMethods::to_fractional_unit(3.666666, 'cup', :numeric, 0.01)      #  "3 2/3 cups"
  # also modes:  :utf  and  :html 
  
  Nth::FloatMethods::inches_to_feet(14.63953, :descriptive, 64)    #  "one foot two and forty-one sixty-fourth inches"
  Nth::FloatMethods::inches_to_feet(14.63953, :numeric_long, 64)   #  "1 foot 2 41/64 inches"
  Nth::FloatMethods::inches_to_feet(14.63953, :numeric_short, 64)  #  "1ft 2 41/64in"
  # also modes:  :tics_utf  and  :tics_html
  
  Nth::FloatMethods::inches_to_yards(136.67134, :descriptive, 16)   #  "three yards two feet four and eleven sixteenth inches"
  Nth::FloatMethods::inches_to_yards(136.67134, :numeric_long, 16)  #  "3 yards 2 feet 4 11/16 inches"
  Nth::FloatMethods::inches_to_yards(136.67134, :numeric_short, 16) #  "3yd 2ft 4 11/16in"
  
  Nth::FloatMethods::to_dms(-121.9361831121, 4)  # can't display on *md file, but try yourself!

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

I need to control this for the time being.

License

The gem is available as open source under the terms of the MIT License.