README.md in by_star-2.2.0 vs README.md in by_star-2.2.1

- old
+ new

@@ -80,29 +80,39 @@ * `next_week` Subsequent 7-day period from current time * `next_fortnight` Subsequent 14-day period from current time * `next_month` Subsequent 30-day period from current time * `next_year` Subsequent 365-day period from current time +### Superlative Finders + +Find the oldest or newest records. Returns an object instance (not a relation): + +* `newest` +* `oldest` + ### Instance Methods -In addition, ByStar adds instance methods to return the next / previous record in the timewise sequence: +In addition, ByStar adds instance methods to return the next / previous record in the timewise sequence. +Returns an object instance (not a relation): * `object.next` * `object.previous` ### Kernel Extensions -Lastly, ByStar extends the kernel `Date`, `Time`, and `DateTime` objects with the following instance methods, +ByStar extends the kernel `Date`, `Time`, and `DateTime` objects with the following instance methods, which mirror the ActiveSupport methods `beginning_of_day`, `end_of_week`, etc: * `beginning_of_weekend` * `end_of_weekend` * `beginning_of_fortnight` * `end_of_fortnight` * `beginning_of_calendar_month` * `end_of_calendar_month` +Lastly, ByStar aliases Rails 3 `Date#to_time_in_current_zone` to the Rails 4 syntax `#in_time_zone`, if it has not already been defined. + ## Usage ### Setting the Query Field By default, ByStar assumes you will use the `created_at` field to query objects by time. @@ -120,11 +130,12 @@ end ``` ### Scoping the Find -All ByStar methods (except `previous` and `next`) return `ActiveRecord::Relation` and/or `Mongoid::Criteria` objects, which can be daisy-chained with other scopes/finder methods: +All ByStar methods (except `oldest`, `newest`, `previous`, `next`) return `ActiveRecord::Relation` and/or +`Mongoid::Criteria` objects, which can be daisy-chained with other scopes/finder methods: ```ruby Post.by_month.your_scope Post.by_month(1).include(:tags).where("tags.name" => "ruby") ``` @@ -142,11 +153,17 @@ ```ruby @post.next(scope: Post.where(category: @post.category)) @post.next(scope: ->{ where(category: 'blog') }) ``` -This is particularly useful for `previous` and `next`, which return a model instance rather than +This is particularly useful for `oldest`, `newest`, `previous`, `next` which return a model instance rather than a Relation and hence cannot be daisy-chained with other scopes. + +`previous` and `next` support a special feature that the `:scope` option may take the subject record as an argument: + +```ruby + @post.next(scope: ->(record){ where(category: record.category) }) +``` You may also set a default scope in the `by_star_field` macro. (It is recommended this be a Proc): ```ruby class Post < ActiveRecord::Base