oracle.ide.util
Class DelimitedStrings

java.lang.Object
  oracle.ide.util.DelimitedStrings

public class DelimitedStrings

extends java.lang.Object

Delimited strings can be very useful for storing text, numeric and date values in a recoverable way for a readable file. A format supported by most databases and spreadsheets, it is based around a set of simple rules for parsing and constructing these strings.

1. All values in the file are separated by occurrences of the field delimiter (or separator). This is usually either a comma or a tab.
   ie. [one,two,three,four,seventy-nine]
2. Where whitespace is to be preserved, the value should be placed in text qualifiers, usually double-quotes.
   ie. [yellow,green,"light blue",white,"dark red"]
3. Where the text qualifier character occurs in the value as data, it must be escaped by means of a repetition (two consecutive).
   ie. " -> ""
4. If the above case applies to a value, or the field separator occurs in the value as data, the value must also be placed in text qualifiers.
   ie. ["""please_keep_the_quotes""","please,_keep_the_comma"]

If the text qualifier is given as null, it is trusted that no whitespace needs preserving from values and that the field separator does not occur in data (as no special delimiting rules will apply).

Constructor Summary

DelimitedStrings(char delimiter, char qualifier)
Construct a new DelimitedStrings object for the purpose of parsing and formatting strings (using the given delimiter and qualifier).

DelimitedStrings(java.lang.String delimiters, java.lang.Character qualifier)
Construct a new DelimitedStrings object for the purpose of parsing and formatting strings.

Method Summary

java.lang.String	format(java.lang.String[] values) Format the given array of values into a delimited String, according to the indicated delimiter style.
static DelimitedStrings	getCommaSeparatedInstance() Retrieve a delimited strings parser / formatter suitable for dealing with comma-separated value strings, a popular style.
static DelimitedStrings	getTabSeparatedInstance() Retrieve a delimited strings parser / formatter suitable for dealing with tab delimited value strings, a popular style.
java.lang.String[]	parse(java.lang.String values) Parse the given String of delimited values into an array, according to the indicated delimiter style.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DelimitedStrings

public DelimitedStrings(char delimiter,
                        char qualifier)

Construct a new DelimitedStrings object for the purpose of parsing and formatting strings (using the given delimiter and qualifier).

Parameters:

qualifier - text qualifier to use in the parsing

DelimitedStrings

public DelimitedStrings(java.lang.String delimiters,
                        java.lang.Character qualifier)

Construct a new DelimitedStrings object for the purpose of parsing and formatting strings. This constructor allows the specification of more than one field delimiter, or the absence of a text delimiter.

Parameters:

delimiters - field separators to use in the parsing (must be non-null and contain a character).

qualifier - text qualifier to use in the parsing, or no text qualifier if null.

Method Detail

parse

public final java.lang.String[] parse(java.lang.String values)

Parse the given String of delimited values into an array, according to the indicated delimiter style. Notes; zero length Strings are considered to have a single value, and two field delimiters in succession (even tabs) is interpreted to be an empty value. Parsing a non-null String should under no circumstances cause failure.

Parameters:

values - the delimited value String.

Returns:

an array containing the separated, extracted values

format

public final java.lang.String format(java.lang.String[] values)

Format the given array of values into a delimited String, according to the indicated delimiter style. A zero-length array will give rise to an empty String. The result of formatting is often relatively compact, as whitespace is not used for legibility. Formatting a non-null array should under no circumstances cause failure.

Parameters:

values - an array containing String values.

Returns:

a String containing the joined & delimited values

getCommaSeparatedInstance

public static final DelimitedStrings getCommaSeparatedInstance()

Retrieve a delimited strings parser / formatter suitable for dealing with comma-separated value strings, a popular style.

Returns:

the staticly created DelimitedStrings instance for CSV.

getTabSeparatedInstance

public static final DelimitedStrings getTabSeparatedInstance()

Retrieve a delimited strings parser / formatter suitable for dealing with tab delimited value strings, a popular style.

Returns:

the staticly created DelimitedStrings instance for TSV.