big update for 1.2.0

Author: SaphiraKai

README.md

@@ -13,11 +13,13 @@ import humanise
 import humanise/time
 
 pub fn main() {
-  humanise.bytes_int(10_000) |> io.println // 10.0KB
+  humanise.bytes_int(10_000) |> io.println // 10KB
 
-  time.Seconds(0.5) |> time.humanise |> time.to_string |> io.println // 500.0ms
+  time.Seconds(0.5) |> time.humanise |> time.to_string |> io.println // 500ms
 
-  time.Hours(1.0) |> time.to_minutes |> io.debug // 60.0
+  time.Hours(1.0) |> time.to_minutes |> echo // 60.0
+
+  time.Months(1.075) |> time.split(time.to_string_full) |> io.println // 1 month, 2.3 days
 }
 ```
 

gleam.toml

@@ -1,5 +1,5 @@
 name = "humanise"
-version = "1.1.0"
+version = "1.2.0"
 
 # Fill out these fields if you intend to generate HTML documentation or publish
 # your project to the Hex package manager.

manifest.toml

@@ -2,7 +2,7 @@
 # You typically do not need to edit this file
 
 packages = [
-  { name = "gleam_stdlib", version = "0.62.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "DC8872BC0B8550F6E22F0F698CFE7F1E4BDA7312FDEB40D6C3F44C5B706C8310" },
+  { name = "gleam_stdlib", version = "0.62.1", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "0080706D3A5A9A36C40C68481D1D231D243AF602E6D2A2BE67BA8F8F4DFF45EC" },
   { name = "gleam_time", version = "1.4.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_time", source = "hex", outer_checksum = "DCDDC040CE97DA3D2A925CDBBA08D8A78681139745754A83998641C8A3F6587E" },
   { name = "gleeunit", version = "1.6.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "FDC68A8C492B1E9B429249062CD9BAC9B5538C6FBF584817205D0998C42E1DAC" },
 ]

src/humanise.gleam

@@ -1,6 +1,8 @@
-//// This module contains a bunch of shortcuts to the `time`, `bytes` and 'bytes1024' modules for directly "humanising" and formatting a number (`Float` or `Int`) to a `String`.
+//// This module contains a bunch of shortcuts to the `time`, `bytes` and 'bytes1024' modules for directly "humanising"
+//// and formatting a number (`Float` or `Int`) to a `String`.
 ////
-//// For more control (e.g. work with `time.Time` or `bytes.Bytes` directly, use the given unit instead of the most optimal one), look at the `time`, `bytes` or `bytes1024` modules.
+//// For more control (e.g. work with `time.Time` or `bytes.Bytes` directly, use the given unit instead of the most
+//// optimal one), look at the `time`, `bytes` or `bytes1024` modules.
 
 import gleam/float
 import gleam/int
@@ -11,41 +13,46 @@ import gleam/time/timestamp.{type Timestamp}
 import humanise/bytes
 import humanise/bytes1024
 import humanise/time
+import humanise/util
 
 /// Format a `Timestamp` relative to the provided current `Timestamp`.
 ///
-/// This function finds the difference between the current time and the given time, and returns a string describing the difference. (e.g. "in 2.0s", "3.5d ago")
+/// This function finds the difference between the current time and the given time, and returns a string describing the
+/// difference using the provided formatter. (e.g. `"in 2s"`, `"3 days, 12 hours ago"`)
 ///
-/// > If you're looking for prettier messages without decimal precision, I recommend the `timeago` package!
-pub fn date_relative(from date: Timestamp, now current: Timestamp) -> String {
+/// Examples:
+///
+/// ```
+/// let now = timestamp.system_time()
+///
+/// let from = now |> timestamp.add(duration.hours(36))
+/// humanise.date_relative(from:, now:, with: time.to_string) // "in 1.5d" 
+///
+/// let from = now |> timestamp.add(duration.hours(-36))
+/// humanise.date_relative(from:, now:, with: time.split(_, time.to_string_full)) // "1 day, 12 hours ago"
+/// ```
+pub fn date_relative(
+  from date: Timestamp,
+  now current: Timestamp,
+  with format: fn(time.Time) -> String,
+) -> String {
   let relative = current |> timestamp.difference(date) |> time.from_duration
 
-  let decompose = fn(a) {
-    case a {
-      time.Nanoseconds(n) -> #(time.Nanoseconds, n)
-      time.Days(n) -> #(time.Days, n)
-      time.Hours(n) -> #(time.Hours, n)
-      time.Microseconds(n) -> #(time.Microseconds, n)
-      time.Milliseconds(n) -> #(time.Milliseconds, n)
-      time.Minutes(n) -> #(time.Minutes, n)
-      time.Seconds(n) -> #(time.Seconds, n)
-      time.Weeks(n) -> #(time.Weeks, n)
-    }
-  }
+  let #(value, constructor) = time.decompose(relative)
 
-  let #(constructor, n) = decompose(relative)
-
-  case n >=. 0.0 {
-    True -> "in " <> time.to_string(relative)
-    False -> time.to_string(constructor(float.absolute_value(n))) <> " ago"
+  case value >=. 0.0 {
+    True -> "in " <> format(relative)
+    False -> float.absolute_value(value) |> constructor |> format <> " ago"
   }
 }
 
-/// Format a `Date`, `TimeOfDay` pair, automatically omitting redundant information (omit year if it matches the current year, omit month and day if it also matches the current day)
-///
+/// Format a `Date`, `TimeOfDay` pair, automatically omitting redundant information (omit year if it matches the current
+/// year, omit month and day if it also matches the current day)
+/// 
 /// The given date will be compared against the provided "current" date to determine what information to omit.
 ///
-/// This function does not currently support internationalization, and simply returns a string in the following largest-to-smallest format:
+/// This function does not currently support internationalization, and simply returns a string in the following
+/// largest-to-smallest format:
 /// ```
 /// <maybe year> <maybe <month> <day>> <hours>:<minutes>:<seconds>
 /// ```
@@ -186,6 +193,26 @@ pub fn weeks_int(from n: Int) -> String {
   time.Weeks(int.to_float(n)) |> time.humanise |> time.to_string
 }
 
+/// Format *n* months as a `Float`, converting to a more optimal unit if possible.
+pub fn months_float(from n: Float) -> String {
+  time.Months(n) |> time.humanise |> time.to_string
+}
+
+/// Format *n* months as an `Int`, converting to a more optimal unit if possible.
+pub fn months_int(from n: Int) -> String {
+  time.Months(int.to_float(n)) |> time.humanise |> time.to_string
+}
+
+/// Format *n* years as a `Float`, converting to a more optimal unit if possible.
+pub fn years_float(from n: Float) -> String {
+  time.Years(n) |> time.humanise |> time.to_string
+}
+
+/// Format *n* years as an `Int`, converting to a more optimal unit if possible.
+pub fn years_int(from n: Int) -> String {
+  time.Years(int.to_float(n)) |> time.humanise |> time.to_string
+}
+
 /// Format *n* bytes as a `Float`, converting to a more optimal unit if possible.
 pub fn bytes_float(from n: Float) -> String {
   bytes.Bytes(n) |> bytes.humanise |> bytes.to_string
@@ -291,3 +318,33 @@ pub fn tebibytes_int(from n: Int) -> String {
   |> bytes1024.humanise
   |> bytes1024.to_string
 }
+
+/// Convert from 1000-multiple `bytes.Bytes` to 1024-multiple `bytes1024.Bytes`.
+pub fn bytes_to_bytes1024(from data: bytes.Bytes) -> bytes1024.Bytes {
+  case data {
+    bytes.Bytes(a) -> bytes1024.Bytes(a)
+    bytes.Kilobytes(a) ->
+      bytes1024.Kibibytes(a *. util.kilobyte /. util.kibibyte)
+    bytes.Megabytes(a) ->
+      bytes1024.Mebibytes(a *. util.megabyte /. util.mebibyte)
+    bytes.Gigabytes(a) ->
+      bytes1024.Gibibytes(a *. util.gigabyte /. util.gibibyte)
+    bytes.Terabytes(a) ->
+      bytes1024.Tebibytes(a *. util.terabyte /. util.tebibyte)
+  }
+}
+
+/// Convert from 1000-multiple `bytes.Bytes` to 1024-multiple `bytes1024.Bytes`.
+pub fn bytes1024_to_bytes(from data: bytes1024.Bytes) -> bytes.Bytes {
+  case data {
+    bytes1024.Bytes(a) -> bytes.Bytes(a)
+    bytes1024.Kibibytes(a) ->
+      bytes.Kilobytes(a *. util.kibibyte /. util.kilobyte)
+    bytes1024.Mebibytes(a) ->
+      bytes.Megabytes(a *. util.mebibyte /. util.megabyte)
+    bytes1024.Gibibytes(a) ->
+      bytes.Gigabytes(a *. util.gibibyte /. util.gigabyte)
+    bytes1024.Tebibytes(a) ->
+      bytes.Terabytes(a *. util.tebibyte /. util.terabyte)
+  }
+}

src/humanise/bytes.gleam

@@ -1,29 +1,20 @@
-//// This module contains functions for formatting amounts of data to `String`s (e.g. `"100.0B"`, `"1.5GB"`).
+//// This module contains functions for formatting amounts of data to `String`s (e.g. `"100B"`, `"1.5GB"`).
 ////
 //// Usage generally looks like this:
 //// ```
-//// bytes.Kilobytes(2000.0) |> bytes.humanise |> bytes.to_string // "2.0MB"
+//// bytes.Kilobytes(2000.0) |> bytes.humanise |> bytes.to_string // "2MB"
 //// 
 //// // or, if you don't want to change the unit
-//// bytes.Kilobytes(2000.0) |> bytes.to_string // "2000.0KB"
+//// bytes.Kilobytes(2000.0) |> bytes.to_string // "2000KB"
 //// ```
 ////
 //// *Note: This module is for 1000-multiple units! (kilobyte, megabyte, etc.)*
 //// *If you're looking for 1024-multiple units (kibibyte, mebibyte, etc.), look at the `bytes1024` module instead.*
 
-import gleam/bool
 import gleam/float
 
 import humanise/util
 
-const kilobyte = 1000.0
-
-const megabyte = 1_000_000.0
-
-const gigabyte = 1_000_000_000.0
-
-const terabyte = 1_000_000_000_000.0
-
 /// The main type for holding data amount information.
 ///
 /// Use its constructors directly to specify a unit for the value you want to format.
@@ -44,10 +35,10 @@ pub type Bytes {
 pub fn as_bytes(this bytes: Bytes) -> Float {
   case bytes {
     Bytes(n) -> n
-    Kilobytes(n) -> n *. kilobyte
-    Megabytes(n) -> n *. megabyte
-    Gigabytes(n) -> n *. gigabyte
-    Terabytes(n) -> n *. terabyte
+    Kilobytes(n) -> n *. util.kilobyte
+    Megabytes(n) -> n *. util.megabyte
+    Gigabytes(n) -> n *. util.gigabyte
+    Terabytes(n) -> n *. util.terabyte
   }
 }
 
@@ -58,7 +49,7 @@ pub fn as_bytes(this bytes: Bytes) -> Float {
 /// bytes.Bytes(1000.0) |> bytes.as_kilobytes // 1.0
 /// ```
 pub fn as_kilobytes(this bytes: Bytes) -> Float {
-  as_bytes(bytes) /. kilobyte
+  as_bytes(bytes) /. util.kilobyte
 }
 
 /// Convert a value to megabytes.
@@ -68,7 +59,7 @@ pub fn as_kilobytes(this bytes: Bytes) -> Float {
 /// bytes.Kilobytes(1000.0) |> bytes.as_megabytes // 1.0
 /// ```
 pub fn as_megabytes(this bytes: Bytes) -> Float {
-  as_bytes(bytes) /. megabyte
+  as_bytes(bytes) /. util.megabyte
 }
 
 /// Convert a value to gigabytes.
@@ -78,7 +69,7 @@ pub fn as_megabytes(this bytes: Bytes) -> Float {
 /// bytes.Megabytes(1000.0) |> bytes.as_gigabytes // 1.0
 /// ```
 pub fn as_gigabytes(this bytes: Bytes) -> Float {
-  as_bytes(bytes) /. gigabyte
+  as_bytes(bytes) /. util.gigabyte
 }
 
 /// Convert a value to terabytes.
@@ -88,7 +79,7 @@ pub fn as_gigabytes(this bytes: Bytes) -> Float {
 /// bytes.Gigabytes(1000.0) |> bytes.as_terabytes // 1.0
 /// ```
 pub fn as_terabytes(this bytes: Bytes) -> Float {
-  as_bytes(bytes) /. terabyte
+  as_bytes(bytes) /. util.terabyte
 }
 
 /// Convert a value to a more optimal unit, if possible.
@@ -98,22 +89,22 @@ pub fn as_terabytes(this bytes: Bytes) -> Float {
 /// bytes.Megabytes(0.5) |> bytes.humanise // bytes.Kilobytes(500.0)
 /// ```
 pub fn humanise(this bytes: Bytes) -> Bytes {
-  let abs = float.absolute_value
   let b = as_bytes(bytes)
 
-  use <- bool.guard(when: abs(b) <. kilobyte, return: Bytes(b))
-  use <- bool.guard(when: abs(b) <. megabyte, return: Kilobytes(b /. kilobyte))
-  use <- bool.guard(when: abs(b) <. gigabyte, return: Megabytes(b /. megabyte))
-  use <- bool.guard(when: abs(b) <. terabyte, return: Gigabytes(b /. gigabyte))
-
-  Terabytes(b /. terabyte)
+  case float.absolute_value(b) {
+    abs_b if abs_b <. util.kilobyte -> Bytes(b)
+    abs_b if abs_b <. util.megabyte -> Kilobytes(b /. util.kilobyte)
+    abs_b if abs_b <. util.gigabyte -> Megabytes(b /. util.megabyte)
+    abs_b if abs_b <. util.terabyte -> Gigabytes(b /. util.gigabyte)
+    _ -> Terabytes(b /. util.terabyte)
+  }
 }
 
-/// Format a value as a `String`, rounded to at most 2 decimal places, followed by a unit suffix.
+/// Format a value as a `String`, rounded to at most 1 decimal place, followed by an abbreviated unit suffix.
 ///
 /// Example:
 /// ```
-/// bytes.Gigabytes(30.125) |> bytes.to_string // "30.13GB"
+/// bytes.Gigabytes(30.125) |> bytes.to_string // "30.1GB"
 /// ```
 pub fn to_string(this bytes: Bytes) -> String {
   let #(n, suffix) = case bytes {
@@ -126,3 +117,47 @@ pub fn to_string(this bytes: Bytes) -> String {
 
   util.format(n, suffix)
 }
+
+/// Format a value as a `String`, rounded to at most 1 decimal place, followed by a long unit suffix.
+///
+/// Example:
+/// ```
+/// bytes.Gigabytes(30.125) |> bytes.to_string_full // "30.1 gigabytes"
+/// bytes.Megabytes(1.0) |> bytes.to_string_full // "1 megabyte"
+/// ```
+pub fn to_string_full(this bytes: Bytes) -> String {
+  let #(n, suffix) = case bytes {
+    Bytes(n) -> #(n, " byte")
+    Kilobytes(n) -> #(n, " kilobyte")
+    Megabytes(n) -> #(n, " megabyte")
+    Gigabytes(n) -> #(n, " gigabyte")
+    Terabytes(n) -> #(n, " terabyte")
+  }
+
+  let plural = case n {
+    1.0 -> ""
+    _ -> "s"
+  }
+
+  util.format(n, suffix) <> plural
+}
+
+/// Decompose a value into its inner value and constructor.
+///
+/// This is useful if you need to operate directly on the value and then reconstruct it (i.e. for custom rounding precision).
+///
+/// Example:
+/// ```
+/// let #(value, constructor) = bytes.decompose(bytes.Megabytes(2.0)) // #(2.0, bytes.Megabytes)
+///
+/// constructor(value *. 2.0) // bytes.Megabytes(4.0)
+/// ```
+pub fn decompose(time: Bytes) -> #(Float, fn(Float) -> Bytes) {
+  case time {
+    Bytes(a) -> #(a, Bytes)
+    Gigabytes(a) -> #(a, Gigabytes)
+    Kilobytes(a) -> #(a, Kilobytes)
+    Megabytes(a) -> #(a, Megabytes)
+    Terabytes(a) -> #(a, Terabytes)
+  }
+}