organicmaps/icu
13
Fork 0
mirror of https://github.com/unicode-org/icu.git synced 2025-04-05 05:25:34 +00:00
Code Issues 1 Projects Releases Wiki Activity Actions 11

ICU-23041 Hard-code the code citations and remove jcite

Browse source
This commit is contained in:
Mihai Nita 2025-02-06 19:15:37 +00:00
parent 362a4aa94b
commit 5d7f0b8100
10 changed files with 414 additions and 169 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/processes/release/tasks/docs.md
View file

@ -368,9 +368,6 @@ Note: This is also referenced below [Upload API documentations](docs.md#upload-a
### ICU4J
**Note:** JCite must be installed for building ICU4J documentation:
<https://icu.unicode.org/setup/java/ant#TOC-Building-ICU4J-API-Reference-Document-with-JCite>
Build the API documentation pages for the new release:
```

5
docs/processes/release/tasks/release-build.md
View file

@ -36,7 +36,6 @@ compiled with Java system libraries from JRE 7.*</span>
* Java Runtime Environment 7 (used as bootclasspath for cross-compilation)
* Apache Ant 1.10.x (the latest available version)
\[<http://ant.apache.org/>\]
* JCite 1.13.0 \[<https://arrenbrecht.ch/jcite/>\]
### Other Prerequisites only for GA
@ -56,9 +55,6 @@ compiled with Java system libraries from JRE 7.*</span>
### Configuration
* Set environment variable `JAVA_HOME` to point to the JDK directory.
* Set environment variable `JCITE_DIR` to specify JCite binary location (see[
Building ICU4J API Reference Document with
JCite](../../../setup/java/ant/index.md))
* See `build.properties` to check version strings are properly set.
* `api.report.version` / `api.report.prev.version` are used for locating
API signature files and should be integer numbers.
@ -150,7 +146,6 @@ compiled with Java system libraries from JRE 7.*</span>
[echo] [WARNING] Insufficient Build Configuration for ICU4J Release
[echo] JDK Tools Version: 1.8.0_152
[echo] JRE 7 System Library Path: Not Defined!
[echo] JCite Library Path: /home/yoshito/java-libs/jcite-1.13.0/build/jcite.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/commons-discovery-0.4.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/commons-logging-1.1.jar:/home/yoshito/java-libs/jcite-1.13.0/lib/java2html.jar`
[echo] ################################################################
BUILD SUCCESSFUL

34
docs/userguide/dev/codingguidelines.md
View file

@ -198,41 +198,9 @@ Coding examples help users to understand the usage of each API. Whenever
possible, it is encouraged to embed a code snippet illustrating the usage of an
API along with the functional specification.
#### Embedding Coding Examples in ICU4J - JCite
Since ICU4J 49M2, the ICU4J ant build target "doc" utilizes an external tool
called [JCite](https://arrenbrecht.ch/jcite/). The tool allows us to cite a
fragment of existing source code into JavaDoc comment using a tag. To embed a
code snippet with the tag. For example,
`{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getNextTransitionExample}`
will be replaced a fragment of code marked by comment lines
`// ---getNextTransisionExample` in `BasicTimeZoneExample.java` in package
`com.ibm.icu.samples.util.timezone`. When embedding code snippet using JCite, we
recommend to follow next guidelines
* A sample code should be placed in `<icu4j_root>/samples/src` directory,
although you can cite any source fragment from source files in
`<icu4j_root>/demos/src`, `<icu4j_root\>/main/core/*/src`,
`<icu4j_root>/main/test/*/src`.
* A sample code should use package name -
`com.ibm.icu.samples.<subpackage>.<facility>`. `<subpackage>` is corresponding
to the target ICU API class's package, that is, one of lang/math/text/util.
`<facility>` is a name of facility, which is usually the base class of the
service. For example, use package `com.ibm.icu.samples.text.dateformat` for
samples related to ICU's date format service,
`com.ibm.icu.samples.util.timezone` for samples related to time zone service.
* A sample code should be self-contained as much as possible (use only JDK and
ICU public APIs if possible). This allows readers to cut & paste a code
snippet to try it out easily.
* The citing comment should start with three consecutive hyphen followed by
lower camel case token - for example, "`// ---compareToExample`"
* Keep in mind that the JCite tag `{@.jcite ...}` is not resolved without JCite.
It is encouraged to avoid placing code snippet within a sentence. Instead,
you should place a code snippet using JCite in an independent paragraph.
#### Embedding Coding Examples in ICU4C
Also since ICU4C 49M2, ICU4C docs (using the [\\snippet command](http://www.doxygen.nl/manual/commands.html#cmdsnippet)
Since ICU4C 49M2, ICU4C docs (using the [\\snippet command](http://www.doxygen.nl/manual/commands.html#cmdsnippet)
which is new in Doxygen 1.7.5) can cite a fragment of existing sample or test code.
Example in `ucnv.h`:

94
icu4j/main/core/src/main/java/com/ibm/icu/text/DateIntervalFormat.java
View file

@ -570,7 +570,54 @@ public class DateIntervalFormat extends UFormat {
* This is a convenient override of
* getInstance(String skeleton, ULocale locale)
*
* <p>Example code:{@.jcite com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:---dtitvfmtPreDefinedExample}
* <!-- From: com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:dtitvfmtPreDefinedExample -->
* <p>Example code:<p>
*
* <pre>
* import java.util.Date;
*
* import com.ibm.icu.text.DateFormat;
* import com.ibm.icu.text.DateIntervalFormat;
* import com.ibm.icu.text.DateIntervalInfo;
* import com.ibm.icu.util.Calendar;
* import com.ibm.icu.util.DateInterval;
* import com.ibm.icu.util.GregorianCalendar;
* import com.ibm.icu.util.ULocale;
* ...
* final Date date[] = {
* new GregorianCalendar(2007,10,10,10,10,10).getTime(),
* new GregorianCalendar(2008,10,10,10,10,10).getTime(),
* new GregorianCalendar(2008,11,10,10,10,10).getTime(),
* new GregorianCalendar(2008,11,10,15,10,10).getTime(),
* };
* final DateInterval dtitv[] = {
* new DateInterval(date[0].getTime(),date[1].getTime()),
* new DateInterval(date[1].getTime(),date[2].getTime()),
* new DateInterval(date[2].getTime(),date[3].getTime()),
* };
* final String [] skeletons = {
* DateFormat.YEAR_ABBR_MONTH_DAY,
* DateFormat.MONTH_DAY,
* DateFormat.HOUR_MINUTE,
* };
* System.out.printf("%-15s%-35s%-35s%-35s%-35s\n", "Skeleton", "from","to","Date Interval in en_US", "Date Interval in Ja");
* int i=0;
* for (String skeleton:skeletons) {
* System.out.printf("%-15s%-35s%-35s", skeleton,date[i].toString(), date[i+1].toString());
* DateIntervalFormat dtitvfmtEn = DateIntervalFormat.getInstance(skeleton, ULocale.ENGLISH);
* DateIntervalFormat dtitvfmtJa = DateIntervalFormat.getInstance(skeleton, ULocale.JAPANESE);
* System.out.printf("%-35s%-35s\n", dtitvfmtEn.format(dtitv[i]),dtitvfmtJa.format(dtitv[i]));
* i++;
* }
* /** output of the sample code:
* *********************************************************************************************************************************************************
* Skeleton from to Date Interval in en_US Date Interval in Ja
* yMMMd Sat Nov 10 10:10:10 EST 2007 Mon Nov 10 10:10:10 EST 2008 Nov 10, 2007 – Nov 10, 2008 2007年11月10日～2008年11月10日
* MMMMd Mon Nov 10 10:10:10 EST 2008 Wed Dec 10 10:10:10 EST 2008 November 10 – December 10 11月10日～12月10日
* jm Wed Dec 10 10:10:10 EST 2008 Wed Dec 10 15:10:10 EST 2008 10:10 AM – 3:10 PM 10:10～15:10
* *********************************************************************************************************************************************************<code>/</code>
* </pre>
*
* @param skeleton the skeleton on which interval format based.
* @param locale the given locale
* @return a date time interval formatter.
@ -650,7 +697,50 @@ public class DateIntervalFormat extends UFormat {
* This is a convenient override of
* getInstance(String skeleton, ULocale locale, DateIntervalInfo dtitvinf)
*
* <p>Example code:{@.jcite com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:---dtitvfmtCustomizedExample}
* <!-- From: com.ibm.icu.samples.text.dateintervalformat.DateIntervalFormatSample:dtitvfmtCustomizedExample -->
* <p>Example code:<p>
*
* <pre>
* final Date date[] = {
* new GregorianCalendar(2007,9,10,10,10,10).getTime(),
* new GregorianCalendar(2007,10,10,10,10,10).getTime(),
* new GregorianCalendar(2007,10,10,22,10,10).getTime(),
* };
* final DateInterval dtitv[] = {
* new DateInterval(date[0].getTime(),date[1].getTime()),
* new DateInterval(date[1].getTime(),date[2].getTime()),
* };
* final String [] skeletons = {
* DateFormat.YEAR_ABBR_MONTH_DAY,
* DateFormat.HOUR24_MINUTE,
* };
* System.out.printf("%-15s%-35s%-35s%-45s%-35s\n", "Skeleton", "from","to", "Date Interval in en_US", "Date Interval in Ja");
* // Create an empty DateIntervalInfo object
* DateIntervalInfo dtitvinf = new DateIntervalInfo(ULocale.ENGLISH);
* // Set Date Time internal pattern for MONTH, DAY_OF_MONTH, HOUR_OF_DAY
* dtitvinf.setIntervalPattern("yMMMd", Calendar.MONTH, "y 'Diff' MMM d --- MMM d");
* dtitvinf.setIntervalPattern("Hm", Calendar.HOUR_OF_DAY, "yyyy MMM d HH:mm ~ HH:mm");
* // Set fallback interval pattern
* dtitvinf.setFallbackIntervalPattern("{0} ~~~ {1}");
* // Get the DateIntervalFormat with the custom pattern
* for (String skeleton:skeletons){
* for (int i=0;i<2;i++) {
* System.out.printf("%-15s%-35s%-35s", skeleton,date[i].toString(), date[i+1].toString());
* DateIntervalFormat dtitvfmtEn = DateIntervalFormat.getInstance(skeleton,ULocale.ENGLISH,dtitvinf);
* DateIntervalFormat dtitvfmtJa = DateIntervalFormat.getInstance(skeleton,ULocale.JAPANESE,dtitvinf);
* System.out.printf("%-45s%-35s\n", dtitvfmtEn.format(dtitv[i]),dtitvfmtJa.format(dtitv[i]));
* }
* }
* /** output of the sample code:
* *************************************************************************************************************************************************************************
* Skeleton from to Date Interval in en_US Date Interval in Ja
* yMMMd Wed Oct 10 10:10:10 EDT 2007 Sat Nov 10 10:10:10 EST 2007 2007 Diff Oct 10 --- Nov 10 2007 Diff 10月 10 --- 11月 10
* yMMMd Sat Nov 10 10:10:10 EST 2007 Sat Nov 10 22:10:10 EST 2007 Nov 10, 2007 2007年11月10日
* Hm Wed Oct 10 10:10:10 EDT 2007 Sat Nov 10 10:10:10 EST 2007 10/10/2007, 10:10 ~~~ 11/10/2007, 10:10 2007/10/10 10:10 ~~~ 2007/11/10 10:10
* Hm Sat Nov 10 10:10:10 EST 2007 Sat Nov 10 22:10:10 EST 2007 2007 Nov 10 10:10 ~ 22:10 2007 11月 10 10:10 ~ 22:10
* *************************************************************************************************************************************************************************<code>/</code>
* </pre>
*
* @param skeleton the skeleton on which interval format based.
* @param locale the given locale
* @param dtitvinf the DateIntervalInfo object to be adopted.

146
icu4j/main/core/src/main/java/com/ibm/icu/text/DateTimePatternGenerator.java
View file

@ -617,7 +617,85 @@ public class DateTimePatternGenerator implements Freezable<DateTimePatternGenera
/**
* Return the best pattern matching the input skeleton. It is guaranteed to
* have all of the fields in the skeleton.
* <p>Example code:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---getBestPatternExample}
*
* <!-- From: com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:getBestPatternExample -->
* <p>Example code:</p>
*
* <pre>
* import java.util.Date;
*
* import com.ibm.icu.text.DateFormat;
* import com.ibm.icu.text.DateTimePatternGenerator;
* import com.ibm.icu.text.SimpleDateFormat;
* import com.ibm.icu.util.GregorianCalendar;
* import com.ibm.icu.util.TimeZone;
* import com.ibm.icu.util.ULocale;
* ...
* final String[] skeletons = {
* "yQQQQ", // year + full name of quarter, i.e., 4th quarter 1999
* "yMMMM", // year + full name of month, i.e., October 1999
* "MMMMd", // full name of month + day of the month, i.e., October 25
* "hhmm", // 12-hour-cycle format, i.e., 1:32 PM
* "jjmm" // preferred hour format for the given locale, i.e., 24-hour-cycle format for fr_FR
* };
* final ULocale[] locales = {
* new ULocale ("en_US"),
* new ULocale ("fr_FR"),
* new ULocale ("zh_CN"),
* };
* DateTimePatternGenerator dtfg = null;
* Date date= new GregorianCalendar(1999,9,13,23,58,59).getTime();
* System.out.printf("%-20s%-35s%-35s%-35s\n\n", "Skeleton", "en_US", "fr_FR","zh_CN");
* for (String skeleton:skeletons) {
* System.out.printf("%-20s", skeleton);
* for (ULocale locale:locales) {
* // create a DateTimePatternGenerator instance for given locale
* dtfg = DateTimePatternGenerator.getInstance(locale);
* // use getBestPattern method to get the best pattern for the given skeleton
* String pattern = dtfg.getBestPattern(skeleton);
* // Constructs a SimpleDateFormat with the best pattern generated above and the given locale
* SimpleDateFormat sdf = new SimpleDateFormat(pattern, locale);
* // Get the format of the given date
* System.out.printf("%-35s",sdf.format(date));
* }
* System.out.println("\n");
* }
* /** output of the sample code:
* *************************************************************************************************************
* Skeleton en_US fr_FR zh_CN
* yQQQQ 4th quarter 1999 4e trimestre 1999 1999年第四季度
* yMMMM October 1999 octobre 1999 1999年10月
* MMMMd October 13 13 octobre 10月13日
* hhmm 11:58 PM 11:58 PM 下午11:58
* jjmm 11:58 PM 23:58 下午11:58
* **************************************************************************************************************<code>/</code>
* // Use DateTime.getPatternInstance to produce the same Date/Time format with predefined constant field value
* final String[] dtfskeleton = {
* DateFormat.YEAR_QUARTER, // year + full name of quarter, i.e., 4th quarter 1999
* DateFormat.YEAR_MONTH, // year + full name of month, i.e., October 1999
* DateFormat.MONTH_DAY // full name of month + day of the month, i.e., October 25
* };
* System.out.printf("%-20s%-35s%-35s%-35s\n\n", "Skeleton", "en_US", "fr_FR","zh_CN");
* for (String skeleton:dtfskeleton) {
* System.out.printf("%-20s", skeleton);
* for (ULocale locale:locales) {
* // Use DateFormat.getPatternInstance to get the date/time format for the locale,
* // and apply the format to the given date
* String df=DateFormat.getPatternInstance(skeleton,locale).format(date);
* System.out.printf("%-35s",df);
* }
* System.out.println("\n");
* }
*
* /** output of the sample code:
* ************************************************************************************************************
* Skeleton en_US fr_FR zh_CN
* yQQQQ 4th quarter 1999 4e trimestre 1999 1999年第四季度
* yMMMM October 1999 octobre 1999 1999年10月
* MMMMd October 13 13 octobre 10月13日
* ************************************************************************************************************<code>/</code>
* </pre>
*
* @param skeleton The skeleton is a pattern containing only the variable fields.
* For example, "MMMdd" and "mmhh" are skeletons.
* @return Best pattern matching the input skeleton.
@ -802,7 +880,31 @@ public class DateTimePatternGenerator implements Freezable<DateTimePatternGenera
* <p>
* Note that single-field patterns (like "MMM") are automatically added, and
* don't need to be added explicitly!
* * <p>Example code:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---addPatternExample}
*
* <!-- From: com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:addPatternExample -->
* <p>Example code:</p>
*
* <pre>
* Date date= new GregorianCalendar(1999,9,13,23,58,59).getTime();
* ULocale locale = ULocale.FRANCE;
* // Create an DateTimePatternGenerator instance for the given locale
* DateTimePatternGenerator gen = DateTimePatternGenerator.getInstance(locale);
* SimpleDateFormat format = new SimpleDateFormat(gen.getBestPattern("MMMMddHmm"), locale);
* DateTimePatternGenerator.PatternInfo returnInfo = new DateTimePatternGenerator.PatternInfo();
* // Add '. von' to the existing pattern
* gen.addPattern("dd'. von' MMMM", true, returnInfo);
* // Apply the new pattern
* format.applyPattern(gen.getBestPattern("MMMMddHmm"));
* System.out.println("New Pattern for FRENCH: "+format.toPattern());
* System.out.println("Date Time in new Pattern: "+format.format(date));
*
* /** output of the sample code:
* **************************************************************************************************
* New Pattern for FRENCH: dd. 'von' MMMM HH:mm
* Date Time in new Pattern: 13. von octobre 23:58
* *************************************************************************************************<code>/</code>
* </pre>
*
* @param pattern Pattern to add.
* @param override When existing values are to be overridden use true, otherwise
* use false.
@ -987,7 +1089,45 @@ public class DateTimePatternGenerator implements Freezable<DateTimePatternGenera
* skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
* "dd-MMMM hh:mm". This is used internally to get the best match for the
* input skeleton, but can also be used externally.
* <p>Example code:{@.jcite com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:---replaceFieldTypesExample}
*
* <!-- From: com.ibm.icu.samples.text.datetimepatterngenerator.DateTimePatternGeneratorSample:replaceFieldTypesExample -->
* <p>Example code:</p>
*
* <pre>
* Date date= new GregorianCalendar(1999,9,13,23,58,59).getTime();
* TimeZone zone = TimeZone.getTimeZone("Europe/Paris");
* ULocale locale = ULocale.FRANCE;
* DateTimePatternGenerator gen = DateTimePatternGenerator.getInstance(locale);
* SimpleDateFormat format = new SimpleDateFormat("EEEE d MMMM y HH:mm:ss zzzz",locale);
* format.setTimeZone(zone);
* String pattern = format.toPattern();
* System.out.println("Pattern before replacement:");
* System.out.println(pattern);
* System.out.println("Date/Time format in fr_FR:");
* System.out.println(format.format(date));
* // Replace zone "zzzz" in the pattern with "vvvv"
* String newPattern = gen.replaceFieldTypes(pattern, "vvvv");
* // Apply the new pattern
* format.applyPattern(newPattern);
* System.out.println("Pattern after replacement:");
* System.out.println(newPattern);
* System.out.println("Date/Time format in fr_FR:");
* System.out.println(format.format(date));
*
* /** output of the sample code:
* ***************************************************************************************************
* Pattern before replacement:
* EEEE d MMMM y HH:mm:ss zzzz
* Date/Time format in fr_FR:
* jeudi 14 octobre 1999 05:58:59 heure avancée d’Europe centrale
* Pattern after replacement:
* EEEE d MMMM y HH:mm:ss vvvv
* Date/Time format in fr_FR:
* jeudi 14 octobre 1999 05:58:59 heure de l’Europe centrale
*
* **************************************************************************************************<code>/</code>
* </pre>
*
* @param pattern input pattern
* @param skeleton For the pattern to match to.
* @return pattern adjusted to match the skeleton fields widths and subtypes.

75
icu4j/main/core/src/main/java/com/ibm/icu/text/PluralFormat.java
View file

@ -295,7 +295,80 @@ public class PluralFormat extends UFormat {
* locale.
* The locale will be used to get the set of plural rules and for
* standard number formatting.
* <p>Example code:{@.jcite com.ibm.icu.samples.text.pluralformat.PluralFormatSample:---PluralFormatExample}
*
* <!-- From: com.ibm.icu.samples.text.pluralformat.PluralFormatSample:PluralFormatExample -->
* <p>Example code:</p>
*
* <pre>
* import java.text.FieldPosition;
*
* import com.ibm.icu.text.MessageFormat;
* import com.ibm.icu.text.PluralFormat;
* import com.ibm.icu.util.ULocale;
* ...
* ULocale locEn = new ULocale("en");
* ULocale locSl = new ULocale("sl");
*
* String patEn = "one{dog} other{dogs}"; // English 'dog'
* String patSl = "one{pes} two{psa} few{psi} other{psov}"; // Slovenian translation of dog in Plural Form
*
* // Create a new PluralFormat for a given locale locale and pattern string
* PluralFormat plfmtEn = new PluralFormat(locEn, patEn);
* PluralFormat plfmtSl = new PluralFormat(locSl, patSl);
* // Constructs a MessageFormat for the specified locale and pattern.
* MessageFormat msgfmtEn = new MessageFormat("{0,number} {1}", locEn);
* MessageFormat msgfmtSl = new MessageFormat("{0,number} {1}", locSl);
*
* final int[] numbers = {0, 1, 2, 3, 4, 5, 10, 100, 101, 102};
* System.out.println("Output by using PluralFormat and MessageFormat API\n");
* System.out.printf("%-16s%-16s%-16s\n", "Number", "English", "Slovenian");
*
* // Use MessageFormat.format () to format the objects and appends to the given StringBuffer
* for (int num : numbers) {
* StringBuffer msgEn = new StringBuffer();
* StringBuffer msgSl = new StringBuffer();
*
* msgfmtEn.format(new Object[] {num, plfmtEn.format(num)}, msgEn, new FieldPosition(0));
* msgfmtSl.format(new Object[] {num, plfmtSl.format(num)}, msgSl, new FieldPosition(0));
*
* System.out.printf("%-16s%-16s%-16s\n", num, msgEn, msgSl);
* }
*
* System.out.println();
*
* // Equivalent code with message format pattern
* String msgPatEn = "{0,plural, one{# dog} other{# dogs}}";
* String msgPatSl = "{0,plural, one{# pes} two{# psa} few{# psi} other{# psov}}";
*
* MessageFormat altMsgfmtEn = new MessageFormat(msgPatEn, locEn);
* MessageFormat altMsgfmtSl = new MessageFormat(msgPatSl, locSl);
* System.out.println("Same Output by using MessageFormat API only\n");
* System.out.printf("%-16s%-16s%-16s\n", "Number", "English", "Slovenian");
* for (int num : numbers) {
* StringBuffer msgEn = new StringBuffer();
* StringBuffer msgSl = new StringBuffer();
*
* altMsgfmtEn.format(new Object[] {num}, msgEn, new FieldPosition(0));
* altMsgfmtSl.format(new Object[] {num}, msgSl, new FieldPosition(0));
*
* System.out.printf("%-16s%-16s%-16s\n", num, msgEn, msgSl);
* }
* /** output of the sample code:
* ********************************************************************
* Number English Slovenian
* 0 0 dogs 0 psov
* 1 1 dog 1 pes
* 2 2 dogs 2 psa
* 3 3 dogs 3 psi
* 4 4 dogs 4 psi
* 5 5 dogs 5 psov
* 10 10 dogs 10 psov
* 100 100 dogs 100 psov
* 101 101 dogs 101 pes
* 102 102 dogs 102 psa
* *******************************************************************<code>/</code>
* </pre>
*
* @param ulocale the <code>PluralFormat</code> will be configured with
* rules for this locale. This locale will also be used for standard
* number formatting.

2
icu4j/main/core/src/main/java/com/ibm/icu/text/RuleBasedNumberFormat.java
View file

@ -419,7 +419,7 @@ import com.ibm.icu.util.UResourceBundleIterator;
* <td>Format the number unchanged</td>
* </tr>
* <tr style="border-top: 1px solid black;">
* <td style="white-space: nowrap;" rowspan="6">[]<br/>[|]</td>
* <td style="white-space: nowrap;" rowspan="6">[]<br>[|]</td>
* <td style="white-space: nowrap; vertical-align: top; padding-left: 1em; padding-right: 1em;">in normal rule</td>
* <td>
* <ul>

107
icu4j/main/core/src/main/java/com/ibm/icu/util/BasicTimeZone.java
View file

@ -35,7 +35,34 @@ public abstract class BasicTimeZone extends TimeZone {
/**
* {@icu} Returns the first time zone transition after the base time.
* <p>Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getNextTransitionExample}
*
* <!-- From: com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:getNextTransitionExample -->
* <p>Example code:</p>
*
* <pre>
* System.out.println("### Iterates time zone transitions in America/Los_Angeles starting 2005-01-01 and forward");
*
* // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
* BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);
*
* // Date format for the wall time
* SimpleDateFormat wallTimeFmt = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss z", ULocale.US);
* wallTimeFmt.setTimeZone(btz);
*
* long start = 1104537600000L; // 2005-01-01 0:00 UTC
* for (int i = 0; i < 5; i++) { // Up to 5 transitions
* TimeZoneTransition trans = btz.getNextTransition(start, false /* not including start time *<code>/</code>);
*
* // Display the transition time and offset information
* long transTime = trans.getTime();
* System.out.println(wallTimeFmt.format(new Date(transTime - 1)) + " -> " + wallTimeFmt.format(new Date(transTime)));
* System.out.println(" - Before (Offset/Save): " + trans.getFrom().getRawOffset() + "/" + trans.getFrom().getDSTSavings());
* System.out.println(" - After (Offset/Save): " + trans.getTo().getRawOffset() + "/" + trans.getTo().getDSTSavings());
*
* // Update start time for next transition
* start = transTime;
* }
* </pre>
*
* @param base The base time.
* @param inclusive Whether the base time is inclusive or not.
@ -50,7 +77,34 @@ public abstract class BasicTimeZone extends TimeZone {
/**
* {@icu} Returns the last time zone transition before the base time.
* <p>Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getPreviousTransitionExample}
*
* <!-- From: com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:getPreviousTransitionExample -->
* <p>Example code:</p>
*
* <pre>
* System.out.println("### Iterates time zone transitions in America/Los_Angeles starting 2010-01-01 and backward");
*
* // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
* BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);
*
* // Date format for the wall time
* SimpleDateFormat wallTimeFmt = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss z", ULocale.US);
* wallTimeFmt.setTimeZone(btz);
*
* long start = 1262304000000L; // 2010-01-01 0:00 UTC
* for (int i = 0; i < 5; i++) { // Up to 5 transitions
* TimeZoneTransition trans = btz.getPreviousTransition(start, false /* not including start time *<code>/</code>);
*
* // Display the transition time and offset information
* long transTime = trans.getTime();
* System.out.println(wallTimeFmt.format(new Date(transTime - 1)) + " -> " + wallTimeFmt.format(new Date(transTime)));
* System.out.println(" - Before (Offset/Save): " + trans.getFrom().getRawOffset() + "/" + trans.getFrom().getDSTSavings());
* System.out.println(" - After (Offset/Save): " + trans.getTo().getRawOffset() + "/" + trans.getTo().getDSTSavings());
*
* // Update start time for next transition
* start = transTime;
* }
* </pre>
*
* @param base The base time.
* @param inclusive Whether the base time is inclusive or not.
@ -68,7 +122,37 @@ public abstract class BasicTimeZone extends TimeZone {
* This method returns true when all of transition times, from/to standard
* offsets and DST savings used by this time zone match the other in the
* time range.
* <p>Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---hasEquivalentTransitionsExample}
*
* <!-- From: com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:hasEquivalentTransitionsExample -->
* <p>Example code:</p>
*
* <pre>
* System.out.println("### Compare America/New_York and America/Detroit since year 1970");
*
* // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
* BasicTimeZone tzNewYork = (BasicTimeZone)TimeZone.getTimeZone("America/New_York", TimeZone.TIMEZONE_ICU);
* BasicTimeZone tzDetroit = (BasicTimeZone)TimeZone.getTimeZone("America/Detroit", TimeZone.TIMEZONE_ICU);
*
* GregorianCalendar cal = new GregorianCalendar(TimeZone.getTimeZone("Etc/GMT"));
*
* // Compare these time zones every 10 years since year 1970 up to year 2009
* for (int startYear = 1970; startYear <= 2000; startYear += 10) {
* long start, end;
*
* cal.set(startYear, Calendar.JANUARY, 1, 0, 0, 0);
* cal.set(Calendar.MILLISECOND, 0);
* start = cal.getTimeInMillis();
*
* // Set the end time to the end of startYear + 9
* int endYear = startYear + 9;
* cal.set(endYear + 1, Calendar.JANUARY, 1, 0, 0, 0);
* end = cal.getTimeInMillis() - 1;
*
* // Check if these two zones have equivalent time zone transitions for the given time range
* boolean isEquivalent = tzNewYork.hasEquivalentTransitions(tzDetroit, start, end);
* System.out.println(startYear + "-" + endYear + ": " + isEquivalent);
* }
* </pre>
*
* @param tz The instance of <code>TimeZone</code>
* @param start The start time of the evaluated time range (inclusive)
@ -227,7 +311,22 @@ public abstract class BasicTimeZone extends TimeZone {
* instance for the initial rule. The rest will be either
* <code>AnnualTimeZoneRule</code> or <code>TimeArrayTimeZoneRule</code>
* instances representing transitions.
* <p>Example code:{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getTimeZoneRulesExample}
*
* <!-- From: com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:getTimeZoneRulesExample -->
* <p>Example code:</p>
*
* <pre>
* System.out.println("### Extracts time zone rules used by America/Los_Angeles since year 2005");
*
* // A TimeZone instance created by getTimeZone with TIMEZONE_ICU is always a BasicTimeZone
* BasicTimeZone btz = (BasicTimeZone)TimeZone.getTimeZone("America/Los_Angeles", TimeZone.TIMEZONE_ICU);
* long since = 1104537600000L; // 2005-01-01 0:00 UTC
* TimeZoneRule[] rules = btz.getTimeZoneRules(since);
* System.out.println("Rule(initial): " + rules[0]);
* for (int i = 1; i < rules.length; i++) {
* System.out.println("Rule: " + rules[i]);
* }
* </pre>
*
* @param start The start time (inclusive).
* @return The array of <code>TimeZoneRule</code> which represents this

25
icu4j/pom.xml
View file

@ -388,18 +388,10 @@
<maxmemory>256m</maxmemory>
<minmemory>256m</minmemory>
<!-- <verbose>true</verbose> -->
<additionalJOptions>
<additionalJOption>-J-Djcitesourcepath=${icu4j.api.doc.root.dir}/samples/src/main/java${path.separator}${icu4j.api.doc.root.dir}/demos/src/main/java${path.separator}${icu4j.api.doc.root.dir}/main/core/src/main/java</additionalJOption>
<additionalJOption>-J-Dfile.encoding=UTF-8</additionalJOption>
<additionalJOption>-J-Djciteverbose=true</additionalJOption>
</additionalJOptions>
<taglets>
<taglet>
<tagletClass>com.ibm.icu.dev.tool.docs.ICUTaglet</tagletClass>
</taglet>
<taglet>
<tagletClass>ch.arrenbrecht.jcite.JCiteTaglet</tagletClass>
</taglet>
</taglets>
<tagletArtifacts>
<!-- To handle the ICU custom taglets (@icu, @draft, @stable, etc -->
@ -408,23 +400,6 @@
<artifactId>tools_build</artifactId>
<version>${project.version}</version>
</tagletArtifact>
<!-- Include code fragments from a .java file. -->
<tagletArtifact>
<groupId>org.mcraig</groupId>
<artifactId>jcite</artifactId>
<version>1.13.0</version>
</tagletArtifact>
<!-- Dependencies for org.mcraig:jcite -->
<tagletArtifact>
<groupId>commons-discovery</groupId>
<artifactId>commons-discovery</artifactId>
<version>0.5</version>
</tagletArtifact>
<tagletArtifact>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
<version>1.2</version>
</tagletArtifact>
</tagletArtifacts>
<tags>
<tag>

92
icu4j/stylesheet8.css
View file

@ -576,95 +576,3 @@ div.block div.block span.interfaceName {
div.contentContainer ul.blockList li.blockList h2{
padding-bottom:0px;
}
/* Styles for JCite */
pre.java /* container for citations */
{
border-style: solid;
border-width: 1px;
border-color: DarkGray;
margin: 1.5em 1.5em 1.5em 1.5em;
padding: 1em;
background-color: cornsilk;
}
tt.java /* single cited line in JCite's -tt mode */
{
border-style: solid;
border-width: 1px;
border-color: DarkGray;
margin: 1.5em 1.5em 1.5em 1.5em;
background-color: cornsilk;
}
span.j-blk /* block comment */
{
color: DarkGreen;
}
span.j-cmt /* line comment */
{
color: DarkGreen;
}
span.j-key /* keyword */
{
/* font-weight:bold; */
color: Purple;
font-weight: bold;
}
span.j-str /* string constants */
{
color: Blue;
}
span.j-chr /* char constants */
{
color: Blue;
}
span.j-num /* number constants */
{
}
span.j-sym /* symbols, punctuation */
{
}
span.j-typ /* primitive types */
{
color: Purple;
font-weight: bold;
}
span.j-jdoc /* javadoc */
{
color: DarkSlateBlue;
}
span.j-jdoc-key /* javadoc keyword */
{
color: MediumSlateBlue;
font-weight: bold;
}
span.j-jdoc-html /* javadoc html tag */
{
color: SlateGray;
}
span.j-jdoc-link /* javadoc link */
{
color: Blue;
}
span.j-undef /* undefined */
{
}
span.j-hl /* highlight */
{
text-decoration: none;
background-color: #FFFFB0;
}