[COMMITTED] iscan-str.pk: add an usage example

[Jose E. Marchesi]

2023-10-28  Jose E. Marchesi  <jemarch@gnu.org>

        * pickles/iscan-str.pk: Add usage example.
---
 ChangeLog            |  4 ++++
 pickles/iscan-str.pk | 21 ++++++++++++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/ChangeLog b/ChangeLog
index 10dfdcbc..c7b96d8c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2023-10-28  Jose E. Marchesi  <jemarch@gnu.org>
+
+       * pickles/iscan-str.pk: Add usage example.
+
 2023-10-28  Jose E. Marchesi  <jemarch@gnu.org>
 
        * pickles/base64.pk: Use std's strchr.
diff --git a/pickles/iscan-str.pk b/pickles/iscan-str.pk
index 1b8c5441..86938a35 100644
--- a/pickles/iscan-str.pk
+++ b/pickles/iscan-str.pk
@@ -19,7 +19,26 @@
 /* This pickle provides facilities to scan strings (sequences of
    characters) stored in some IO space.  This is inspired by the
    string scanning generators provided by the Icon programming
-   language.  */
+   language.
+
+   Usage example (read lines from /etc/password):
+
+     load iscan;
+
+     var iscan = IScan_String { };
+     var lines = string[][]();
+     for (eol in iscan.find ("\n"))
+       {
+         var line = string[]();
+         for (sep in iscan.find (":", eol))
+           {
+             apush (line, iscan.tab (sep));
+             iscan.move (1#B);
+           }
+         apush (lines, line);
+         iscan.move (1#B);
+       }
+ */
 
 type IScan_String =
   struct
-- 
2.30.2