add in a couple usage examples

README.md

@@ -3,10 +3,11 @@
 
 [![Build Status](https://travis-ci.org/ryannhg/elm-date-format.svg?branch=master)](https://travis-ci.org/ryannhg/elm-date-format)
 
+
 ### Using the [elm package](http://package.elm-lang.org/packages/ryannhg/date-format/latest)
 
 ```
-elm package install ryannhg/date-format
+elm install ryannhg/date-format
 ```
 
 
@@ -16,7 +17,7 @@ If you're coming from Javascript, you might have heard of [MomentJS](https://mom
 
 MomentJS is a great library for formatting dates!
 
-`date-format` has similar [formatting options](https://momentjs.com/docs/#/displaying/format/) as Moment, but uses Elm's awesome type system to provide human readable names, and catch typos for you at compile time!
+`date-format` has similar [formatting options](https://momentjs.com/docs/#/displaying/format/) as Moment, but it uses Elm's awesome type system to provide __human readable__ names, and catch typos for you at compile time!
 
 No need to remember the difference between `mm` and `MM` and `M`!
 
@@ -25,12 +26,14 @@ No need to remember the difference between `mm` and `MM` and `M`!
 
 ```elm
 import DateFormat
-import Time exposing (Zone, Posix)
+import Time exposing (Posix, Zone, utc)
+
 
 
 -- Let's create a custom formatter we can use later:
 
-ourFormatter : Zone -> Prefix -> String
+
+ourFormatter : Zone -> Posix -> String
 ourFormatter =
     DateFormat.format
         [ DateFormat.monthNameFull
@@ -41,13 +44,19 @@ ourFormatter =
         ]
 
 
+
 -- With our formatter, we can format any date as a string!
 
+
 ourTimezone : Zone
 ourTimezone =
     utc
 
+
+
 -- 2018-05-20T19:18:24.911Z
+
+
 ourPosixTime : Posix
 ourPosixTime =
     Time.millisToPosix 1526843861289
@@ -64,3 +73,21 @@ Would make `ourPrettyDate` return:
 ```
 "May 20th, 2018" : String
 ```
+
+### Want more examples?
+
+I've created a few more examples in the `examples/` folder for this repo.
+
+Here's how you can try them out:
+
+1. `git clone https://github.com/ryannhg/date-format`
+
+1. `cd date-format/examples`
+
+1. `elm reactor`
+
+1. Go to [http://localhost:8000](http://localhost:8000)
+
+
+
+

elm.json

@@ -1,7 +1,7 @@
 {
     "type": "package",
     "name": "ryannhg/elm-date-format",
-    "summary": "A reliable way to format dates with Elm",
+    "summary": "A reliable way to format dates and times with Elm.",
     "license": "BSD-3-Clause",
     "version": "2.1.1",
     "exposed-modules": [

examples/Basic.elm

@@ -0,0 +1,52 @@
+module Main exposing (..)
+
+import Browser exposing (staticPage)
+import DateFormat
+import Html exposing (text)
+import Time exposing (Posix, Zone, utc)
+
+
+
+-- Let's create a custom formatter we can use later:
+
+
+ourFormatter : Zone -> Posix -> String
+ourFormatter =
+    DateFormat.format
+        [ DateFormat.monthNameFull
+        , DateFormat.text " "
+        , DateFormat.dayOfMonthSuffix
+        , DateFormat.text ", "
+        , DateFormat.yearNumber
+        ]
+
+
+
+-- With our formatter, we can format any date as a string!
+
+
+ourTimezone : Zone
+ourTimezone =
+    utc
+
+
+
+-- 2018-05-20T19:18:24.911Z
+
+
+ourPosixTime : Posix
+ourPosixTime =
+    Time.millisToPosix 1526843861289
+
+
+ourPrettyDate : String
+ourPrettyDate =
+    ourFormatter ourTimezone ourPosixTime
+
+
+
+-- Show on the screen
+
+
+main =
+    staticPage (text ourPrettyDate)

examples/Relative.elm

@@ -0,0 +1,84 @@
+module Main exposing (..)
+
+import Browser
+import DateFormat.Relative as Relative
+import Html exposing (..)
+import Task
+import Time exposing (Posix, Zone, utc)
+
+
+main =
+    Browser.embed
+        { init = init
+        , view = view
+        , update = update
+        , subscriptions = subscriptions
+        }
+
+
+type alias Model =
+    { timeSinceExample : Posix
+    , initialTime : Maybe Posix
+    , now : Maybe Posix
+    }
+
+
+init : () -> ( Model, Cmd Msg )
+init _ =
+    ( Model
+        (Time.millisToPosix 1526852818792)
+        Nothing
+        Nothing
+    , Task.perform SetInitialTime Time.now
+    )
+
+
+view : Model -> Html Msg
+view model =
+    div []
+        [ h3 [] [ text "Model" ]
+        , p [] [ text <| Debug.toString model ]
+        , case ( model.initialTime, model.now ) of
+            ( Just initialTime, Just now ) ->
+                p []
+                    [ strong [] [ text "Time since you loaded this page: " ]
+                    , span [] [ text <| Relative.relativeTime now initialTime ]
+                    ]
+
+            ( _, _ ) ->
+                p [] [ text "Getting times..." ]
+        , case model.now of
+            Just now ->
+                p []
+                    [ strong [] [ text "Time since Ryan wrote this example: " ]
+                    , span [] [ text <| Relative.relativeTime now model.timeSinceExample ]
+                    ]
+
+            Nothing ->
+                p [] [ text "Getting now time..." ]
+        ]
+
+
+type Msg
+    = SetInitialTime Posix
+    | SetNow Posix
+
+
+update : Msg -> Model -> ( Model, Cmd Msg )
+update msg model =
+    case msg of
+        SetInitialTime initialTime ->
+            ( { model
+                | initialTime = Just initialTime
+                , now = Just initialTime
+              }
+            , Cmd.none
+            )
+
+        SetNow now ->
+            ( { model | now = Just now }, Cmd.none )
+
+
+subscriptions : Model -> Sub Msg
+subscriptions model =
+    Time.every 1000 SetNow

examples/elm.json

@@ -0,0 +1,22 @@
+{
+    "type": "application",
+    "source-directories": [
+        ".",
+        "../src"
+    ],
+    "elm-version": "0.19.0",
+    "dependencies": {
+        "elm-lang/browser": "1.0.0",
+        "elm-lang/core": "6.0.0",
+        "elm-lang/html": "3.0.0",
+        "elm-lang/json": "1.0.0",
+        "elm-lang/time": "1.0.0"
+    },
+    "test-dependencies": {},
+    "do-not-edit-this-by-hand": {
+        "transitive-dependencies": {
+            "elm-lang/url": "1.0.0",
+            "elm-lang/virtual-dom": "3.0.0"
+        }
+    }
+}

src/DateFormat.elm

@@ -40,7 +40,7 @@ module DateFormat
         , yearNumberLastTwo
         )
 
-{-| A reliable way to format dates with elm
+{-| A reliable way to format dates and times with Elm.
 
 
 # The `format` function

src/DateFormat/Relative.elm

@@ -17,33 +17,29 @@ module DateFormat.Relative
 import Time exposing (Month(..), Posix, Weekday(..), Zone, utc)
 
 
-{-| This function takes in two dates and returns the relative difference!
-
-The date inputs are in **chronological order**, to make it easy to remember.
-
-With `relativeTime`, we see a date with both past _and_ future dates!
+{-| This function takes in two times and returns the relative difference!
 
 Here are a few examples to help:
 
-    relativeTime tenSecondsAgo now ==  "just now"
-    relativeTime now tenSecondsInTheFuture ==  "in a few seconds"
+    relativeTime now tenSecondsAgo ==  "just now"
+    relativeTime now tenSecondsFromNow ==  "in a few seconds"
 
-    relativeTime fortyThreeMinutesAgo now == "43 minutes ago"
+    relativeTime now fortyThreeMinutesAgo == "43 minutes ago"
 
-    relativeTime oneHundredDaysAgo now == "100 days ago"
+    relativeTime now oneHundredDaysAgo == "100 days ago"
     relativeTime now oneHundredDaysFromNow == "in 100 days"
 
     -- Order matters!
-    relativeTime tenSecondsAgo now ==  "just now"
-    relativeTime now tenSecondsAgo ==  "in a few seconds"
+    relativeTime now tenSecondsAgo ==  "just now"
+    relativeTime tenSecondsAgo now ==  "in a few seconds"
 
 -}
 relativeTime : Posix -> Posix -> String
 relativeTime =
     relativeTimeWithOptions defaultRelativeOptions
 
 
-{-| Maybe `relativeTime` is too lame. (Or maybe you speak a different language)
+{-| Maybe `relativeTime` is too lame. (Or maybe you speak a different language than English!)
 
 With `relativeTimeWithOptions`, you can provide your own custom messages for each time range.
 
@@ -55,16 +51,16 @@ You can provide a set of your own custom options, and use `relativeTimeWithOptio
 relativeTimeWithOptions : RelativeTimeOptions -> Posix -> Posix -> String
 relativeTimeWithOptions options start end =
     let
-        differenceInSeconds : Float
-        differenceInSeconds =
-            toSeconds end - toSeconds start
+        differenceInMilliseconds : Int
+        differenceInMilliseconds =
+            toMilliseconds end - toMilliseconds start
 
         time : Posix
         time =
-            Time.millisToPosix (round <| abs differenceInSeconds)
+            Time.millisToPosix (abs differenceInMilliseconds)
     in
     relativeTimeWithFunctions utc time <|
-        if differenceInSeconds < 0 then
+        if differenceInMilliseconds < 0 then
             RelativeTimeFunctions
                 options.someSecondsAgo
                 options.someMinutesAgo
@@ -144,10 +140,9 @@ divideBy divisor dividend =
     toFloat dividend / toFloat divisor
 
 
-toSeconds : Posix -> Float
-toSeconds =
+toMilliseconds : Posix -> Int
+toMilliseconds =
     Time.posixToMillis
-        >> divideBy 1000
 
 
 type alias RelativeTimeFunctions =