Package javolution.text

Text handling package.

See: Description

Class Summary

Class	Description
CharArray	A CharSequence backed up by a char array.
CharSet	A set of characters (typically used for parsing purpose where it is significantly faster than regular expressions for simple patterns).
Cursor	A parsing cursor over the characters read.
Text	An immutable character sequence with fast concatenation, insertion and deletion capabilities (O[Log(n)]) instead of O[n] for StringBuffer/StringBuilder).
TextBuilder	An Appendable text whose capacity expands gently without incurring expensive resize/copy operations ever.
TextContext	A context for plain text parsing/formatting.
TextFormat<T>	The service for plain text parsing and formatting; it supports CharSequence and Appendable interfaces for greater flexibility.
TypeFormat	Utility class to parse CharSequence into primitive types and to format primitive types into any Appendable.

Annotation Types Summary

Annotation Type	Description
DefaultTextFormat	Specifies the default text format of a class (for parsing/formatting).

Package javolution.text Description

Text handling package.

FAQ:

1. Is parsing/formatting of floating-points numbers (e.g. double) equivalent to standard String/Double methods?

   With Javolution 4.1, double formatting/parsing is lossless and functionally the same as with the standard library. Parsing a character sequence will always result in the same number whether it is performed with TypeFormat or using Double.parseDouble(String)). When formatting a double number, the number of digits output is adjustable. The default (if the number of digits is unspecified) is 17 or 16 when the the 16 digits representation can be parsed back to the same double (mimic the standard library formatting).

   Javolution parsing/formatting do not generate garbage and has no adverse effect on GC. Better, it does not force the user to create intermediate String objects, any CharSequence/Appendable can be used! Serial parsing is also supported (cursor parameter).

2. I'm accumulating a large string, and all I want to do is append to the end of the current string, which is the better class to use, Text or TextBuilder? Bearing in mind that speed is important, but I also want to conserve memory.

   It all depends of the size of the text to append (the actual size of the document being appended has almost no impact in both cases).

   If the text being appended is large (or arbitrarily large) then using Text is preferable.

   class FastCollection<T> {
        public final Text toText() {
            // We don't know the length of the text representation for
            // the collection's elements, we use Text concatenation 
            // to avoid copying what could be quite large.
            Text text = Text.valueOf("{");
            boolean isFirst = true;      
            for (T e : this) {
                 if (!isFirst) { text = text.plus(", "); isFirst = false; }      
                 text = text.plus(e);
            }
            return text.plus("}");
        }
   }

3. In our project's use of strings, there are a lot of instances of directory path names, such as "/proj/lodecase/src/com/lodecase/util/foo.java", and "/proj/lodecase/src/com/lodecase/util/bar.java". Can the 'Text' class save us memory when strings have common prefixes?

   It depends how you build your text. For example in following code:

   Text directoryName = Text.valueOf("/proj/lodecase/src/com/lodecase/util/");
   Text fooFileName = directoryName.plus("foo.java");
   Text barFileName = directoryName.plus("bar.java");

   The prefix (directoryName)is shared between fooFileName and barFileName.

   Text is a binary tree of blocks of characters. In the example, above, fooFileName is a node with directoryName for head and "foo.java" for tail. The tree is maintained balanced automatically through tree rotations.