License:
BSD style: see license.txtVersion:
Initial release: December 2005Author:
Kris Text is a class for managing and manipulating Unicode character arrays. Text maintains a current "selection", controlled via the select() and search() methods. Each of append(), prepend(), replace() and remove() operate with respect to the selection. The search() methods also operate with respect to the current selection, providing a means of iterating across matched patterns. To set a selection across the entire content, use the select() method with no arguments. Indexes and lengths of content always count code units, not code points. This is similar to traditional ascii string handling, yet indexing is rarely used in practice due to the selection idiom: substring indexing is generally implied as opposed to manipulated directly. This allows for a more streamlined model with regard to utf-surrogates. Strings support a range of functionality, from insert and removal to utf encoding and decoding. There is also an immutable subset called TextView, intended to simplify life in a multi-threaded environment. However, TextView must expose the raw content as needed and thus immutability depends to an extent upon so-called "honour" of a callee. D does not enable immutability enforcement at this time, but this class will be modified to support such a feature when it arrives - via the slice() method. The class is templated for use with char[], wchar[], and dchar[], and should migrate across encodings seamlessly. In particular, all functions in tango.text.Util are compatible with Text content in any of the supported encodings. In future, this class will become a principal gateway to the extensive ICU unicode library. Note that several common text operations can be constructed through combining tango.text.Text with tango.text.Util e.g. lines of text can be processed thusly:
1 2 3 4 | auto source = new Text!(char)("one\ntwo\nthree"); foreach (line; Util.lines(source.slice)) // do something with line |
1 2 3 4 | auto dst = new Text!(char); foreach (element; Util.delims ("all cows eat grass", " ")) dst.prepend (element); |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 | class Text(T) : TextView!(T) { // set or reset the content Text set (T[] chars, bool mutable=true); Text set (TextView other, bool mutable=true); // retrieve currently selected text T[] selection (); // set and retrieve current selection point Text point (uint index); uint point (); // mark a selection Text select (int start=0, int length=int.max); // return an iterator to move the selection around. // Also exposes "replace all" functionality Search search (T chr); Search search (T[] pattern); // format arguments behind current selection Text format (T[] format, ...); // append behind current selection Text append (T[] text); Text append (TextView other); Text append (T chr, int count=1); Text append (InputStream source); // transcode behind current selection Text encode (char[]); Text encode (wchar[]); Text encode (dchar[]); // insert before current selection Text prepend (T[] text); Text prepend (TextView other); Text prepend (T chr, int count=1); // replace current selection Text replace (T chr); Text replace (T[] text); Text replace (TextView other); // remove current selection Text remove (); // clear content Text clear (); // trim leading and trailing whitespace Text trim (); // trim leading and trailing chr instances Text strip (T chr); // truncate at point, or current selection Text truncate (int point = int.max); // reserve some space for inserts/additions Text reserve (int extra); // write content to stream Text write (OutputStream sink); } class TextView(T) : UniText { // hash content hash_t toHash (); // return length of content uint length (); // compare content bool equals (T[] text); bool equals (TextView other); bool ends (T[] text); bool ends (TextView other); bool starts (T[] text); bool starts (TextView other); int compare (T[] text); int compare (TextView other); int opEquals (Object other); int opCmp (Object other); // copy content T[] copy (T[] dst); // return content T[] slice (); // return data type typeinfo encoding (); // replace the comparison algorithm Comparator comparator (Comparator other); } class UniText { // convert content abstract char[] toString (char[] dst = null); abstract wchar[] toString16 (wchar[] dst = null); abstract dchar[] toString32 (dchar[] dst = null); } struct Search { // select prior instance bool prev(); // select next instance bool next(); // return instance count size_t count(); // contains instance? bool within(); // replace all with char void replace(T); // replace all with text (null == remove all) void replace(T[]); } |
Deprecated:
use point() insteadNote:
A character like 'a' will be implicitly converted to uint and thus will be accepted for this constructor, making it appear like you can initialize a Text instance with a single character, something which is not supported.Deprecated:
use point() instead
1 2 3 4 5 | auto t = new Text ("hello world"); auto s = t.search ("world"); assert (s.next); assert (t.selection == "world"); |
1 2 3 4 5 6 | auto t = new Text ("hello world"); auto s = t.search ("world"); // replace all instances of "world" with "everyone" assert (s.replace ("everyone")); assert (s.count is 0); |
Deprecated:
use search() insteadDeprecated:
use search() insteadDeprecated:
use search() insteadDeprecated:
use search() insteadDeprecated:
use search() insteadDeprecated:
use search() insteadDeprecated:
use format() insteadDeprecated:
use format() insteadDeprecated:
use format() instead
1 2 3 4 5 6 7 | Text string; wchar[] buffer; wchar[] result = string.utf16 (buffer); if (result.length > buffer.length) buffer = result; |