vector_number 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c55a93e873d8e98092a5be77940f3f91cf06e90abb973f16d2fc91f0df0276ca
-  data.tar.gz: 446cb27d60ff3b588ffbc6fa49489013d6a2cfc8e6f2b577abc4a40b47587658
+  metadata.gz: b935cacefb185478f7f923046b28589c6da2763574c315f19c6b8050cd5835e1
+  data.tar.gz: a93dd71a4de2d07255962e13a81a357c92f5a1653d916e95d5a54a99afa984a6
 SHA512:
-  metadata.gz: 2a069408f786816659721505e8e09d50aeaf891e6dcc85c35d008a161500548e74c3cb0224a8992521c3e9385cb8cabe6c9b565874981c0098d5fb5c081ee65f
-  data.tar.gz: 99c2b90210dfceaeec85f6f8fd897074296c27ba6e9a6cb8ffcd0d407b3f65482b445b721fd5a41139a339d5d54f8ce81f4860dfdffccc0db1909002744fa8fe
+  metadata.gz: 9d6ea64b09d12434470d65c7ff808b63b9ccc59cb1e479bc7659ed973a8f03a3fb137dfe3641163dc56b06163b7d0c472ed74af2f49f6623b866eff90961aa7c
+  data.tar.gz: 85a927c88c99533e434a185a239f2d129567adf8d2e8c4d8d62e6239560d889e24fc7d3e478039b6d8c4213596e9ea7a61da5d0ab867162f9fbe7bee4edf05e5

data/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Next]
+## [v0.3.1] — 2025-06-21
+
+This is mostly a documentation update with a side of improved gemspec.
+
+**Changed**
+- Improve method documentation and unify documentation style across the board.
+- Improve gemspec:
+  - change source code and changelog links to point to a tagged commit;
+  - add links to bugtracker and documentation (for appropriate version);
+  - properly add CHANGELOG.md to doc generation.
+- Improve documentation for NumericRefinements to include examples and more info.
+- `#dup` is now an alias of `#+@` with no change in function.
+- `#abs` is now calculated from `#abs2` instead of the other way around to reduce errors.
+
+**Fixed**
+- Correct broken changelog link in gem metadata.
+
+[Compare v0.3.0...main](https://github.com/trinistr/vector_number/compare/v0.3.0...main)
+
 ## [v0.3.0] — 2025-05-12
 
 **Added**
@@ -18,7 +37,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
    When creating new vector through any operation, participating vector's options
    are copied to the new one. When several vectors are present, only first one matters.
 - Both `#+@` and `#dup` are now aliases of `#itself` instead of full methods.
-- [🚀 CI] Refactor workflows to reduce duplication.
+- [🚀 CI] "CI" workflow now reports status of all checks,
+   excluding allowed-to-fail workflows (currently JRuby and TruffleRuby).
+
+[Compare v0.2.6...v0.3.0](https://github.com/trinistr/vector_number/compare/v0.2.6...v0.3.0)
 
 ## [v0.2.6] — 2025-04-30
 
@@ -33,11 +55,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 **Changed**
 - [🚀 CI] Add Ruby 3.4 to CI.
 
+[Compare v0.2.5...v0.2.6](https://github.com/trinistr/vector_number/compare/v0.2.5...v0.2.6)
+
 ## [v0.2.5] — 2025-02-26
 
 Technical update after release to rubygems.org.
 README was updated to reflect this change.
 
+[Compare v0.2.4...v0.2.5](https://github.com/trinistr/vector_number/compare/v0.2.4...v0.2.5)
+
 ## [v0.2.4] — 2025-02-26
 
 **Added**
@@ -55,11 +81,15 @@ README was updated to reflect this change.
 **Fixed**
 - `#dup` and `#clone` now behave exactly like Numeric versions, preventing unfreezing.
 
+[Compare v0.2.3...v0.2.4](https://github.com/trinistr/vector_number/compare/v0.2.3...v0.2.4)
+
 ## [v0.2.3] — 2024-10-15
 
 **Fixed**
 - BigDecimal tests are now properly skipped when BigDecimal is not available, instead of always.
 
+[Compare v0.2.2...v0.2.3](https://github.com/trinistr/vector_number/compare/v0.2.2...v0.2.3)
+
 ## [v0.2.2] — 2024-10-07
 
 **Added**
@@ -74,6 +104,8 @@ README was updated to reflect this change.
 **Fixed**
 - `Kernel#BigDecimal` refinement now correctly works without `ndigits` argument.
 
+[Compare v0.2.1...v0.2.2](https://github.com/trinistr/vector_number/compare/v0.2.1...v0.2.2)
+
 ## [v0.2.1] — 2024-08-24
 
 **Added**
@@ -90,6 +122,8 @@ README was updated to reflect this change.
 - Remove `#to_str`, as VectorNumber is not a String-like object.
 - Due to the above, `Kernel.BigDecimal` no longer works without refinements.
 
+[Compare v0.2.0...v0.2.1](https://github.com/trinistr/vector_number/compare/v0.2.0...v0.2.1)
+
 ## [v0.2.0] — 2024-08-19
 
 **Added**
@@ -97,8 +131,20 @@ README was updated to reflect this change.
 - Addition and subtraction are supported.
 - VectorNumbers are mostly interoperable with core numbers.
 
+[Compare v0.1.0...v0.2.0](https://github.com/trinistr/vector_number/compare/v0.1.0...v0.2.0)
+
 ## [v0.1.0] — 2024-05-09
 
 - Initial work.
 
+[Next]: https://github.com/trinistr/vector_number/tree/main
+[v0.3.0]: https://github.com/trinistr/vector_number/tree/v0.3.0
+[v0.2.6]: https://github.com/trinistr/vector_number/tree/v0.2.6
+[v0.2.5]: https://github.com/trinistr/vector_number/tree/v0.2.5
+[v0.2.4]: https://github.com/trinistr/vector_number/tree/v0.2.4
+[v0.2.3]: https://github.com/trinistr/vector_number/tree/v0.2.3
+[v0.2.2]: https://github.com/trinistr/vector_number/tree/v0.2.2
+[v0.2.1]: https://github.com/trinistr/vector_number/tree/v0.2.1
+[v0.2.0]: https://github.com/trinistr/vector_number/tree/v0.2.0
+[v0.1.0]: https://github.com/trinistr/vector_number/tree/v0.1.0
 [🚀 CI]: https://github.com/trinistr/vector_number/actions/workflows/CI.yaml

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-2025 Alexandr Bulancov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,26 +1,35 @@
 # VectorNumber
 
+> [!TIP]
+> You may be viewing documentation for an older (or newer) version of the gem.
+> Check badges below to see what the latest released version is.
+> Look at [Changelog](https://github.com/trinistr/vector_number/blob/main/CHANGELOG.md)
+> to see all versions, including unreleased changes!
+
+Latest: [![Gem Version](https://badge.fury.io/rb/vector_number.svg?icon=si%3Arubygems)](https://rubygems.org/gems/vector_number)
 [![CI](https://github.com/trinistr/vector_number/actions/workflows/CI.yaml/badge.svg)](https://github.com/trinistr/vector_number/actions/workflows/CI.yaml)
 
-A library to add together anything: be it a number, string or random Object, it can be added together in an infinite-dimensional vector space, with math operations available on results.
+***
 
-This is similar in a sense to hypercomplex numbers, such as quaternions, but with a focus on arbitrary dimensions.
+A library to add together anything: be it a number, string or random Object, it can be added together with math operations available on results in a real vector space, though some operations are modeled on hypercomplex numbers.
 
 Similar projects:
-- [vector_space](https://github.com/tomstuart/vector_space) aims to provide typed vector spaces with limited dimensions and nice formatting.
-- [named_vector](https://rubygems.org/gems/named_vector) provides simple vectors with named dimensions.
-- Various quaternion libraries.
+- [vector_space](https://github.com/tomstuart/vector_space) aims to provide typed vector spaces with limited dimensions and nice formatting;
+- [named_vector](https://rubygems.org/gems/named_vector) provides simple vectors with named dimensions;
+- various quaternion libraries like [quaternion](https://github.com/tanahiro/quaternion) or [rmath3d](https://github.com/vaiorabbit/rmath3d).
+
+However, none of them have been updated in *years*.
 
 ## Installation
 
 VectorNumber does not have any dependencies and does not include extensions.
 
-Install with `gem` (available from 0.2.4):
+Install with `gem` (available from [0.2.4](https://github.com/trinistr/vector_number/tree/v0.2.4)):
 ```sh
 gem install vector_number
 ```
 
-If using `bundler`, add gem to your Gemfile:
+If using Bundler, add gem to your Gemfile:
 ```ruby
 gem "vector_number"
 ```

data/lib/vector_number/comparing.rb

@@ -2,17 +2,33 @@
 
 class VectorNumber
   # Methods for comparing with other numbers.
+  #
+  # +Comparable+ is included for parity with numbers.
+  # @example using Comparable methods
+  #   VectorNumber[12] < 0 # => false
+  #   VectorNumber[12, "a"] < 0 # ArgumentError
+  #   (VectorNumber[12]..VectorNumber[15]).include?(13) # => true
   module Comparing
+    # @since 0.2.0
     include ::Comparable
 
     # Compare to +other+ for equality.
     #
     # Values are considered equal if
     # - +other+ is a VectorNumber and it is +eql?+ to this one, or
-    # - +other+ is a Numeric equal in value to this number.
+    # - +other+ is a Numeric equal in value to this (real or complex) number.
+    #
+    # @example
+    #   VectorNumber[3.13] == 3.13 # => true
+    #   VectorNumber[1.4, 1.5i] == Complex(1.4, 1.5) # => true
+    #   VectorNumber["a", "b", "c"] == VectorNumber["c", "b", "a"] # => true
+    #   VectorNumber["a", 14] == 14 # => false
+    #   VectorNumber["a"] == "a" # => false
     #
     # @param other [Object]
     # @return [Boolean]
+    #
+    # @since 0.2.0
     def ==(other)
       return true if eql?(other)
 
@@ -25,8 +41,24 @@ class VectorNumber
       end
     end
 
+    # Compare to +other+ for strict equality.
+    #
+    # Values are considered equal only if +other+ is a VectorNumber
+    # and it has exactly the same units and coefficients, though possibly in a different order.
+    #
+    # Note that {#options} are not considered for equality.
+    #
+    # @example
+    #   VectorNumber["a", "b", "c"].eql? VectorNumber["c", "b", "a"] # => true
+    #   VectorNumber[3.13].eql? 3.13 # => false
+    #   VectorNumber[1.4, 1.5i].eql? Complex(1.4, 1.5) # => false
+    #   VectorNumber["a", 14].eql? 14 # => false
+    #   VectorNumber["a"].eql? "a" # => false
+    #
     # @param other [Object]
     # @return [Boolean]
+    #
+    # @since 0.1.0
     def eql?(other)
       return true if equal?(other)
 
@@ -37,8 +69,29 @@ class VectorNumber
       end
     end
 
+    # Compare to +other+ and return -1, 0, or 1
+    # if +self+ is less than, equal, or larger than +other+.
+    #
+    # @example
+    #   VectorNumber[130] <=> 12 # => 1
+    #   1 <=> VectorNumber[13] # => -1
+    #   VectorNumber[12.1] <=> Complex(12.1, 0) # => 0
+    #   # This doesn't work as expected without NumericRefinements:
+    #   Complex(12.1, 0) <=> VectorNumber[12.1] # => nil
+    #
+    #   # Any non-real comparison returns nil:
+    #   VectorNumber[12.1] <=> Complex(12.1, 1) # => nil
+    #   VectorNumber[12.1i] <=> 2 # => nil
+    #   VectorNumber["a"] <=> 2 # => nil
+    #
     # @param other [Object]
-    # @return [Integer, nil]
+    # @return [-1, 0, 1]
+    # @return [nil] if +self+ or +other+ isn't a real number.
+    #
+    # @see Comparable
+    # @see NumericRefinements
+    #
+    # @since 0.2.0
     def <=>(other)
       return nil unless numeric?(1)
 

data/lib/vector_number/converting.rb

@@ -4,47 +4,115 @@ class VectorNumber
   # Methods for converting to different number classes.
   module Converting
     # Return real part of the number.
+    #
+    # @example
+    #   VectorNumber[23, "a"].real # => 23
+    #   VectorNumber["a"].real # => 0
+    #
     # @return [Integer, Float, Rational, BigDecimal]
-    def real
-      @data[R]
-    end
+    #
+    # @since 0.1.0
+    def real = @data[R]
 
     # Return imaginary part of the number.
+    #
+    # @example
+    #   VectorNumber[23, "a"].imaginary # => 0
+    #   VectorNumber["a", Complex(1, 2r)].imag # => (2/1)
+    #
     # @return [Integer, Float, Rational, BigDecimal]
-    def imaginary
-      @data[I]
-    end
+    #
+    # @since 0.1.0
+    def imaginary = @data[I]
 
+    # @since 0.2.1
     alias imag imaginary
 
     # Return value as an Integer, truncating it, if only real part is non-zero.
+    #
+    # @example
+    #   VectorNumber[13.5].to_i # => 13
+    #   VectorNumber[13r/12].to_int # => 1
+    #   [1.1, 2.2, 3.3][VectorNumber[2]] # => 3.3
+    #   VectorNumber[2, 2i].to_i # RangeError
+    #   VectorNumber[2, :i].to_f # RangeError
+    #
+    #   Integer(VectorNumber[2]) # => 2
+    #   Integer(VectorNumber[2, "i"]) # RangeError
+    #
     # @return [Integer]
     # @raise [RangeError] if any non-real part is non-zero
+    #
+    # @since 0.1.0
     def to_i
       numeric?(1) ? real.to_i : raise_convert_error(Integer)
     end
 
+    # @since 0.1.0
     alias to_int to_i
 
     # Return value as a Float if only real part is non-zero.
+    #
+    # @example
+    #   VectorNumber[13.5].to_f # => 13.5
+    #   VectorNumber[13r/12].to_f # => 1.0833333333333333
+    #   VectorNumber[2, 2i].to_f # RangeError
+    #   VectorNumber[2, :i].to_f # RangeError
+    #
+    #   Float(VectorNumber[2]) # => 2.0
+    #   Float(VectorNumber[2, "i"]) # RangeError
+    #
     # @return [Float]
     # @raise [RangeError] if any non-real part is non-zero
+    #
+    # @since 0.1.0
     def to_f
       numeric?(1) ? real.to_f : raise_convert_error(Float)
     end
 
     # Return value as a Rational if only real part is non-zero.
+    #
+    # @example
+    #   VectorNumber[13.5].to_r # => (27/2)
+    #   VectorNumber[13r/12].to_r # => (13/12)
+    #   VectorNumber[2, 2i].to_r # RangeError
+    #   VectorNumber[2, :i].to_r # RangeError
+    #
+    #   Rational(VectorNumber[2]) # => (2/1)
+    #   Rational(VectorNumber[2, "i"]) # RangeError
+    #
     # @return [Rational]
     # @raise [RangeError] if any non-real part is non-zero
+    #
+    # @since 0.1.0
     def to_r
       numeric?(1) ? real.to_r : raise_convert_error(Rational)
     end
 
     # Return value as a BigDecimal if only real part is non-zero.
+    #
+    # @example
+    #   VectorNumber[13.5].to_d # => 0.135e2
+    #   VectorNumber[13r/12].to_d # ArgumentError
+    #   VectorNumber[13r/12].to_d(5) # => 0.10833e1
+    #   VectorNumber[2, 2i].to_d # RangeError
+    #   VectorNumber[2, :i].to_d # RangeError
+    #
+    #   # This does't work without NumericRefinements:
+    #   BigDecimal(VectorNumber[2]) # TypeError
+    #   # #to_s can be used as a workaround if refinements aren't used:
+    #   BigDecimal(VectorNumber[2].to_s) # => 0.2e1
+    #   BigDecimal(VectorNumber[2, "i"].to_s) # => ArgumentError
+    #
     # @param ndigits [Integer] precision
     # @return [BigDecimal]
     # @raise [RangeError] if any non-real part is non-zero
     # @raise [NameError] if BigDecimal is not defined
+    #
+    # @see Kernel.BigDecimal
+    # @see NumericRefinements
+    #
+    # @since 0.1.0
     def to_d(ndigits = nil)
       if numeric?(1)
         return BigDecimal(real, ndigits) if ndigits
@@ -57,8 +125,20 @@ class VectorNumber
     end
 
     # Return value as a Complex if only real and/or imaginary parts are non-zero.
+    #
+    # @example
+    #   VectorNumber[13.5].to_c # => (13.5+0i)
+    #   VectorNumber[13r/12].to_c # => ((13/12)+0i)
+    #   VectorNumber[2, 2i].to_c # => (2+2i)
+    #   VectorNumber[2, :i].to_c # RangeError
+    #
+    #   Complex(VectorNumber[2]) # => (2+0i)
+    #   Complex(VectorNumber[2, "i"]) # RangeError
+    #
     # @return [Complex]
     # @raise [RangeError] if any non-real, non-imaginary part is non-zero
+    #
+    # @since 0.1.0
     def to_c
       numeric?(2) ? Complex(real, imaginary) : raise_convert_error(Complex)
     end

data/lib/vector_number/enumerating.rb

@@ -2,11 +2,28 @@
 
 class VectorNumber
   # Methods for enumerating values of the number.
+  #
+  # +Enumerable+ is included so its methods can be used.
+  # @example using Enumerable methods
+  #   VectorNumber["a", "b", 6].include?(["a", 1]) # => true
+  #   VectorNumber["a", "b", 6].select { |u, c| u.is_a?(String) } # => [["a", 1], ["b", 1]]
   module Enumerating
+    # @since 0.1.0
     include ::Enumerable
 
     # Iterate through every pair of unit and coefficient.
-    # Returns {::Enumerator} if no block is given.
+    # Returns +Enumerator+ (with set +size+) if no block is given.
+    #
+    # @example
+    #   v = VectorNumber["a", "b", 6]
+    #   units = []
+    #   v.each { |u, c| units << u unless u.is_a?(Numeric) } # => (1⋅'a' + 1⋅'b' + 6)
+    #   units # => ["a", "b"]
+    # @example Enumerator
+    #   v.each.size # => 3
+    #   (v.each + [["d", 0]]).map(&:first) # => ["a", "b", (0+0i), "d"]
+    #   v.each_pair.peek # => ["a", 1]
+    #
     # @overload each
     #   @yieldparam unit [Object]
     #   @yieldparam coefficient [Integer, Float, Rational, BigDecimal]
@@ -14,6 +31,11 @@ class VectorNumber
     #   @return [VectorNumber] self
     # @overload each
     #   @return [Enumerator]
+    #
+    # @see Enumerable
+    # @see Enumerator
+    #
+    # @since 0.1.0
     def each(&)
       return to_enum { size } unless block_given?
 
@@ -21,24 +43,50 @@ class VectorNumber
       self
     end
 
+    # @since 0.1.0
     alias each_pair each
 
+    # Get a list of units with non-zero coefficients.
+    #
+    # @example
+    #   VectorNumber["a", "b", 6].units # => ["a", "b", (0+0i)]
+    #   VectorNumber.new.keys # => []
+    #
     # @return [Array<Object>]
-    def units
-      @data.keys
-    end
+    #
+    # @since 0.1.0
+    def units = @data.keys
 
+    # @since 0.1.0
     alias keys units
 
+    # Get a list of non-zero coefficients.
+    #
+    # @example
+    #   VectorNumber["a", "b", 6].coefficients # => [1, 1, 6]
+    #   VectorNumber.new.values # => []
+    #
     # @return [Array<Integer, Float, Rational, BigDecimal>]
-    def coefficients
-      @data.values
-    end
+    #
+    # @since 0.1.0
+    def coefficients = @data.values
 
+    # @since 0.1.0
     alias values coefficients
 
+    # Get mutable hash with vector's data.
+    #
+    # Returned hash has a default value of 0.
+    #
+    # @example
+    #   VectorNumber["a", "b", 6].to_h # => {"a"=>1, "b"=>1, (0+0i)=>6}
+    #   VectorNumber["a", "b", 6].to_h["c"] # => 0
+    #
     # @return [Hash{Object => Integer, Float, Rational, BigDecimal}]
+    #
+    # @since 0.1.0
     def to_h(&)
+      # TODO: Remove block argument.
       if block_given?
         @data.to_h(&)
       else
@@ -52,20 +100,29 @@ class VectorNumber
     # Note that units for real and imaginary parts are
     # VectorNumber::R and VectorNumber::I respectively.
     #
+    # @example
+    #   VectorNumber["a", "b", 6]["a"] # => 1
+    #   VectorNumber["a", "b", 6]["c"] # => 0
+    #
     # @param unit [Object]
     # @return [Integer, Float, Rational, BigDecimal]
-    def [](unit)
-      @data[unit] || 0
-    end
+    #
+    # @since 0.2.4
+    def [](unit) = @data[unit]
 
     # Check if a unit has a non-zero coefficient.
     #
+    # @example
+    #   VectorNumber["a", "b", 6].unit?("a") # => true
+    #   VectorNumber["a", "b", 6].key?("c") # => false
+    #
     # @param unit [Object]
     # @return [Boolean]
-    def unit?(unit)
-      @data.key?(unit)
-    end
+    #
+    # @since 0.2.4
+    def unit?(unit) = @data.key?(unit)
 
+    # @since 0.2.4
     alias key? unit?
   end
 end

data/lib/vector_number/math_converting.rb

@@ -3,45 +3,105 @@
 class VectorNumber
   # Various mathematical operations that are also conversions.
   module MathConverting
-    # Return the absolute value of the vector, i.e. its length.
+    # Calculate the absolute value of the vector, i.e. its length.
+    #
+    # @example
+    #   VectorNumber[5.3].abs # => 5.3
+    #   VectorNumber[-5.3i].magnitude # => 5.3
+    #   VectorNumber[-5.3i, "i"].abs # => 5.3935146240647205
+    #
     # @return [Float]
+    #
+    # @since 0.2.2
     def abs
-      Math.sqrt(coefficients.sum(&:abs2)) # rubocop:disable Naming/VariableNumber
+      Math.sqrt(abs2)
     end
 
     alias magnitude abs
 
-    # Return the square of absolute value.
+    # Calculate the square of absolute value.
+    #
+    # @example
+    #   VectorNumber[5.3].abs2 # => 5.3
+    #   VectorNumber[-5.3i].abs2 # => 5.3
+    #   VectorNumber[-5.3i, "i"].abs2 # => 29.09
+    #
     # @return [Float]
-    def abs2 # rubocop:disable Naming/VariableNumber
-      abs**2
+    #
+    # @since 0.2.2
+    def abs2
+      coefficients.sum(&:abs2)
     end
 
     # Return a new vector with every coefficient truncated using their +#truncate+.
+    #
+    # @example
+    #   VectorNumber[5.39].truncate # => (5)
+    #   VectorNumber[-5.35i].truncate # => (-5i)
+    #   VectorNumber[-5.35i, "i"].truncate # => (-5i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].truncate(1) # => (-5.3i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].truncate(-1) # => (0)
+    #
     # @param digits [Integer]
     # @return [VectorNumber]
+    #
+    # @since 0.2.1
     def truncate(digits = 0)
       new { _1.truncate(digits) }
     end
 
     # Return a new vector with every coefficient rounded using their +#ceil+.
+    #
+    # @example
+    #   VectorNumber[5.39].ceil # => (6)
+    #   VectorNumber[-5.35i].ceil # => (-5i)
+    #   VectorNumber[-5.35i, "i"].ceil # => (-5i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].ceil(1) # => (-5.3i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].ceil(-1) # => (10⋅'i')
+    #
     # @param digits [Integer]
     # @return [VectorNumber]
+    #
+    # @since 0.2.2
     def ceil(digits = 0)
       new { _1.ceil(digits) }
     end
 
     # Return a new vector with every coefficient rounded using their +#floor+.
+    #
+    # @example
+    #   VectorNumber[5.39].floor # => (5)
+    #   VectorNumber[-5.35i].floor # => (-6i)
+    #   VectorNumber[-5.35i, "i"].floor # => (-6i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].floor(1) # => (-5.4i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].floor(-1) # => (-10i)
+    #
     # @param digits [Integer]
     # @return [VectorNumber]
+    #
+    # @since 0.2.2
     def floor(digits = 0)
       new { _1.floor(digits) }
     end
 
     # Return a new vector with every coefficient rounded using their +#round+.
+    #
+    # @example
+    #   VectorNumber[-4.5i, "i"].round(half: :up) # => (-5i + 1⋅'i')
+    #   VectorNumber[-4.5i, "i"].round(half: :even) # => (-4i + 1⋅'i')
+    #   VectorNumber[-5.5i, "i"].round(half: :even) # => (-6i + 1⋅'i')
+    #   VectorNumber[-5.5i, "i"].round(half: :down) # => (-5i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].round(1) # => (-5.4i + 1⋅'i')
+    #   VectorNumber[-5.35i, "i"].round(-1) # => (-10i)
+    #
     # @param digits [Integer]
-    # @param half [Symbol, nil] one of +:up+, +:down+ or +:even+, see +Float#round+ for meaning
+    # @param half [Symbol, nil] one of +:up+, +:down+ or +:even+,
+    #   see +Float#round+ for meaning
     # @return [VectorNumber]
+    #
+    # @see Float#round
+    #
+    # @since 0.2.2
     def round(digits = 0, half: :up)
       if defined?(BigDecimal)
         bd_mode =