ICU-403 add version number documentation
X-SVN-Rev: 2260
This commit is contained in:
Alan Liu
parent
8e99af2483
commit
e1dfa965e8
@ -68,6 +68,8 @@ All Rights Reserved.</p>
|
||||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#CharsetConvert">Character
|
||||
Set Conversion Information</a></li>
|
||||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#VersionNumbers">Version Numbers in ICU</a></li>
|
||||
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
|
||||
mso-list:l3 level1 lfo3;tab-stops:list .5in'><a href="#ProgrammingNotes">Programming
|
||||
Notes</a></li>
|
||||
@ -1014,6 +1016,210 @@ http://oss.software.ibm.com/developerworks/opensource/icu/localeexplorer/?conver
|
||||
document number SC09-2190-00. The cost of this publication is $75.00 US not
|
||||
including tax. </p>
|
||||
|
||||
<h3><a name=VersionNumbers></a><u>Version Numbers in ICU</u></h3>
|
||||
|
||||
<p>ICU supports extensive versioning of its code and data. Versioning
|
||||
allows clients to determine when parts of ICU change, and what the
|
||||
effect of the change is.
|
||||
|
||||
<p>ICU as a whole has a version number. ICU components such as Collator
|
||||
have their own distinct version numbers. Each resource bundle,
|
||||
including all the locale data resource bundles, has its own version
|
||||
number. Individual tagged items within a resource bundle have their
|
||||
own version numbers.
|
||||
|
||||
<p>All version numbers are in the form of a UVersionInfo structure, which
|
||||
is an array of four unsigned bytes. These bytes are:
|
||||
|
||||
<ul>
|
||||
<li>0: Major version number</li>
|
||||
<li>1: Minor version number</li>
|
||||
<li>2: Milli version number</li>
|
||||
<li>3: Patch version number</li>
|
||||
</ul>
|
||||
|
||||
<p>UVersionNumber structures can be converted to and from string
|
||||
representations as dotted integers, such as "1.4.5.0", using the
|
||||
u_versionToString() and u_stringToVersion() functions.
|
||||
|
||||
<p>Version numbers monotonically increase as changes are made. Two
|
||||
UVersionInfo structure may be compared using binary comparison
|
||||
(memcmp) to see which is larger (newer). It only makes sense to
|
||||
compare the same flavor of version number; you cannot compare the ICU
|
||||
version number to the Collator version number, for instance.
|
||||
|
||||
<p>The interpretation of version numbers depends on what is being
|
||||
described.
|
||||
|
||||
<h4>ICU Release Version Number</h4>
|
||||
|
||||
<p>0 (Major): Reference release with major feature addition or change.
|
||||
|
||||
<p>1 (Minor): Reference release without major feature addition.
|
||||
|
||||
<p>2 (Milli): Maintenance update to the reference releases.
|
||||
|
||||
<p>3 (Patch): Enhancement/patch update.
|
||||
|
||||
|
||||
<h4>Code Component Version Numbers</h4>
|
||||
|
||||
<p>0 (Major): Breaking change. Results and data generated by the new
|
||||
version are incompatible with those generated by the preceding
|
||||
version. <em>Example</em>: In ICU 1.5, the implementation of ResourceBundle
|
||||
changed drastically. The data structure, algorithm for parsing data,
|
||||
and so on are completely different in 1.5. This required an increment
|
||||
of the major version number.
|
||||
|
||||
<p>1 (Minor): Backward-compatible change. The new version of the code
|
||||
can read or use data generated by the old version, but the old version
|
||||
cannot read or use data generated by the new version. <em>Example</em>: The
|
||||
delimiter in the CollationKey gets changed from 0x0000 to 0xFFFF. The
|
||||
algorithm keeps track of the differences and recognize these two
|
||||
different formats before and after a particular release.
|
||||
|
||||
<p>2 (Milli): Compatible change. Results and data generated by the new
|
||||
version are compatible with those generated by the preceding version.
|
||||
<em>Example</em>: A byte in the reserved bytes in the data structure is now
|
||||
used as a flag/bitmask or whatever, e.g. UDataInfo. The size of the
|
||||
data structure is changed and new code is added to check for this
|
||||
flag. No other changes are made.
|
||||
|
||||
<p>3 (Patch): Enhancement. A minor change. <em>Example</em>: Performance
|
||||
enhancements applied to the code but no changes other than that.
|
||||
|
||||
|
||||
<h4>Data Component Version Numbers</h4>
|
||||
|
||||
<p>0 (Major): Incompatible format change. The layout or format of the
|
||||
data has changed. For example, an additional array element has been
|
||||
added, or an additional tag. <em>Example</em>: ICU 1.6 changes the element
|
||||
layout in "CollationElements". We changed this from a tag with plain
|
||||
string value to a tagged array with 3 new subtags, "Version",
|
||||
"Override" and "Sequence". This change is incompatible with pre-1.6
|
||||
code and data.
|
||||
|
||||
<p>1 (Minor): Backward-compatible format change. A change that can be
|
||||
read and used by previous versions of ICU, but that adds data used by
|
||||
newer versions. <em>Example</em>: We added a new tag called "Author" to the
|
||||
data file. The only difference between the previous version of the
|
||||
data files and the current version is this tag.
|
||||
|
||||
<p>2 (Milli): Compatible change. A change to the data without
|
||||
modification of the format. <em>Example</em>: We updated the value of a tag
|
||||
"LocaleID" from "041C" to "3801". No other changes were made.
|
||||
|
||||
<p>3 (Patch): Enhancement. A minor change. <em>Example</em>: We changed the
|
||||
comments in the data file, perhaps the copyright notices.
|
||||
|
||||
|
||||
<h4>Resource Bundles and Elements</h4>
|
||||
|
||||
<p>The data stored in resource bundles is tagged with version numbers.
|
||||
A resource bundle can contain a tagged string named "Version" that
|
||||
declares the version number in dotted-integer format. <em>Example</em>:
|
||||
|
||||
<pre>
|
||||
en {
|
||||
Version { "1.0.3.5" }
|
||||
...
|
||||
}
|
||||
</pre>
|
||||
|
||||
<p>A resource bundle may omit the "Version" element, in which case it
|
||||
will inherit one along the usual chain. <em>Example</em>: If the resource
|
||||
bundle en_US contained no "Version" element, it would inherit
|
||||
"1.0.3.5" from en.
|
||||
|
||||
<p>If inheritance passes all the way to the root resource bundle and it
|
||||
contains no "Version" resource, then the default version number
|
||||
1.0.0.0 is returned.
|
||||
|
||||
<p>Elements within a resource bundle may also contain version numbers,
|
||||
for example:
|
||||
|
||||
<pre>
|
||||
be {
|
||||
CollationElements {
|
||||
Version { "1.0.0.0" }
|
||||
...
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
<p>Here the CollationElements data is version 1.0.0.0. This version
|
||||
may differ from the version of the enclosing bundle.
|
||||
|
||||
<p>If a resource element lacks a "Version" element, then it inherits the
|
||||
"Version" element of its enclosing resource bundle. (This is a special
|
||||
case; in general, resource bundle elements do not inherit data from
|
||||
enclosing structures.) <em>Example</em>:
|
||||
|
||||
<pre>
|
||||
en {
|
||||
Version { "1.0.3.5" }
|
||||
...
|
||||
}
|
||||
|
||||
en_US {
|
||||
CollationElements {
|
||||
...(contains no "Version" element)
|
||||
}
|
||||
}
|
||||
</pre>
|
||||
|
||||
<p>Here, the version of the CollationElements in en_US is 1.0.3.5. It
|
||||
inherits the en_US version, which is inherited from en.
|
||||
|
||||
<p><b>NOTE</b>: The API and code to fully support the mechanism described above
|
||||
is not in place yet as of ICU 1.6. See Future Enhancements below.
|
||||
|
||||
|
||||
<h4>What Components are Versioned</h4>
|
||||
|
||||
<p>Currently, the following components are versioned.
|
||||
|
||||
<ul>
|
||||
<li>The version of ICU as a whole is returned by u_getVersion().</li>
|
||||
|
||||
<li>The version of a ResourceBundle is returned by ures_getVersion() and
|
||||
ResourceBundle::getVersion(). This is a data version number for the
|
||||
bundle as a whole.</li>
|
||||
|
||||
<li>The version of the Unicode character data underlying ICU is returned
|
||||
by u_getUnicodeVersion() and Unicode::getUnicodeVersion(). This
|
||||
version reflects the numbering of the Unicode releases; see
|
||||
<a href="http://www.unicode.org">http://www.unicode.org</a>.</li>
|
||||
|
||||
<li>The version of the Collator is returned by Collator::getVersion().
|
||||
This is a code version number for the collation code and algorithm.</li>
|
||||
</ul>
|
||||
|
||||
<h4>Future Enhancements</h4>
|
||||
|
||||
<ul>
|
||||
<li>The ResourceBundle version number inheritance mechanism is not fully
|
||||
implemented and tested.</li>
|
||||
|
||||
<li>The resource element version number is not implemented at all.
|
||||
API for this does not yet exist.</li>
|
||||
|
||||
<li>Versioning of a RuleBasedCollator's data is only possible through
|
||||
the ResourceBundle API. There should probably be API on
|
||||
RuleBasedCollator (or Collator) to obtain the data version number.</li>
|
||||
|
||||
<li>Versioning of the Normalizer data is not implemented.</li>
|
||||
|
||||
<li>Versioning of the Normalizer algorithm is not implemented.</li>
|
||||
|
||||
<li>Versioning of the Transliterators is not implemented.</li>
|
||||
|
||||
<li>Versioning of formatters, break iterators, and so on is not
|
||||
implemented.</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<h3><a name=ProgrammingNotes></a><u>Programming Notes</u></h3>
|
||||
|
||||
<h4><u>Reporting Errors</u></h4>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user