branch: elpa/datetime
commit faa0a9186d50eb03639d96a3d23fb6f76d1f0116
Author: Paul Pogonyshev <pogonys...@gmail.com>
Commit: Paul Pogonyshev <pogonys...@gmail.com>
Document parsing functionality.
---
README.md | 26 ++++++++++++++++++++++++++
datetime.el | 15 +++++++--------
2 files changed, 33 insertions(+), 8 deletions(-)
diff --git a/README.md b/README.md
index cd69becc47..1a8fbee14a 100644
--- a/README.md
+++ b/README.md
@@ -27,6 +27,32 @@ written in such a way that support for other types can be
added
relatively easily.
+## Parsing timestamps
+
+Parsing timestamps using the library is a two-step operation. First
+you create a *parser function* for a specific pattern and options.
+Then call the parser function with one argument — the timestamp as a
+string. It returns a floating point number — number of seconds since
+UNIX epoch in UTC timezone.
+
+Create a parser:
+
+ (datetime-parser-to-float 'java "yyyy-MM-dd HH:mm:ss.SSS"
+ :timezone 'system)
+
+And use it:
+
+ (let ((parser (datetime-parser-to-float 'java "yyyy-MM-dd HH:mm:ss.SSS"
+ :timezone 'system)))
+ (funcall parser "2018-09-18 21:20:00.000"))
+
+Remember that if you parse timestamps formatted on your machine, you
+need to pass `'system` as `:timezone` option to
+`datetime-parser-to-float`: default timezone is UTC. Parsing
+timestamps with varying timezones (i.e. with timezone information
+directly in the input string) is not yet supported.
+
+
## Formatting timestamps
To format timestamps you first need to create a *formatter function*.
diff --git a/datetime.el b/datetime.el
index 4c6ee71b20..4f1f0d0d5c 100644
--- a/datetime.el
+++ b/datetime.el
@@ -4,7 +4,7 @@
;; Author: Paul Pogonyshev <pogonys...@gmail.com>
;; Maintainer: Paul Pogonyshev <pogonys...@gmail.com>
-;; Version: 0.4
+;; Version: 0.6
;; Keywords: lisp, i18n
;; Homepage: https://github.com/doublep/datetime
;; Package-Requires: ((emacs "24.1") (extmap "1.0"))
@@ -31,9 +31,11 @@
;; in two steps: first you need to generate a formatting function for
;; given pattern, and only using it obtain formatted strings.
;;
-;; Package's main feature currently is timestamp formatting based on
+;; Package's main feature is timestamp parsing and formatting based on
;; Java pattern. Arbitrary timezones and locales (i.e. not
-;; necessarily those used by the system) are supported. See function
+;; necessarily those used by the system) are supported. However,
+;; specifying timezone in the input string to the parser function is
+;; not implemented yet. See functions `datetime-parser-to-float' and
;; `datetime-float-formatter' for details.
;;
;; Library also supports timestamp matching. It can generate regular
@@ -45,11 +47,8 @@
;; Finally, library provides functions to select an appropriate
;; timestamp format for given locale. For example, function
;; `datetime-locale-date-pattern' returns a Java pattern suitable for
-;; formatting date only, without time part. However, it is not
-;; required that formats are generated this way.
-;;
-;; Timestamp parsing is currently not implemented, but planned for a
-;; future version.
+;; formatting (or parsing) date only, without time part. However, it
+;; is not required that patterns are generated this way.
;;; Code:
