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