collatz 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 189ee8518b71ff1013f294eb8da44f83f7d0dcdcb9409c17a50a215db5cb3b6f
-  data.tar.gz: 3b19474f8148f22e8c0191be3ce6ed530ea1aadd2e4954c33774679ff05da733
+  metadata.gz: 30d4085b4e190a4e1aaf4fdd5f4108abb26688c8223bc1725091d6976b257252
+  data.tar.gz: 3467c2848b02d28909455f092759a8cad3e67eba18583c3873e2bf74c456b11c
 SHA512:
-  metadata.gz: 36abd5f5f2a213a38dce9f293bef02d19e551499fb82a92a6b9580312efe5031a9dea5443190877eef6e08e077983f8863482b5ca9e23d0fa9eb30c2b997b988
-  data.tar.gz: 32a82e1b51f5eb0dbe9e10655156d86c8ab729dbfeec10c4b5724cc40b7ca6fcfa43551e67f41db0d5bb326ebb848355c5136e72e82cd10551325468c93d08cf
+  metadata.gz: 9e6d2e859b8cc330406d54989b4a01ee1e83d7e7da1ffad2d66b78eb588aa19e8bcd7b504bd4aeb8320710ae69eb1e2f9d6762a33a5b9b8532a2a91e0190e5f4
+  data.tar.gz: df4b8fa5f25bbc86664ea45d012db4deb07c1197c8addb5fb2f8cb3c22354a89e1612a3b0eb362c8c3bacf2c9b8792a4ba7f746fb40d43ba30066b4aebcd20d8

data/.rubocop.yml

@@ -20,6 +20,8 @@ Security/CompoundHash:
 Security/IoMethods:
   Enabled: true
 
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
 Layout/LineLength:
   Max: 120
 Layout/LineContinuationLeadingSpace:
@@ -28,15 +30,27 @@ Layout/LineContinuationSpacing:
   Enabled: true
 Layout/LineEndStringConcatenationIndentation:
   Enabled: true
+Layout/MultilineHashBraceLayout:
+  Enabled: false
 Layout/SpaceAroundOperators:
   Enabled: false
 Layout/SpaceBeforeBrackets:
   Enabled: true
 
+Metrics/AbcSize:
+  Enabled: false
 Metrics/BlockLength:
   AllowedMethods: ['describe', 'context']
+Metrics/BlockNesting:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
 Metrics/ParameterLists:
   Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
 
 Lint/AmbiguousAssignment:
   Enabled: true
@@ -100,10 +114,15 @@ Style/StringLiterals:
 Style/StringLiteralsInInterpolation:
   Enabled: true
   EnforcedStyle: double_quotes
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+  AllowModifiersOnSymbols: false
 Style/ArgumentsForwarding:
   Enabled: true
 Style/CollectionCompact:
   Enabled: true
+Style/ConditionalAssignment:
+  Enabled: false
 Style/DocumentDynamicEvalDefinition:
   Enabled: true
 Style/EmptyHeredoc:
@@ -118,6 +137,8 @@ Style/FileRead:
   Enabled: true
 Style/FileWrite:
   Enabled: true
+Style/For:
+  Enabled: false
 Style/HashConversion:
   Enabled: true
 Style/HashExcept:
@@ -126,6 +147,8 @@ Style/IfWithBooleanLiteralBranches:
   Enabled: true
 Style/InPatternThen:
   Enabled: true
+Style/Lambda:
+  EnforcedStyle: lambda
 Style/MagicCommentFormat:
   Enabled: true
 Style/MapCompactWithConditionalBlock:
@@ -138,6 +161,8 @@ Style/NegatedIfElseCondition:
   Enabled: true
 Style/NestedFileDirname:
   Enabled: true
+Style/Next:
+  Enabled: false
 Style/NilLambda:
   Enabled: true
 Style/NumberedParameters:
@@ -156,6 +181,8 @@ Style/RedundantArgument:
   Enabled: true
 Style/RedundantInitialize:
   Enabled: true
+Style/RedundantSelf:
+  Enabled: false
 Style/RedundantSelfAssignmentBranch:
   Enabled: true
 Style/SelectByRegexp:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    collatz (0.1.0)
+    collatz (1.0.0)
 
 GEM
   remote: https://rubygems.org/
@@ -60,4 +60,4 @@ DEPENDENCIES
   rubocop (~> 1.21)
 
 BUNDLED WITH
-   2.3.21
+   2.3.22

data/Rakefile

@@ -31,5 +31,5 @@ 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")
+  rdoc.rdoc_files.include("README.md", "lib/*.rb", "lib/collatz/*.rb")
 end

data/devlog.md

@@ -80,3 +80,61 @@ We're now ready to add once again create an empty orphan branch;
 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`
+
+Well, v0.1.0 has been released, with the function and reverse function. The ruby discord has been very helpful, and has a "Community: code review" channel dedicated for requests for feedback on code samples, so I've asked on there for a review, and gotten some feedback! I want to try and make it more ruby-esque before working on the hailstone and tree graph functions, so that they are made right from the start. The feedback is as thus;
+1. It's odd to have all the code in the central `~/collatz.rb` file with a separate `~/collatz/version.rb`, with the suggestion seeming to be to either do away with having a subfolder that contains `example.rb` files that are then included in the main file via `require_relative "collatz/example"`, or move all the contents of the main file into other `*.rb` files that are then required into the main file. The version file was part of what was auto generated by bundler, and I like having the version on its own in its own file, as it makes setting the version file, and reading the version from it in the workflow, much easier.
+1. The next piece of feedback, and something I wondered why bundler didn't do from the beginning honestly, is to put _**everything**_ inside a `Collatz` module. I assumed when I first saw that this wasn't done automatically by bundler that the contents of a gem that would then be required into a script would set up the namespace similar to python, and disregarded the fact that it appeared not to do that while setting up the RSpec tests. So moving everything into a top level module to unclobber the "public"`?` namespace.
+1. Change `unless p != 0` to `if p.zero?`. I vaguely recall trying something along the lines of inline conditionals when first setting that up, and thought a rubocop had complained about it _not_ being an "unless" clause, but it might have been some other part of the inlining of the conditional, so will definitely try this change, as it certainly is much more readable.
+1. In the `reverse_function` rather than do a `pre_values +=`, use the array's `.push` method. Although another user suggest using `<<` instead? It was finally suggested to instead just settle for a multi line if, which isn't _not_ a reasonable suggestion, even if my preference happens to be for flatter lines. It was also made apparent that similar to the `.zero?` function, there is a `.nonzero?` function that can be used instead of the negated assertion of `.zero?`.
+1. Instead of setting methods to private with `private :stopping_time_terminus` following the method declaration, simply add `private` before the def (e.g. `private def stopping_time_terminus`). A few sites indicated the same concern another user noted that doing so would make all the methods declared after it also private, however this concern was dissuaded with the assurance that it would not behave that way, instead asserting that the `def something` would return a `Symbol`, which would make `private def something` the same as subsequently passing the symbol of the method to the private modifier.
+1. The abuse of `NotImplementedError`, which is meant to be ruby internal only, was mentioned. I was aware of this ahead of time, and probably could have done without adding the function headers before implementing them.
+1. On the `KNOWN_CYCLES`, rather than apply the `.freeze` to all elements in the list individually, set `.each(&:freeze).freeze` on the final outer closing bracket `]` of the whole list.
+
+I've fixed most of the above, although some aren't operable at the moment. Setting methods private via `private def method_name` instead of `private :method_name` after the method declaration is causing rubocop to break. I'll get an error message `An error occurred while Style/AccessModifierDeclarations cop was inspecting /mnt/c/Workspaces/GitHub_Skenvy/Collatz/ruby/lib/collatz.rb:71:0.` for both lines, which is then followed by this stack trace.
+```
+uninitialized constant RuboCop::Version::Server
+Did you mean?  TCPServer
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/version.rb:22:in `version'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:82:in `display_error_summary'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:58:in `display_summary'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:27:in `block in execute_runner'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:52:in `with_redirect'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:25:in `execute_runner'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command/execute_runner.rb:17:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/command.rb:11:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli/environment.rb:18:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli.rb:72:in `run_command'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli.rb:79:in `execute_runners'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/cli.rb:48:in `run'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/rake_task.rb:51:in `run_cli'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/rake_task.rb:26:in `block (2 levels) in initialize'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/file_utils_ext.rb:58:in `verbose'
+/var/lib/gems/2.7.0/gems/rubocop-1.36.0/lib/rubocop/rake_task.rb:24:in `block in initialize'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:281:in `block in execute'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:281:in `each'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:281:in `execute'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:219:in `block in invoke_with_call_chain'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:199:in `synchronize'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:199:in `invoke_with_call_chain'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/task.rb:188:in `invoke'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:160:in `invoke_task'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:116:in `block (2 levels) in top_level'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:116:in `each'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:116:in `block in top_level'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:125:in `run_with_threads'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:110:in `top_level'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:83:in `block in run'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:186:in `standard_exception_handling'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/lib/rake/application.rb:80:in `run'
+/var/lib/gems/2.7.0/gems/rake-13.0.6/exe/rake:27:in `<top (required)>'
+/usr/local/bin/rake:23:in `load'
+/usr/local/bin/rake:23:in `<main>'
+RuboCop failed!
+```
+It appears though that this error may have already had a bug raised and fixed at [rubocop/issues/10994](https://github.com/rubocop/rubocop/issues/10994). It appears in the meantime however that the `Style/AccessModifierDeclarations` cop isn't working as intended. Setting the below does not cause it to error on the `private :method_name` after the method declaration, which is what `AllowModifiersOnSymbols: false` is supposed to disallow.
+```yaml
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+  AllowModifiersOnSymbols: false
+```
+Even though it is not causing it to throw a cop error on the modifier on symbol pattern `private :method_name`, having the above config _is_ preventing it from throwing the hard error above `uninitialized constant RuboCop::Version::Server` that stopped the whole rubocop process, and indeed it passes with `no offenses detected`.

data/lib/collatz/constants.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Collatz
+  # The four known cycles for the standard parameterisation.
+  KNOWN_CYCLES = [
+    [1, 4, 2], [-1, -2], [-5, -14, -7, -20, -10],
+    [-17, -50, -25, -74, -37, -110, -55, -164, -82, -41, -122, -61, -182, -91, -272, -136, -68, -34]
+  ].each(&: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.
+end

data/lib/collatz/function.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "utilities"
+
+module Collatz # rubocop:disable Style/Documentation
+  module_function # rubocop:disable Style/AccessModifierDeclarations
+
+  # 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.
+  private def assert_sane_parameterisation(p, a, _b) # :nodoc:
+    # 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 if p.zero?
+    raise FailedSaneParameterCheck, SaneParameterErrMsg::SANE_PARAMS_A if a.zero?
+  end
+
+  # 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 +List<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)
+    if ((n-b)%a).zero? && ((n-b)%(p*a)).nonzero?
+      [p*n, (n-b)/a]
+    else
+      [p*n]
+    end
+  end
+end

data/lib/collatz/hailstone_sequence.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require_relative "utilities"
+require_relative "function"
+
+module Collatz # rubocop:disable Style/Documentation
+  # Contains the results of computing a hailstone sequence via hailstone_sequence(~).
+  class HailstoneSequence
+    # The set of values that comprise the hailstone sequence.
+    attr_reader :values
+
+    # A terminal condition that reflects the final state of the hailstone sequencing,
+    # whether than be that it succeeded at determining the stopping time, the total
+    # stopping time, found a cycle, or got stuck on zero (or surpassed the max total).
+    attr_reader :terminal_condition # SequenceState
+
+    # A status value that has different meanings depending on what the terminal condition
+    # was. If the sequence completed either via reaching the stopping or total stopping time,
+    # or getting stuck on zero, then this value is the stopping/terminal time. If the sequence
+    # got stuck on a cycle, then this value is the cycle length. If the sequencing passes the
+    # maximum stopping time then this is the value that was provided as that maximum.
+    attr_reader :terminal_status
+
+    # Initialise and compute a new Hailstone Sequence.
+    #
+    # @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 An initialised, and computed, hailstone sequence
+    def initialize(initial_value, p, a, b, max_total_stopping_time, total_stopping_time)
+      terminate = stopping_time_terminus(initial_value, total_stopping_time)
+      if initial_value.zero?
+        # 0 is always an immediate stop.
+        @values = [0]
+        @terminal_condition = SequenceState::ZERO_STOP
+        @terminal_status = 0
+      elsif initial_value == 1
+        # 1 is always an immediate stop, with 0 stopping time.
+        @values = [1]
+        @terminal_condition = SequenceState::TOTAL_STOPPING_TIME
+        @terminal_status = 0
+      else
+        # Otherwise, hail!
+        min_max_total_stopping_time = [max_total_stopping_time, 1].max
+        pre_values = Array.new(min_max_total_stopping_time+1)
+        pre_values[0] = initial_value
+        for k in 1..min_max_total_stopping_time do
+          next_value = Collatz.function(pre_values[k-1], p: p, a: a, b: b)
+          # Check if the next_value hailstone is either the stopping time, total
+          # stopping time, the same as the initial value, or stuck at zero.
+          if terminate.call(next_value)
+            pre_values[k] = next_value
+            if next_value == 1
+              @terminal_condition = SequenceState::TOTAL_STOPPING_TIME
+            else
+              @terminal_condition = SequenceState::STOPPING_TIME
+            end
+            @terminal_status = k
+            @values = pre_values.slice(0, k+1)
+            return
+          end
+          if pre_values.include? next_value
+            pre_values[k] = next_value
+            cycle_init = 1
+            for j in 1..k do
+              if pre_values[k-j] == next_value
+                cycle_init = j
+                break
+              end
+            end
+            @terminal_condition = SequenceState::CYCLE_LENGTH
+            @terminal_status = cycle_init
+            @values = pre_values.slice(0, k+1)
+            return
+          end
+          if next_value.zero?
+            pre_values[k] = 0
+            @terminal_condition = SequenceState::ZERO_STOP
+            @terminal_status = -k
+            @values = pre_values.slice(0, k+1)
+            return
+          end
+          pre_values[k] = next_value
+        end
+        @terminal_condition = SequenceState::MAX_STOP_OUT_OF_BOUNDS
+        @terminal_status = min_max_total_stopping_time
+        @values = pre_values
+      end
+    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 +lambda<Integer>:<Boolean>+ The lambda to check for the stopping time.
+    private def stopping_time_terminus(n, total_stop)
+      if total_stop
+        lambda { |x| x == 1 }
+      elsif n >= 0
+        lambda { |x| (x < n && x.positive?) }
+      else
+        lambda { |x| (x > n && x.negative?) }
+      end
+    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.
+  module_function def hailstone_sequence(initial_value, p: 2, a: 3, b: 1, max_total_stopping_time: 1000, total_stopping_time: true) # rubocop:disable Layout/LineLength
+    # Prior to starting the hailstone, which has some magic case handling,
+    # call the function to trigger any assert_sane_parameterisation flags.
+    _throwaway = function(initial_value, p: p, a: a, b: b)
+    # Return the hailstone sequence.
+    HailstoneSequence.new(initial_value, p, a, b, max_total_stopping_time, total_stopping_time)
+  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.
+  module_function def stopping_time(initial_value, p: 2, a: 3, b: 1, max_stopping_time: 1000, total_stopping_time: false) # rubocop:disable Layout/LineLength
+    # Although the "max_~_time" for hailstones is named for "total stopping" time
+    # and the "max_~_time" for this "stopping time" function is _not_ "total",
+    # they are handled the same way, as the default for "total_stopping_time"
+    # for hailstones is true, but for this, is false. Thus the naming difference.
+    # rubocop:disable Layout/HashAlignment
+    hail = hailstone_sequence(initial_value, p: p, a: a, b: b,
+                              max_total_stopping_time: max_stopping_time,
+                              total_stopping_time: total_stopping_time)
+    # rubocop:enable Layout/HashAlignment
+    # For total/regular/zero stopping time, the value is already the same as
+    # that present, for cycles we report infinity instead of the cycle length,
+    # and for max stop out of bounds, we report None instead of the max stop cap
+    { SequenceState::TOTAL_STOPPING_TIME => hail.terminal_status,
+      SequenceState::STOPPING_TIME => hail.terminal_status,
+      SequenceState::CYCLE_LENGTH => Float::INFINITY,
+      SequenceState::ZERO_STOP => hail.terminal_status,
+      SequenceState::MAX_STOP_OUT_OF_BOUNDS => nil
+    }.fetch(hail.terminal_condition, nil)
+  end
+end

data/lib/collatz/tree_graph.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative "utilities"
+require_relative "function"
+
+module Collatz # rubocop:disable Style/Documentation
+  # 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
+    # The value of this node in the tree.
+    attr_reader :node_value
+
+    # The terminal SequenceState; nil if not a terminal node, MAX_STOP_OUT_OF_BOUNDS if the max_orbit_distance
+    # has been reached, CYCLE_LENGTH if the node's value is found to have occured previously, or
+    # CYCLE_INIT, retroactively applied when a CYCLE_LENGTH state node is found.
+    attr_accessor :terminal_sequence_state
+
+    # The "Pre N/P" TreeGraphNode child of this node that
+    # is always present if this is not a terminal node.
+    attr_reader :pre_n_div_p_node
+
+    # The "Pre aN+b" TreeGraphNode child of this node that is
+    # present if it exists and this is not a terminal node.
+    attr_reader :pre_an_plus_b_node
+
+    # Create an instance of TreeGraphNode which will yield its entire sub-tree of all child nodes.
+    #
+    # @raise FailedSaneParameterCheck If p or a are 0.
+    #
+    # @param +Integer+ *node_value:* The value for which to find the tree graph node reversal.
+    #
+    # @param +Integer+ *max_orbit_distance:* The maximum distance/orbit/branch length to travel.
+    #
+    # @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 +Hash<Integer>+ *cycle_check:* A hash used to keep track of already graphed values
+    #
+    # @param +Boolean+ *create_raw:* Used to instruct the initialiser method to take 1:1 inputs, used in testing.
+    #
+    # @param SequenceState *terminal_sequence_state:*
+    #
+    # @param TreeGraphNode *pre_n_div_p_node:*
+    #
+    # @param TreeGraphNode *pre_an_plus_b_node:*
+    #
+    # @return [TreeGraphNode] A computed tree graph node
+    def initialize(node_value, max_orbit_distance, p, a, b, cycle_check: nil, create_raw: false,
+                   terminal_sequence_state: nil, pre_n_div_p_node: nil, pre_an_plus_b_node: nil)
+      @node_value = node_value
+      if create_raw
+        @terminal_sequence_state = terminal_sequence_state
+        @pre_n_div_p_node = pre_n_div_p_node
+        @pre_an_plus_b_node = pre_an_plus_b_node
+        return
+      end
+      # Handle cycle prevention for recursive calls
+      if cycle_check.nil?
+        cycle_check = { @node_value => self }
+      elsif !cycle_check[@node_value].nil?
+        # The value already exists in the cycle so this is a cyclic terminal
+        cycle_check[@node_value].terminal_sequence_state = SequenceState::CYCLE_INIT
+        @terminal_sequence_state = SequenceState::CYCLE_LENGTH
+        @pre_n_div_p_node = nil
+        @pre_an_plus_b_node = nil
+        return
+      else
+        cycle_check[@node_value] = self
+      end
+      if [0, max_orbit_distance].max.zero?
+        @terminal_sequence_state = SequenceState::MAX_STOP_OUT_OF_BOUNDS
+        @pre_n_div_p_node = nil
+        @pre_an_plus_b_node = nil
+      else
+        reverses = Collatz.reverse_function(node_value, p: p, a: a, b: b)
+        @pre_n_div_p_node = TreeGraphNode.new(reverses[0], max_orbit_distance-1, p, a, b, cycle_check: cycle_check)
+        if reverses.length == 2
+          @pre_an_plus_b_node = TreeGraphNode.new(reverses[1], max_orbit_distance-1, p, a, b, cycle_check: cycle_check)
+        else
+          @pre_an_plus_b_node = nil
+        end
+      end
+    end
+
+    # This will only confirm an equality if the whole subtree of both nodes, including
+    # node values, sequence states, and child nodes, checked recursively, are equal.
+    #
+    # @param TreeGraphNode *tgn:* The TreeGraphNode with which to compare equality.
+    #
+    # @return +Boolean+ true, if the entire sub-trees are equal.
+    def sub_tree_equals(tgn)
+      return false if self.node_value != tgn.node_value
+      return false if self.terminal_sequence_state != tgn.terminal_sequence_state
+      return false if self.pre_n_div_p_node.nil? && !tgn.pre_n_div_p_node.nil?
+      return false if !self.pre_n_div_p_node.nil? && !self.pre_n_div_p_node.sub_tree_equals(tgn.pre_n_div_p_node)
+      return false if self.pre_an_plus_b_node.nil? && !tgn.pre_an_plus_b_node.nil?
+      return false if !self.pre_an_plus_b_node.nil? && !self.pre_an_plus_b_node.sub_tree_equals(tgn.pre_an_plus_b_node)
+      true
+    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
+    # The root node of the tree of TreeGraphNode's.
+    attr_reader :root
+
+    # Create a new TreeGraph with the root node defined by the inputs.
+    #
+    # @raise FailedSaneParameterCheck If p or a are 0.
+    #
+    # @param +Integer+ *node_value:* The value for which to find the tree graph node reversal.
+    #
+    # @param +Integer+ *max_orbit_distance:* The maximum distance/orbit/branch length to travel.
+    #
+    # @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 +Boolean+ *create_raw:* Used to instruct the initialiser method to take 1:1 inputs, used in testing.
+    #
+    # @param TreeGraphNode *root:* A node that will be set to the root of this tree
+    #
+    # @return [TreeGraph] A tree graph, with a computed root node.
+    def initialize(node_value, max_orbit_distance, p, a, b, create_raw: false, root: nil)
+      if create_raw && !root.nil?
+        @root = root
+      else
+        @root = TreeGraphNode.new(node_value, max_orbit_distance, p, a, b)
+      end
+    end
+
+    # The equality between TreeGraph's is determined by the equality check on
+    # subtrees. A subtree check will be done on both TreeGraph's root nodes.
+    #
+    # @param TreeGraph
+    #
+    # @return +Boolean+ true, if both are TreeGraph, with the entire root's sub-trees being equal.
+    def ==(other)
+      # Generic checks
+      return false if other.nil?
+      return false unless other.is_a?(self.class)
+      # Actual check
+      self.root.sub_tree_equals(other.root)
+    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.
+  module_function def tree_graph(initial_value, max_orbit_distance, p: 2, a: 3, b: 1)
+    # Prior to starting the tree graph, which has some magic case handling, call
+    # the reverse_function to trigger any assert_sane_parameterisation flags.
+    _throwaway = reverse_function(initial_value, p: p, a: a, b: b)
+    TreeGraph.new(initial_value, max_orbit_distance, p, a, b)
+  end
+end

data/lib/collatz/utilities.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Collatz
+  # 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
+
+  # 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
+
+  # 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
+end

data/lib/collatz/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Collatz
-  VERSION = "0.1.0"
+  # The current semver version.
+  VERSION = "1.0.0"
 end

data/lib/collatz.rb

@@ -1,237 +1,25 @@
 # frozen_string_literal: true
 
 require_relative "collatz/version"
+require_relative "collatz/constants"
+require_relative "collatz/utilities"
+require_relative "collatz/function"
+require_relative "collatz/hailstone_sequence"
+require_relative "collatz/tree_graph"
 
-# :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.
+module Collatz
+  # Using a module to proctor a namespace for the functions, none of which
+  # are instance methods. All are "class" methods, so set module_function
+  # at the head of each required file which opens this module and has defs.
+  # https://github.com/rubocop/ruby-style-guide#modules-vs-classes
+  # rubocop:disable Lint/UselessAccessModifier
 
-# 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.
+  module_function # rubocop:disable Style/AccessModifierDeclarations
 
-# 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"
+  # rubocop:enable Lint/UselessAccessModifier
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: collatz
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Nathan Levett
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-09-21 00:00:00.000000000 Z
+date: 2022-09-24 00:00:00.000000000 Z
 dependencies: []
 description: |-
   Provides the basic functionality to interact with the Collatz conjecture.
@@ -34,6 +34,11 @@ files:
 - collatz.gemspec
 - devlog.md
 - lib/collatz.rb
+- lib/collatz/constants.rb
+- lib/collatz/function.rb
+- lib/collatz/hailstone_sequence.rb
+- lib/collatz/tree_graph.rb
+- lib/collatz/utilities.rb
 - lib/collatz/version.rb
 homepage: https://skenvy.github.io/Collatz/ruby/
 licenses: