|
Generated by JDiff |
||||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packagejava.text
as colored differences. Deletions are shownlike this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.
Constant that is returned when the iterator has reached either the end or the beginning of the text. Theunicode 2.0 standard statesvaluethatis '\\uFFFF'isthean"notinvalidaunicodecharacter" valueandwhich should not occur in any validunicodeUnicode string.
AChoiceFormat
allows you to attach a format to a range of numbers. It is generally used in aMessageFormat
for handling plurals. The choice is specified with an ascending list of doubles where each item specifies a half-open interval up to the next item:If there is no match then either the first or last index is used depending on whether the number (X) is too low or too high. If the limit array is not in ascending order the results of formatting will be incorrect. ChoiceFormat also acceptsX matches j if and only if limit[j] <= X < limit[j+1]as equivalent to infinity(INF).
\\\u221ENote:
ChoiceFormat
differs from the otherFormat
classes in that you create aChoiceFormat
object with a constructor (not with agetInstance
style factory method). The factory methods aren't necessary becauseChoiceFormat
doesn't require any complex setup for a given locale. In factChoiceFormat
doesn't implement any locale specific behavior.When creating a
ChoiceFormat
you must specify an array of formats and an array of limits. The length of these arrays must be the same. For example
- limits = {1 2 3 4 5 6 7}
formats = {"Sun" "Mon" "Tue" "Wed" "Thur" "Fri" "Sat"}- limits = {0 1 ChoiceFormat.nextDouble(1)}
formats = {"no files" "one file" "many files"}
(nextDouble
can be used to get the next higher double to make the half-open interval.)Here is a simple example that shows formatting and parsing:
Here is a more complex example with a pattern format:double[] limits = {1 2 3 4 5 6 7}; String[] monthNames = {"Sun" "Mon" "Tue" "Wed" "Thur" "Fri" "Sat"}; ChoiceFormat form = new ChoiceFormat(limits monthNames); ParsePosition status = new ParsePosition(0); for (double i = 0.0; i <= 8.0; ++i) { status.setIndex(0); System.out.println(i + " -> " + form.format(i) + " -> " + form.parse(form.format(i) status)); }double[] filelimits = {0 1 2}; String[] filepart = {"are no files" "is one file" "are {2} files"}; ChoiceFormat fileform = new ChoiceFormat(filelimits filepart); Format[] testFormats = {fileform null NumberFormat.getInstance()}; MessageFormat pattform = new MessageFormat("There {0} on {1}"); pattform.setFormats(testFormats); Object[] testArgs = {null "ADisk" null}; for (int i = 0; i < 4; ++i) { testArgs[0] = new Integer(i); testArgs[2] = testArgs[0]; System.out.println(pattform.format(testArgs)); }Specifying a pattern for ChoiceFormat objects is fairly straightforward. For example:
And the output result would be like the following:ChoiceFormat fmt = new ChoiceFormat( "-1#is negative| 0#is zero or fraction | 1#is one |1.0<is 1+ |2#is two |2<is more than 2."); System.out.println("Formatter Pattern : " + fmt.toPattern()); System.out.println("Format with -INF : " + fmt.format(Double.NEGATIVE_INFINITY)); System.out.println("Format with -1.0 : " + fmt.format(-1.0)); System.out.println("Format with 0 : " + fmt.format(0)); System.out.println("Format with 0.9 : " + fmt.format(0.9)); System.out.println("Format with 1.0 : " + fmt.format(1)); System.out.println("Format with 1.5 : " + fmt.format(1.5)); System.out.println("Format with 2 : " + fmt.format(2)); System.out.println("Format with 2.1 : " + fmt.format(2.1)); System.out.println("Format with NaN : " + fmt.format(Double.NaN)); System.out.println("Format with +INF : " + fmt.format(Double.POSITIVE_INFINITY));Format with -INF : is negative Format with -1.0 : is negative Format with 0 : is zero or fraction Format with 0.9 : is zero or fraction Format with 1.0 : is one Format with 1.5 : is 1+ Format with 2 : is two Format with 2.1 : is more than 2. Format with NaN : is negative Format with +INF : is more than 2.
Choice formats are not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently it must be synchronized externally. @see DecimalFormat @see MessageFormat @version 1.22 09/21/98 @author Mark Davis
Class ChoiceFormat, constructor ChoiceFormat(String)
Constructs with limits and corresponding formats based on the pattern. @see #applyPattern
TheCollationElementIterator
class is used as an iterator to walk through each character of an international string. Use the iterator to return the ordering priority of the positioned character. The ordering priority of a character which we refer to as a key defines how a character is collated in the given collation object.For example consider the following in Spanish:
And in German"ca" -> the first key is key('c') and second key is key('a'). "cha" -> the first key is key('ch') and second key is key('a').The key of a character is an integer composed of primary order(short) secondary order(byte) and tertiary order(byte). Java strictly defines the size and signedness of its primitive data types. Therefore the static functions"äb"-> the first key is key('a') the second key is key('e') and the third key is key('b').primaryOrder
secondaryOrder
andtertiaryOrder
returnint
short
andshort
respectively to ensure the correctness of the key value.Example of the iterator usage
// get the first key of the stringStringstrtestString = "This is a test";CollationElementIteratorRuleBasedCollatorcruleBasedCollator =new CollationElementIterator(str 0 str.length(RuleBasedCollator)Collator.getInstance(); CollationElementIterator collationElementIterator = ruleBasedCollator.getCollationElementIterator(testString); int primaryOrder = CollationElementIterator.primaryOrder(c-collationElementIterator.next());
CollationElementIterator.next
returns the collation order of the next character. A collation order consists of primary order secondary order and tertiary order. The data type of the collation order is int. The first 16 bits of a collation order is its primary order; the next 8 bits is the secondary order and the last 8 bits is the tertiary order. @see Collator @see RuleBasedCollator @version 1.24 07/27/98 @author Helena Shih Laura Werner Richard Gillam
ACollationKey
represents aString
under the rules of a specificCollator
object. Comparing twoCollationKey
s returns the relative order of theString
s they represent. UsingCollationKey
s to compareString
s is generally faster than usingCollator.compare
. Thus when theString
s must be compared multiple times for example when sorting a list ofString
s. It's more efficient to useCollationKey
s.You can not create
CollationKey
s directly. Rather generate them by callingCollator.getCollationKey
. You can only compareCollationKey
s generated from the sameCollator
object.Generating a
CollationKey
for aString
involves examining the entireString
and converting it to series of bits that can be compared bitwise. This allows fast comparisons once the keys are generated. The cost of generating keys is recouped in faster comparisons whenString
s need to be compared many times. On the other hand the result of a comparison is often determined by the first couple of characters of eachString
.Collator.compare
examines only as many characters as it needs which allows it to be faster when doing single comparisons.The following example shows how
CollationKey
s might be used to sort a list ofString
s.@see Collator @see RuleBasedCollator @version 1.// Create an array of CollationKeys for the Strings to be sorted. Collator myCollator = Collator.getInstance(); CollationKey[] keys = new CollationKey[3]; keys[0] = myCollator.getCollationKey("Tom"); keys[1] = myCollator.getCollationKey("Dick"); keys[2] = myCollator.getCollationKey("Harry"); sort( keys );
//...
// Inside body of sort routine compare keys this way if( keys[i].compareTo( keys[j] ) > 0 ) // swap keys[i] and keys[j]
//...
// Finally when we've returned from sort. System.out.println( keys[0].getSourceString() ); System.out.println( keys[1].getSourceString() ); System.out.println( keys[2].getSourceString() );14 0115 12/1903/0001 @author Helena Shih
TheClass Collator, int CANONICAL_DECOMPOSITIONCollator
class performs locale-sensitiveString
comparison. You use this class to build searching and sorting routines for natural language text.
Collator
is an abstract base class. Subclasses implement specific collation strategies. One subclassRuleBasedCollator
is currently provided with the Java 2 platform and is applicable to a wide set of languages. Other subclasses may be created to handle more specialized needs.Like other locale-sensitive classes you can use the static factory method
getInstance
to obtain the appropriateCollator
object for a given locale. You will only need to look at the subclasses ofCollator
if you need to understand the details of a particular collation strategy or if you need to modify that strategy.The following example shows how to compare two strings using the
Collator
for the default locale.// Compare two strings in the default locale Collator myCollator = Collator.getInstance(); if( myCollator.compare("abc" "ABC") <0 ) System.out.println("abc is less than ABC"); else System.out.println("abc is greater than or equal to ABC");You can set a
Collator
's strength property to determine the level of difference considered significant in comparisons. Four strengths are provided:PRIMARY
SECONDARY
TERTIARY
andIDENTICAL
. The exact assignment of strengths to language features is locale dependant. For example in Czech "e" and "f" are considered primary differences while "e" and "ê" are secondary differences "e" and "E" are tertiary differences and "e" and "e" are identical. The following shows how both case and accents could be ignored for US English.//Get the Collator for US English and set its strength to PRIMARY Collator usCollator = Collator.getInstance(Locale.US); usCollator.setStrength(Collator.PRIMARY); if( usCollator.compare("abc" "ABC") == 0 ) { System.out.println("Strings are equivalent"); }For comparing
String
s exactly once thecompare
method provides the best performance. When sorting a list ofString
s however it is generally necessary to compare eachString
multiple times. In this caseCollationKey
s provide better performance. TheCollationKey
class converts aString
to a series of bits that can be compared bitwise against otherCollationKey
s. ACollationKey
is created by aCollator
object for a givenString
.
Note:CollationKey
s from differentCollator
s can not be compared. See the class description for CollationKey for an example usingCollationKey
s. @see RuleBasedCollator @see CollationKey @see CollationElementIterator @see Locale @version 1.27 0132 12/1903/0001 @author Helena Shih Laura Werner Richard Gillam
Decomposition mode value. With CANONICAL_DECOMPOSITION set characters that are canonical variants according to Unicode 2.0 will be decomposed for collation. ThisClass Collator, int FULL_DECOMPOSITIONis the default setting andshould be used to get correct collation of accented characters.CANONICAL_DECOMPOSITION corresponds to Normalization Form D as described in Unicode Technical Report #15. @see java.text.Collator#getDecomposition @see java.text.Collator#setDecomposition
Decomposition mode value. With FULL_DECOMPOSITION set both Unicode canonical variants and Unicode compatibility variants will be decomposed for collation. This causes not only accented characters to be collated but also characters that have special formats to be collated with their norminal form. For example the half-width and full-width ASCII and Katakana characters are then collated together. FULL_DECOMPOSITION is the most complete and therefore the slowest decomposition mode.Class Collator, int NO_DECOMPOSITIONFULL_DECOMPOSITION corresponds to Normalization Form
DCKD as described in Unicode Technical Report #15. @see java.text.Collator#getDecomposition @see java.text.Collator#setDecomposition
Decomposition mode value. With NO_DECOMPOSITION set accented characters will not be decomposed for collation. This is the default setting and provides the fastest collation but will only produce correct results for languages that do not use accents. @see java.text.Collator#getDecomposition @see java.text.Collator#setDecomposition
DateFormat is an abstract class for date/time formatting subclasses which formats and parses dates or time in a language-independent manner. The date/time formatting subclass such as SimpleDateFormat allows for formatting (i.e. date -> text) parsing (text -> date) and normalization. The date is represented as aClass DateFormat, StringBuffer format(Date, StringBuffer, FieldPosition)Date
object or as the milliseconds since January 1 1970 00:00:00 GMT.DateFormat provides many class methods for obtaining default date/time formatters based on the default or a given
loaclelocale and a number of formatting styles. The formatting styles include FULL LONG MEDIUM and SHORT. More detail and examples of using these styles are provided in the method descriptions.DateFormat helps you to format and parse dates for any locale. Your code can be completely independent of the locale conventions for months days of the week or even the calendar format: lunar vs. solar.
To format a date for the current Locale use one of the static factory methods:
myString = DateFormat.getDateInstance().format(myDate);If you are formatting multiple
numbersdates it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.DateFormat df = DateFormat.getDateInstance(); for (int i = 0; iTo format a
numberdate for a different Locale specify it in the call to getDateInstance().DateFormat df = DateFormat.getDateInstance(DateFormat.LONG Locale.FRANCE);
You can use a DateFormat to parse also.
myDate = df.parse(myString);Use getDateInstance to get the normal date format for that country. There are other static factory methods available. Use getTimeInstance to get the time format for that country. Use getDateTimeInstance to get a date and time format. You can pass in different options to these factory methods to control the length of the result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the locale but generally:
- SHORT is completely numeric such as 12.13.52 or 3:30pm
- MEDIUM is longer such as Jan 12 1952
- LONG is longer such as January 12 1952 or 3:30:32pm
- FULL is pretty completely specified such as Tuesday April 12 1952 AD or 3:30:42pm PST.
You can also set the time zone on the format if you wish. If you want even more control over the format or parsing (or want to give your users more control) you can try casting the DateFormat you get from the factory methods to a SimpleDateFormat. This will work for the majority of countries; just remember to put it in a try block in case you encounter an unusual one.
You can also use forms of the parse and format methods with ParsePosition and FieldPosition to allow you to
- progressively parse through pieces of a string.
- align any particular field or find out where it is for selection on the screen.
Synchronization
Date formats are not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently it must be synchronized externally. @see Format @see NumberFormat @see SimpleDateFormat @see java.util.Calendar @see java.util.GregorianCalendar @see java.util.TimeZone @version 1.
38 0145 12/1903/0001 @author Mark Davis Chen-Lieh Huang Alan Liu
Formats a Date into a date/time string. @param date a Date to be formatted into a date/time string. @param toAppendTo the string buffer for the returning date/time string. @param fieldPosition keeps track of the position of the field within the returned string. On input: an alignment field if desired. On output: the offsets of the alignment field. For example given a time text "1996.07.10 AD at 15:08:56 PDT" if the given fieldPosition is DateFormat.YEAR_FIELD the begin index and end index of fieldPosition will be set to 0 and 4 respectively. Notice that if the same time field appears more than once in a pattern the fieldPosition will be set for the firstClass DateFormat, StringBuffer format(Object, StringBuffer, FieldPosition)occurenceoccurrence of that time field. For instance formatting a Date to the time string "1 PM PDT (Pacific Daylight Time)" using the pattern "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD the begin index and end index of fieldPosition will be set to 5 and 8 respectively for the firstoccurenceoccurrence of the timezone pattern character 'z'. @return the formatted date/time string.
Overrides Format. Formats a time object into a time string. Examples of time objects are a time value expressed in milliseconds and a Date object. @param obj must be a Number or a Date. @param toAppendTo the string buffer for the returning time string. @return the formatted time string. @param fieldPosition keeps track of the position of the field within the returned string. On input: an alignment field if desired. On output: the offsets of the alignment field. For example given a time text "1996.07.10 AD at 15:08:56 PDT" if the given fieldPosition is DateFormat.YEAR_FIELD the begin index and end index of fieldPosition will be set to 0 and 4 respectively. Notice that if the same time field appears more than once in a pattern the fieldPosition will be set for the firstClass DateFormat, Date parse(String)occurenceoccurrence of that time field. For instance formatting a Date to the time string "1 PM PDT (Pacific Daylight Time)" using the pattern "h a z (zzzz)" and the alignment field DateFormat.TIMEZONE_FIELD the begin index and end index of fieldPosition will be set to 5 and 8 respectively for the firstoccurenceoccurrence of the timezone pattern character 'z'. @see java.text.Format
Class DateFormat, Date parse(String, ParsePosition)ParseParses text from the beginning of the given string to produce a date/time. The method may not use the entire text of the given string.See the ParsePosition) method for more information on date parsing. @param
text Thesource Adate/timeString
stringwhosetobeginning should be parsed. @return ADate
or nullparsediffrom theinput could not be parsedstring. @exception ParseExceptionIfif thegivenbeginning of the specified string cannot be parsedas a date.@see #parse(String ParsePosition)
Parse a date/time string according to the given parse position. For example a time text "07/10/96 4:5 PM PDT" will be parsed into a Date that is equivalent to Date(837039928046).Class DateFormat, Object parseObject(String, ParsePosition)By default parsing is lenient: If the input is not in the form used by this object's format method but can still be parsed as a date then the parse succeeds. Clients may insist on strict adherence to the format by calling setLenient(false). @see java.text.DateFormat#setLenient(boolean) @param
textsource The date/time string to be parsed @param pos On input the position at which to start parsing; on output the position at which parsing terminated or the start position if the parse failed. @return A Date or null if the input could not be parsed
Parse aParses textdate/timefrom a stringintotoanproduce aObjectDate
.This convenienceThe method
simplyattemptscallsto parse text starting at the index given bypos
. If parsing succeeds then the index ofpos
is updated to the index after the last character used (Stringparsing does not necessarily use all characters up to the end of the string) and the parsed date is returned. The updatedpos
can be used to indicate the starting point for the next call to this method. If an error occurs then the index ofpos
is not changed the error index ofpos
is set to the index of the character where the error occurred and null is returned. ParsePosition) method for more information on date parsing. @seeparam#parse(source AString part of which should be parsed. @param pos A
ParsePosition
)object with index and error index information as described above. @return ADate
parsed from the string. In case of error returns null. @exception NullPointerException ifpos
is null.
Class DateFormatSymbols, String[] getAmPmStrings()DateFormatSymbols
is a public class for encapsulating localizable date-time formatting data such as the names of the months the names of the days of the week and the time zone data.DateFormat
andSimpleDateFormat
both useDateFormatSymbols
to encapsulate this information.Typically you shouldn't use
DateFormatSymbols
directly. Rather you are encouraged to create a date-time formatter with theDateFormat
class's factory methods:getTimeInstance
getDateInstance
orgetDateTimeInstance
. These methods automatically create aDateFormatSymbols
for the formatter so that you don't have to. After the formatter is created you may modify its format pattern using thesetPattern
method. For more information about creating formatters usingDateFormat
's factory methods see DateFormatIf you decide to create a date-time formatter with a specific format pattern for a specific locale you can do so with:
new SimpleDateFormat(aPattern new DateFormatSymbols(aLocale)).
DateFormatSymbols
objects areclonablecloneable. When you obtain aDateFormatSymbols
object feel free to modify the date-time formatting data. For instance you can replace the localized date-time format pattern characters with the ones that you feel easy to remember. Or you can change the representative cities to your favorite ones.New
DateFormatSymbols
subclasses may be added to supportSimpleDateFormat
for date-time formatting for additional locales. @see DateFormat @see SimpleDateFormat @see java.util.SimpleTimeZone @version 1.32390112/1903/0001 @author Chen-Lieh Huang
Gets ampm strings. For example: "AM" and "PM". @return theweekdayampm strings.
Class DecimalFormat, constructor DecimalFormat()DecimalFormat
is a concrete subclass ofNumberFormat
that formats decimal numbers. It has a variety of features designed to make it possible to parse and format numbers in any locale including support for Western Arabic and Indic digits. It also supports different kinds of numbers including integers (123) fixed-point numbers (123.4) scientific notation (1.23E4) percentages (12%) and currency amounts ($123). All of these can be localized.To obtain a
NumberFormat
for a specific locale including the default locale call one ofNumberFormat
's factory methods such asgetInstance()
. In general do not call theDecimalFormat
constructors directly since theNumberFormat
factory methods may return subclasses other thanDecimalFormat
. If you need to customize the format object do something like this:NumberFormat f = NumberFormat.getInstance(loc); if (f instanceof DecimalFormat) { ((DecimalFormat) f).setDecimalSeparatorAlwaysShown(true); }A
DecimalFormat
comprises a pattern and a set of symbols. The pattern may be set directly usingapplyPattern()
or indirectly using the API methods. The symbols are stored in aDecimalFormatSymbols
object. When using theNumberFormat
factory methods the pattern and symbols are read from localizedResourceBundle
sin the.packagePatterns
java.text.resourceDecimalFormat. Example// Print out a numberpatternsusinghave thelocalized number currency // and percent format for each locale Locale[] locales = NumberFormat.getAvailableLocales(); double myNumber = -1234.56; NumberFormat form; forfollowing(intsyntax:j=0;j;Pattern:++j)PositivePattern{PositivePatternSystem.out.println("FORMAT");forNegativePattern(intPositivePattern:iPrefixopt=Number0;SuffixoptiNegativePattern:locales.length;Prefixopt++i)Number{SuffixoptifPrefix:(locales[i].getCountry().length()any==Unicode0)characters{exceptcontinue\;// Skip language-onlyuFFFElocales } System.out.print(locales[i].getDisplayName())\;switchuFFFF(j)and{ casespecial characters0Suffix:form= NumberFormat.getInstance(locales[i]); break; case 1:anyform =Unicode charactersNumberFormat.getCurrencyInstance(locales[i]);exceptbreak\;default: form =uFFFENumberFormat.getPercentInstance(locales[i])\;uFFFFbreak;and} tryspecial characters{Number://IntegerAssumeExponentoptformIntegeris.aFractionDecimalFormatExponentoptSystem.out.print("Integer:" +((DecimalFormat)MinimumIntegerform).toPattern()#+#"Integer-#"Integer+MinimumInteger:form.format(myNumber));0}0catchMinimumInteger(IllegalArgumentException0e)MinimumInteger{}Fraction:tryMinimumFractionopt{OptionalFractionoptSystem.out.println("MinimumFraction:-0"MinimumFractionopt+OptionalFraction:form.parse(form.format(myNumber)));#}OptionalFractionoptcatchExponent:(ParseExceptionEe)MinimumExponent{}MinimumExponent:}0}MinimumExponentopt
PatternsADecimalFormat
pattern contains apostivepositive and negative subpattern for example"# ##0.00;(# ##0.00)"
. Each subpattern has a prefix numeric part and suffix. The negative subpattern is optional; if absent then the positive subpattern prefixed with the localized minus sign (code>'-' in most locales) is used as the negative subpattern. That is"0.00"
alone is equivalent to"0.00;-0.00"
. If there is an explicit negative subpattern it serves only to specify the negative prefix and suffix; the number of digits minimal digits and other characteristics are all the same as the positive pattern. That means that"# ##0.0#;(#)"
produces precisely the same behavior as"# ##0.0#;(# ##0.0#)"
.The prefixes suffixes and various symbols used for infinity digits thousands separators decimal separators etc. may be set to arbitrary values and they will appear properly during formatting. However care must be taken that the symbols and strings do not conflict or parsing will be unreliable. For example either the positive and negative prefixes or the suffixes must be distinct for
DecimalFormat.parse()
to be able to distinguish positive from negative values. (If they are identical thenDecimalFormat
will behave as if no negative subpattern was specified.) Another example is that the decimal separator and thousands separator should be distinct characters or parsing will be impossible.The grouping separator is commonly used for thousands but in some countries it separates ten-thousands. The grouping size is a constant number of digits between the grouping characters such as 3 for 100 000 000 or 4 for 1 0000 0000. If you supply a pattern with multiple grouping characters the interval between the last one and the end of the integer is the one that is used. So
"# ## ### ####"
=="###### ####"
=="## #### ####"
.Illegal patternsSpecial
suchPatternasCharacters"#.#.#"Many
orcharacters"#.###in###"awill causepattern areDecimalFormattakentoliterally;throw anthey areIllegalArgumentExceptionmatchedwith a message that describes the problemduring parsing and output unchanged during formatting.Parsing DecimalFormat parses all UnicodeSpecial charactersthat representondecimal digits as defined bythe other hand stand forCharacter.digit().otherIn additioncharacters stringsDecimalFormatoralso recognizesclasses ofascharacters.digits the ten consecutive characters starting with the localized zero digit definedThey must be quoted unless noted otherwise if they are to appear in theDecimalFormatSymbols object. During formatting theprefixDecimalFormatSymbols-basedordigits are outputsuffix as literals.
DecimalFormat.parse returns aThesubclass ofcharacters listedjava.lang.Numberhererepresenting the parsedare used innumericnon-localizedstringpatterns.DecimalFormat chooses the most economical subclass thatLocalizedcan representpatterns use thenumeric string. This means mostcorrespondinginteger values are returnedcharacters taken from thisasformatter's
LongDecimalFormatSymbolsobjects noobjectmatter how they areinstead and these characterswritten:lose"17"theirandspecial"17status.000"both parse toTwoLong(17).exceptionsValues that cannot fit into aare the currency sign and quoteLongwhich arereturned asnotDoubleslocalized.This includesScientific Notationvalues with
aSymbol fractionalLocation partLocalized infiniteMeaning values
NaN0andNumber theYes valueDigit -0.0.
DecimalFormat#does not decideNumber whetherYes toDigit return azero showsDoubleasor aabsent
Long.basedNumber onYes theDecimal presence of aseparator or monetary decimal separatorin the sourcestring. Doing so-
wouldNumber preventYes integersMinus that overflowsignthe
mantissaofNumber aYes doubleGrouping such asseparator"10E
000Number 000Yes 000Separates 000mantissa000.00"andfrom being parsed accuratelyexponent in scientific notation.Currently theNeedonly classes thatnot be quotedDecimalFormatinreturns areprefix orLongsuffix.and
Double;but callers should not rely onSubpattern this.boundaryCallersYes maySeparates use thepositive andNumbernegativemethodssubpatternsdoubleValue
longValue%etc. to obtain the type theyPrefix want.orIfsuffixDecimalFormat.parse(StringYes ParsePosition)Multiply fails to parse a string it returnsby 100 and show as percentage
null\u2030leaves thePrefix ParsePositionorindexsuffixunchangedYes andMultiply sets theby 1000ParsePositionanderrorshowindex.asThe convenience methodper mille
DecimalFormat.parse(String)¤indicates parse failure by throwing a(
ParseException\u00A4. Special)ValuesPrefix NaNorissuffixformattedNo asCurrency a single character typicallysign replaced by currency\uFFFDsymbol.This characterIfis determineddoubled replaced bytheinternationalDecimalFormatSymbolscurrencyobjectsymbol.This is theIfonly value for whichpresent in a pattern theprefixes andmonetarysuffixes are notdecimal separator is used. Infinityis formattedinsteadas a singleof the decimalcharacterseparator.typically
\u221E'with the positivePrefix or negative prefixes andsuffixsuffixesNo applied.Used The infinity character is determined by theto quote special characters in a prefixDecimalFormatSymbolsorobject.suffixNegativeforzero (example"
-0'#'#")parsesformats 123 to.
Double(-0.0)"#123"unlessToisParseIntegerOnly()createis true in which case it parsesa single quote itself use two intoa row:.
Long(0)"# o''clock"Numbers in scientific notation are expressed as the product of a mantissa and a power of ten for example 1234 can be expressed as 1.234 x 10^3. The mantissa is often in the range 1.0 < x <10.0 but it need not be.
DecimalFormat
can be instructed to format and parse scientific notation only via a pattern; there is currently no factory method that creates a scientific notation format. In a pattern the exponent character immediately followed by one or more digit characters indicates scientific notation. Example:"0.###E0"
formats the number 1234 as"1.234E3"
.
- The number of digit characters after the exponent character gives the minimum exponent digit count. There is no maximum. Negative exponents are formatted using the localized minus sign not the prefix and suffix from the pattern. This allows patterns such as
"0.###E0 m/s"
.- The minimum and maximum number of integer digits are interpreted together:
- If the maximum number of integer digits is greater than their minimum number and greater than 1 it forces the exponent to be a multiple of the maximum number of integer digits and the minimum number of integer digits to be interpreted as 1. The most common use of this is to generate engineering notation in which the exponent is a multiple of three e.g.
"##0.#####E0"
. Using this pattern the number 12345 formats to"12.345E3"
and 123456 formats to"123.456E3"
.- Otherwise the minimum number of integer digits is achieved by adjusting the exponent. Example: 0.00123 formatted with
"00.###E0"
yields"12.3E-4"
.- The number of significant digits in the mantissa is the sum of the minimum integer and maximum fraction digits and is unaffected by the maximum integer digits. For example 12345 formatted with
"##0.##E0"
is"12.3E3"
. To show all digits set the significant digits count to zero. The number of significant digits does not affect parsing.- Exponential patterns may not contain grouping separators.
PatternRounding
SyntaxDecimalFormat
usespatternhalf-even:=roundingpos_pattern{';'(seenegROUND_pattern} posHALF_pattern :=EVEN{prefix}number{suffix}forneg_patternformatting.:=Digits
{prefix}number{suffix}Fornumberformatting:=DecimalFormat
integer{'.'usesfraction}{exponent}theprefixten:=consecutive'\u0000'..'\uFFFD'characters-startingspecial_characterswithsuffixthe:=localized'\u0000'..'\uFFFD'zero-digitspecial_charactersdefinedintegerin:=themin_intDecimalFormatSymbols
|object'#'as|digits.'#'Forinteger |parsing these'#'digits' ' integeras well asmin_intall:=Unicode'0'decimal|digits'0'asmin_intdefined|by'0'Character.digit'are'recognized.min_intSpecial
fractionValues:=
NaN
'0'*is'#'*formattedexponentas:=a'E'single'0'character'0'*typically.
3292;Notation: X* 0 or more instances of X { X } 0 or 1 instances of X X | Y either X or Y X.uFFFDYanyThis characterfromisX up todetermined by theYDecimalFormatSymbols
inclusiveobject.S - T characters in S except those in TThis is the only value for which the prefixes and suffixesSpecialarePatternnotCharactersused.
Many charactersInfinity isinformatted as apattern are takensingle character typicallyliterally\;
theyu221Eare matched during parsing and output unchanged during formattingwith the positive or negative prefixes and suffixes applied.SpecialThecharacters on the other hand standinfinity character is determined by theforDecimalFormatSymbols
otherobject.charactersNegative
stringszeroor("-0"
)classes ofparses tocharactersDouble(-0.
unlessThey must be quoted0)noted otherwise if they areisParseIntegerOnly()
to appearis true inthewhichprefix or suffix ascase it parses toliteralsLong(0)
.TheSynchronization
characters listed hereDecimal formats are
used ingenerallynon-localizednotpatternssynchronized.Localized patterns use the corresponding characters taken from this formatter'sItDecimalFormatSymbolsisobject instead and these characters lose their special statusrecommended to create separate format instances for each thread.TwoIfexceptions are the currency sign and quote which are not localizedmultiple threads access a format concurrently it must be synchronized externally.Example
SymbolLocationLocalized@seeMeaning//0NumberYDigitPrint#NumberYDigitoutzero shows asa number usingabsentthe.NumberYDecimallocalizedseparator or monetarynumber integer currencydecimal//separatorand-NumberYMinuspercentsignformat forNumberYGroupingeachseparatorlocaleENumberYLocale[]Separateslocalesmantissa=andNumberFormat.getAvailableLocales();exponent in scientificdouble myNumber =notation-1234.56;NeedNumberFormatnotform;beforquoted(intinj=0;prefixj<;or++j)suffix.{ System.out.println("FORMAT");Subpattern boundaryYSeparatesforpositive(intand negativei =subpatterns0;%Prefixior<locales.length;suffixYMultiply++i)by 100{ ifand(locales[i].getCountry().length()show==as0)percentage{\continue;u2030Prefix or suffixY Multiply by 1000and//showSkipaslanguage-onlyperlocalesmille}¤System.out.print(\u00A4locales[i].getDisplayName()Prefix);orswitchsuffixN(j)Currency{signcasereplaced0:by currency symbolform = NumberFormat.IfgetInstance(locales[i]);doubledbreak;replacedcaseby1:international currency symbolform = NumberFormat.If present in a patterngetIntegerInstance(locales[i]);thebreak;monetarycasedecimal2:separator isform =usedNumberFormat.getCurrencyInstance(locales[i]);insteadbreak;ofdefault:the decimal separatorform = NumberFormat.'Prefix orgetPercentInstance(locales[i]);suffixNbreak;Used}toifquote(formspecialinstanceofcharactersDecimalFormat)in{aSystem.out.print(":prefix or" +suffix((DecimalFormat)forform).toPattern());example}"'#'#System.out.print("formats->123 to" +"#123"form.format(myNumber));To createtry {aSystem.out.println("single->quote itself" +useform.parse(form.format(myNumber)));two in} catcha(ParseExceptionrow:e)"#{}o''clock".} }java.text.FormatJava Tutorial @seejava.text.NumberFormat @seejava.text.ChoiceFormatDecimalFormatSymbols @seejava.text.ParsePosition @version 1.59 0268 12/0903/01 @author Mark Davis @author Alan Liu
Class DecimalFormat, constructor DecimalFormat(String)CreateCreates a DecimalFormat using the default pattern and symbols for the default locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.To obtain standard formats for a given locale use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale. @see java.text.NumberFormat#getInstance @see java.text.NumberFormat#getNumberInstance @see java.text.NumberFormat#getCurrencyInstance @see java.text.NumberFormat#getPercentInstance
Class DecimalFormat, constructor DecimalFormat(String, DecimalFormatSymbols)CreateCreates a DecimalFormatfromusing the given pattern and the symbols for the default locale. This is a convenient way to obtain a DecimalFormat when internationalization is not the main concern.To obtain standard formats for a given locale use the factory methods on NumberFormat such as getNumberInstance. These factories will return the most appropriate sub-class of NumberFormat for a given locale. @param pattern A non-localized pattern string. @exception NullPointerException if
pattern
is null @exception IllegalArgumentException if the given pattern is invalid. @see java.text.NumberFormat#getInstance @see java.text.NumberFormat#getNumberInstance @see java.text.NumberFormat#getCurrencyInstance @see java.text.NumberFormat#getPercentInstance
Class DecimalFormat, void applyLocalizedPattern(String)CreateCreates a DecimalFormatfromusing the given pattern and symbols. Use this constructor when you need to completely customize the behavior of the format.To obtain standard formats for a given locale use the factory methods on NumberFormat such as getInstance or getCurrencyInstance. If you need only minor adjustments to a standard format you can modify the format returned by a NumberFormat factory method. @param pattern a non-localized pattern string @param symbols the set of symbols to be used @exception NullPointerException if any of the given arguments is null @exception IllegalArgumentException if the given pattern is invalid @see java.text.NumberFormat#getInstance @see java.text.NumberFormat#getNumberInstance @see java.text.NumberFormat#getCurrencyInstance @see java.text.NumberFormat#getPercentInstance @see java.text.DecimalFormatSymbols
Apply the given pattern to this Format object. The pattern is assumed to be in a localized notation. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.Class DecimalFormat, void applyPattern(String)There is no limit to integer digits are set by this routine since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers use a second pattern separated by a semicolon
Example
"# #00.0#"
-> 1 234.56This means a minimum of 2 integer digits 1 fraction digit and a maximum of 2 fraction digits.
Example:
"# #00.0#;(# #00.0#)"
for negatives inparanthesesparentheses.In negative patterns the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern. @exception NullPointerException if
pattern
is null @exception IllegalArgumentException if the given pattern is invalid.
Apply the given pattern to this Format object. A pattern is a short-hand specification for the various formatting properties. These properties can also be changed individually through the various setter methods.Class DecimalFormat, StringBuffer format(double, StringBuffer, FieldPosition)There is no limit to integer digits are set by this routine since that is the typical end-user desire; use setMaximumInteger if you want to set a real value. For negative numbers use a second pattern separated by a semicolon
Example
"# #00.0#"
-> 1 234.56This means a minimum of 2 integer digits 1 fraction digit and a maximum of 2 fraction digits.
Example:
"# #00.0#;(# #00.0#)"
for negatives inparanthesesparentheses.In negative patterns the minimum and maximum counts are ignored; these are presumed to be set in the positive pattern. @exception NullPointerException if
pattern
is null @exception IllegalArgumentException if the given pattern is invalid.
Formats a double to produce a string. @param number The double to format @paramClass DecimalFormat, StringBuffer format(long, StringBuffer, FieldPosition)toAppendToresult where the text is to be appended @param fieldPosition On input: an alignment field if desired. On output: the offsets of the alignment field. @return Thevalue passed in as theformattedresult parameternumber string @see java.text.FieldPosition
Format a long to produce a string. @param number The long to format @paramClass DecimalFormat, Number parse(String, ParsePosition)toAppendToresult where the text is to be appended @param fieldPosition On input: an alignment field if desired. On output: the offsets of the alignment field. @return Thevalue passed in as theformattedresult parameternumber string @see java.text.FieldPosition
Returns an instanceParses text fromofa string to produce aNumber
.with a value matchingThe method attempts to parse text starting at the index given by
pos
. If parsing succeeds then the index ofpos
is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string) and the parsed number is returned. The updatedpos
can be used to indicate the starting point for the next call to this method. If an error occurs then the index ofpos
is not changed the error index ofpos
is set to the index of the character where the error occurred and null is returned.The most economical subclass that can represent
allthebits of the sourcenumber given by the string is chosen.@paramMosttext theinteger valuesstringare returned asLong
objects no matter how they are written:"17"
and"17.000"
both parse tobeLong(17)
.parsedValues@paramthatparsePosition on entrycannot fit intowhereaLong
are returned asDouble
s. This includes values with a fractional part infinite valuesNaN
and the value -0.0.DecimalFormat
does not decide whether tobeginreturn aparsing;Double
or aLong
based onexitthe presencejustof a decimalpastseparator in thelastsourceparsedstring.characterDoing so would prevent integers that overflow the mantissa of a double such as"10 000 000 000 000 000
.00"If parsingfrom beingfailsparsed accurately. Currently theindex will notonly classes thatmoveparse
returns areLong
andDouble
but callers should not rely on this. Callers may use theNumber
methodsdoubleValue
longValue
etc. to obtain the type they want.
DecimalFormat
parses all Unicode characters that represent decimal digits as defined byCharacter.digit()
. In additionDecimalFormat
also recognizes as digits the ten consecutive characters starting with the localized zero digit defined in theDecimalFormatSymbols
object. @param text the string to be parsed @param pos AParsePosition
object with index and error indexwill beinformation assetdescribed above. @return the parsed value ornull
if the parse fails @exception NullPointerException iftext
orpos
is null.
This class represents the set of symbols (such as the decimal separator the grouping separator and so on) needed byClass DecimalFormatSymbols, constructor DecimalFormatSymbols(Locale)DecimalFormat
to format numbers.DecimalFormat
creates for itself an instance ofDecimalFormatSymbols
from its locale data. If you need to change any of these symbols you can get theDecimalFormatSymbols
object from yourDecimalFormat
and modify it. @see java.util.Locale @see DecimalFormat @version 1.30 0135 12/1903/0001 @author Mark Davis @author Alan Liu
Create a DecimalFormatSymbols object for the given locale. @exception NullPointerException if locale
is null
Class DecimalFormatSymbols, String getCurrencySymbol()Class DecimalFormatSymbols, String getInfinity()ReturnReturns thestringcurrencydenoting the localsymbol for the currency of these DecimalFormatSymbols in their locale.
Gets theClass DecimalFormatSymbols, String getInternationalCurrencySymbol()characterstring used to represent infinity. Almost always left unchanged.
Class DecimalFormatSymbols, char getMonetaryDecimalSeparator()ReturnReturns theinternationalISOstring denoting the4217 currency codelocalof the currency of these DecimalFormatSymbols.
Class DecimalFormatSymbols, String getNaN()ReturnReturns the monetary decimal separator.
Gets theClass DecimalFormatSymbols, void setCurrencySymbol(String)characterstring used to representNaN"not a number". Almost always left unchanged.
Class DecimalFormatSymbols, void setDecimalSeparator(char)SetSets thestringcurrencydenoting the localsymbol for the currency of these DecimalFormatSymbols in their locale.
Class DecimalFormatSymbols, void setDigit(char)SetSets the character used for decimal sign. Different for French etc.
Class DecimalFormatSymbols, void setGroupingSeparator(char)SetSets the character used for a digit in a pattern.
Class DecimalFormatSymbols, void setInfinity(String)SetSets the character used for thousands separator. Different for French etc.
Class DecimalFormatSymbols, void setInternationalCurrencySymbol(String)SetSets thecharacterstring used to represent infinity. Almost always left unchanged.
Class DecimalFormatSymbols, void setMinusSign(char)SetSets theinternationalISOstring4217denotingcurrency code of the currency of these DecimalFormatSymbols. If the currency code is valid (as defined by Currency.getInstance this also sets the currency attribute to the corresponding Currency instance and the currency symbol attribute to the currency's symbol in the DecimalFormatSymbols' locale. If the currency code is not valid then thelocalcurrency attribute is set to null and the currency symbol attribute is not modified. @see #setCurrency @see #setCurrencySymbol
Class DecimalFormatSymbols, void setMonetaryDecimalSeparator(char)SetSets the character used to represent minus sign. If no explicit negative format is specified one is formed by prefixing minusSign to the positive format.
Class DecimalFormatSymbols, void setNaN(String)SetSets the monetary decimal separator.
Class DecimalFormatSymbols, void setPatternSeparator(char)SetSets thecharacterstring used to representNaN"not a number". Almost always left unchanged.
Class DecimalFormatSymbols, void setPerMill(char)SetSets the character used to separate positive and negative subpatterns in a pattern.
Class DecimalFormatSymbols, void setPercent(char)SetSets the character used for mille percent sign. Different for Arabic etc.
Class DecimalFormatSymbols, void setZeroDigit(char)SetSets the character used for percent sign. Different for Arabic etc.
SetSets the character used for zero. Different for Arabic etc.
FieldPosition
is a simple class used byFormat
and its subclasses to identify fields in formatted output. Fieldsarecan be identifiedbyinconstantstwo ways:
By an integer constant whose names typically end with _FIELD
. The constants are defined in the various subclasses ofFormat
.SeeBy a Format.Field
constant seeERA_FIELD
and its friends inDateFormat
for an example.
FieldPosition
keeps track of the position of the field within the formatted output with two indices: the index of the first character of the field and the index of the last character of the field.One version of the
format
method in the variousFormat
classes requires aFieldPosition
object as an argument. You use thisformat
method to perform partial formatting or to get information about the formatted output (such as the position of a field).If you are interested in the positions of all attributes in the formatted string use the
Format
methodformatToCharacterIterator
. @version 1.16 0118 12/1903/0001 @author Mark Davis @see java.text.Format
Class Format, Object clone()Format
is an abstract base class for formatting locale-sensitive information such as dates messages and numbers.
Format
defines the programming interface for formatting locale-sensitive objects intoString
s (theformat
method) and for parsingString
s back into objects (theparseObject
method).Any
StringGenerallyformattedabyformat's
formatparseObjectis guaranteedmethodtomust beparseable by parseObject.ableIf formatting is unsuccessful because theto parse any string formatted by its
Format object cannotformatthe type ofobjectmethod.specifiedHoweverformattherethrows anmay beIllegalArgumentException.exceptionalOtherwise if therecases where this issomethingnotillformedpossible.about the objectFor example aformat
returns the Unicodemethodreplacement charactermight create\\uFFFD.twoIf there isadjacent integer numbers with nomatchseparatorwhen parsingin betweenparseObject(String)andthrows ain thisParseExceptioncaseandtheparseObject
(String ParsePosition)leaves thecould notParsePositiontellindexwhichmember unchanged and returnsdigits belong to whichnullnumber.Subclassing
The Java 2 platform provides three:concretespecialized subclasses ofFormat
--DateFormat
MessageFormat
andNumberFormat
--for formatting dates messages and numbers respectively.Concrete subclasses must implement
these twothree methods:These general methods allow polymorphic parsing and formatting of objects and are used for example by
format(Object obj StringBuffer toAppendTo FieldPosition pos)
parseObjectformatToCharacterIterator(Object obj)parseObject(String source ParsePosition pos)
MessageFormat
. Subclasses often also provide additionalformat
methods for specific input types as well asparse
methods for specific result types. Anyparse
method that does not take aParsePosition
argument should throwParseException
when no text in the required format is at the beginning of the input text.Most subclasses will also implement the following
twofactory methods:In addition some subclasses may also
getInstance
for getting a useful format object appropriate for the current localegetInstance(Locale)
for getting a useful format object appropriate for the specified localechoose toimplement othergetXxxxInstance
methods for more specialized control. For example theNumberFormat
class providesgetPercentInstance
andgetCurrencyInstance
methods for getting specialized number formatters.Subclasses of
Format
that allow programmers to create objects for locales (withgetInstance(Locale)
for example) must also implement the following class method:public static Locale[] getAvailableLocales()And finally subclasses may define a set of constants to identify the various fields in the formatted output. These constants are used to create a FieldPosition object which identifies what information is contained in the field and its position in the formatted result. These constants should be named
item_FIELD
whereitem
identifies the field. For examples of these constants seeERA_FIELD
and its friends in DateFormatSynchronization
Formats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently it must be synchronized externally. @see java.text.ParsePosition @see java.text.FieldPosition @see java.text.NumberFormat @see java.text.DateFormat @see java.text.MessageFormat @version 1.
28 0131 12/1903/0001 @author Mark Davis
Class Format, String format(Object)OverridesCreatesCloneableand returns a copy of this object. @return a clone of this instance.
Formats an object to produce a string.@param obj The object to format @return Formatted string. @exception IllegalArgumentExceptionSubclassesThiswill override the StringBufferis equivalent toversionStringBuffeofFieldPosition) format}(obj new StringBuffer() new FieldPosition(0))
.toString();
Formats an objectClass Format, Object parseObject(String)to produceandaappendsstring.theSubclasses will implement for particular objectresulting text to a given stringsuchbuffer.as:If theStringBufferpos
formatargument(Numberidentifiesobj StringBuffera fieldtoAppendTo)usedNumber parseby the(Stringformatstr)thenThese general routines allow polymorphic parsingits indices are set to the beginning andformattingendfor objects such as the MessageFormatof the first such field encountered. @param obj The object to format @param toAppendTo where the text is to be appended @param posOnAinput:FieldPosition
an alignmentidentifying a fieldif desired. On output: the offsets ofin thealignmentformattedfield.text @return thevaluestring buffer passed in astoAppendTo
(thiswithallows chaining asformatted text appendedwith@exceptionStringBuffer.append())NullPointerException iftoAppendTo
orpos
is null @exception IllegalArgumentExceptionwhenif the Format cannot format the given object. @see MessageFormat @see java.text.FieldPosition
ParsesClass Format, Object parseObject(String, ParsePosition)atext from the beginning of the given string to produce an object. The method may not use the entire text of the given string. @param source AString
whose beginning should be parsed. @return AnObject
parsed from the string. @exception ParseException if the beginning of the specified stringiscannot beinvalidparsed.
Parses text from a string to produce an object.Subclasses will typically implement for particular object such as:
String formatThe method attempts(Numbertoobj);parseString formattext starting(longatobj);theString formatindex given(doublebyobj);pos
.Number parseIf parsing(Stringsucceedsstr);then the@paramindexstatusofInput-Outputpos
parameter.isBeforeupdatedcalling setto thestatus.indextoafter theoffset you wantlastto startcharacter used (parsingat in thedoes not necessarilysource.useAfter callingall charactersstatus.indexupisto the end of thetext you parsed.string)If error occurs indexand the parsed object isunchangedreturned.When parsing leading whitespace is discarded (with successful parse) while trailing whitespace is leftTheasupdatedis.pos
Example:canParsingbe"_12_xy"used(whereto_ represents aindicate the startingspace)point fora number with index == 0 will result inthenumber 12 with status.indexnextupdatedcall to3 (just before the secondthisspace)method.Parsing a secondIftime will result in a ParseException sincean error occurs then the index of"xy"pos
is nota numberchangedand leavethe error indexat 3. Subclasses will typically supply specificofparsepos
methods that return different typesis set to the index ofvalues. Since methodsthecan'tcharacteroverload on return types these will typicallywhere the error occurred and null isbereturned.named@param"parse"sourcewhileAthisString
polymorphic method will alwayspart of which should becalled parseObjectparsed.Any parse method that does not take a status should throw@paramParseException whenpos AnoParsePosition
text in the required format is at the start positionobject with index and error index information as described above. @return AnObject parsed from the string. In case of error returns null. @
seeexceptionjava.textNullPointerException ifpos
is null.ParsePosition
Typically the message format will come from resources and theMessageFormat
provides a means to produce concatenated messages in language-neutral way. Use this to construct messages displayed for end users.
MessageFormat
takes a set of objects formats them then inserts the formatted strings into the pattern at the appropriate places.Note:
MessageFormat
differs from the otherFormat
classes in that you create aMessageFormat
object with one of its constructors (not with agetInstance
style factory method). The factory methods aren't necessary becauseMessageFormat
itself doesn'trequire any compleximplementsetup forlocale specificabehavior.givenAny locale. InfactspecificMessageFormatbehaviordoesn'tisimplement any locale specific behavior atdefined by the pattern that youall.provideIt just needs to be set up onas well as the subformats used for insertedaarguments.sentencePatterns
by sentenceand Theirbasis.InterpretationMessageFormat
Here are some examples of usageuses patterns of the following form:Object[]MessageFormatPattern:argumentsString=MessageFormatPattern FormatElement String FormatElement: {newArgumentIndexInteger(7)}new{Date(System.currentTimeMillis())ArgumentIndex"aFormatTypedisturbance in} {theArgumentIndexForce"FormatType FormatStyle };StringFormatType:result =one ofMessageFormat.format("Atnumber{1date time}onchoice{1FormatStyle:date}shortthere wasmedium long{2}fullon planetinteger currency{0percentnumberSubformatPatterninteger}."String:arguments);StringPartoptoutputString StringPart StringPart:At''12' QuotedString ' UnquotedString SubformatPattern: SubformatPatternPartopt SubformatPattern SubformatPatternPart SubFormatPatternPart:30 PM'onQuotedPatternJul'3UnquotedPattern2053there wasWithin a
disturbance inStringthe"''"
Force on planet 7represents a single quote. A QuotedStringTypically the message format will comecan contain arbitrary characters except singlefromquotes;resources and the arguments willthe surrounding single quotes areberemoved.dynamicallyAnsetUnquotedStringatcanruntime.containExamplearbitrary characters2:exceptsingle quotesObject[]andtestArgs =left curly{newbrackets.Long(3)Thus"MyDisk"};aMessageFormat form = newstring that should resultMessageFormat(in"Thethediskformatted\message "'{10}\'"containscan be written as"'''
{'0}file(s).''");System.out.println(formor"'''{0}'''"
.format(testArgs));//
output withWithin a SubformatPattern differenttestArgsrulesoutput:apply.TheAdiskQuotedPattern"MyDisk"cancontains 0contain arbitraryfile(s).charactersoutput:exceptThesinglediskquotes;"MyDisk"butcontains 1the surroundingfile(s).singleoutput:quotesThearedisknot"MyDisk"removedcontains 1 273so they mayfile(s).beinterpreted by theThesubformat.pattern isFor exampleof"{1
thenumberform:$'#' ##}"messageFormatPatternwill produce:=astring (number format"{"withmessageFormatElementthe"}"pound-signstringquoted)*withmessageFormatElementa:=resultargumentsuch{as: "$#31 45".elementFormatAn}UnquotedPatternelementFormatcan:=contain"time"arbitrary{ " " datetimeStyle } |characters except single quotes but curly"date"braces{ " " datetimeStylewithin it must be}balanced.|For"numberexample"ab {
"0} de"numberStyle }|and"choice"ab
{'}' de"" choiceStyle } datetimeStyleare valid subformat patterns:=but"short"ab
|{0'}'"mediumde"|and"long"ab
|}"fullde"|aredateFormatPatternnot.numberStyle
- Warning:
=- The
"currency"rules|for"percent"using|quotes"integer"within| numberFormatPattern choiceStylemessage format patterns:=unfortunatelychoiceFormatPattern If therehave shown to be somewhatisconfusing.noInelementFormatparticularthenittheisn'targument must be a string which isalways obvious to localizers whether single quotessubstituted.needIf there is noto be doubled ordateTimeStylenot.orMakenumberStylesurethento inform localizers about thedefault format is usedrules and tell them (for exampleNumberFormat.getInstancebyDateFormat.getTimeInstanceusingorcommentsDateFormat.getInstance).inIn stringsresource bundle sourcesinglefiles)quotes can be used to quotewhich strings will be processed bytheMessageFormat."{"Note(curlythatbrace)localizersifmaynecessary.needA realto use singlequotequotesis represented byin translated strings'where the original version doesn't have them.Inside amessageFormatElementThequotesArgumentIndexarevaluenotisremoved.aFornon-negativeexampleinteger{1writtennumberusing$the digits '#0'##}throughwill'9'produce a number format withand represents an index into thepound-signarguments
quoted witharray passedato theformat
methods or the resultsucharrayas:returned"$#31by45"theparse
methods.
IfTheaFormatTypepatternandisFormatStyle values are usedthento createunquotedabracesFormat
ininstance for thepatternformat element.if any mustThe following tablematch:showsthat ishow the"abvalues{0}mapde"toandFormat"abinstances.'}'Combinationsde"not shown in the table areokillegal.butA"abSubformatPattern{0'}'mustde"beanda"abvalid}patternde"stringarefornotthe Format subclass used.
The argument
isFormat aTypenumberFormat fromStyle0Subformat to 9Createdwhich(none) correspondsnull
tothenumber
arguments(none) presentedNumberFormat.getInstance(getLocale())
inaninteger
arrayNumberFormat.getIntegerInstance(getLocale())
tobecurrency
formattedNumberFormat.getCurrencyInstance(getLocale())
Itpercent
isNumberFormat.getPercentInstance(getLocale())
oktoSubformatPattern havenew
unusedDecimalFormat(subformatPatternargumentsnewinDecimalFormatSymbols(getLocale()))thearray.date
With(none) missingDateFormat.getDateInstance(DateFormat.DEFAULT
argumentsgetLocale())orargumentsshort
thatDateFormat.getDateInstance(DateFormat.SHORT
aregetLocale())notofmedium
theDateFormat.getDateInstance(DateFormat.DEFAULT
rightgetLocale())classforlong
theDateFormat.getDateInstance(DateFormat.LONG
specifiedgetLocale())formatafull
ParseExceptionDateFormat.getDateInstance(DateFormat.FULL getLocale())isthrown.SubformatPattern new SimpleDateFormat(subformatPattern getLocale())
First
formattimechecks(none) toDateFormat.getTimeInstance(DateFormat.DEFAULT
seegetLocale())ifashort
FormatDateFormat.getTimeInstance(DateFormat.SHORT getLocale())objecthasmedium
beenDateFormat.getTimeInstance(DateFormat.DEFAULT
specifiedgetLocale())forthelong
argumentDateFormat.getTimeInstance(DateFormat.LONG
withgetLocale())the
setFormatsfullmethodDateFormat.getTimeInstance(DateFormat.FULL
IfgetLocale())sothenSubformatPattern
formatnewusesSimpleDateFormat(subformatPatternthatgetLocale())
FormatchoiceobjectSubformatPattern tonew
formatChoiceFormat(subformatPattern)theargument
Usage Information
Here are some examples of usage:
.currentTimeMillis()) "aObject[] arguments = { new Integer(7) new Date(SystemOtherwisedisturbance in theargumentForce"is};formattedString result = MessageFormat.format( "At {1 time} on {1 date} there wasbased{2} ontheplanetobject's{0 numbertypeinteger}."Ifarguments);theoutput:argumentAtis12:30 PM on Jul 3 2053 there was aNumberdisturbancetheninformattheusesForceNumberFormaton planet 7.getInstanceto
Example 2:
;Object[] testArgs = {new Long(3) "MyDisk"}
For more sophisticated patterns you can use a ChoiceFormat
to get output such as:
You can either do this programmatically as in the above example or by using a pattern (see ChoiceFormat for more information) as in:MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}."); double[] filelimits = {0 1 2}; String[] filepart = {"no files" "one file" "{0 number} files"}; ChoiceFormat fileform = new ChoiceFormat(filelimits filepart); form.setFormatsetFormatByArgumentIndex(10 fileform);// NOT zero see belowObject[] testArgs = {new Long(12373) "MyDisk"}; System.out.println(form.format(testArgs)); // output with different testArgs output: The disk "MyDisk" contains no files. output: The disk "MyDisk" contains one file. output: The disk "MyDisk" contains 1 273 files.
form.applyPattern( "There {0 choice 0#are no files|1#is one file|1#<are {0 number integer} files}.");
Note: As we see above the string produced by a ChoiceFormat
in MessageFormat
is treated specially; occurances of '{' are used to indicated subformats and cause recursion. If you create both a MessageFormat
and ChoiceFormat
programmatically (instead of using the string patterns) then be careful not to produce a format that recurses on itself which will cause an infinite loop.
Note: formats are numbered by order of variable in the string. This is not the same as the argument numbering For example: with "abc{2}def{3}ghi{0}..." format0 affects the first variable {2} format1 affects the second variable {3} format2 affects the second variable {0} and so on. When a single argument is parsed more than once in the string the last match will be the final result of the parsing. For example
MessageFormat mf = new MessageFormat("{0 number #.##} {0 number #.#}"); Object[] objs = {new Double(3.1415)}; String result = mf.format( objs ); // result now equals "3.14 3.1" objs = null; objs = mf.parse(result new ParsePosition(0)); // objs now equals {new Double(3.1)}
Likewise parsing with a MessageFormat object using patterns containing multiple occurances of the same argument would return the last match. For example
MessageFormat mf = new MessageFormat("{0} {0} {0}"); String forParsing = "x y z"; Object[] objs = mf.parse(forParsing new ParsePosition(0)); // result now equals {new String("z")}
You can useMessage formats are setLocalenot followedsynchronized. byIt applyPatternis (andrecommended then possiblyto create setFormat)separate toformat re-initializeinstances afor MessageFormateach withthread. If multiple threads access a differentformat localeconcurrently it must be synchronized externally. @see java.util.Locale @see Format @see NumberFormat @see DecimalFormat @see ChoiceFormat @version 1.38 0147 12/1903/0001 @author Mark Davis
Class MessageFormat, constructor MessageFormat(String)
ConstructsClass MessageFormat, void applyPattern(String)witha MessageFormat for the default locale and the specified pattern. The constructor first sets the locale then parses the pattern and creates a list of subformats for the format elements contained in it. Patterns and their interpretation are specified in the class description. @seeparamMessageFormat#applyPatternpattern the pattern for this message format @exception IllegalArgumentException if the pattern is invalid
Sets the pattern used by this message format. The method parses the pattern and creates a list of subformats for the format elements contained in it.Class MessageFormat, Object clone()SeePatterns and their interpretation are specified in the class description. @param pattern the pattern for this message format @exception IllegalArgumentException if the pattern is invalid
Class MessageFormat, boolean equals(Object)OverridesCreatesCloneableand returns a copy of this object. @return a clone of this instance.
EqualityClass MessageFormat, StringBuffer format(Object, StringBuffer, FieldPosition)comparisioncomparison between two message format objects
@paramReturns pattern with formattedFormats an array of objects. If sourceis nulland appends theoriginalMessageFormat
's patternis returnedwith formatifelements replacedsource contains nullby the formatted objects to theformattedprovidedresultStringBuffer
. Thiswill substitute each argumentis equivalent towith{@link
the#format(java.lang.Object[]stringjava.lang.StringBuffer"null"java.text.FieldPosition) format}((Object[]) arguments result pos)
arguments
Class MessageFormat, String format(String, Object[])ReturnsFormats an array of objects and appends theMessageFormat
's pattern with format elements replaced by the formatted objects to the providedStringBuffer
.If source isThe text
nullsubstituted for theoriginalindividualpatternformat elements isreturned if source contains null objectsderived from the current subformat of theformattedformatresultelementwilland thearguments
element atsubstitutethe formateachelement's argumentwithindex as indicated by thestringfirst matching line of the following table. An argument is unavailable ifarguments
isnull
or has fewer than argumentIndex+1 elements.
Subformat Argument Formatted Text any unavailable "{" + argumentIndex + "}"
any null
"null"
instanceof ChoiceFormat
any subformat.format(argument).indexOf('{') >= 0
(new MessageFormat(subformat.format(argument) getLocale())).format(argument) : subformat.format(argument)= null
any subformat.format(argument)
null
instanceof Number
NumberFormat.getInstance(getLocale()).format(argument)
null
instanceof Date
DateFormat.getDateTimeInstance(DateFormat.SHORT DateFormat.SHORT getLocale()).format(argument)
null
instanceof String
argument
null
any argument.toString()
If
. @parampos
is non-null and refers toField.ARGUMENT
the location of the first formatted string will be returnedsourcearguments an array of objects to be formatted&and substituted. @param result where text is appended. @paramignorepos On input: an alignment field if desired. On output: the offsets of the alignment field. @exception IllegalArgumentException if an argument innotheusefularguments
statusarray isreturnednot of the type expected by the format element(s) that use it.
@exception IllegalArgumentException if the pattern is invalid or if an argument in theConvenienceCreatesroutinea MessageFormat with the given pattern and uses it to format the given arguments.Avoids explicit creationThis is equivalentofto(new MessageFormat}(pattern)).{@lin #format(java.lang.Object[] java.lang.StringBuffer java.text.FieldPosition) format}(arguments new StringBuffer() null).toString()
arguments
array is not of the type expected by the Gets the formatsClass MessageFormat, Locale getLocale()thatused for the format elements in thewerepreviously setwithpattern string. The order of formats in the returned array corresponds to the order of format elements in the patternsetFormatsstring.SeeSince the order of format elements in a pattern string often changes during localization it's generally better to use the getFormatsByArgumentIndex method which assumes an order of formats corresponding to the order of elements in the
classarguments
arraydescription aboutpassed to theformat methods
numberingor the result array returned by theparse
methods. @return the formats used for the format elements in the pattern
Gets the localeClass MessageFormat, Object[] parse(String).Thisthat'slocale is used for fetchingused when creating or comparingdefaultsubformats.number@returnorthedatelocale usedformatwheninformation.creating or comparing subformats
Parses text from the beginning of the given string to produce an object array.Class MessageFormat, Object[] parse(String, ParsePosition)DoesThe method may notyetuse thehandle recursionentire text(whereof thesubstitutedgivenstringsstring.contain
{n}Seereferences.the ParsePosition) method for more information on message parsing. @param source AString
whose beginning should be parsed. @return AnObject
array parsed from the string. @exception ParseException if the beginning of the specified stringcan'tcannot be parsed.
Parses the string.Class MessageFormat, Object parseObject(String, ParsePosition)Caveats: The parse may fail in a number of circumstances. For example:
When the parse fails use ParsePosition.getErrorIndex() to find out where in the string did the parsing failed. The returned error index is the starting offset of the sub-patterns that the string is comparing with. For example if the parsing string "AAA {0} BBB" is comparing against the pattern "AAD {0} BBB" the error index is 0. When an error occurs the call to this method will return null. If the
- If one of the arguments does not occur in the pattern.
- If the format of an argument loses information such as with a choice format where a large number formats to "many".
- Does not yet handle recursion (where the substituted strings contain {n} references.)
- Will not always find a match (or the correct match) if some part of the parse is ambiguous. For example if the pattern "{1} {2}" is used with the string arguments {"a b" "c"} it will format as "a b c". When the result is parsed it will return {"a" "b c"}.
- If a single argument is parsed more than once in the string then the later parse wins.
sorucesource is null return an empty array.
Parses text from a string to produce an object array.Class MessageFormat, void setFormat(int, Format)The method attempts to parse text starting at the index given by
the string) and the parsed object array is returned. The updatedpos
. If parsing succeeds then the index ofpos
is updated to the index after the last character used (parsing does not necessarily use all characters up to the end ofpos
can be used to indicate the starting point for the next call to this method.DoesIf an error occurs then the index ofpos
is notyetchanged thehandle recursionerror index(ofpos
is set to the index of the character where thesubstituted strings containerror occurred and%nnullreferencesis returned.See the ParsePosition
) method for more information on message parsing. @param source AString
part of which should be parsed. @param pos AParsePosition
object with index and error index information as described above. @return AnObject
array parsed from the string. In case of error returns null. @exception NullPointerException ifpos
is null.
Class MessageFormat, void setFormats(Format[])Set aSets the format tobeuseused on a variablefor the format elementinwith the given format element index within the previously set pattern string.@paramThe formatvariableelement index is the zero-based number of thevariableformat elementincounting from theformatstart of the pattern string.ThisSince the order of format elements in a pattern string often changes during localization it is
notgenerally better to use the setFormatByArgumentIndex method which accesses format elements based on the argumentnumberindex they specify.If@paramvariableformatElementIndexis outthe index ofrangea formatanelementArrayIndexOutOfBoundsExceptionwithinisthethrown.pattern @param newFormat the format to use for the specifiedvariableformat element @exception ArrayIndexOutOfBoundsException if formatElementIndex is equal to or larger than the number of format elements in the pattern string
Sets the formats to useClass MessageFormat, void setLocale(Locale)onfor the format elements in the previously set pattern string. The order of formats innewFormats
corresponds to the order of format elements in the pattern string.If more formats are provided than needed by the pattern string the remaining ones are ignored. If fewer formats are provided than needed then only the first
newFormats.length
formats areparametersreplaced.SeeSince the order of format elements in a pattern string often changes during localization it is generally better to use the setFormatsByArgumentIndex method which assumes an order of formats corresponding to the
class description aboutorder of elements in thearguments
array passed to theformat methods or the result array returned by the
parse
numberingmethods. @param newFormats the new formats to use @exception NullPointerException ifnewFormats
is null
Class MessageFormat, String toPattern()ConstructsSetswiththespecifiedlocale to be used when creating or comparing subformats. This affects subsequent callspatternto the applyPattern andformatstoPattern methodsforas well as to theargumentsformat
inandthatformatToCharacterIteratorpatternmethods. @param locale the locale to be used when creating or comparing subformats
Gets theReturns a pattern representing the current state of the message format.SeeThe string is constructed from internal information and therefore does not necessarily equal theclasspreviouslydescriptionapplied pattern. @return a pattern representing the current state of the message format
Class NumberFormat, StringBuffer format(Object, StringBuffer, FieldPosition)NumberFormat
is the abstract base class for all number formats. This class provides the interface for formatting and parsing numbers.NumberFormat
also provides methods for determining which locales have number formats and what their names are.
NumberFormat
helps you to format and parse numbers for any locale. Your code can be completely independent of the locale conventions for decimal points thousands-separators or even the particular decimal digits used or whether the number format is even decimal.To format a number for the current Locale use one of the factory class methods:
If you are formatting multiple numbers it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times.myString = NumberFormat.getInstance().format(myNumber);To format a number for a different Locale specify it in the call toNumberFormat nf = NumberFormat.getInstance(); for (int i = 0; igetInstance
.You can also use aNumberFormat nf = NumberFormat.getInstance(Locale.FRENCH);NumberFormat
to parse numbers:UsemyNumber = nf.parse(myString);getInstance
orgetNumberInstance
to get the normal number format. UsegetIntegerInstance
to get an integer number format. UsegetCurrencyInstance
to get the currency number format. And usegetPercentInstance
to get a format for displaying percentages. With this format a fraction like 0.53 is displayed as 53%.You can also control the display of numbers with such methods as
setMinimumFractionDigits
. If you want even more control over the format or parsing or want to give your users more control you can try casting theNumberFormat
you get from the factory methods to a. This will work for the vast majority of locales; just remember to put it in a
DecimalNumberFormatDecimalFormattry
block in case you encounter an unusual one.NumberFormat and DecimalFormat are designed such that some controls work for formatting and others work for parsing. The following is the detailed description for each these control methods
setParseIntegerOnly : only affects parsing e.g. if true "3456.78" -> 3456 (and leaves the parse position just after index 6) if false "3456.78" -> 3456.78 (and leaves the parse position just after index 8) This is independent of formatting. If you want to not show a decimal point where there might be no digits after the decimal point use setDecimalSeparatorAlwaysShown.
setDecimalSeparatorAlwaysShown : only affects formatting and only where there might be no digits after the decimal point such as with a pattern like "# ##0.##" e.g. if true 3456.00 -> "3 456." if false 3456.00 -> "3456" This is independent of parsing. If you want parsing to stop at the decimal point use setParseIntegerOnly.
You can also use forms of the
parse
andformat
methods withParsePosition
andFieldPosition
to allow you to:For example you can align numbers in two ways:
- progressively parse through pieces of a string
- align the decimal point and other areas
- If you are using a monospaced font with spacing for alignment you can pass the
FieldPosition
in your format call withfield
=INTEGER_FIELD
. On outputgetEndIndex
will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.- If you are using proportional fonts instead of padding with spaces measure the width of the string in pixels from the start to
getEndIndex
. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text. It also works where there is no decimal but possibly additional characters at the end e.g. with parentheses in negative numbers: "(12)" for -12.Synchronization
Number formats are generally not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently it must be synchronized externally. @see DecimalFormat @see ChoiceFormat @version 1.
47 0157 12/1903/0001 @author Mark Davis @author Helena Shih
Formats an object to produce a string. This general routines allows polymorphic parsing and formatting forClass NumberFormat, NumberFormat getInstance()objectstobjects. @param obj The object to format @param toAppendTo where the text is to be appended @param pos On input: an alignment field if desired. On output: the offsets of the alignment field. @return the value passed in as toAppendTo (this allows chaining as with StringBuffer.append()) @exception IllegalArgumentException when the Format cannot format the given object. @see java.text.FieldPosition
Returns the default number format for the current default locale. The default format is one of the styles provided by the other factory methods: getNumberInstance getIntegerInstance getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.Class NumberFormat, NumberFormat getInstance(Locale)
Returns the default number format for the specified locale. The default format is one of the styles provided by the other factory methods: getNumberInstance getIntegerInstance getCurrencyInstance or getPercentInstance. Exactly which one is locale dependant.Class NumberFormat, Number parse(String)
Class NumberFormat, Object parseObject(String, ParsePosition)ConvenienceParses text from the beginning of the given string to produce a number. The method may not use the entire text of the given string.See the ParsePosition)
method for more information on number parsing. @param source AString
whose beginning should be parsed. @return ANumber
parsed from the string. @exception ParseException if the beginning of the specified stringiscannotinvalid. @seebe#formatparsed.
Parses text from a string to produceanaobjectNumber
.@param
source the stringThe method attempts to parse.@paramtext starting atparsePositionthe index givenInput-Outputbyparameterpos
.OnIf parsing succeedsinputthen thepositionindex ofpos
is updated tobeginthe index after the last character used (parsing does not necessarily use all characters up to the end of the string) and the parsed number is returned. The updatedpos
can be used to indicate the starting point for the next call to this method.OnIf an error occursoutputthen thepositionindex ofpos
is not changed the error index ofpos
is set to thefirstindex ofunparsethe character where the error occurred and null is returned.See the ParsePosition) method for more information on number parsing. @param source A
. @returnString
part of which should be parsed. @param pos AParsePosition
object with index and error index information as described aboveObjectANumber
parsed from the string. In case of error returns null. @seeexceptionjava.textNullPointerException ifpos
is null.ParsePosition
Signals that an error has been reached unexpectedly while parsing. @see java.lang.Exception @see java.text.Format @see java.text.FieldPosition @version 1.13 0114 12/1903/0001 @author Mark Davis
ParsePosition
is a simple class used byFormat
and its subclasses to keep track of the current position during parsing. TheparseObject
method in the variousFormat
classes requires aParsePosition
object as an argument.By design as you parse through a string with different formats you can use the same
ParsePosition
since the index parameter records the current position. @version 1.15 0116 12/1903/0001 @author Mark Davis @see java.text.Format
TheRuleBasedCollator
class is a concrete subclass ofCollator
that provides a simple data-driven table collator. With this class you can create a customized table-basedCollator
.RuleBasedCollator
maps characters to sort keys.
RuleBasedCollator
has the following restrictions for efficiency (other subclasses may be used for more complex languages) :
- If a
French secondaryspecial collationorderingrule controlled by a <modifier> is specified it applies to the whole collator object.- All non-mentioned Unicode characters are at the end of the collation order.
The collation table is composed of a list of collation rules where each rule is of one of three forms:
<modifierThe> <relation> <text-argument> <reset> <text-argument>following demonstratesdefinitionshow to create your own collation rulesof the rule elements is as follows:
- Text-Argument: A text-argument is any sequence of characters excluding special characters (that is common whitespace characters [0009-000D 0020] and rule syntax characters [0021-002F 003A-0040 005B-0060 007B-007E]). If those characters are desired you can put them in single quotes (e.g. ampersand => '&'). Note that unquoted white space characters are ignored; e.g.
b c
is treated asbc
.- Modifier: There
isarea single modifier which is used to specifycurrently two modifiers that turn on special collationthatrules.all
- '@' : Turns on
backwards sorting of accents (secondary differences)areasbackwardsin French.- ' ' : Turns on Thai/Lao vowel-consonant swapping. If this rule is in force when a Thai vowel of the range \U0E40-\U0E44 precedes a Thai consonant of the range \U0E01-\U0E2E OR a Lao vowel of the range \U0EC0-\U0EC4 precedes a Lao consonant of the range \U0E81-\U0EAE then the vowel is placed after the consonant for collation purposes
.'@' : Indicates that accents are sorted backwards as in French.
- Relation: The relations are the following:
- '<' : Greater as a letter difference (primary)
- ';' : Greater as an accent difference (secondary)
- ' ' : Greater as a case difference (tertiary)
- '=' : Equal
- Reset: There is a single reset which is used primarily for contractions and expansions but which can also be used to add a modification at the end of a set of rules.
'&' : Indicates that the next rule follows the position to where the reset text-argument would be sorted.
This sounds more complicated than it is in practice. For example the following are equivalent ways of expressing the same thing:
Notice that the order is important as the subsequent item goes immediately after the text-argument. The following are not equivalent:a < b < c a < b & b < c a < c & a < bEither the text-argument must already be present in the sequence or some initial substring of the text-argument must be present. (e.g. "a < b & ae < e" is valid since "a" is present in the sequence before "ae" is reset). In this latter case "ae" is not entered and treated as a single character; instead "e" is sorted as if it were expanded to two characters: "a" followed by an "e". This difference appears in natural languages: in traditional Spanish "ch" is treated as though it contracts to a single character (expressed as "c < ch < d") while in traditional German a-umlaut is treated as though it expanded to two characters (expressed as "a A < b B ... &a < b & a < c a < c & a < bamp;ae;ã\u00e3&AE;Ã\u00c3"). [ã\u00e3 andÃ\u00c3 are of course the escape sequences for a-umlaut.]Ignorable Characters
For ignorable characters the first rule must start with a relation (the examples we have used above are really fragments; "a < b" really should be "< a < b"). If however the first relation is not "<" then all the all text-arguments up to the first "<" are ignorable. For example " - < a < b" makes "-" an ignorable character as we saw earlier in the word "black-birds". In the samples for different languages you see that most accents are ignorable.
Normalization and Accents
RuleBasedCollator
automatically processes its rule table to include both pre-composed and combining-character versions of accented characters. Even if the provided rule string contains only base characters and separate combining accent characters the pre-composed accented characters matching all canonical combinations of characters from the rule string will be entered in the table.This allows you to use a RuleBasedCollator to compare accented strings even when the collator is set to NO_DECOMPOSITION. There are two caveats however. First if the strings to be collated contain combining sequences that may not be in canonical order you should set the collator to CANONICAL_DECOMPOSITION or FULL_DECOMPOSITION to enable sorting of combining sequences. Second if the strings contain characters with compatibility decompositions (such as full-width and half-width forms) you must use FULL_DECOMPOSITION since the rule tables only include canonical mappings. For more information see The Unicode Standard Version 2.0.)
Errors
The following are errors:
If you produce one of these errors a
- A text-argument contains unquoted punctuation symbols (e.g. "a < b-c < d").
- A relation or reset character not followed by a text-argument (e.g. "a < b").
- A reset where the text-argument (or an initial substring of the text-argument) is not already in the sequence. (e.g. "a < b & e < f")
RuleBasedCollator
throws aParseException
.Examples
Simple: "< a < b < c < d"
Norwegian: "< a A< b B< c C< d D< e E< f F< g G< h H< i I< j J < k K< l L< m M< n N< o O< p P< q Q< r R< s S< t T < u U< v V< w W< x X< y Y< z Z
å< \u00E5=a\u030AÅ\u00C5=A\u030A ;aa AAæ< \u00E6 \u00C6<Æø\u00F8Ø\u00D8"Normally to create a rule-based Collator object you will use
Collator
's factory methodgetInstance
. However to create a rule-based Collator object with specialized rules tailored to your needs you construct theRuleBasedCollator
with the rules contained in aString
object. For example:Or:String Simple = "< a< b< c< d"; RuleBasedCollator mySimple = new RuleBasedCollator(Simple);String Norwegian = "< a A< b B< c C< d D< e E< f F< g G< h H< i I< j J" + "< k K< l L< m M< n N< o O< p P< q Q< r R< s S< t T" + "< u U< v V< w W< x X< y Y< z Z" + "å< \u00E5=a\u030AÅ\u00C5=A\u030A" + ";aa AAæ< \u00E6 \u00C6<Æø\u00F8Ø\u00D8"; RuleBasedCollator myNorwegian = new RuleBasedCollator(Norwegian);Combining
Collator
s is as simple as concatenating strings. Here's an example that combines twoCollator
s from two different locales:// Create an en_US Collator object RuleBasedCollator en_USCollator = (RuleBasedCollator) Collator.getInstance(new Locale("en" "US" "")); // Create a da_DK Collator object RuleBasedCollator da_DKCollator = (RuleBasedCollator) Collator.getInstance(new Locale("da" "DK" "")); // Combine the two // First get the collation rules from en_USCollator String en_USRules = en_USCollator.getRules(); // Second get the collation rules from da_DKCollator String da_DKRules = da_DKCollator.getRules(); RuleBasedCollator newCollator = new RuleBasedCollator(en_USRules + da_DKRules); // newCollator has the combined rulesAnother more interesting example would be to make changes on an existing table to create a new
Collator
object. For example add "&C< ch cH Ch CH" to theen_USCollator
object to create your own:// Create a new Collator object with additional rules String addRules = "&C< ch cH Ch CH"; RuleBasedCollator myCollator = new RuleBasedCollator(en_USCollator + addRules); // myCollator contains the new rulesThe following example demonstrates how to change the order of non-spacing accents
// old rule String oldRules = "=\u0301;\u0300;\u0302;\u0308" // main accents + ";\u0327;\u0303;\u0304;\u0305" // main accents + ";\u0306;\u0307;\u0309;\u030A" // main accents + ";\u030B;\u030C;\u030D;\u030E" // main accents + ";\u030F;\u0310;\u0311;\u0312" // main accents + "< a A ; ae AE ;æ\u00e6Æ\u00c6" + "< b B < c C < e E & C < d D"; // change the order of accent characters String addOn = "& \u0300 ; \u0308 ; \u0302"; RuleBasedCollator myCollator = new RuleBasedCollator(oldRules + addOn);The last example shows how to put new primary ordering in before the default setting. For example in Japanese
Collator
you can either sort English characters before or after Japanese characters@see Collator @see CollationElementIterator @version 1.25 07/24/98 @author Helena Shih Laura Werner Richard Gillam// get en_US Collator rules RuleBasedCollator en_USCollator = (RuleBasedCollator)Collator.getInstance(Locale.US); // add a few Japanese character to sort before English characters // suppose the last character before the first base letter 'a' in // the English collation rule is \u2212 String jaString = "& \u2212 < \u3041 \u3042 < \u3043 \u3044"; RuleBasedCollator myJapaneseCollator = new RuleBasedCollator(en_USCollator.getRules() + jaString);
Class SimpleDateFormat, constructor SimpleDateFormat()SimpleDateFormat
is a concrete class for formatting and parsing dates in a locale-sensitive manner. It allows for formatting (date -> text) parsing (text -> date) and normalization.
SimpleDateFormat
allows you to start by choosing any user-defined patterns for date-time formatting. However you are encouraged to create a date-time formatter with eithergetTimeInstance
getDateInstance
orgetDateTimeInstance
inDateFormat
. Each of these class methods can return a date/time formatter initialized with a default format pattern. You may modify the format pattern using theapplyPattern
methods as desired. For more information on using these methods see DateFormatDate
TimeandFormatTimeSyntax:Patterns
To specifyDatetheand timeformatformats areuse aspecified by date and time patternstringstrings.InWithinthisdate and time patternall ASCIIstrings unquoted lettersarefromreserved'A'
astopattern'Z'
lettersand from'a'
towhich'z'
aredefinedinterpreted as pattern letters representing thefollowing:componentsSymbol Meaning Presentationof a date or timeExamplestring.------Text-------can------------be-------quotedG era designatorusing single quotes (Text'
)AD ytoyearavoid(Number)interpretation.1996"''"
M month inrepresents a singleyearquote.(TextAll&otherNumber)charactersJuly &are not07interpreted;dthey'reday in monthsimply copied into(Number)the10 h hour inoutput string during formattingam/pmor(1~12)matched(Number)against12 H hour inthe input string duringdayparsing.(0~23)
(Number)The0 m minute in hourfollowing pattern letters are defined (Number)all30 s secondother characters fromin'A'
minuteto(Number)'Z'
55andSfrom'a'
millisecondto(Number'z'
are reserved):978 E dayPattern letters are usually repeated
inLetter weekDate (Text)orTuesday DTime ComponentdayPresentation inExamples year(Number)G
189Era FdesignatordayText ofAD
weekiny
monthYear (Number)Year 21996
;(2nd96
WedM
Month in year Month July
;)Jul
;07
w
weekWeek in year (Number )27
W
weekWeek in month (Number )2
a am/pm marker (Text)PMkD
hourDay in day (1~24)year(Number )24189
Khourd
inDay am/pmin(0~11)month(Number )010
ztimeF
zoneDay (Text)ofPacific Standard Timeweek in month'Number escape2
fortextE
(Delimiter)Day ''insingleweekquoteText (Literal)Tuesday
;'Tue
a
TheAm/pm countmarkerofText patternPM
lettersdetermineH
theHour format.in day (Text0-23): 4orNumber more0
patternletters--usek
fullHour formin<day4-(1-use short24)orNumber abbreviated24
formifK
oneHour exists.in am/pm (Number0-11): theminimumNumber number0
ofdigits.h
ShorterHour numbersinaream/pmzero(1-padded12)toNumber this12
amount.Yearm
isMinute handledinspecially;hourthatNumber is30
ifthes
countSecond ofin'y'minuteisNumber 255
theYearS
willMillisecond beNumber truncated978
to2z
digits.Time zone (TextGeneral &timeNumber):zone3Pacific
;orStandardoverTimeusePST
;textGMT-08:00
otherwiseuseZ
number.Time zone AnyRFC characters in822 timethezonepattern-0800
that are not in the ranges of['a'..'z']asandtheir['A'..'Z']numberwill be treateddetermines the exactaspresentation:quoted
text.- Text: For
instance characters likeformatting':'if'.'the' 'number of'#'patternandletters'@'iswill appear in4 or more theresulting time textfulleven theyform isareused;not embraced within singleotherwise a short orquotes.abbreviatedA pattern containingform is used ifanyavailable.invalid pattern letter will result in a thrown exception during formatting or parsingFor parsing both forms are accepted independent of the number of pattern letters.Examples Using the US LocaleNumber:Format Pattern Result --------------For-------formatting"yyyy.MM.ddtheGnumber'at'ofhh:mm:sspatternz"letters-is1996.07.10theAD atminimum number15:08:56ofPDTdigits"EEEandMMM dshorter numbers''yy"are zero-Wed Julypadded10to'96this"h:mmamount.a"For-parsing12:08thePMnumber"hhof'o''clock'patternaletterszzzz"is-ignored12 ounless it'clock PM Pacific Daylight Time "K:mm a z" - 0:00 PM PSTs"yyyyy.MMMMM.ddneededGGGtohh:mmseparateaaa"two-adjacent1996fields.July.10 AD 12:08 PMCode SampleYear:SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000For"PST");formattingpdt.setStartRule(DateFields.APRILif1theDateFields.SUNDAYnumber2*60*60*1000);ofpdt.setEndRule(DateFields.OCTOBERpattern-1lettersDateFields.SUNDAYis 2*60*60*1000); // Formatthecurrent time. SimpleDateFormat formatter = new SimpleDateFormat ("yyyy.MM.ddyearGis'at'truncatedhh:mm:sstoa2zzz")digits;Date currentTime_1 =otherwisenewitDate();isString dateString =interpreted as aformatternumber.format(currentTime_1);For
//parsingParseif theprevious string back into a Date.numberParsePosition pos = newof pattern letters isParsePosition(0);moreDatethancurrentTime_2= formatter.parse(dateString pos); In the examplethetime value currentTime_2 obtained from parsing will be equal to currentTime_1. However theyyearmay not be equal ifis interpreted literally regardless of theam/pm marker 'a'numberisofleftdigits.out fromSo using theformatpatternwhile the"hour in amMM/pmdd/yyyy"pattern symbol is used. This information loss can happen"01/11/12"when formatting the time inparses to Jan 11 12PMA.D.
WhenFor parsinga date string usingwith the abbreviated year pattern ("y" or "yy")SimpleDateFormat
must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 80 years before and 20 years after the time theSimpleDateFormat
instance is created. For example using a pattern of "MM/dd/yy" and aSimpleDateFormat
instance created on Jan 1 1997 the string "01/11/12" would be interpreted as Jan 11 2012 while the string "05/04/64" would be interpreted as May 4 1964. During parsing only strings consisting of exactly two digits as defined by Character#isDigit(char) will be parsed into the default century. Any other numeric string such as a one digit string a three or more digit string or a two digit string that isn't all digits (for example "-1") is interpreted literally. So "01/02/3" or "01/02/003" are parsed using the same pattern as Jan 2 3 AD. Likewise "01/02/-3" is parsed as Jan 2 4 BC.- Month: If the
year pattern has more than twonumber of pattern letters is 3'y'orcharactersmore theyearmonth is interpretedliterallyasregardlesstext;ofotherwisetheit is interpreted as a number.of- General
digitstime zone: Time zones are interpreted as text if they have names.SoForusingtime zones representing a GMT offset value thepatternfollowing"MM/dd/yyyy"syntax"01/11/12"isparsesused:toHours must be between 0 and 23 and Minutes must be between 00 and 59.JanGMTOffsetTimeZone:11GMT
12Sign HoursA:
Minutes Sign: one of+ -
Hours: Digit Digit Digit Minutes: Digit Digit Digit: one of0 1 2 3 4 5 6 7 8 9
DThe format is locale independent and digits must be taken from the Basic Latin block of the Unicode standard.
For parsing RFC 822 time zonesthat haveare alsonoaccepted.names- RFC
use strings822 timeGMT+hourszone:minutesorForGMTformatting the RFC 822 4-hoursdigit time zone format is used:RFC822TimeZone: Sign TwoDigitHours Minutes TwoDigitHours:minutesDigit Digit TwoDigitHours must be between 00 and 23. Other definitions are as for general time zones.For
Theparsingcalendargeneraldefinestimewhatzonesisare also accepted.SimpleDateFormat
also supports localized date and time pattern strings. In these strings thefirst daypattern lettersofdescribed above may be replaced with other locale dependent pattern letters.SimpleDateFormat
does not deal with theweeklocalization of text other than thefirstpatternweekletters; that's up to the client of theyearclass.
Examples
Thewhetherfollowing examples show how date andhourstime patterns arezero based orinterpreted in thenotU.S.(0locale. The given date and time arevs2001-07-04 12:08:56orlocal24)timeandin the U.S. Pacific Time time zone.There
Date and Time Pattern Result "yyyy.MM.dd G 'at' HH:mm:ss z"
2001.07.04 AD at 12:08:56 PDT
"EEE MMM d ''yy"
Wed Jul 4 '01
"h:mm a"
12:08 PM
"hh 'o''clock' a zzzz"
12 o'clock PM Pacific Daylight Time
"K:mm a z"
0:08 PM PDT
"yyyyy.MMMMM.dd GGG hh:mm aaa"
02001.July.04 AD 12:08 PM
"EEE d MMM yyyy HH:mm:ss Z"
Wed 4 Jul 2001 12:08:56 -0700
"yyMMddHHmmssZ"
010704120856-0700
Synchronization
Date formats are not synchronized. It is
onerecommended tocommon decimalcreate separate formattoinstanceshandle allfor eachthethread.numbers;Ifthe digit count is handled programmatically according to themultiple threads access a format concurrently it must bepatternsynchronized externally. @seejava.util.CalendarJava Tutorial @see java.util.GregorianCalendarCalendar @see java.util.TimeZone @see DateFormat @see DateFormatSymbols @see DecimalFormat @version 1.52 0168 12/1903/0001 @author Mark Davis Chen-Lieh Huang Alan Liu
Class SimpleDateFormat, constructor SimpleDateFormat(String)ConstructConstructs aSimpleDateFormat
using the default pattern and date format symbols for the default locale. Note:Not allThis constructorlocalesmay not supportSimpleDateFormat;allforlocales. For fullgeneralitycoverage use the factory methods in the DateFormat class.@see java.text.DateFormat
Class SimpleDateFormat, constructor SimpleDateFormat(String, DateFormatSymbols)ConstructConstructs aSimpleDateFormat
using the given patterninand the default date format symbols for the default locale. Note:Not allThis constructorlocalesmay not supportSimpleDateFormat;allforlocales. For fullgeneralitycoverage use the factory methods in the DateFormat class. @param pattern the pattern describing the date and time format @exception NullPointerException if the given pattern is null @exception IllegalArgumentException if the given pattern is invalid
Class SimpleDateFormat, constructor SimpleDateFormat(String, Locale)ConstructConstructs aSimpleDateFormat
using the given pattern andlocale-specificdatesymbol dataformat symbols. @param pattern the pattern describing the date and time format @param formatSymbols the date format symbols to be used for formatting @exception NullPointerException if the given pattern or formatSymbols is null @exception IllegalArgumentException if the given pattern is invalid
Class SimpleDateFormat, void applyLocalizedPattern(String)ConstructConstructs aSimpleDateFormat
using the given pattern and the default date format symbols for the given locale. Note:Not all localesThis constructor may not supportSimpleDateFormat;allforlocales. For fullgeneralitycoverage use the factory methods in the DateFormat class. @param pattern the pattern describing the date and time format @param locale the locale whose date format symbols should be used @exception NullPointerException if the given pattern is null @exception IllegalArgumentException if the given pattern is invalid
Class SimpleDateFormat, void applyPattern(String)ApplyApplies the given localized pattern string to this date format. @param pattern a String to be mapped to the new date and time format pattern for this format @exception NullPointerException if the given pattern is null @exception IllegalArgumentException if the given pattern is invalid
Class SimpleDateFormat, Object clone()ApplyApplies the givenunlocalizedpattern string to this date format. @param pattern the new date and time pattern for this date format @exception NullPointerException if the given pattern is null @exception IllegalArgumentException if the given pattern is invalid
Class SimpleDateFormat, boolean equals(Object)OverridesCreatesCloneablea copy of thisSimpleDateFormat
. This also clones the format's date format symbols. @return a clone of thisSimpleDateFormat
Class SimpleDateFormat, StringBuffer format(Date, StringBuffer, FieldPosition)OverrideComparesequalsthe given object with thisSimpleDateFormat
for equality. @return true if the given object is equal to thisSimpleDateFormat
Class SimpleDateFormat, Date get2DigitYearStart()Overrides DateFormatFormatsa date or time which isthestandard millis sincegivenJanuaryDate
1 1970into a00:00:00date/timeGMT.stringExample:andusingappends theUS locale: "yyyy.MM.dd G 'at'resultHH:mm:sstozzz"the-given1996StringBuffer
.07.10 AD at 15:08:56 PDT@param date the date-time value to be formatted into a date-time string. @param toAppendTo where the new date-time text is to be appended. @param pos the formatting position. On input: an alignment field if desired. On output: the offsets of the alignment field. @return the formatted date-time string. @seeexceptionjava.text.DateFormatNullPointerException if the given date is null
Returns the beginning date of the 100-year period 2-digit years are interpreted as being within. @return the start of the 100-year period into which two digit years are parsed @see #set2DigitYearStartClass SimpleDateFormat, DateFormatSymbols getDateFormatSymbols()
Gets a copy of the dateClass SimpleDateFormat, int hashCode()/and timeformattingformatdata.symbols@returnofa copythis dateofformat. @return the date-timeandformatting data associated withtime format symbols of this date-timeformatter.format @see #setDateFormatSymbols
Class SimpleDateFormat, Date parse(String, ParsePosition)OverrideReturnshashCodethe hash code value for thisSimpleDateFormat
object.Generates@return the hash code value forthethisSimpleDateFormat
object.
Class SimpleDateFormat, void set2DigitYearStart(Date)OverridesParsesDateFormattext from a string to produce aDate
.The method attempts to parse text starting at the index given by
If an error occurs then the index ofpos
. If parsing succeeds then the index ofpos
is updated to the index after the last character used (parsing does not necessarily use all characters up to the end of the string) and the parsed date is returned. The updatedpos
can be used to indicate the starting point for the next call to this method.pos
is not changed the error index ofpos
is set to the index of the character where the error occurred and null is returned. @param source AString
part of which should be parsed. @param pos AParsePosition
object with index and error index information as described above. @seereturn AjavaDate
parsed from the string. In case of error returns null. @exception NullPointerException iftext or
pos
is null.DateFormat
Sets the 100-year period 2-digit years will be interpreted as being in to begin on the date the user specifies. @param startDate During parsing two digit years will be placed in the rangeClass SimpleDateFormat, void setDateFormatSymbols(DateFormatSymbols)startDate
tostartDate + 100 years
. @see #get2DigitYearStart
Class SimpleDateFormat, String toLocalizedPattern()AllowsSetsyou to setthe date/and timeformattingformat symbols ofdatathis date format. @paramnewFormatDatanewFormatSymbols thegivennew date-and timeformattingformatdata.symbols @exception NullPointerException if the given newFormatSymbols is null @see #getDateFormatSymbols
Class SimpleDateFormat, String toPattern()ReturnReturns a localized pattern string describing this date format. @return a localized pattern string describing this date format.
ReturnReturns a pattern string describing this date format. @return a pattern string describing this date format.