diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..f6cbac1 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,41 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socioeconomic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +## Our Standards + +Examples of behavior that contributes to a positive environment: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +monora@gmail.com. All complaints will be reviewed and investigated promptly +and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 704fc5a..4c9e93f 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -34,7 +34,7 @@ bundle install ```bash bundle exec rake test # full test suite -bundle exec rake test TEST=test/stream_test.rb # single file +bundle exec rake test TEST=test/teststream.rb # single file ``` ## How to Contribute diff --git a/README.rdoc b/README.rdoc index a260e96..911af77 100644 --- a/README.rdoc +++ b/README.rdoc @@ -1,5 +1,5 @@ {Build Status}[https://github.com/monora/stream/actions/workflows/ruby.yml] -{Version}[https://badge.fury.io/rb/stream] +{Version}[https://rubygems.org/gems/stream] = Extended External Iterators (forward and backward) @@ -34,7 +34,7 @@ conditions must be true: s.at_beginning? <=> s.current_edge == [x0,x1] s.at_end? <=> s.current_edge == [xn,xn+1] - s.isEmpty? <=> s.at_beginning? && s.at_end? <=> s.current_edge == [x0,x1] <=> n = 0 + s.empty? <=> s.at_beginning? && s.at_end? <=> s.current_edge == [x0,x1] <=> n = 0 s.set_to_end => s.at_end? s.set_to_begin => s.at_beginning? diff --git a/lib/stream.rb b/lib/stream.rb index 9fb7fd0..0501294 100644 --- a/lib/stream.rb +++ b/lib/stream.rb @@ -24,15 +24,17 @@ def at_beginning? end # Move forward one position. Returns the _target_ of current_edge. - # Raises Stream::EndOfStreamException if at_end? is true. + # @raise [EndOfStreamException] if at_end? is true + # @return [Object] the next element def forward raise EndOfStreamException if at_end? basic_forward end - # Move backward one position. Returns the _source_ of current_edge. Raises - # Stream::EndOfStreamException if at_beginning? is true. + # Move backward one position. Returns the _source_ of current_edge. + # @raise [EndOfStreamException] if at_beginning? is true + # @return [Object] the previous element def backward raise EndOfStreamException if at_beginning? @@ -79,6 +81,8 @@ def basic_peek # This is similar to #detect, but starts the search from the # current position. #detect, which is inherited from Enumerable uses # #each, which implicitly calls #set_to_begin. + # @yield [element] each element in forward direction + # @return [Object, nil] the first matching element, or nil def move_forward_until until at_end? element = basic_forward @@ -89,6 +93,8 @@ def move_forward_until # Move backward until the boolean block is not false and returns the element # found. Returns nil if no object matches. + # @yield [element] each element in backward direction + # @return [Object, nil] the first matching element, or nil def move_backward_until until at_beginning? element = basic_backward @@ -192,6 +198,7 @@ class CollectionStream < BasicStream attr_reader :pos # Creates a new CollectionStream for the indexable sequence _seq_. + # @param seq [Array] an integer-indexed collection def initialize(seq) @seq = seq set_to_begin @@ -252,6 +259,7 @@ class IntervalStream < BasicStream # Create a new IntervalStream with upper bound _stop_. stop - 1 is the last # element. By default _stop_ is zero which means that the stream is empty. + # @param stop [Integer] exclusive upper bound; stream yields 0..stop-1 def initialize(stop = 0) @stop = stop - 1 set_to_begin @@ -617,6 +625,8 @@ class ImplicitStream < BasicStream # # If a block is given to new, than it is called with the new ImplicitStream # stream as parameter letting the client overwriting the default blocks. + # @param other_stream [Stream, nil] optional stream to wrap + # @yield [self] the new ImplicitStream instance for customization def initialize(other_stream = nil) # Initialize with defaults @at_beginning_proc = proc { true } @@ -674,7 +684,9 @@ def set_to_begin ## # Return a Stream::FilteredStream which iterates over all my elements - # satisfying the condition specified by the block. + # satisfying the condition specified by the block. + # @yield [element] filter predicate + # @return [FilteredStream] def filtered(&block) FilteredStream.new(self, &block) end @@ -687,6 +699,8 @@ def reverse # Create a Stream::MappedStream wrapper on self. Instead of returning the # stream element on each move, the value of calling _mapping_ is returned # instead. See Stream::MappedStream for examples. + # @yield [element] mapping block applied to each element + # @return [MappedStream] def collect(&mapping) MappedStream.new(self, &mapping) end @@ -708,8 +722,10 @@ def concatenate_collected(&mapping) collect(&mapping).concatenate end - # Create a Stream::ConcatenatedStream by concatenatating the receiver and - # _other_stream_ + # Create a Stream::ConcatenatedStream by concatenating the receiver and + # _other_stream_. + # @param other [Stream] the stream to append + # @return [ConcatenatedStream] # # (%w(a b c).create_stream + [4,5].create_stream).to_a # ==> ["a", "b", "c", 4, 5]