humane 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 433a88d823e187b4481fb3c2632ba816b487b3b8047f272b5c4b17a930b6227b
-  data.tar.gz: 5c90d3a7ee778274382e8ca25d604d39e672333ddfb8985941b97e7ce345f335
+  metadata.gz: 94b64259f8b2dc0d78f3f6feb6b48b4d908f23bfa74f133d901c57f5232294bd
+  data.tar.gz: 65e61cee90061fb0eba0e08053c2d24104d7e7d8bc711b8789661a5b27dd9f52
 SHA512:
-  metadata.gz: 42ceb33a1bd570aa85b8cc5a9417204fcd9d6041e79e6e44c3b7a65469f9139c2897019afef22aab9269bd3956599c2e1ed430021a64f399a2fc6fac0e996c30
-  data.tar.gz: fc9eaa4b043bf6547444631fde9fa2bba69c493ecc07d5e43375ac65f6a20c9f607c73776c7f3e535080a4d2c682747cb8bff8e017e5ddfe67a0f79e3869a4ae
+  metadata.gz: a3320656c10207ff6e941325d26085bc16acb4a56807cf4daafd2bb7560396cd36a37afcc77b270114b330d83ae9e0a7b8b394444958b0a7f96207a775c9492a
+  data.tar.gz: 84d09dac947371900807718502d17055a914b91e58833a10fc2868c0179794fbf8ba80a42d14b359aef4fa4c32c2dbdcaa9265d737195f90c7978bc381a2dce2

data/README.md

@@ -33,6 +33,11 @@ let formatter = RelativeDateTimeFormatter(); formatter.unitsStyle = .full
 formatter.localizedString(for: time, relativeTo: now) // "3 minutes ago"
 ```
 
+If you're writing Swift directly rather than calling Foundation by hand,
+[`humane-swift`](https://github.com/woodie/humane-swift) wraps these same two
+formatters with the identical API shape -- including the
+`includeSeconds`/`approximate` options below.
+
 ## Install
 
 ```
@@ -45,6 +50,26 @@ or in a `Gemfile`:
 gem "humane"
 ```
 
+## Beyond Foundation's defaults
+
+Two options on `Humane::TimeFormatter`, both off by default so it matches
+`RelativeDateTimeFormatter` exactly out of the box:
+
+- `include_seconds` (default `false`): under 30 seconds, collapses to "less than a
+  minute ago"/"in less than a minute" instead of an exact second count. Named after
+  ActionView's `include_seconds`, which defaults the same way.
+- `approximate` (default `false`): prefixes "about"/"in about" on the hour-scale
+  buckets (1 hour, and 2..24 hours), the way ActionView's `distance_of_time_in_words`
+  does for those same buckets -- for a render that can't refresh itself and shouldn't
+  overstate its own precision. Matches ActionView's own table exactly (down to its
+  44:30/89:30 rounding cutoffs), through the "1 day" bucket; week/month/year buckets
+  are out of scope. See [issue #1](https://github.com/woodie/humane-ruby/issues/1).
+
+```ruby
+Humane::TimeFormatter.new(approximate: true).string(at: t - 15 * 3600, relative_to: t)
+# => "about 15 hours ago"
+```
+
 ## Scope
 
 Finder's `.file` byte-count style, and a numeric (non-calendar-aware)

data/lib/humane/time_formatter.rb

@@ -4,8 +4,10 @@ module Humane
   # Formats one time relative to another the way Finder-adjacent tools do.
   class TimeFormatter
     # include_seconds shows exact seconds under a minute instead of collapsing to "less than a minute ago/in less than a minute". Defaults to false, matching ActionView's include_seconds.
-    def initialize(include_seconds: false)
+    # approximate prefixes "about"/"in about" on the hour-scale buckets (1 hour, and 2..24 hours), matching ActionView's distance_of_time_in_words wording for those buckets. Defaults to false. See docs/COMMENTS.md and humane-ruby issue #1 for the full bucket table this ports.
+    def initialize(include_seconds: false, approximate: false)
       @include_seconds = include_seconds
+      @approximate = approximate
     end
 
     # Returns the time at `at` relative to `relative_to` as a human-readable string.
@@ -14,26 +16,37 @@ module Humane
       future = seconds.negative?
       seconds = seconds.abs
 
-      if !@include_seconds && seconds < 60
+      if !@include_seconds && seconds < 30
         return future ? "in less than a minute" : "less than a minute ago"
       end
 
-      text =
-        if seconds < 60
-          pluralize(seconds.to_i, "second")
-        elsif seconds < 3600
-          pluralize((seconds / 60.0).round, "minute")
-        elsif seconds < 86_400
-          pluralize((seconds / 3600.0).round, "hour")
-        else
-          pluralize((seconds / 86_400.0).round, "day")
+      if @include_seconds && seconds < 60
+        return wrap(pluralize(seconds.to_i, "second"), future: future)
+      end
+
+      # Buckets come from distance_in_minutes, not raw seconds re-divided per unit -- see docs/COMMENTS.md.
+      distance_in_minutes = (seconds / 60.0).round
+
+      text, approximable =
+        case distance_in_minutes
+        when 1 then ["1 minute", false]
+        when 2..44 then [pluralize(distance_in_minutes, "minute"), false]
+        when 45..89 then ["1 hour", true]
+        when 90..1439 then [pluralize((distance_in_minutes / 60.0).round, "hour"), true]
+        when 1440..2519 then ["1 day", false]
+        else [pluralize((distance_in_minutes / 1440.0).round, "day"), false]
         end
 
-      future ? "in #{text}" : "#{text} ago"
+      text = "about #{text}" if @approximate && approximable
+      wrap(text, future: future)
     end
 
     private
 
+    def wrap(text, future:)
+      future ? "in #{text}" : "#{text} ago"
+    end
+
     def pluralize(count, unit)
       count == 1 ? "1 #{unit}" : "#{count} #{unit}s"
     end

data/lib/humane/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Humane
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: humane
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - John Woodell