collatz 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac3403918c8be4b788fdfab2ec298d657c29eb05437c01652f9dd91387a61290
-  data.tar.gz: 67c1ad526601163e3356d0b2318710ff9e2b7691696e08c511fe71e029d83d16
+  metadata.gz: 189ee8518b71ff1013f294eb8da44f83f7d0dcdcb9409c17a50a215db5cb3b6f
+  data.tar.gz: 3b19474f8148f22e8c0191be3ce6ed530ea1aadd2e4954c33774679ff05da733
 SHA512:
-  metadata.gz: 5987d1636fb13b32ab6f886b4c9223eb747584e43bae7476d5ec69d7ee5515d2d38ff658ccb902690fd87442f6c7ec608c4c02d078feb134a196bd2b43d101fb
-  data.tar.gz: e0ff96c1119cc04ec3cd9c235830436e6b1dabb80b1188b731bd90eee5168d31fb3aedfa136dfdfe3b5e554a0b8afd5c80c9f1c7c81b0727f90ef5c046b01a8b
+  metadata.gz: 36abd5f5f2a213a38dce9f293bef02d19e551499fb82a92a6b9580312efe5031a9dea5443190877eef6e08e077983f8863482b5ca9e23d0fa9eb30c2b997b988
+  data.tar.gz: 32a82e1b51f5eb0dbe9e10655156d86c8ab729dbfeec10c4b5724cc40b7ca6fcfa43551e67f41db0d5bb326ebb848355c5136e72e82cd10551325468c93d08cf

data/.rubocop.yml

@@ -1,10 +1,9 @@
 AllCops:
   TargetRubyVersion: 2.7.0
   UseCache: false
+  SuggestExtensions: false
   # NewCops: enable # would silence the recommendation
   # # to enable new, but would hide which ones were run
-  # SuggestExtensions: false # would silence the tips
-  # # for recommended suggested gems.
 
 Gemspec/DeprecatedAttributeAssignment:
   Enabled: true
@@ -13,6 +12,8 @@ Gemspec/RequireMFA:
 
 Naming/BlockForwarding:
   Enabled: true
+Naming/MethodParameterName:
+  MinNameLength: 1
 
 Security/CompoundHash:
   Enabled: true
@@ -27,9 +28,16 @@ Layout/LineContinuationSpacing:
   Enabled: true
 Layout/LineEndStringConcatenationIndentation:
   Enabled: true
+Layout/SpaceAroundOperators:
+  Enabled: false
 Layout/SpaceBeforeBrackets:
   Enabled: true
 
+Metrics/BlockLength:
+  AllowedMethods: ['describe', 'context']
+Metrics/ParameterLists:
+  Enabled: false
+
 Lint/AmbiguousAssignment:
   Enabled: true
 Lint/AmbiguousOperatorPrecedence:
@@ -136,6 +144,8 @@ Style/NumberedParameters:
   Enabled: true
 Style/NumberedParametersLimit:
   Enabled: true
+Style/NumericLiterals:
+  Enabled: false
 Style/ObjectThen:
   Enabled: true
 Style/OpenStructUse:

data/Gemfile

@@ -7,6 +7,8 @@ gemspec
 
 gem "rake", "~> 13.0"
 
+gem "rdoc", "~> 6.0"
+
 gem "rspec", "~> 3.0"
 
 gem "rubocop", "~> 1.21"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    collatz (0.0.4)
+    collatz (0.1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -12,8 +12,12 @@ GEM
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
+    psych (4.0.5)
+      stringio
     rainbow (3.1.1)
     rake (13.0.6)
+    rdoc (6.4.0)
+      psych (>= 4.0.0)
     regexp_parser (2.5.0)
     rexml (3.2.5)
     rspec (3.11.0)
@@ -42,6 +46,7 @@ GEM
     rubocop-ast (1.21.0)
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
+    stringio (3.0.2)
     unicode-display_width (2.2.0)
 
 PLATFORMS
@@ -50,8 +55,9 @@ PLATFORMS
 DEPENDENCIES
   collatz!
   rake (~> 13.0)
+  rdoc (~> 6.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
 
 BUNDLED WITH
-   2.3.22
+   2.3.21

data/Makefile

@@ -1,4 +1,4 @@
-.PHONY: setup setup_github clean test build install push_rubygems push_github
+.PHONY: setup setup_github clean docs test build install push_rubygems push_github
 SHELL:=/bin/bash
 
 # Assumes `gem install bundler`
@@ -10,11 +10,17 @@ setup_github:
 
 clean:
 	bundle exec rake clean
+	bundle exec rake clobber
 	rm -f collatz-*.gem
 	rm -f pkg/collatz-*.gem
 
+docs: clean
+	bundle exec rake rdoc
+
+# default (just `rake`) is spec + rubocop, but be pedantic in case this changes.
 test: clean
-	bundle exec rake
+	bundle exec rake spec
+	bundle exec rake rubocop
 
 # We can choose from `gem build collatz.gemspec` or `bundle exec rake build`.
 # The gem build command creates a ./collatz-$VER.gem file, and the rake build

data/README.md

@@ -1,20 +1,37 @@
 # [Collatz](https://github.com/Skenvy/Collatz): [Ruby](https://github.com/Skenvy/Collatz/tree/main/ruby) 🔻💎🔻
 Functions related to [the Collatz/Syracuse/3N+1 problem](https://en.wikipedia.org/wiki/Collatz_conjecture), implemented in [Ruby](https://www.ruby-lang.org/).
 ## Getting Started
-[To install the latest from RubyGems](https://rubygems.org/); ([empty search results for collatz](https://rubygems.org/search?query=collatz))
+[To install the latest from RubyGems](https://rubygems.org/gems/collatz);
 ```sh
 gem install collatz
 ```
+[Or to install from GitHub's hosted gems](https://github.com/Skenvy/Collatz/packages/1636643);
+```sh
+gem install collatz --source "https://rubygems.pkg.github.com/skenvy"
+```
+### Add to the Gemfile
+[Add the RubyGems hosted gem](https://rubygems.org/gems/collatz);
+```ruby
+gem "collatz", ">= 0.1.0
+```
+[Add the GitHub hosted gem](https://github.com/Skenvy/Collatz/packages/1636643);
+```ruby
+source "https://rubygems.pkg.github.com/skenvy" do
+  gem "collatz", ">= 0.1.0"
+end
+```
 ## Usage
 Provides the basic functionality to interact with the Collatz conjecture.
 The parameterisation uses the same `(P,a,b)` notation as Conway's generalisations.
 Besides the function and reverse function, there is also functionality to retrieve the hailstone sequence, the "stopping time"/"total stopping time", or tree-graph. 
 The only restriction placed on parameters is that both `P` and `a` can't be `0`.
-## [<lang-docs-name> generated docs](https://skenvy.github.io/Collatz/ruby)
+## [RDoc generated docs](https://skenvy.github.io/Collatz/ruby)
 ## Developing
 ### The first time setup
 ```sh
-git clone https://github.com/Skenvy/Collatz.git && cd Collatz/ruby && <localised-setup-command>
+git clone https://github.com/Skenvy/Collatz.git && cd Collatz/ruby && make setup
 ```
 ### Iterative development
-* <list-worthwhile-recipes>
+The majority of `make` recipes for this are just wrapping a `bundle` invocation of `rake`.
+* `make docs` will recreate the RDoc docs
+* `make test` will run both the RSpec tests and the RuboCop linter.

data/Rakefile

@@ -10,3 +10,26 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+# The below recommended way to add rdoc to rake from rdoc's site has a lot of
+# things it will compain about, and wont work OotB, so use 'rdoc/task' below.
+# require 'rdoc/rdoc'
+# options = RDoc::Options.new
+# # see RDoc::Options
+# options.rdoc_include << ["lib/*.rb"]
+# rdoc = RDoc::RDoc.new
+# rdoc.document options
+# # see RDoc::RDoc
+
+# https://ruby.github.io/rdoc/RDocTask.html
+# doc is the default output location of the rdoc binary, and is the location
+# added in the standard ruby gitignore, but the rake task defaults to ./html
+# and we need to use the rdoc_dir option to change it to doc.
+
+require "rdoc/task"
+
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.main = "README.md" # !? README.rdoc ?!
+  rdoc.rdoc_files.include("README.md", "lib/*.rb")
+end

data/collatz.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   Besides the function and reverse function, there is also functionality to retrieve
   the hailstone sequence, the \"stopping time\"/\"total stopping time\", or tree-graph.
   The only restriction placed on parameters is that both P and a can't be 0."
-  spec.homepage = "https://github.com/Skenvy/Collatz/tree/main/ruby"
+  spec.homepage = "https://skenvy.github.io/Collatz/ruby/"
   spec.required_ruby_version = ">= 2.7.0"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/Skenvy/Collatz/tree/main/ruby"

data/devlog.md

@@ -53,3 +53,30 @@ While the [GitHub: Working with the RubyGems registry](https://docs.github.com/e
 :github: Bearer <PAT|TOKEN>
 ```
 We can `base64 ~/.gem/credentials` the rubygems_api_key we got from the `gem signin`, add the string (without the newlines) to our github secrets, and then do something like `echo -n "$RUBYGEMS_API_KEY_BASE64" | base64 --decode > ~/.gem/credentials` to recreate the credentials. GitHub's credentials should be passable with a `echo -e "---\n:github: Bearer <PAT|TOKEN>" > ~/.gem/credentials`.
+
+With that now merged we can work on adding the functionality and setting up documentation. The two main choices for documentation generation appear to be [rdoc](https://github.com/ruby/rdoc) or [yard](https://yardoc.org/). Yard looks alright, but we're trying to stick to any "official" way of doing something, and with rdoc being put out by ruby, we'll start off with rdoc. We can [`bundle add rdoc --version "~> 6.0" --verbose`](https://bundler.io/man/bundle-add.1.html), but doing this just leads to it permanently hanging on a ""HTTP GET https://index.rubygems.org/versions" immediately after a "HTTP 416 Range Not Satisfiable https://index.rubygems.org/versions". There's quite a few hits for this or similar issues cropping up, but none with a definitive answer or cause, and none that worked to fix the issue here. It took a 20 minute wait for it to finally do anything, then kept asking for my sudo password and refusing to accept it. I retried and it succeeded much quicker, although still took 4 entries of my password to get it to successfully pass and hit that "Bundle complete! 5 Gemfile dependencies, 23 gems now installed". Following the [rdoc](https://github.com/ruby/rdoc) guide to add rdoc to the rakefile leads to a ``rake aborted! NoMethodError: undefined method `delete_if' for nil:NilClass`` which could be connected to [this issue](https://github.com/ruby/rdoc/issues/352), namely ["You haven't told RDoc to document any files"](https://github.com/ruby/rdoc/issues/352#issuecomment-110185993). We can avoid this issue if we use the [rdoc task](https://ruby.github.io/rdoc/RDocTask.html) instead.
+
+As we start to add the first few lines to the main rb file, we've run into yet another rubocop yelling about something inconsequential (Style/NumericLiterals isn't even listed in our rubocop yaml, so we'll have to add it to disable it);
+```
+lib/collatz.rb:19:20: C: [Correctable] Style/NumericLiterals: Use underscores(_) as thousands separator and separate every 3 digits with them.
+VERIFIED_MAXIMUM = 295147905179352825856
+                   ^^^^^^^^^^^^^^^^^^^^^
+```
+We'll also have to add the cop `Naming/MethodParameterName: MinNameLength: 1` to stop it from complaining about all our uses of `"P"`, `"a"`, and `"b"`. Also worth mentioning is that, unlike other implementations, in ruby we can't use a capital letter to start a non-constant value, so we have to swap all capital `"P"` for lowercase `"p"`'s, lest we get the `"Formal argument cannot be a constant"` error. I'm also cautious of `Style/RedundantReturn` -- I'd like to try and stick to the normal ruby style, but it relies on the novel awareness that the last line of a function without an explicit return is returned. I'll have to simply remember that for later. Another cop is complaining about `Lint/AmbiguousOperatorPrecedence: Wrap expressions with varying precedence with parentheses to avoid ambiguity.`, which seems absurd. After fixing some of these, my line `if n%p == 0 then n/p else ((a*n)+b) end` is still generating the following errors;
+```
+lib/collatz.rb:96:3: C: [Correctable] Style/OneLineConditional: Favor the ternary operator (?:) or multi-line constructs over single-line if/then/else/end constructs.
+  if n%p == 0 then n/p else ((a*n)+b) end
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+lib/collatz.rb:96:6: C: [Correctable] Style/NumericPredicate: Use (n%p).zero? instead of n%p == 0.
+  if n%p == 0 then n/p else ((a*n)+b) end
+     ^^^^^^^^
+```
+Rubocop is happy if we replace it with `(n%p).zero? ? (n/p) : ((a*n)+b)`, which feels so much less readable, and absurd than anyone would consider that more "readable" than the verbose `if/then/else/end`. Another odd ambiguity is that an error can be raised either with `raise StandardError, 'message'` or `raise StandardError.new('message')` or `raise StandardError.new 'message'`, but the `Style/RaiseArgs` cop has a preference for `raise StandardError, 'message'`. Now we just have to configure the `Metrics/BlockLength` cop which doesn't like all the lines in the spec test. A good suggestion is to set `IgnoredMethods: ['describe', 'context']` according to the docs, which does silence the error, but now returns ``Warning: obsolete parameter `IgnoredMethods` (for `Metrics/BlockLength`) found in .rubocop.yml `IgnoredMethods` has been renamed to `AllowedMethods` and/or `AllowedPatterns`.``. So why are they not mentioned as such on the [rubocop docs](https://docs.rubocop.org/rubocop/cops_metrics.html#metricsblocklength). It feels like a lot of the problems we've run into so far with ruby have been the same as those with go, where it's been historically developed at a pace greater than which it is then adopted, leading to a fragmented ecosystem, although not as badly as it is in go, with solutions to circumvent the at times antithetical expectations easier to find than they were for go. Although a large portion of these issues have been with rubocop. It might be useful, but it adds a lot of noise that needs to be hushed while trying to learn ruby for the first time, even if its suggestions might be temporarily useful. I will say though that setting up the gem deployment was much easier than the maven deployment for java, so all in all it's not too much of a hassle.
+
+The last thing worth mentioning before trying to release 0.1.0 with the function and reverse function, is that there seems to be a bit of a difference in how to provide "kwargs" than in python. In python kwargs are listed as `some_arg_name = some_default_value`, and can then be referenced by name in the function invocation, or supplied positionally, and without specifying a `**kwargs` to splatter additionl inputs, any name supplied that is not specified as an input will cause an error. In ruby, kwargs are listed as `some_arg_name: some_default_value`, and like python, an error will be thrown if a named kwarg is provided on invocation that isn't specified in the function inputs, however it **can only** be supplied to the invocation per its keyword name, it can't be supplied positionally. Meanwhile, "optional" args in ruby that are specified in the function inputs via `some_arg_name = some_default_value` aren't kwargs, but rather positional args that happen to have default values; they can't be supplied to a function invocation by name, only by position, and a quirk of testing how to assign them to learn the difference between ruby and python demonstrates that while specifying `**kwargs` to splatter inputs in python means parameters can be supplied to the invocation by name that weren't specified in the input, attempting to see how "optional args" affect splattering in ruby leads to a false positive of demonstrating something akin to, but not exactly splattering. That is, if some `some_other_arg_name = some_other_value` is supplied to a function invocation in ruby as the input to an "optional arg", this is not splatting the differently named inputs, rather, it is assigning the value to the name as a variable, and providing that value as the input to the positional optional args. So to achieve true "kwargs" in ruby, we need to use `some_arg_name: some_default_value`, and specify them by name in the invocations.
+
+We're now ready to add once again create an empty orphan branch;
+1. `git checkout --orphan gh-pages-ruby`
+1. `rm .git/index ; git clean -fdx`
+1. `git commit -m "Initial empty orphan" --allow-empty`
+1. `git push --set-upstream origin gh-pages-ruby`

data/lib/collatz/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Collatz
-  VERSION = "0.0.4"
+  VERSION = "0.1.0"
 end

data/lib/collatz.rb

@@ -2,7 +2,236 @@
 
 require_relative "collatz/version"
 
-module Collatz
-  class Error < StandardError; end
-  # Your code goes here...
+# :section: Main
+# Provides the basic functionality to interact with the Collatz conjecture. The
+# parameterisation uses the same (p,a,b) notation as Conway's generalisations.
+# Besides the function and reverse function, there is also functionality to
+# retrieve the hailstone sequence, the "stopping time"/"total stopping time", or
+# tree-graph.
+
+# The four known cycles for the standard parameterisation.
+KNOWN_CYCLES = [
+  [1, 4, 2].freeze, [-1, -2].freeze, [-5, -14, -7, -20, -10].freeze,
+  [-17, -50, -25, -74, -37, -110, -55, -164, -82, -41, -122, -61, -182, -91, -272, -136, -68, -34].freeze
+].freeze
+# The current value up to which the standard parameterisation has been verified.
+VERIFIED_MAXIMUM = 295147905179352825856
+# The current value down to which the standard parameterisation has been verified.
+VERIFIED_MINIMUM = -272 # TODO: Check the actual lowest bound.
+
+# Error message constants, to be used as input to the FailedSaneParameterCheck.
+module SaneParameterErrMsg
+  # Message to print in the FailedSaneParameterCheck if p, the modulus, is zero.
+  SANE_PARAMS_P = "'p' should not be 0 ~ violates modulo being non-zero."
+  # Message to print in the FailedSaneParameterCheck if a, the multiplicand, is zero.
+  SANE_PARAMS_A = "'a' should not be 0 ~ violates the reversability."
+end
+
+# Thrown when either p, the modulus, or a, the multiplicand, are zero.
+class FailedSaneParameterCheck < StandardError
+  # Construct a FailedSaneParameterCheck with a message associated with the provided enum.
+  # @param [String] msg One of the SaneParameterErrMsg strings.
+  def initialize(msg = "This is a custom exception", exception_type = "FailedSaneParameterCheck")
+    @exception_type = exception_type
+    super(msg)
+  end
+end
+
+# SequenceState for Cycle Control: Descriptive flags to indicate when some event occurs in the
+# hailstone sequences or tree graph reversal, when set to verbose, or stopping time check.
+module SequenceState
+  # A Hailstone sequence state that indicates the stopping
+  # time, a value less than the initial, has been reached.
+  STOPPING_TIME = "STOPPING_TIME"
+  # A Hailstone sequence state that indicates the total
+  # stopping time, a value of 1, has been reached.
+  TOTAL_STOPPING_TIME = "TOTAL_STOPPING_TIME"
+  # A Hailstone and TreeGraph sequence state that indicates the
+  # first occurence of a value that subsequently forms a cycle.
+  CYCLE_INIT = "CYCLE_INIT"
+  # A Hailstone and TreeGraph sequence state that indicates the
+  # last occurence of a value that has already formed a cycle.
+  CYCLE_LENGTH = "CYCLE_LENGTH"
+  # A Hailstone and TreeGraph sequence state that indicates the sequence
+  # or traversal has executed some imposed 'maximum' amount of times.
+  MAX_STOP_OUT_OF_BOUNDS = "MAX_STOP_OUT_OF_BOUNDS"
+  # A Hailstone sequence state that indicates the sequence terminated
+  # by reaching "0", a special type of "stopping time".
+  ZERO_STOP = "ZERO_STOP"
+end
+
+# Handles the sanity check for the parameterisation (p,a,b)
+# required by both the function and reverse function.
+#
+# @raise [FailedSaneParameterCheck] If p or a are 0.
+#
+# @param [Integer] p Modulus used to devide n, iff n is equivalent to (0 mod p)
+# @param [Integer] a Factor by which to multiply n.
+# @param [Integer] b Value to add to the scaled value of n.
+def assert_sane_parameterisation(p, a, _b)
+  # Sanity check (p,a,b) ~ p absolutely can't be 0. a "could" be zero
+  # theoretically, although would violate the reversability (if ~a is 0 then a
+  # value of "b" as the input to the reverse function would have a pre-emptive
+  # value of every number not divisible by p). The function doesn't _have_ to
+  # be reversable, but we are only interested in dealing with the class of
+  # functions that exhibit behaviour consistant with the collatz function. If
+  # _every_ input not divisable by p went straight to "b", it would simply
+  # cause a cycle consisting of "b" and every b/p^z that is an integer. While
+  # p in [-1, 1] could also be a reasonable check, as it makes every value
+  # either a 1 or 2 length cycle, it's not strictly an illegal operation.
+  # "b" being zero would cause behaviour not consistant with the collatz
+  # function, but would not violate the reversability, so no check either.
+  # " != 0" is redundant for python assertions.
+  raise FailedSaneParameterCheck, SaneParameterErrMsg::SANE_PARAMS_P unless p != 0
+  raise FailedSaneParameterCheck, SaneParameterErrMsg::SANE_PARAMS_A unless a != 0
+end
+
+private :assert_sane_parameterisation
+
+# Returns the output of a single application of a Collatz-esque function.
+#
+# @raise [FailedSaneParameterCheck] If p or a are 0.
+#
+# @param [Integer] n The value on which to perform the Collatz-esque function.
+# @param [Integer] p Modulus used to devide n, iff n is equivalent to (0 mod p).
+# @param [Integer] a Factor by which to multiply n.
+# @param [Integer] b Value to add to the scaled value of n.
+#
+# @return [Integer] The result of the function
+def function(n, p: 2, a: 3, b: 1)
+  assert_sane_parameterisation(p, a, b)
+  (n%p).zero? ? (n/p) : ((a*n)+b)
+end
+
+# Returns the output of a single application of a Collatz-esque reverse function. If
+# only one value is returned, it is the value that would be divided by p. If two values
+# are returned, the first is the value that would be divided by p, and the second value
+# is that which would undergo the multiply and add step, regardless of which is larger.
+#
+# @raise [FailedSaneParameterCheck] If p or a are 0.
+#
+# @param [Integer] n The value on which to perform the reverse Collatz function.
+# @param [Integer] p Modulus used to devide n, iff n is equivalent to (0 mod p).
+# @param [Integer] a Factor by which to multiply n.
+# @param [Integer] b Value to add to the scaled value of n.
+#
+# @return [Integer] The values that would return the input if given to the function.
+def reverse_function(n, p: 2, a: 3, b: 1)
+  assert_sane_parameterisation(p, a, b)
+  pre_values = [p*n]
+  pre_values += [(n-b)/a] if ((n-b)%a).zero? && !((n-b)%(p*a)).zero?
+  pre_values
+end
+
+# Provides the appropriate lambda to use to check if iterations on an initial
+# value have reached either the stopping time, or total stopping time.
+# @param [Integer] n The initial value to confirm against a stopping time check.
+# @param [Boolean] total_stop If false, the lambda will confirm that iterations of n
+#     have reached the oriented stopping time to reach a value closer to 0.
+#     If true, the lambda will simply check equality to 1.
+# @return [Method(Integer)->(Boolean)] The lambda to check for the stopping time.
+def stopping_time_terminus(n, total_stop)
+  raise NotImplementedError, "Will be implemented at, or before, v1.0.0"
+end
+
+private :stopping_time_terminus
+
+# Contains the results of computing a hailstone sequence via hailstone_sequence(~).
+class HailstoneSequence
+  def initialize
+    raise NotImplementedError, "Will be implemented at, or before, v1.0.0"
+  end
+end
+
+# Returns a list of successive values obtained by iterating a Collatz-esque
+# function, until either 1 is reached, or the total amount of iterations
+# exceeds max_total_stopping_time, unless total_stopping_time is False,
+# which will terminate the hailstone at the "stopping time" value, i.e. the
+# first value less than the initial value. While the sequence has the
+# capability to determine that it has encountered a cycle, the cycle from "1"
+# wont be attempted or reported as part of a cycle, regardless of default or
+# custom parameterisation, as "1" is considered a "total stop".
+#
+# @raise [FailedSaneParameterCheck] If p or a are 0.
+#
+# @param [Integer] initial_value The value to begin the hailstone sequence from.
+# @param [Integer] p Modulus used to devide n, iff n is equivalent to (0 mod p).
+# @param [Integer] a Factor by which to multiply n.
+# @param [Integer] b Value to add to the scaled value of n.
+# @param [Integer] max_total_stopping_time Maximum amount of times to iterate the function, if 1 is not reached.
+# @param [Boolean] total_stopping_time Whether or not to execute until the "total" stopping time
+#     (number of iterations to obtain 1) rather than the regular stopping time (number
+#     of iterations to reach a value less than the initial value).
+#
+# @return [HailstoneSequence] A set of values that form the hailstone sequence.
+def hailstone_sequence(initial_value, p: 2, a: 3, b: 1, max_total_stopping_time: 1000, total_stopping_time: true)
+  raise NotImplementedError, "Will be implemented at, or before, v1.0.0"
+end
+
+# Returns the stopping time, the amount of iterations required to reach a
+# value less than the initial value, or nil if max_stopping_time is exceeded.
+# Alternatively, if total_stopping_time is True, then it will instead count
+# the amount of iterations to reach 1. If the sequence does not stop, but
+# instead ends in a cycle, the result will be infinity.
+# If (p,a,b) are such that it is possible to get stuck on zero, the result
+# will be the negative of what would otherwise be the "total stopping time"
+# to reach 1, where 0 is considered a "total stop" that should not occur as
+# it does form a cycle of length 1.
+#
+# @raise [FailedSaneParameterCheck] If p or a are 0.
+#
+# @param [Integer] initial_value The value for which to find the stopping time.
+# @param [Integer] p Modulus used to devide n, iff n is equivalent to (0 mod p).
+# @param [Integer] a Factor by which to multiply n.
+# @param [Integer] b Value to add to the scaled value of n.
+# @param [Integer] max_stopping_time Maximum amount of times to iterate the function, if
+#     the stopping time is not reached. IF the max_stopping_time is reached,
+#     the function will return nil.
+# @param [Boolean] total_stopping_time Whether or not to execute until the "total" stopping
+#     time (number of iterations to obtain 1) rather than the regular stopping
+#     time (number of iterations to reach a value less than the initial value).
+#
+# @return [Integer] The stopping time, or, in a special case, infinity, nil or a negative.
+def stopping_time(initial_value, p: 2, a: 3, b: 1, max_stopping_time: 1000, total_stopping_time: false)
+  raise NotImplementedError, "Will be implemented at, or before, v1.0.0"
+end
+
+# Nodes that form a "tree graph", structured as a tree, with their own node's value,
+# as well as references to either possible child node, where a node can only ever have
+# two children, as there are only ever two reverse values. Also records any possible
+# "terminal sequence state", whether that be that the "orbit distance" has been reached,
+# as an "out of bounds" stop, which is the regularly expected terminal state. Other
+# terminal states possible however include the cycle state and cycle length (end) states.
+class TreeGraphNode
+  def initialize
+    raise NotImplementedError, "Will be implemented at, or before, v1.0.0"
+  end
+end
+
+# Contains the results of computing the Tree Graph via tree_graph(~).
+# Contains the root node of a tree of TreeGraphNode's.
+class TreeGraph
+  def initialize
+    raise NotImplementedError, "Will be implemented at, or before, v1.0.0"
+  end
+end
+
+# Returns a directed tree graph of the reverse function values up to a maximum
+# nesting of max_orbit_distance, with the initial_value as the root.
+#
+# @raise [FailedSaneParameterCheck] If p or a are 0.
+#
+# @param [Integer] initial_value The root value of the directed tree graph.
+# @param [Integer] max_orbit_distance Maximum amount of times to iterate the reverse
+#     function. There is no natural termination to populating the tree graph, equivalent
+#     to the termination of hailstone sequences or stopping time attempts, so this is not
+#     an optional argument like max_stopping_time / max_total_stopping_time, as it is the intended
+#     target of orbits to obtain, rather than a limit to avoid uncapped computation.
+# @param [Integer] p Modulus used to devide n, iff n is equivalent to (0 mod p).
+# @param [Integer] a Factor by which to multiply n.
+# @param [Integer] b Value to add to the scaled value of n.
+#
+# @return [TreeGraph] The branches of the tree graph as determined by the reverse function.
+def tree_graph(initial_value, max_orbit_distance, p: 2, a: 3, b: 1, __cycle_prevention: nil)
+  raise NotImplementedError, "Will be implemented at, or before, v1.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: collatz
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Nathan Levett
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-14 00:00:00.000000000 Z
+date: 2022-09-21 00:00:00.000000000 Z
 dependencies: []
 description: |-
   Provides the basic functionality to interact with the Collatz conjecture.
@@ -35,14 +35,13 @@ files:
 - devlog.md
 - lib/collatz.rb
 - lib/collatz/version.rb
-- sig/collatz.rbs
-homepage: https://github.com/Skenvy/Collatz/tree/main/ruby
+homepage: https://skenvy.github.io/Collatz/ruby/
 licenses:
 - Apache-2.0
 metadata:
-  homepage_uri: https://github.com/Skenvy/Collatz/tree/main/ruby
+  homepage_uri: https://skenvy.github.io/Collatz/ruby/
   source_code_uri: https://github.com/Skenvy/Collatz/tree/main/ruby
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -58,7 +57,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.6
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Functions Related to the Collatz/Syracuse/3n+1 Problem
 test_files: []

data/sig/collatz.rbs

@@ -1,4 +0,0 @@
-module Collatz
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end