commit bench folder (also committing examples folder but that's kind of broken at this state)

examples/examples.mlb

@@ -0,0 +1,6 @@
+$(SML_LIB)/basis/basis.mlb
+
+tiny_rope.sml
+tiny_rope23.sml
+rope.sml
+examples.sml

examples/examples.sml

@@ -0,0 +1,139 @@
+(* An empty rope, containing no strings. *)
+val rope = Rope.empty;
+
+(* Initialise rope from a string. 
+ *
+ * You probably want to avoid initialising the rope with very long strings,
+ * because a rope is meant to represent a long string 
+ * by holding nodes that contain smaller strings in a binary tree. 
+ * The implementation avoids building strings that are ever larger than 1024,
+ * but that was done in an attempt to find the ideal length for performance. 
+ * A user shouldn't notice any delays in larger lengths like 65535 either. 
+ *
+ * In their text buffer (a piece-tree, which is slower than a rope), 
+ * the VS Code team had other issues with excessively large strings.
+ * https://code.visualstudio.com/blogs/2018/03/23/text-buffer-reimplementation#_avoid-the-string-concatenation-trap *)
+val rope = Rope.fromString "hello, world!\n";
+
+(* Convert a rope to a string.
+ *
+ * This may involve allocating an extremely large string in some cases,
+ * which should be avoided for the reason mentioned in the above comment. *)
+val str = Rope.toString rope;
+
+(* Insert a string into the rope. 
+ *
+ * There isn't any validation to check that you inserted at a reasonable
+ * position. 
+ * If you insert at an index lower than 0, your inserted string is just
+ * prepended to the start. 
+ * If you insert at an index greater than the length, your inserted string is
+ * just appended to the end.
+ *
+ * One thing to watch out for if you are using the line-rope is making sure 
+ * that you don't insert in the middle of a \r\n pair, separating \r from \n. 
+ * That would mess up the line metadata the rope contains and make the line
+ * metadata invalid. *)
+val rope = Rope.insert (14, "goodbye, world!", rope);
+
+(* Append a string into the rope. *)
+val rope = Rope.append ("hello again\n", rope);
+
+(* Append a string into the rope, providing line metadata with it. 
+ *
+ * The point of this function is for performance: the other insertion functions
+ * calculate the line metadata by scanning the string itself, but in some cases
+ * this is already known. The larger example below is such a case. *)
+val rope = Rope.appendLine ("my new line", Vector.fromList [], rope);
+
+(** Second larger example motivating String.appendLine below. *)
+(*** Returns the start index of a line, 
+ *** returning the index of \r if line ends with a \r\n pair. *)
+fun getLineStart line =
+  let
+    val lastIdx = String.size line - 1
+    val lastChr = String.sub (line, lastIdx)
+  in
+    if lastChr = #"\n" andalso lastIdx - 1 >= 0 then
+      if String.sub (line, lastIdx - 1) = #"\r" then lastIdx - 1 else lastIdx
+    else
+      lastIdx
+  end;
+
+(*** Appends the lines in a file to a rope. *)
+fun readLines (rope, file) =
+  case TextIO.inputLine file of
+    SOME line =>
+      let
+        (* Don't need to scan string to find line breaks, 
+         * because we already know. *)
+        val lineIdx = getLineStart (line)
+        val vec = Vector.fromList [lineIdx]
+        val rope = Rope.appendLine (line, vec, rope)
+      in
+        readLines (rope, file)
+      end
+  | NONE => rope;
+
+val licenseRope = readLines (Rope.empty, TextIO.openIn "LICENSE");
+
+(* Deletes the given range from rope, from the start index to the end index. 
+ *
+ * As with insert, one should make sure they don't corrupt the line metadata. 
+ * Specifically, in a \r\n pair, the line metadata points to \r. 
+ * Deleting \r would corrupt it, but deleting \n would be fine. 
+ * In general, if you want to delete a line break, you would want to delete both
+ * \r and \n. The user thinks of the \r\n pair as a single character so they are
+ * expecting the whole line break to be deleted. *)
+
+(** Initialise new rope. *)
+val rope = Rope.fromString "hello, world!";
+(** New rope contains "hello world!" without comma. *)
+val rope = Rope.delete (5, 1, rope);
+
+(* Folds over the characters in a rope, starting from the given index. 
+ *
+ * This is meant to be an alternative to queries for a specific line or a
+ * substring.
+ * If a rope is meant to avoid allocating large strings, then it seems more
+ * performant to query its contents through higher-order functions rather than 
+ * allocating substrings and querying the substring. *)
+val rope = Rope.fromString "hello!";;
+
+fun apply (chr, lst) = chr :: lst;
+(** val result = [#"!",#"o",#"l",#"l",#"e"] : char list *)
+val result = Rope.foldFromIdx (apply, 1, rope, []);
+
+(* Folds over the characters in a rope, accepting a predicate function
+ * that terminates the fold when it returns true. *)
+fun apply (chr, acc) =
+  (print (Char.toString chr); acc + 1);
+
+fun term acc = acc = 3;
+
+(** Below function prints first three letters, "hel", 
+ ** and then steops folding. *)
+val _ = Rope.foldFromIdxTerm (apply, term, 0, rope, 0);
+
+(* Folds over the characters in a rope, starting from the given line number.
+ * 
+ * This is just like the foldFromIdxTerm function, except that it starts folding
+ * from the given line number instead. *)
+val rope = Rope.fromString "hello, world!\ngoodbye, world!\nhello again!";
+
+fun apply (chr, _) =
+  print (Char.toString chr);
+
+fun term _ = false;
+
+(** Below line prints the whole string, one character at a time. *)
+Rope.foldLines (apply, term, 0, rope, ());
+(** Prints starting from #"g" in "goodbye". *)
+Rope.foldLines (apply, term, 1, rope, ());
+(** Prints the very last line. *)
+Rope.foldLines (apply, term, 2, rope, ());
+
+(** Prints the whole string if specifying a line before 0, which doesn't exist. *)
+Rope.foldLines (apply, term, ~3, rope, ());
+(** Raises a subscript exception: there is no corresponding line in the rope. *)
+Rope.foldLines (apply, term, 4, rope, ());