Revert "ICU-21878 Sync icu4j's CjkBreakEngine to icu4c's"

This reverts commit 08c3f99c08.

.bazeliskrc

@@ -0,0 +1,9 @@
+# © 2021 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
+# .bazeliskrc is the configuration file for the wrapper program for the Bazel
+# build system, called Bazelisk. Bazelisk can be used as a drop-in replacement
+# for running Bazel commands while ensuring, through configuration, that only a
+# specific version of Bazel is executed.
+
+USE_BAZEL_VERSION=4.1.0

.ci-builds/.azure-exhaustive-tests.yml

@@ -0,0 +1,74 @@
+# Azure Pipelines configuration for Exhaustive Tests for ICU.
+# 
+# Note: The exhaustive test configuration is in a separate file
+# so that it can be run independently from the regular builds.
+#
+# Only run the exhaustive tests on the main and maint branches, and
+# also batch up any pending changes so that we will only have at most
+# one build running at a given time (since they take a long time).
+trigger:
+  batch: true
+  branches:
+    include:
+    - main
+    - maint/maint-*
+  paths:
+    include:
+    - '*'
+    exclude:
+    - .github/*
+    - .ci-builds/.azure-pipelines.yml
+    - .ci-builds/.azure-valgrind.yml
+    - docs/*
+    - tools/*
+    - vendor/*
+    - .cpyskip.txt
+    - .travis.yml
+    - KEYS
+    - README.md
+
+jobs:
+#-------------------------------------------------------------------------
+# Note: The exhaustive tests can take more than 1 hour to complete.
+- job: ICU4J_OpenJDK_Ubuntu_1804
+  displayName: 'J: Linux OpenJDK (Ubuntu 18.04)'
+  timeoutInMinutes: 120
+  pool:
+    vmImage: 'ubuntu-18.04'
+    demands: ant
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        echo "Building ICU4J" && cd icu4j && ant init && ant exhaustiveCheck
+      displayName: 'Build and Exhaustive Tests'
+      env:
+        BUILD: ICU4J
+    - script: |
+        [ -d icu4j/out/junit-results ] && cd icu4j && cat `find out/junit-results -name "*.txt" -exec grep -l FAILED {} \;`
+      condition: failed() # only run if the build fails.
+      displayName: 'List failures (if any)'
+      timeoutInMinutes: 2
+#-------------------------------------------------------------------------
+# Note: The exhaustive tests can take more than 1 hour to complete.
+- job: ICU4C_Clang_Exhaustive_Ubuntu_1804
+  displayName: 'C: Linux Clang Exhaustive Tests (Ubuntu 18.04)'
+  timeoutInMinutes: 120
+  pool:
+    vmImage: 'ubuntu-18.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        cd icu4c/source && ./runConfigureICU Linux && make -j2
+      displayName: 'Build'
+    - script: |
+        cd icu4c/source && make check-exhaustive
+      displayName: 'Exhaustive Tests'
+      env:
+        CC: clang
+        CXX: clang++
+#-------------------------------------------------------------------------
+

.ci-builds/.azure-pipelines.yml

@@ -0,0 +1,631 @@
+# Azure Pipelines (VSTS) configuration for CI builds for ICU.
+
+jobs:
+#-------------------------------------------------------------------------
+- job: ICU4J_OpenJDK_Ubuntu_1804
+  displayName: 'J: Linux OpenJDK (Ubuntu 18.04)'
+  timeoutInMinutes: 20
+  pool:
+    vmImage: 'ubuntu-18.04'
+    demands: ant
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        echo "Building ICU4J" && cd icu4j && ant init && ant check && ant localespiCheck
+      displayName: 'Build and Test'
+      env:
+        BUILD: ICU4J
+    # exit with a non-zero status in order to make this step show as a red X in the UI.
+    - script: |
+        [ -d icu4j/out/junit-results ] && cd icu4j && cat `find out/junit-results -name "*.txt" -exec grep -l FAILED {} \;` && exit 1
+      condition: failed() # only run if the build fails.
+      displayName: 'List failures (if any)'
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang_Ubuntu_1804
+  displayName: 'C: Linux Clang (Ubuntu 18.04)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-18.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        cd icu4c/source && ./runConfigureICU Linux && make -j2 check
+      displayName: 'Build and Test'
+      env:
+        CC: clang
+        CXX: clang++
+    - script: |
+        cd icu4c/source/test/cintltst && LANG=C LD_LIBRARY_PATH=../../lib:../../tools/ctestfw ./cintltst /tsutil/cloctst/TestCDefaultLocale
+      displayName: 'Test C Default locale'
+    - script: |
+        cd icu4c/source/test/cintltst && LANG=C.UTF-8 LD_LIBRARY_PATH=../../lib:../../tools/ctestfw ./cintltst /tsutil/cloctst/TestCDefaultLocale
+      displayName: 'Test C.UTF-8 Default locale'
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang13_Ubuntu_2004_WarningsAsErrors
+  displayName: 'C: Linux Clang-13 WarningsAsErrors (Ubuntu 20.04)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-20.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    # Install Clang-13 from https://apt.llvm.org/
+    - script: |
+        curl -Ls https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+        sudo apt-add-repository 'deb http://apt.llvm.org/focal/ llvm-toolchain-focal-13 main'
+        sudo apt update
+        sudo apt install -qy clang-13 lld-13 libc++-13-dev libc++abi-13-dev
+      displayName: 'Install Clang-13'
+    - script: |
+        export CPPFLAGS="-Werror -Wall -Wextra -Wextra-semi -Wundef -Wnon-virtual-dtor -Wsuggest-override" && cd icu4c/source && ./runConfigureICU Linux && make -j2 tests
+      displayName: 'Build only (WarningsAsErrors)'
+      env:
+        CC: clang-13
+        CXX: clang++-13
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang_Ubuntu_DataFilter_1804
+  displayName: 'C: Linux Clang DataFilter (Ubuntu 18.04)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-18.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        cd icu4c/source && \
+        ICU_DATA_FILTER_FILE=../../.ci-builds/data-filter.json ./runConfigureICU Linux && \
+        make -j2 tests && \
+        \[ ! -d data/out/build/icudt66l/translit \] && \
+        (cd test/intltest && LD_LIBRARY_PATH=../../lib:../../tools/ctestfw ./intltest translit/TransliteratorTest/TestBasicTransliteratorEvenWithoutData)
+      displayName: 'Build with Data Filter'
+      env:
+        CC: clang
+        CXX: clang++
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang_Cpp14_Debug_Ubuntu_1804
+  displayName: 'C: Linux Clang C++17 Debug (Ubuntu 18.04)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-18.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        export CXXFLAGS="-std=c++17 -Winvalid-constexpr" && cd icu4c/source && ./runConfigureICU --enable-debug --disable-release Linux && make -j2 check
+      displayName: 'Build and Test C++17'
+      env:
+        CC: clang
+        CXX: clang++
+#-------------------------------------------------------------------------
+- job: ICU4C_GCC_Ubuntu_2004
+  displayName: 'C: Linux GCC (Ubuntu 20.04)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-20.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        cd icu4c/source && ./runConfigureICU Linux && make -j2 check
+      displayName: 'Build and Test'
+      env:
+        CC: gcc
+        CXX: g++
+#-------------------------------------------------------------------------
+- job: ICU4C_GCC11_Cpp20_Ubuntu_2004
+  displayName: 'C: Linux GCC-11 C++20 (Ubuntu 20.04)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-20.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        sudo add-apt-repository ppa:ubuntu-toolchain-r/test
+        sudo apt update
+        sudo apt install gcc-11 g++-11
+      displayName: 'Install GCC-11'
+    - script: |
+        cd icu4c/source && ./runConfigureICU Linux && make -j2 check
+      displayName: 'Build and Test'
+      env:
+        CC: gcc-11
+        CXX: g++-11
+        CXXFLAGS: '-std=c++20 -fext-numeric-literals'
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang_Ubuntu_2004_LANG
+  displayName: 'C: Linux Clang (Ubuntu 20.04) - LANG has extension tags'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-20.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        cd icu4c/source && ./runConfigureICU Linux && make -j2 check
+      displayName: 'Build and Test'
+      env:
+        CC: clang
+        CXX: clang++
+        LANG: "en_US@calendar=gregorian;hours=h12"
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang13_Cpp20_Ubuntu_2004
+  displayName: 'C: Linux Clang-13 C++20 (Ubuntu 20.04)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-20.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    # Install Clang-13 from https://apt.llvm.org/
+    - script: |
+        curl -Ls https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+        sudo apt-add-repository 'deb http://apt.llvm.org/focal/ llvm-toolchain-focal-13 main'
+        sudo apt update
+        sudo apt install -qy clang-13 lld-13 libc++-13-dev libc++abi-13-dev
+      displayName: 'Install Clang-13'
+    - script: |
+        cd icu4c/source && ./runConfigureICU Linux && make -j2 check
+      displayName: 'Build and Test'
+      env:
+        CC: clang-13
+        CXX: clang++-13
+        CXXFLAGS: '-std=c++20'
+#-------------------------------------------------------------------------
+# VS 2019 Builds
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x64_Release_Distrelease
+  displayName: 'C: MSVC 64-bit Release (VS 2019) + Distrelease'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: x64
+        configuration: Release
+    - task: BatchScript@1
+      displayName: 'Run Tests (icucheck.bat)'
+      inputs:
+        filename: icu4c/source/allinone/icucheck.bat
+        arguments: 'x64 Release'
+    - task: PowerShell@2
+      displayName: 'PowerShell: Distrelease script (x64)'
+      inputs:
+        targetType: filePath
+        filePath: 'icu4c/packaging/distrelease.ps1'
+        arguments: '-arch x64'
+        workingDirectory: icu4c
+    - task: PublishBuildArtifacts@1
+      displayName: 'Publish x64 Artifacts: icu-windows.zip'
+      inputs:
+        PathtoPublish: 'icu4c/source/dist/icu-windows.zip'
+        ArtifactName: '$(Build.BuildNumber)_ICU4C_MSVC_x64_Release'
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x64_Release_DataFilter
+  displayName: 'C: MSVC 64-bit Release DataFilter (VS 2019)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - powershell: |
+        $filterPath = $Env:BUILD_SOURCESDIRECTORY + "\.ci-builds\data-filter.json"
+        $vstsCommandString = "vso[task.setvariable variable=ICU_DATA_FILTER_FILE]" + $filterPath
+        Write-Host "##$vstsCommandString"
+    - task: VSBuild@1
+      displayName: 'Build Solution with Data Filter'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: x64
+        configuration: Release
+        msbuildArgs: '/p:SkipUWP=true'
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x86_Release_Distrelease
+  displayName: 'C: MSVC 32-bit Release (VS 2019) + Distrelease'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: Win32
+        configuration: Release
+    - task: BatchScript@1
+      displayName: 'Run Tests (icucheck.bat)'
+      inputs:
+        filename: icu4c/source/allinone/icucheck.bat
+        arguments: 'x86 Release'
+    - task: PowerShell@2
+      displayName: 'PowerShell: Distrelease script (x86)'
+      inputs:
+        targetType: filePath
+        filePath: 'icu4c/packaging/distrelease.ps1'
+        arguments: '-arch x86'
+        workingDirectory: icu4c
+    - task: PublishBuildArtifacts@1
+      displayName: 'Publish x86 Artifacts: icu-windows.zip'
+      inputs:
+        PathtoPublish: 'icu4c/source/dist/icu-windows.zip'
+        ArtifactName: '$(Build.BuildNumber)_ICU4C_MSVC_x86_Release'
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x64_ARM32_ARM64_Release_Distrelease
+  displayName: 'C: MSVC x64 ARM32 ARM64 Release (VS 2019) + Distrelease ARM64'
+  timeoutInMinutes: 60
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: x64
+        configuration: Release
+    - task: VSBuild@1
+      displayName: 'Build ARM32'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: ARM
+        configuration: Release
+    - task: VSBuild@1
+      displayName: 'Build ARM64'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: ARM64
+        configuration: Release
+    - task: PowerShell@2
+      displayName: 'PowerShell: Distrelease script (ARM64)'
+      inputs:
+        targetType: filePath
+        filePath: 'icu4c/packaging/distrelease.ps1'
+        arguments: '-arch ARM64'
+        workingDirectory: icu4c
+    - task: PublishBuildArtifacts@1
+      displayName: 'Publish ARM64 Artifacts: icu-windows.zip'
+      inputs:
+        PathtoPublish: 'icu4c/source/dist/icu-windows.zip'
+        ArtifactName: '$(Build.BuildNumber)_ICU4C_MSVC_ARM64_Release'
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x64_ARM64_Debug
+  displayName: 'C: MSVC x64 ARM64 Debug (VS 2019)'
+  timeoutInMinutes: 45
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: x64
+        configuration: Debug
+    - task: BatchScript@1
+      displayName: 'Run x64 Debug Tests (icucheck.bat)'
+      inputs:
+        filename: icu4c/source/allinone/icucheck.bat
+        arguments: 'x64 Debug'
+    - task: VSBuild@1
+      displayName: 'Build ARM64 Debug'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: ARM64
+        configuration: Debug
+#-------------------------------------------------------------------------
+# There is no /std:c++20 yet, so use c++latest as that includes many of
+# the C++20 compiler and library changes.
+- job: ICU4C_MSVC_x64_Release_CppLatest
+  displayName: 'C: MSVC 64-bit Release (VS 2019) /std:c++latest'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: x64
+        configuration: Release
+        msbuildArgs: '/p:LanguageStandard="stdcpplatest"'
+    - task: BatchScript@1
+      displayName: 'Run Tests (icucheck.bat)'
+      inputs:
+        filename: icu4c/source/allinone/icucheck.bat
+        arguments: 'x64 Release'
+#-------------------------------------------------------------------------
+# VS2019 using the VS2017 toolset builds
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x64_Release_VS2017
+  displayName: 'C: MSVC 64-bit Release (VS 2017)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: x64
+        configuration: Release
+        msbuildArgs: /p:DefaultPlatformToolset=v141
+    - task: BatchScript@1
+      displayName: 'Run Tests (icucheck.bat)'
+      inputs:
+        filename: icu4c/source/allinone/icucheck.bat
+        arguments: 'x64 Release'
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x86_Debug_VS2017
+  displayName: 'C: MSVC 32-bit Debug (VS 2017)'
+  timeoutInMinutes: 60
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: Win32
+        configuration: Debug
+        msbuildArgs: /p:DefaultPlatformToolset=v141
+    - task: BatchScript@1
+      displayName: 'Run Tests (icucheck.bat)'
+      inputs:
+        filename: icu4c/source/allinone/icucheck.bat
+        arguments: 'x86 Debug'
+#-------------------------------------------------------------------------
+# VS2019 using the VS2015 toolset
+#-------------------------------------------------------------------------
+- job: ICU4C_MSVC_x64_Release_VS2015
+  displayName: 'C: MSVC 64-bit Release (VS 2015)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'windows-2019'
+    demands: 
+      - msbuild
+      - visualstudio
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - task: VSBuild@1
+      displayName: 'Build Solution'
+      inputs:
+        solution: icu4c/source/allinone/allinone.sln
+        platform: x64
+        configuration: Release
+        msbuildArgs: /p:SkipUWP=true /p:DefaultPlatformToolset=v140 /p:AutodetectWin10SDK=true
+    - task: BatchScript@1
+      displayName: 'Run Tests (icucheck.bat)'
+      inputs:
+        filename: icu4c/source/allinone/icucheck.bat
+        arguments: 'x64 Release'
+#-------------------------------------------------------------------------
+- job: ICU4C_MSYS2_GCC_x86_64_Release
+  displayName: 'C: MSYS2 GCC x86_64 Release'
+  timeoutInMinutes: 45
+  pool:
+    vmImage: 'windows-2019'
+    demands:
+      - Cmd
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+       choco install -y msys2
+       rem refreshenv
+      displayName: 'Install MSYS2'
+    - script: |
+       c:\tools\msys64\usr\bin\bash.exe -lc "echo 'Hello World' && uname -a"
+       c:\tools\msys64\usr\bin\bash.exe -lc "pacman --noconfirm -S mingw-w64-x86_64-toolchain"
+       c:\tools\msys64\usr\bin\bash.exe -lc "pacman --noconfirm -S make"
+       exit
+      displayName: 'Install mingw-w64-x86_64-toolchain'
+    - script: |
+       set MSYSTEM=MINGW64
+       c:\tools\msys64\usr\bin\bash.exe -lc "cd $BUILD_SOURCESDIRECTORY && cd icu4c/source && ./runConfigureICU MinGW --prefix='/tmp/build-icu' && make -j2 check"
+      displayName: 'Build and Test'
+    - script: |
+       set MSYSTEM=MINGW64
+       c:\tools\msys64\usr\bin\bash.exe -lc "cd $BUILD_SOURCESDIRECTORY && cd icu4c/source && make install && cd /tmp/build-icu && echo 'Recursive ls' && ls -lR"
+      displayName: 'make install'
+    - script: |
+       set MSYSTEM=MINGW64
+       c:\tools\msys64\usr\bin\bash.exe -lc "echo 'Run icuinfo from MSYS shell' && cd /tmp/build-icu/bin && ./icuinfo.exe"
+       echo 'Run icuinfo from CMD shell' && cd /d C:\tools\msys64\tmp\build-icu\bin && set PATH=C:\tools\msys64\mingw64\bin;%PATH% && icuinfo.exe"
+      displayName: 'run icuinfo'
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang_MacOSX_WarningsAsErrors
+  displayName: 'C: macOSX Clang WarningsAsErrors (Catalina 10.15)'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'macOS-10.15'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        export CPPFLAGS="-Werror -Wall -Wextra -Wextra-semi -Wundef -Wnon-virtual-dtor" && cd icu4c/source && ./runConfigureICU MacOSX && make -j2 check
+      displayName: 'Build and Test (WarningsAsErrors)'
+      env:
+        CC: clang
+        CXX: clang++
+#-------------------------------------------------------------------------
+- job: ICU4C_Cygwin_GCC_x86_64_Release
+  displayName: 'C: Cygwin GCC x86_64 Release'
+  timeoutInMinutes: 180
+  pool:
+    vmImage: 'windows-2019'
+  variables:
+    ICU_CI_CACHE: c:\icu-ci-cache
+    CYG_URL: https://cygwin.com/setup-x86_64.exe
+    CYG_MIRROR: http://mirrors.kernel.org/sourceware/cygwin/
+    CYG_PACKAGES: automake,gcc-core,gcc-g++,make,pkg-config,perl,python3
+    CYG_ROOT: c:\cygwin-root
+    CYG_CACHE: '$(ICU_CI_CACHE)\cygwin64-v3'
+    CYG_CACHED_SETUP: '$(CYG_CACHE)\setup.exe'
+    CYG_VERSION_KEY: cygwin-3.2
+  steps:
+    # Use 'autocrlf input' since checked-in files may already be using CRLF.
+    - script: |
+        git config --global core.autocrlf input
+      displayName: 'Configure Git to checkout with Unix line endings (LF)'
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    # Cache expires after 7 days of no activity.
+    - task: Cache@2
+      displayName: 'Restore Cygwin cache'
+      inputs:
+        # Use the contents of the file ".azure-pipelines.yml" as part of the key, as that contains the list of CYG_PACKAGES.
+        # Also include the Cygwin version as part of the key. If we want to use a newer version of Cygwin, we can update CYG_VERSION_KEY.
+        # Note: CYG_VERSION_KEY may become out of sync with (older than) the version we actually use if we update this file
+        #       without updating CYG_VERSION_KEY. Any updates to this file guarantees that we're using the latest version.
+        key: '"$(CYG_VERSION_KEY)" | .ci-builds/.azure-pipelines.yml'
+        path: "$(CYG_CACHE)"
+    - task: PowerShell@2
+      displayName: 'Download Cygwin setup'
+      inputs:
+        targetType: inline
+        script: |
+          if ( !(Test-Path "${env:CYG_CACHED_SETUP}" -NewerThan (Get-Date).AddDays(-7)) )
+          {
+            Write-Host "Cached Cygwin setup does not exist or is older than 7 days, downloading from external site."
+
+            New-Item -Force -Type Directory $env:CYG_CACHE
+            Write-Host "Downloading Cygwin setup..."
+
+            $start_time = Get-Date
+            (New-Object System.Net.WebClient).DownloadFile($env:CYG_URL, $env:CYG_CACHED_SETUP)
+
+            Write-Output "Download took: $((Get-Date).Subtract($start_time).Seconds) second(s)."
+          }
+    - script: |
+        %CYG_CACHED_SETUP% --no-verify --quiet-mode --no-shortcuts --no-startmenu --no-desktop --upgrade-also --only-site --site "%CYG_MIRROR%" --root "%CYG_ROOT%" --local-package-dir "%CYG_CACHE%" --packages "%CYG_PACKAGES%"
+      displayName: 'Install Cygwin'
+    - script: |
+        %CYG_ROOT%\\bin\\sh -lc 'echo Hello' && %CYG_ROOT%\\bin\\sh -lc 'uname -a'
+      displayName: 'Check Cygwin environment'
+    - script: |
+        %CYG_ROOT%\\bin\\bash -lc "cd $(cygpath \"$(Build.SourcesDirectory)\") && cd icu4c/source && ./runConfigureICU Cygwin && make tests"
+      displayName: 'Build ICU (source and test)'
+      env:
+        CC: gcc
+        CXX: g++
+    - script: |
+        %CYG_ROOT%\\bin\\bash -lc "cd $(cygpath \"$(Build.SourcesDirectory)\") && cd icu4c/source && make check"
+      displayName: 'Run Tests'
+      env:
+        CC: gcc
+        CXX: g++
+#-------------------------------------------------------------------------
+- job: ICU4C_icuexportdata_Ubuntu_1804
+  displayName: 'C: Create Artifacts from icuexportdata'
+  timeoutInMinutes: 30
+  pool:
+    vmImage: 'ubuntu-18.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        cd icu4c/source && ./runConfigureICU Linux && make -j2
+      displayName: 'Build'
+      env:
+        CC: clang
+        CXX: clang++
+    - script: |
+        mkdir -p icu4c/source/icuexportdata_uprops_full/fast
+        mkdir -p icu4c/source/icuexportdata_uprops_full/small
+        cd icu4c/source
+        LD_LIBRARY_PATH=lib ./bin/icuexportdata --mode uprops --index --copyright --destdir icuexportdata_uprops_full/fast --trie-type fast --all
+        LD_LIBRARY_PATH=lib ./bin/icuexportdata --mode uprops --index --copyright --destdir icuexportdata_uprops_full/small --trie-type small --all
+      displayName: 'Build Unicode property data export file (Full)'
+    # In the sample file, include:
+    # - Basic binary properties: AHex WSpace
+    # - Property of strings: Basic_Emoji
+    # - POSIX binary property: blank
+    # - Enumerated properties: gc nt sc
+    - script: |
+        mkdir -p icu4c/source/icuexportdata_uprops_sample/fast
+        mkdir -p icu4c/source/icuexportdata_uprops_sample/small
+        cd icu4c/source
+        LD_LIBRARY_PATH=lib ./bin/icuexportdata --mode uprops --index --copyright --destdir icuexportdata_uprops_sample/fast --trie-type fast AHex gc nt Basic_Emoji sc WSpace blank
+        LD_LIBRARY_PATH=lib ./bin/icuexportdata --mode uprops --index --copyright --destdir icuexportdata_uprops_sample/small --trie-type small AHex gc nt Basic_Emoji sc WSpace blank
+      displayName: 'Build Unicode property data export file (Sample)'
+    - task: PublishBuildArtifacts@1
+      displayName: 'Publish Artifact: icuexportdata_uprops_full'
+      inputs:
+        PathtoPublish: 'icu4c/source/icuexportdata_uprops_full'
+        ArtifactName: 'icuexportdata_uprops_full'
+    - task: PublishBuildArtifacts@1
+      displayName: 'Publish Artifact: icuexportdata_uprops_sample'
+      inputs:
+        PathtoPublish: 'icu4c/source/icuexportdata_uprops_sample'
+        ArtifactName: 'icuexportdata_uprops_sample'

.ci-builds/.azure-valgrind.yml

@@ -0,0 +1,70 @@
+# Azure Pipelines configuration for Valgrind for ICU4C.
+# 
+# Note: The valgrind test configuration is in a separate file
+# as it used to be run independently from the regular CI builds.
+#
+# The Ubuntu images don't have valgrind installed by default, so we need
+# install it first.
+#
+# Run Valgrind for every Pull Request that goes into main
+# or a maint- branch. This lets us catch any issues sooner rather than later. 
+pr:
+  branches:
+    include:
+    - main
+    - maint/maint-*
+  paths:
+    include:
+    - '*'
+    exclude:
+    - docs/*
+    - icu4j/*
+    - tools/*
+    - vendor/*
+    - .cpyskip.txt
+    - .travis.yml
+    - KEYS
+    - README.md
+
+jobs:
+#-------------------------------------------------------------------------
+- job: ICU4C_Clang_Valgrind_Ubuntu_1804
+  displayName: 'C: Linux Clang Valgrind (Ubuntu 18.04)'
+  timeoutInMinutes: 60
+  pool:
+    vmImage: 'ubuntu-18.04'
+  steps:
+    - checkout: self
+      lfs: true
+      fetchDepth: 10
+    - script: |
+        set -ex
+        sudo apt -y update
+        sudo apt install -y valgrind
+      displayName: 'Install valgrind'
+      timeoutInMinutes: 5
+    - script: |
+        cd icu4c/source && ./runConfigureICU --enable-debug Linux --disable-renaming && make -j2 tests
+      displayName: 'Build'
+      timeoutInMinutes: 10
+      env:
+        CC: clang
+        CXX: clang++
+    - script: |
+        cd icu4c/source/test/intltest && LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH valgrind --tool=memcheck --error-exitcode=1 --leak-check=full --show-reachable=yes ./intltest
+      displayName: 'Valgrind intltest'
+      timeoutInMinutes: 45
+    - script: |
+        cd icu4c/source/test/cintltst && LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH valgrind --tool=memcheck --error-exitcode=1 --leak-check=full --show-reachable=yes ./cintltst
+      displayName: 'Valgrind cintltst'
+      timeoutInMinutes: 15
+    - script: |
+        cd icu4c/source/test/iotest && LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH valgrind --tool=memcheck --error-exitcode=1 --leak-check=full --show-reachable=yes ./iotest
+      displayName: 'Valgrind iotest'
+      timeoutInMinutes: 5
+    - script: |
+        cd icu4c/source/tools/icuinfo && LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH valgrind --tool=memcheck --error-exitcode=1 --leak-check=full --show-reachable=yes ./icuinfo
+      displayName: 'Valgrind icuinfo'
+      timeoutInMinutes: 5
+
+#-------------------------------------------------------------------------

.ci-builds/data-filter.json

@@ -0,0 +1,49 @@
+{
+  "localeFilter": {
+    "filterType": "locale",
+    "whitelist": [
+      "en",
+      "de",
+      "zh"
+    ]
+  },
+// Test mixed feature filter and resource filter
+// Exclude translit data so we can run test for ICU-20673
+// Also test for "whitelist" versus "includelist"
+  "featureFilters": {
+    "misc": {
+      "whitelist": ["supplementalData"]
+    },
+    "translit": "exclude",
+    "curr_tree": {
+      "filterType": "locale",
+      "includelist": ["my"]
+    },
+    "brkitr_rules": {
+      "excludelist": ["line"]
+    },
+    "brkitr_dictionaries": {
+      "blacklist": ["cjdict"]
+    }
+  },
+  "resourceFilters": [
+    {
+      "categories": ["misc"],
+      "files": {
+        "includelist": ["supplementalData"]
+      },
+      "rules": ["+/*"]
+    }
+  ],
+// Test fileReplacements (relative path)
+  "fileReplacements": {
+    "directory": "$SRC",
+    "replacements": [
+      {
+        "src": "brkitr/rules/line.txt",
+        "dest": "brkitr/rules/line_normal.txt"
+      },
+      "misc/dayPeriods.txt"
+    ]
+  }
+}

.cpyskip.txt

@@ -0,0 +1,119 @@
+#
+# Copyright (C) 2017 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+#
+# Copyright (c) 2005-2011 International Business Machines
+# Corporation and others. All Rights Reserved.
+## see NOTE below.
+## Also see: http://icu-project.org/copyright-scan.html
+#
+# git stuff
+# .git is ignored by code.
+#.git/*
+.github/*
+.gitignore
+.gitattributes
+.travis.yml
+.ci-builds/*
+# PGP Keys
+KEYS
+# suffix matches - start with '*'.  They are turned into as RE, '.brk$'
+*.brk
+*.bz2
+*.classpath
+*.csproj
+*.cvsignore
+*.dat
+*.DS_Store
+*.doc
+*.fuzz
+*.gif
+*.gz
+*.ico
+*.icu
+*.intaglio
+*.jar
+*.jpg
+*.launch
+*.nrm
+*.odp
+*.otf
+*.pdf
+*.png
+*.ppt
+*.prefs
+*.project
+*.res
+*.rtf
+*.sln
+*.sxd
+*.sxg
+*.sxw
+*.tri2
+*.vcproj
+*.vcxproj
+*.vcxproj.filters
+*.zip
+
+# UnicodeData.txt does not have any header.
+*/UnicodeData.txt
+
+#
+# ICU4C
+#
+icu4c/source/aclocal.m4
+icu4c/source/config.guess
+icu4c/source/config.log
+icu4c/source/config.status
+icu4c/source/config.sub
+icu4c/source/install-sh
+icu4c/source/extra/uconv/samples/*
+icu4c/source/samples/layout/Sample.txt
+icu4c/source/samples/ucnv/data01.txt
+icu4c/source/samples/ufortune/resources/res-file-list.txt
+icu4c/source/test/fuzzer/*_seed_corpus.txt
+icu4c/source/test/testdata/ConverterSelectorTestUTF8.txt
+icu4c/source/test/testdata/encoded.utf16be
+icu4c/source/test/testdata/idna_conf.txt
+icu4c/source/test/testdata/ra.xlf
+icu4c/source/test/testdata/re_tests.txt
+icu4c/source/test/thaitest/space.txt
+icu4c/source/tools/tzcode/asctime.c
+icu4c/source/tools/tzcode/ialloc.c
+icu4c/source/tools/tzcode/localtime.c
+icu4c/source/tools/tzcode/private.h
+icu4c/source/tools/tzcode/scheck.c
+icu4c/source/tools/tzcode/tzfile.h
+icu4c/source/tools/tzcode/tzselect.ksh
+icu4c/source/tools/tzcode/zdump.c
+icu4c/source/tools/tzcode/zic.c
+#
+# ICU4J
+#
+icu4j/eclipse-build/pdebuild/allElements.xml
+icu4j/eclipse-build/pdebuild/customTargets.xml
+icu4j/main/tests/core/src/com/ibm/icu/dev/data/IDNATestInput.txt
+icu4j/main/tests/core/src/com/ibm/icu/dev/data/unicode/confusablesWholeScript.txt
+icu4j/main/tests/core/src/com/ibm/icu/dev/data/unicode/UnicodeData.txt
+icu4j/main/tests/core/src/com/ibm/icu/dev/test/duration/testdata/*
+icu4j/perf-tests/data/conversion/*
+icu4j/perf-tests/data/udhr/*
+icu4j/perf-tests/data/collation/thesis.txt
+icu4j/perf-tests/data/collation/ulyss10.txt
+icu4j/perf-tests/data/collation/2drvb10.txt
+icu4j/perf-tests/data/collation/vfear11a.txt
+icu4j/perf-tests/data/collation/nvsbl10.txt
+#
+# docs
+#
+docs/ide4c/vscode/*.json
+docs/Gemfile.lock
+#
+# tools
+#
+tools/trac/IcuCodeTools/*
+tools/unicodetools/*
+#
+# vendor
+#
+vendor/double-conversion/upstream/*

.gitattributes

@@ -1,32 +1,49 @@
+# The line "* text=auto !eol" means the following:
+#  For text files (auto-detected), EOLs will be converted on checkout to OS-dependent EOL (LF for Unix, CRLF for Windows).
+#  No EOL (end of line) conversion for binary files.
 * text=auto !eol
 
-*.c text !eol
-*.cc text !eol
+# Note:
+#  "text" tells git the file is text.
+#  "-text" tells git the file is binary.
+#  The only difference between the two is that git will do EOL conversion for text files.
+#  "!eol" is the equivalent of "svneol=native".
+
+*.bat text !eol
+*.c text !eol diff=cpp
+*.cc text !eol diff=cpp
 *.classpath text !eol
-*.cpp text !eol
-*.css text !eol
+*.cmd text eol=crlf
+*.cpp text !eol diff=cpp
+*.css text !eol diff=css
 *.dsp text !eol
 *.dsw text !eol
+*.dtd text !eol
+*.el text !eol
 *.filters text !eol
-*.h text !eol
-*.htm text !eol
-*.html text !eol
+*.h text !eol diff=cpp
+*.htm text !eol diff=html
+*.html text !eol diff=html
 *.in text !eol
-*.java text !eol
+*.java text !eol diff=java
 *.launch text !eol
+*.m4 text !eol
 *.mak text !eol
 *.md text !eol
 *.MF text !eol
 *.mk text !eol
-*.pl text !eol
-*.pm text !eol
+*.pl text !eol diff=perl
+*.pm text !eol diff=perl
 *.project text !eol
 *.properties text !eol
-*.py text !eol
+*.props text !eol
+*.py text !eol diff=python
 *.rc text !eol
 *.sh text eol=lf
+*.sed text eol=lf
 *.sln text !eol
 *.stub text !eol
+*.targets text !eol
 *.txt text !eol
 *.ucm text !eol
 *.vcproj text !eol
@@ -34,11 +51,18 @@
 *.xml text !eol
 *.xsl text !eol
 *.xslt text !eol
-Makefile text !eol
-configure text !eol
+AUTHORS text !eol
+BUILD text !eol
+COPYING text !eol
+Changelog text !eol
 LICENSE text !eol
+Makefile text !eol
 README text !eol
+SConscript text !eol
+SConstruct text !eol
+configure text !eol
 
+# Explicitly set the following file types as binary files.
 *.bin -text
 *.brk -text
 *.cnv -text
@@ -47,589 +71,16 @@ README text !eol
 *.nrm -text
 *.spp -text
 *.tri2 -text
-
-icu4c/icu4c.css -text
-icu4c/source/aclocal.m4 -text
-icu4c/source/allinone/Build.Windows.ProjectConfiguration.props -text
-icu4c/source/allinone/Build.Windows.UWP.ProjectConfiguration.props -text
-icu4c/source/allinone/Windows.CopyUnicodeHeaderFiles.targets -text
-icu4c/source/config/m4/icu-conditional.m4 -text
-icu4c/source/data/curr/pool.res -text
-icu4c/source/data/in/coll/ucadata-implicithan.icu -text
-icu4c/source/data/in/coll/ucadata-unihan.icu -text
-icu4c/source/data/in/nfc.nrm -text
-icu4c/source/data/in/nfkc.nrm -text
-icu4c/source/data/in/nfkc_cf.nrm -text
-icu4c/source/data/in/pnames.icu -text
-icu4c/source/data/in/ubidi.icu -text
-icu4c/source/data/in/ucase.icu -text
-icu4c/source/data/in/unames.icu -text
-icu4c/source/data/in/uprops.icu -text
-icu4c/source/data/in/uts46.nrm -text
-icu4c/source/data/lang/pool.res -text
-icu4c/source/data/locales/pool.res -text
-icu4c/source/data/region/pool.res -text
-icu4c/source/data/unit/pool.res -text
-icu4c/source/data/zone/pool.res -text
-icu4c/source/samples/all/samplecheck.bat -text
-icu4c/source/samples/ucnv/data02.bin -text
-icu4c/source/test/depstest/icu-dependencies-mode.el -text
-icu4c/source/test/perf/README -text
-icu4c/source/test/testdata/TestFont1.otf -text
-icu4c/source/test/testdata/encoded.utf16be -text
-icu4c/source/test/testdata/importtest.bin -text
-icu4c/source/test/testdata/old_e_testtypes.res -text
-icu4c/source/test/testdata/old_l_testtypes.res -text
-icu4c/source/test/testdata/uni-text.bin -text
-icu4c/source/tools/gencolusb/README.md -text
-icu4c/source/tools/tzcode/icuregions -text
-icu4j/main/shared/data/icudata.jar -text
-icu4j/main/shared/data/icutzdata.jar -text
-icu4j/main/shared/data/testdata.jar -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.impl.OlsonTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.impl.TimeZoneAdapter.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.math.BigDecimal.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.math.MathContext.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.ArabicShapingException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.ChineseDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.ChineseDateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.DateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.DateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.DecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.DecimalFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.MessageFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.NumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.RuleBasedNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.SimpleDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.text.StringPrepParseException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.BuddhistCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.Calendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.ChineseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.CopticCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.Currency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.EthiopicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.GregorianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.HebrewCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.IslamicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.JapaneseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.SimpleTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.TimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.ULocale.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_3.6/com.ibm.icu.util.UResourceTypeMismatchException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.DateNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.IllegalIcuArgumentException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.InvalidFormatException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.JavaTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.OlsonTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.RelativeDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.TZDBTimeZoneNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.TimeZoneAdapter.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.TimeZoneGenericNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.TimeZoneNamesImpl.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.duration.BasicDurationFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.impl.locale.LocaleSyntaxException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.math.BigDecimal.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.math.MathContext.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.ArabicShapingException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.ChineseDateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.ChineseDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.ChineseDateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.CompactDecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.CurrencyPluralInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DateIntervalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DateIntervalInfo$PatternInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DateIntervalInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.DecimalFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.MeasureFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.MessageFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.MessageFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.NumberFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.NumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.PluralFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.PluralRules.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.RuleBasedNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.SelectFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.SimpleDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.StringPrepParseException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.TimeUnitFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.text.TimeZoneFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.AnnualTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.BuddhistCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.Calendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.ChineseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.CopticCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.Currency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.DangiCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.DateInterval.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.DateTimeRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.EthiopicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.GregorianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.HebrewCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.ICUCloneNotSupportedException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.ICUException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.ICUUncheckedIOException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.IllformedLocaleException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.IndianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.InitialTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.IslamicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.JapaneseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.MeasureUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.PersianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.RuleBasedTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.SimpleTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.TaiwanCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.TimeArrayTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.TimeUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.TimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.ULocale.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.UResourceTypeMismatchException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_58.1/com.ibm.icu.util.VTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.DateNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.IllegalIcuArgumentException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.InvalidFormatException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.JavaTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.OlsonTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.RelativeDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.TZDBTimeZoneNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.TimeZoneAdapter.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.TimeZoneGenericNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.TimeZoneNamesImpl.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.duration.BasicDurationFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.locale.LocaleSyntaxException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.impl.number.Properties.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.math.BigDecimal.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.math.MathContext.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.ArabicShapingException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.ChineseDateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.ChineseDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.ChineseDateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.CompactDecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.CurrencyPluralInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DateIntervalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DateIntervalInfo$PatternInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DateIntervalInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.DecimalFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.MeasureFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.MessageFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.MessageFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.NumberFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.NumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.PluralFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.PluralRules.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.RuleBasedNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.SelectFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.SimpleDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.StringPrepParseException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.TimeUnitFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.text.TimeZoneFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.AnnualTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.BuddhistCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.Calendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.ChineseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.CopticCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.Currency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.DangiCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.DateInterval.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.DateTimeRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.EthiopicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.GregorianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.HebrewCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.ICUCloneNotSupportedException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.ICUException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.ICUUncheckedIOException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.IllformedLocaleException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.IndianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.InitialTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.IslamicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.JapaneseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.MeasureUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.PersianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.RuleBasedTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.SimpleTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.TaiwanCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.TimeArrayTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.TimeUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.TimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.ULocale.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.UResourceTypeMismatchException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_59.1/com.ibm.icu.util.VTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.DateNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.IllegalIcuArgumentException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.InvalidFormatException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.JavaTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.OlsonTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.RelativeDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.TZDBTimeZoneNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.TimeZoneAdapter.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.TimeZoneGenericNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.TimeZoneNamesImpl.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.duration.BasicDurationFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.locale.LocaleSyntaxException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.number.CustomSymbolCurrency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.number.DecimalFormatProperties.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.impl.number.Properties.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.math.BigDecimal.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.math.MathContext.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.ArabicShapingException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.ChineseDateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.ChineseDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.ChineseDateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.CompactDecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.CurrencyPluralInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DateIntervalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DateIntervalInfo$PatternInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DateIntervalInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.DecimalFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.MeasureFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.MessageFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.MessageFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.NumberFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.NumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.PluralFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.PluralRules.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.RuleBasedNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.SelectFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.SimpleDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.StringPrepParseException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.TimeUnitFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.text.TimeZoneFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.AnnualTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.BuddhistCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.Calendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.ChineseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.CopticCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.Currency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.DangiCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.DateInterval.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.DateTimeRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.EthiopicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.GregorianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.HebrewCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.ICUCloneNotSupportedException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.ICUException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.ICUUncheckedIOException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.IllformedLocaleException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.IndianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.InitialTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.IslamicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.JapaneseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.MeasureUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.NoUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.PersianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.RuleBasedTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.SimpleTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.TaiwanCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.TimeArrayTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.TimeUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.TimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.ULocale.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.UResourceTypeMismatchException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_60.1/com.ibm.icu.util.VTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.DateNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.IllegalIcuArgumentException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.InvalidFormatException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.JavaTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.OlsonTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.RelativeDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.TZDBTimeZoneNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.TimeZoneAdapter.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.TimeZoneGenericNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.TimeZoneNamesImpl.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.duration.BasicDurationFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.locale.LocaleSyntaxException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.number.CustomSymbolCurrency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.number.DecimalFormatProperties.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.impl.number.Properties.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.math.BigDecimal.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.math.MathContext.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.ArabicShapingException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.ChineseDateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.ChineseDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.ChineseDateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.CompactDecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.CurrencyPluralInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DateIntervalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DateIntervalInfo$PatternInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DateIntervalInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.DecimalFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.MeasureFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.MessageFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.MessageFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.NumberFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.NumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.PluralFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.PluralRules.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.RuleBasedNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.SelectFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.SimpleDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.StringPrepParseException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.TimeUnitFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.text.TimeZoneFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.AnnualTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.BuddhistCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.Calendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.ChineseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.CopticCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.Currency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.DangiCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.DateInterval.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.DateTimeRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.EthiopicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.GregorianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.HebrewCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.ICUCloneNotSupportedException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.ICUException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.ICUUncheckedIOException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.IllformedLocaleException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.IndianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.InitialTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.IslamicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.JapaneseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.MeasureUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.NoUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.PersianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.RuleBasedTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.SimpleTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.TaiwanCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.TimeArrayTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.TimeUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.TimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.ULocale.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.UResourceTypeMismatchException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_61.1/com.ibm.icu.util.VTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.DateNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.IllegalIcuArgumentException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.InvalidFormatException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.JavaTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.OlsonTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.RelativeDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.TZDBTimeZoneNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.TimeZoneAdapter.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.TimeZoneGenericNames.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.TimeZoneNamesImpl.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.duration.BasicDurationFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.locale.LocaleSyntaxException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.number.CustomSymbolCurrency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.number.DecimalFormatProperties.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.number.LocalizedNumberFormatterAsFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.impl.number.Properties.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.math.BigDecimal.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.math.MathContext.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.number.SkeletonSyntaxException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.ArabicShapingException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.ChineseDateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.ChineseDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.ChineseDateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.CompactDecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.CurrencyPluralInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DateFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DateFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DateIntervalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DateIntervalInfo$PatternInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DateIntervalInfo.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DecimalFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.DecimalFormatSymbols.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.MeasureFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.MessageFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.MessageFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.NumberFormat$Field.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.NumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.PluralFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.PluralRules.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.RuleBasedNumberFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.SelectFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.SimpleDateFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.StringPrepParseException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.TimeUnitFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.text.TimeZoneFormat.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.AnnualTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.BuddhistCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.Calendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.ChineseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.CopticCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.Currency.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.DangiCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.DateInterval.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.DateTimeRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.EthiopicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.GregorianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.HebrewCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.ICUCloneNotSupportedException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.ICUException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.ICUUncheckedIOException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.IllformedLocaleException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.IndianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.InitialTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.IslamicCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.JapaneseCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.MeasureUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.NoUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.PersianCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.RuleBasedTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.SimpleTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.TaiwanCalendar.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.TimeArrayTimeZoneRule.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.TimeUnit.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.TimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.ULocale.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.UResourceTypeMismatchException.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_62.1/com.ibm.icu.util.VTimeZone.dat -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRanges1.16.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRanges1.32.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRanges2.16.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRanges2.32.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRanges3.16.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRanges3.32.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRangesEmpty.16.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRangesEmpty.32.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRangesSingleValue.16.tri2 -text
-icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/Trie2Test.setRangesSingleValue.32.tri2 -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/popmsg/en.res -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/popmsg/es.res -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/popmsg/res_index.res -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/popmsg/root.res -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/reshello/es.res -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/reshello/mt.res -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/reshello/res_index.res -text
-icu4j/samples/src/com/ibm/icu/samples/iuc/data/reshello/root.res -text
-icu4j/tools/build/icu4j53.api3.gz -text
-icu4j/tools/build/icu4j54.api3.gz -text
-icu4j/tools/build/icu4j55.api3.gz -text
-icu4j/tools/build/icu4j56.api3.gz -text
-icu4j/tools/build/icu4j57.api3.gz -text
-icu4j/tools/build/icu4j58.api3.gz -text
-icu4j/tools/build/icu4j59.api3.gz -text
-icu4j/tools/build/icu4j60.api3.gz -text
-icu4j/tools/build/icu4j61.api3.gz -text
-icu4j/tools/build/icu4j62.api3.gz -text
-tools/multi/c/Makefile-c.inc -text
-tools/multi/c/patch/3_0 -text
-tools/multi/c/patch/3_2 -text
-tools/multi/c/patch/3_4_1 -text
-tools/multi/common/Makefile-multi.inc -text
-tools/multi/j/Makefile-j.inc -text
-tools/multi/proj/icu4cscan/Makefile -text
-tools/multi/proj/icu4cscan/Makefile.local.sample -text
-tools/multi/proj/icu4cscan/Makefile_c -text
-tools/multi/proj/icu4cscan/Makefile_j -text
-tools/multi/proj/icu4cscan/dtd/icucaps.dtd -text
-tools/multi/proj/icu4cscan/old-xmls.tar.bz2 -text
-tools/multi/proj/icu4cscan/zappit.sed -text
-tools/multi/proj/icu4jscan/.classpath -text
-tools/multi/proj/icu4jscan/.project -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/CapDocument.java -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/CapElement.java -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/CapNode.java -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/CapScan.java -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/ScanICU.java -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/ScanJava.java -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/SimpleScan.java -text
-tools/multi/proj/icu4jscan/src/com/ibm/icu/dev/scan/Spinner.java -text
-tools/multi/proj/provider/Makefile.local-sample -text
-tools/multi/proj/provider/icu-config.sed -text
-tools/multi/proj/provider/readme.txt -text
-tools/release/c/bomfix.py -text
-tools/release/java/.classpath -text
-tools/release/java/.project -text
-tools/release/java/Makefile -text
-tools/release/java/icu4c.css -text
-tools/release/java/lib/README.TXT -text
-tools/release/java/lib/serializer.jar -text
-tools/release/java/lib/xalan.jar -text
-tools/release/java/lib/xercesImpl.jar -text
-tools/release/java/src/com/ibm/icu/dev/tools/docs/dumpAllCFunc_xml.xslt -text
-tools/release/java/src/com/ibm/icu/dev/tools/docs/dumpAllCppFunc_xml.xslt -text
-tools/release/java/src/com/ibm/icu/dev/tools/docs/genreport_xml.xslt -text
-tools/scripts/icurun -text
-tools/scripts/reticket -text
-tools/unicodetools/com/ibm/rbm/docs/images/TitleLogo_transparent.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/arrow_bullet.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/diamond_bullet.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/ibm_logo_small_white.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/RBReporter.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/basic_file.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/basic_group.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/basic_resource.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/basic_translation.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/basic_untranslated.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/create_group.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/empty_group.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/empty_resource.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/empty_screen.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/empty_with_preferences.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/laf_metal.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/laf_motif.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/laf_windows.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/lookup_resource.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/main_page.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/menu_file.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/menu_file_export.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/menu_file_import.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/menu_help.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/menu_options.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/menu_popup_tree.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/new_baseclass.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/new_bundle.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/preferences_dialog.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_groups_bundle.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_groups_file.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_search.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_stats_bundle.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_stats_file.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_tree_basic.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_untrans_bundle.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_untrans_dialog0.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/screenshots/view_untrans_file.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/spacer.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/template_l.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/template_line.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/template_ll.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/template_u.gif -text
-tools/unicodetools/com/ibm/rbm/docs/images/template_ul.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/TitleLogo_transparent.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_bundle.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_country.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_file.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_group.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_item.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_language.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_project.gif -text
-tools/unicodetools/com/ibm/rbm/gui/images/tree_icon_variant.gif -text
-vendor/double-conversion/UPDATING.md -text
-vendor/double-conversion/upstream/AUTHORS -text
-vendor/double-conversion/upstream/BUILD -text
-vendor/double-conversion/upstream/COPYING -text
-vendor/double-conversion/upstream/Changelog -text
-vendor/double-conversion/upstream/LICENSE -text
-vendor/double-conversion/upstream/README.md -text
-vendor/double-conversion/upstream/SConstruct -text
-vendor/double-conversion/upstream/WORKSPACE -text
-vendor/double-conversion/upstream/double-conversion/SConscript -text
-vendor/double-conversion/upstream/msvc/testrunner.cmd -text
-vendor/double-conversion/upstream/test/cctest/SConscript -text
+*.otf -text
+*.utf16be -text
 
 # The following file types are stored in Git-LFS.
+# Only .jars
 *.jar filter=lfs diff=lfs merge=lfs -text
-*.dat filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.gif filter=lfs diff=lfs merge=lfs -text
+
+# Enable syntax highlighting on GitHub.com
+.cpyskip.txt linguist-language=Ignore-List
+
+# Use JSONC for syntax highlighting on GitHub.com
+*.json linguist-language=jsonc
 

.github/lstm_for_th_my.json

@@ -0,0 +1,15 @@
+// © 2021 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+// Generated using tools/cldr/cldr-to-icu/build-icu-data.xml
+//
+// Include Burmese and Thai lstm models.
+{
+  "featureFilters": {
+    "brkitr_lstm": {
+      "includelist": [
+	"Thai_graphclust_model4_heavy",
+	"Burmese_graphclust_model5_heavy"
+      ]
+    }
+  }
+}

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+<!--
+Thank you for your pull request!
+
+Please see http://site.icu-project.org/processes/contribute for general
+information on contributing to ICU.
+
+You will be automatically asked to sign the contributors license agreement (CLA) before the PR is accepted.
+- sign: https://cla-assistant.io/unicode-org/icu
+- license: http://www.unicode.org/copyright.html
+-->
+
+##### Checklist
+
+- [ ] Required: Issue filed: https://unicode-org.atlassian.net/browse/ICU-_____
+- [ ] Required: The PR title must be prefixed with a JIRA Issue number. <!-- For example: "ICU-1234 Fix xyz" -->
+- [ ] Required: The PR description must include the link to the Jira Issue, for example by completing the URL in the first checklist item
+- [ ] Required: Each commit message must be prefixed with a JIRA Issue number. <!-- For example: "ICU-1234 Fix xyz" -->
+- [ ] Issue accepted (done by Technical Committee after discussion)
+- [ ] Tests included, if applicable
+- [ ] API docs and/or User Guide docs changed or added, if applicable

.github/workflows/icu_ci.yml

@@ -0,0 +1,442 @@
+# Copyright (C) 2016 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+#
+# GitHub Action configuration script for ICU continuous integration tasks.
+
+name: GHA CI
+
+on:
+  push:
+    branches:
+      - main
+      - 'maint/maint*'
+  pull_request:
+    branches: '**'
+
+jobs:
+
+  # ICU4C docs build using doxygen..
+  icu4c-docs-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C doc
+        run: |
+          sudo apt-get -y install doxygen;
+          cd icu4c/source;
+          ./runConfigureICU Linux --disable-renaming;
+           # Fail if 'warning:' appears in doxygen's output, but ignore warnings from file Doxyfile.
+           # Regex note: (?! ... ) is a negative lookahead. Succeed if the pattern is not present. 
+          set +o pipefail && make doc 2>&1 | tee doxygen.log && ( ! grep -P 'warning:(?! .* file .?Doxyfile)' doxygen.log )
+
+  # Java7 ICU4J build and unit test
+  java7-icu4j-build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout and setup
+        uses: actions/checkout@v2
+        with:
+          lfs: true
+      - name: Checkout lfs objects
+        run: git lfs pull
+      - uses: actions/setup-java@v1
+        with:
+          java-version: '8'
+      - name: Cache for Java 7 tarball
+        id: cache-java7
+        uses: actions/cache@v2
+        with:
+          path: java7-tarball
+          key: ${{ runner.os }}-java7-tarball
+      - name: Download Java 7
+        if: steps.cache-java7.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p java7-tarball
+          download_url="https://download.java.net/openjdk/jdk7u75/ri/openjdk-7u75-b13-linux-x64-18_dec_2014.tar.gz"
+          wget -O java7-tarball/java_package.tar.gz $download_url
+          pushd java7-tarball
+          gunzip java_package.tar.gz
+          tar xvf java_package.tar
+          popd
+      - name: Configure Ant build to use Java 7 JRE
+        run: |
+          echo "java7.bootclasspath" > $RUNNER_TEMP/draft
+          ls java7-tarball/java-se-7u75-ri/jre/lib/*.jar|paste -sd ":" - >> $RUNNER_TEMP/draft
+          paste -sd "=" < $RUNNER_TEMP/draft >  icu4j/build-local.properties
+      - name: ICU4J
+        run: |
+          cd icu4j;
+          ant init;
+          ant check;
+          ant localespiCheck
+      - name: List failures (if any)
+        run: |
+          [ -d icu4j/out/junit-results ] && cd icu4j && cat `find out/junit-results -name "*.txt" -exec grep -l FAILED {} \;`;
+        if: ${{ failure() }}
+
+
+  # ICU4J build and unit test under Java11
+  java11-icu4j-build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout and setup
+        uses: actions/checkout@v2
+        with:
+          lfs: true
+      - name: Checkout lfs objects
+        run: git lfs pull
+      - uses: actions/setup-java@v1
+        with:
+          java-version: '11'
+      - name: ICU4J
+        run: |
+          cd icu4j;
+          ant init;
+          ant check;
+          ant localespiCheck
+      - name: List failures (if any)
+        run: |
+          [ -d icu4j/out/junit-results ] && cd icu4j && cat `find out/junit-results -name "*.txt" -exec grep -l FAILED {} \;`;
+        if: ${{ failure() }}
+
+  # ICU4J build and unit test under Java16
+  java16-icu4j-build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout and setup
+        uses: actions/checkout@v2
+        with:
+          lfs: true
+      - name: Checkout lfs objects
+        run: git lfs pull
+      - uses: actions/setup-java@v1
+        with:
+          java-version: '16'
+      - name: ICU4J
+        run: |
+          cd icu4j;
+          ant init;
+          ant check;
+          ant localespiCheck
+      - name: List failures (if any)
+        run: |
+          [ -d icu4j/out/junit-results ] && cd icu4j && cat `find out/junit-results -name "*.txt" -exec grep -l FAILED {} \;`;
+        if: ${{ failure() }}
+
+  # ICU4J build and unit test under lstm
+  lstm-icu4j-build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout and setup
+        uses: actions/checkout@v2
+        with:
+          lfs: true
+      - name: Checkout lfs objects
+        run: git lfs pull
+      - uses: actions/setup-java@v1
+        with:
+          java-version: '11'
+      - name: Config LSTM and Rebuild data jar
+        run: |
+          cd icu4c/source;
+          ICU_DATA_BUILDTOOL_OPTS=--include_uni_core_data ICU_DATA_FILTER_FILE=../../.github/lstm_for_th_my.json ./runConfigureICU --enable-debug --disable-release Linux -disable-layoutex;
+          make clean;
+          make -j2 ICU4J_ROOT=../../../icu4j icu4j-data-install;
+          cd ../..
+      - name: ICU4J
+        run: |
+          cd icu4j;
+          ant init;
+          ant check;
+          ant localespiCheck
+      - name: List failures (if any)
+        run: |
+          [ -d icu4j/out/junit-results ] && cd icu4j && cat `find out/junit-results -name "*.txt" -exec grep -l FAILED {} \;`;
+        if: ${{ failure() }}
+
+  # gcc debug build.
+  # Includes dependency checker.
+  # Note - the dependency checker needs to be run on both a debug and an optimized build.
+  # This one (gcc) for debug, and linux clang (see job below) for optimized.
+  #
+  # Test both out-of-source and in-source builds. This one (gcc) for out-of-source,
+  # and linux clang (below) for in-source.
+  #
+  # Invokes test/hdrtst to check public headers compliance.
+  gcc-debug-build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C with gcc
+        env:
+          PREFIX: /tmp/icu-prefix
+        run: |
+          mkdir build;
+          cd build;
+          ../icu4c/source/runConfigureICU --enable-debug --disable-release Linux/gcc --prefix=$PREFIX --enable-tracing;
+          make -j2;
+          make -j2 check;
+          ( cd ../icu4c/source/test/depstest && ./depstest.py ../../../../build/ );
+          make install;
+          PATH=$PREFIX/bin:$PATH make -C test/hdrtst check
+
+  # clang release build with some options to enforce useful constraints.
+  # Includes dependency checker on an in-source, optimized build.
+  # Includes checking @draft etc. API tags vs. ifndef guards like
+  # U_HIDE_DRAFT_API and U_FORCE_HIDE_DRAFT_API.
+  # (FORCE guards make this tool pass but won't compile to working code.
+  # See the testtagsguards.sh script for details.)
+  clang-release-build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C with clang
+        env:
+          CPPFLAGS: -DU_NO_DEFAULT_INCLUDE_UTF_HEADERS=1
+          CFLAGS: -Wimplicit-fallthrough
+          CXXFLAGS: -Wimplicit-fallthrough
+        run: |
+          sudo apt-get -y install doxygen;
+          cd icu4c/source;
+          ./runConfigureICU Linux;
+          make -j 2;
+          make -j 2 check;
+          ( cd test/depstest && python3 depstest.py ../../../source/ );
+          ( cd .. && source/test/hdrtst/testtagsguards.sh );
+          make dist
+
+  # Out of source build with gcc 10, c++14, and extra warnings; executes icuinfo.
+  gcc-10-stdlib14:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C with gcc 10 and c++14 and extra warnings.
+        env:
+          PREFIX: /tmp/icu-prefix
+          CC: gcc-10
+          CXX: g++-10
+          CXXFLAGS: -std=c++14 -Wextra
+        run: |
+          mkdir build;
+          cd build;
+          ../icu4c/source/runConfigureICU Linux --disable-layout --disable-layoutex --prefix=$PREFIX;
+          make -j2;
+          make -j2 check;
+          make install;
+          cd $PREFIX/bin;
+          LD_LIBRARY_PATH=../lib ./icuinfo
+
+  # Clang Linux with address sanitizer.
+  clang-asan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C with clang and asan
+        run: |
+          cd icu4c/source;
+          ./runConfigureICU --enable-debug --disable-release Linux --disable-renaming --enable-tracing;
+          make -j2;
+          make -j2 check
+        env:
+          CPPFLAGS: -fsanitize=address
+          LDFLAGS: -fsanitize=address
+
+  # Clang Linux with thread sanitizer.
+  clang-tsan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C with clang and tsan
+        run: |
+          cd icu4c/source;
+          ./runConfigureICU --enable-debug --disable-release Linux --disable-renaming
+          make -j2;
+          make -j2 -C test;
+          make -j2 -C test/intltest check
+        env:
+          INTLTEST_OPTS: utility/MultithreadTest
+          CPPFLAGS: -fsanitize=thread
+          LDFLAGS: -fsanitize=thread
+
+  # MacOS with clang
+  macos-clang:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C with clang on MacOS
+        run: |
+          cd icu4c/source;
+          PYTHON=python3 ./runConfigureICU MacOSX;
+          make -j2 check
+
+  # Run ICU4C tests with stubdata.
+  run-with-stubdata:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: ICU4C tests with stubdata
+        run: |
+          cd icu4c/source;
+          ./runConfigureICU Linux;
+          make -j2 check;
+          rm lib/libicudata.so*;
+          cp -P stubdata/libicudata.so* lib;
+
+          cd test/cintltst;
+          echo 'Running ICU4C cintltst with stubdata.';
+          # Note: 'Elapsed Time: ' is printed by makefile upon final success.
+          CINTLTST_OPTS=-w make check 2>&1 | tee stubdata_ctest.log;
+          if ! grep 'Elapsed Time: ' stubdata_ctest.log
+          then
+            echo
+            echo cintltst run with stubdata failed
+            echo
+            echo See
+            echo https://unicode-org.github.io/icu/processes/release/tasks/integration.html#run-tests-without-icu-data
+            echo for how to reproduce and debug the failure
+            exit 1
+          fi
+
+          cd ../intltest;
+          echo 'Running ICU4C intltest with stubdata.';
+          INTLTEST_OPTS=-w make check 2>&1 | tee stubdata_intltest.log;
+          if ! grep 'Elapsed Time: ' stubdata_intltest.log
+          then
+            echo
+            echo intltest run with stubdata failed
+            echo
+            echo See
+            echo https://unicode-org.github.io/icu/processes/release/tasks/integration.html#run-tests-without-icu-data
+            echo for how to reproduce and debug the failure
+            exit 1
+          fi
+
+  # Test U_CHARSET_IS_UTF8
+  u-charset-is-utf8-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          cd icu4c/source;
+          ./runConfigureICU Linux CPPFLAGS="-DU_CHARSET_IS_UTF8=1";
+          make -j2 check
+
+  # Test U_OVERRIDE_CXX_ALLOCATION-is-0-test
+  u-override-cxx-allocation-is-0-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          cd icu4c/source;
+          ./runConfigureICU Linux CPPFLAGS="-DU_OVERRIDE_CXX_ALLOCATION=0";
+          make clean;
+          make -j2 check
+
+  # Test LSTM
+  lstm-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          cd icu4c/source;
+          ICU_DATA_FILTER_FILE=../../.github/lstm_for_th_my.json ./runConfigureICU --enable-debug --disable-release Linux -disable-layoutex;
+          make clean;
+          make -j2 check
+
+  # Build and run testmap
+  testmap:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: |
+          cd icu4c/source;
+          ./runConfigureICU Linux;
+          make -j2 check;
+          CONFIG_FILES=test/testmap/Makefile ./config.status;
+          cd test/testmap;
+          make check | grep '*** PASS PASS PASS, test PASSED!!!!!!!!'
+
+  # Copyright scan
+  copyright-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: perl tools/scripts/cpysearch/cpyscan.pl
+
+  # Check compilation of internal headers.
+  internal-header-compilation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: cd icu4c/source; test/hdrtst/testinternalheaders.sh
+
+  # Check source files for valid UTF-8 and for absence of BOM.
+  valid-UTF-8-and-no-BOM-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: tools/scripts/icu-file-utf8-check.py
+
+  # Verify icu4c release tools buildability.
+  icu4c-release-tools:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: mvn -f tools/release/java/pom.xml package dependency:analyze
+
+  # Run unit tests with UCONFIG_NO_XXX variations.
+  uconfig_variation-check-unit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: python3 tools/scripts/uconfig_vars_test.py -u
+
+  # Run header tests with UCONFIG_NO_XXX variations.
+  uconfig_variation-check-all-header-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - run: python3 tools/scripts/uconfig_vars_test.py -p
+
+  # Build Unicode update tools
+  unicode-update-tools:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: bazelbuild/setup-bazelisk@v1
+    - name: Mount bazel cache
+      uses: actions/cache@v2
+      with:
+        path: "~/.cache/bazel"
+        key: bazel
+
+    - name: Generate the data
+      run: |
+        export ICU_SRC=`pwd`;
+        icu4c/source/data/unidata/generate.sh;
+        if $?
+        then
+          echo
+          echo Build of Unicode update tools failed.
+          echo See
+          echo https://unicode-org.github.io/icu/processes/unicode-update#bazel-build-process
+          echo for how to reproduce and debug the failure
+          exit 1
+        fi
+
+        git diff --exit-code;
+        if $?
+        then
+          echo
+          echo ICU unicode data has changed!
+          echo Did you forget to include the changed data files in this PR?
+          exit 1
+        fi

.github/workflows/icu_merge_ci.yml

@@ -0,0 +1,38 @@
+# Copyright (C) 2021 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+#
+# GitHub Action continuous integration script for ICU post-merge tasks.
+
+name: GHA ICU Merge CI
+
+on:
+  push:
+    branches:
+      - main	
+      - 'maint/maint*'
+
+jobs:
+
+  # Test ICU4J with little-endian ICU4C data only
+  icu4j-little-endian-data-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout and setup
+        uses: actions/checkout@v2
+        with:
+          lfs: true
+      - name: Checkout lfs objects
+        run: git lfs pull
+      - uses: actions/setup-java@v1
+        with:
+          java-version: '11'
+      - name: ICU4J little-endian
+        run: |
+          cd icu4c/source;
+          ICU_DATA_BUILDTOOL_OPTS=--include_uni_core_data ./runConfigureICU Linux;
+          make -j2 check;
+          mkdir /tmp/icu4j_data_test;
+          cp -P data/out/tmp/icudt*l* /tmp/icu4j_data_test/
+          cd ../../icu4j;
+          ant clean;
+          ant -Dicu4c.data.path=/tmp/icu4j_data_test check;

.github/workflows/maven.yaml

@@ -0,0 +1,40 @@
+name: Publish icu4j.jar/utilities.jar to GH Maven
+on:
+  release:
+    types: [created]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          lfs: true
+      - uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+      - name: icu4j ant releaseCLDR
+        run: ant -noinput releaseCLDR -f icu4j/build.xml
+      - name: deploy it
+        run: |
+          MYVERSION=$(sed -n -e 's%^\s*maven.pom.ver[ =]*%%p' < icu4j/build.properties)-$(echo ${GITHUB_REF} | cut -d/ -f3- | tr ./ _-)
+          echo Github Ref ${GITHUB_REF} @ ${GITHUB_SHA}, version ${MYVERSION}
+          mvn deploy:deploy-file -DgroupId=com.ibm.icu \
+            -DartifactId=icu4j-for-cldr \
+            -Dversion=${MYVERSION} \
+            -Dpackaging=jar \
+            -Dfile=icu4j/release_cldr/icu4j.jar \
+            -Dsources=icu4j/release_cldr/icu4j-src.jar \
+            -DrepositoryId=github \
+            -Durl=https://maven.pkg.github.com/${GITHUB_REPOSITORY}
+          mvn deploy:deploy-file -DgroupId=com.ibm.icu \
+            -DartifactId=utilities-for-cldr \
+            -Dversion=${MYVERSION} \
+            -Dpackaging=jar \
+            -Dfile=icu4j/release_cldr/utilities.jar \
+            -Dsources=icu4j/release_cldr/utilities-src.jar \
+            -DrepositoryId=github \
+            -Durl=https://maven.pkg.github.com/${GITHUB_REPOSITORY}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+# Note: can use 0.0.0-${GITHUB_SHA} as the version for hash-based.
+# i.e. build on every commit

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# Contributing to ICU
+
+Thank you for wanting to contribute to ICU!
+
+Please see our instructions at <https://icu.unicode.org/processes/contribute>
+
+### License
+
+Please see [./icu4c/LICENSE](./icu4c/LICENSE) (C and J are under an identical license file.)
+
+> Copyright © 2021 and later Unicode, Inc. and others. All Rights Reserved.
+Unicode and the Unicode Logo are registered trademarks
+of Unicode, Inc. in the U.S. and other countries.
+[Terms of Use and License](http://www.unicode.org/copyright.html)

KEYS

@@ -0,0 +1,962 @@
+This file contains the PGP keys of ICU developers.
+Compare to http://www.apache.org/dist/ant/KEYS and read https://www.apache.org/dev/openpgp.html for background
+
+To import these keys:
+   gpg --import KEYS
+
+To update this file:
+replace $KEYID is your key's ID:
+  (gpg --list-sigs  $KEYID && gpg --armor --export $KEYID ) >> KEYS
+
+
+pub   2048R/825EA2CD 2010-11-02
+uid                  ICU Project @IBM (International Components for Unicode Development at IBM) <icuintl@us.ibm.com>
+sig 3        825EA2CD 2010-11-02  ICU Project @IBM (International Components for Unicode Development at IBM) <icuintl@us.ibm.com>
+sig 3        FD8FABF1 2013-12-12  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+sig          0F0DE47D 2014-09-17  Steven R. Loomis (CODE SIGNING KEY) <srl@icu-project.org>
+sub   2048R/1D06B1BF 2010-11-02
+sig          825EA2CD 2010-11-02  ICU Project @IBM (International Components for Unicode Development at IBM) <icuintl@us.ibm.com>
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG v2.0.14 (GNU/Linux)
+
+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
+AZA1XWLRgZ3+5+vD
+=NkHr
+-----END PGP PUBLIC KEY BLOCK-----
+
+
+pub   4096R/0F0DE47D 2014-09-17 [expires: 2019-09-16]
+uid                  Steven R. Loomis (CODE SIGNING KEY) <srl@icu-project.org>
+sig 3        0F0DE47D 2014-09-17  Steven R. Loomis (CODE SIGNING KEY) <srl@icu-project.org>
+sig          FD8FABF1 2014-09-17  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG v2.0.14 (GNU/Linux)
+
+mQINBFQZ3doBEACpnA2AbRRVxu9TeDTnjHtz6h5NyMyGZIPZOX7Iv2bNS0JSAS/H
+9f2WP9+3ANHuKI32rYh0snKpWjYsgUCxZ8x2Wp4cu8YnTvvpL6a5fn5n04dTyd4s
+/gPLb51qHIL8L6MDfK2ARgukntzfLR2CoL+RwGLDOjNlnoGNw65XEdjkzZ65s05Q
+/YHdlMYJE6gQ7VzJf7JYO6z6MpclLSj106TDs0hmOSetRm66nt+G7q1iY/jMXSMm
+bs3CFe4MNoVlRnl2THFZWjGSrVNYkenKexrjJ5HD9sm2nFF5pXgMQBoyOE5gic/b
+H5hMeh3v4vmhxRL5GPmI9Ir25LwqYCaWZDu6TC8mDDJj82YQMOzvElpRU/5V8KVc
+R7e4FN7D6tXDPb8IMgHb1U7zEnKYAc+uAS5NQ6Vq/S3NoueEQNk+rwqy44yIigtD
+iOJOnLvf1JFUPNFUxRu2JUy7YzvvcyGG9PY7bxQEb/MLwa424GWRTHV4Yw+hHP6D
++XgylCyd36wfwgF48+gFeDza9gMPPDgGqJu059PjEEG9ELgBFkTVjM0+rqq1M6Jk
++WPFRgM9ioccwdVIvfVZNnkp+EUjpl/PHLYlFvP0orkK3SGc1jaqW5m3Y6P60RzM
+7OovZqtqUDTEfMZ4bQKT4EdLayBPFALvz4TgndxrZwoPi2QGmFU9Dy+snwARAQAB
+tDlTdGV2ZW4gUi4gTG9vbWlzIChDT0RFIFNJR05JTkcgS0VZKSA8c3JsQGljdS1w
+cm9qZWN0Lm9yZz6JAj4EEwECACgFAlQZ3doCGwMFCQlmAYAGCwkIBwMCBhUIAgkK
+CwQWAgMBAh4BAheAAAoJEKqprpwPDeR9St0P/RJzlQDOgtD/rq8ThV5clhcgzCQU
+J34bC9+SdvQVtG6cOu+/mE9fjPcRuMSC2saj3e6KdfdCF51ZUelFgg7Nf4VjzKXK
+egYFe11CJSYFt0YQyT3CwlX5a6lKv9BH4RJPdAjeACSNCLvuZYlkxfAFPAwJFMAH
+CeiY6P7Llm2sHHIIubK+yFviZiD1ic92ADt2llM06VwniCS2Cs0kx4NAl70jd/vW
+B/j9+k+PphZFA2IUuB80qnTdrEb+nVLQ9n0SMFwFm89bEm8IhXe0Lb//jl5ZbZCr
+afn02GvdSqU73jqOfEHS7hHemB1KSM4hEdWGFRhUf0+Xpc31aOsnKY5Wu89A8Sz/
+sKp554qAhGmBGeEjkKbw0t+k4liP+LW2efmVBt+/6msF+TGq0Rr5vFQEUNCYeIzz
+DS5nKDlKvRwgx/41RnSUYiLJS9GkCB6skxIQZvW2G7rnkGQkgmP3/tkTTX0EP0rT
+GlW4ivfp+AKoYozkZ5FNLXC06yzCSKYL0z9uoL38uR6opXo4768byzzkBOvSut3Q
+V9gbvAtZvwEibwOt0A4UhbIyv96+Oi2WI66q37Wl33F/QIsxpC9UjXju1RrAajOv
+0gY8VMxwuWHN8ewslykX5rohxgA7mkTf/YeELSiYEM1WpmKmj30uJapgDwVRpsTC
+dfSvIc/nOLji4u0iiQEcBBABAgAGBQJUGfLZAAoJEKyl2+H9j6vx+58IAMIzjJTv
+9n7Yq2iyncFyg7fmPmlKo28l6cIrmveGtzLWgO7pXw9hZy8mTwUAhg9nMnNbnjDw
+qSA+YH8rNy0MB/AaTj46faE/RlqB8bCUlnLlRk9b6IxKODOVAarFk0ltCUeNt1IP
+w8YziwUaJewmb2//tEjwG4RuliQeo8EPcg2MejsxctNJ1gWQxZFOSMk2M6I9NwW6
+xMUmqGzzKdPChdwzOBaHK2f4lB3IlPqpJVqAWuXdINzi91tCIKfo508hJSpzGm/n
+Lq4yQHJPjQjxTldFBxC8Ji5yYIQ2ZcWLaYndWH4aVbAkEelU3eIp44mU4tqhqCP6
+zJJjdh87G81yUoE=
+=pu4w
+-----END PGP PUBLIC KEY BLOCK-----
+pub   2048R/FD8FABF1 2013-12-12 [expires: 2020-10-03]
+uid                  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+sig 3        FD8FABF1 2017-10-04  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+uid                  [jpeg image of size 10375]
+sig 3        FD8FABF1 2017-10-04  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+sig 3        FD8FABF1 2013-12-12  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+sig 3        FD8FABF1 2013-12-12  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+sub   2048R/A6EB1469 2013-12-12 [expires: 2019-10-04]
+sig          FD8FABF1 2017-10-04  Steven R. Loomis (ICU Project) <srl@icu-project.org>
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+mQENBFKpD3cBCADklZIzuPsYrEy08rASB+MRnFF8hqDDUkDHuvS0bJwEDge2EEHT
+l9rnUOt3SGtSrokeniQbwut26vuY/V59SSpwClytbHovIRJ/ovjq3nUasCRPOxDL
+mlmftkRGrO6WYH6hSzmRy2x3NTgQOlE/YRtOya3CAVlkiybpYXL3L1mJA4e80NpF
+V4UG7vyfw44OHFeO6mInqkcxVgKkxwp3wBbck3FEySEZT0DTT+sQHI52fgUftb+P
+xBH1s58lLAub4o2z1hnImPN/BR0lZpiNj59vzNlqmcnRHTpa6KIz+Qeep9dwLL7i
+71lMfCsEgVyDZxkQxFpNoRYRHRkfvBEY7JLpABEBAAG0NFN0ZXZlbiBSLiBMb29t
+aXMgKElDVSBQcm9qZWN0KSA8c3JsQGljdS1wcm9qZWN0Lm9yZz6JAT4EEwECACgC
+GwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheABQJZ1XNBBQkMz/5KAAoJEKyl2+H9
+j6vxKIEH/0aFGlFOtgXNHKEG7F1mVxhjNyFlZD5O/9t8oI46vYCgVfwsn6BsHFpv
+9yAtzA6z26Zt2NsPjH6dVRfc3sGCojBIKQ/lxnyQqjAYaEbVVQ/3jhAhgnm+uAF4
+3Rr54g+6FL7aHB33nDy9FmRtmQsyVf1OySR7VXbHpwEVzWeLrgmPKR1t8P1hdiSo
+YfroXVAPy2pynXUWgWbMbuqAcTj0iAQQ7LuVOVZ8bYA922LRgUxg/ZPxiGGm2g3M
+LF/QVWMH6FAHtSf9DOaFjZqQuypkUoOZZuFfNMvKaYIe+XviZRtWls5M6H8wOz6c
+bFrLBV5XBBwKbOXULpDv/3+oehDO22vR/wAAKJ3/AAAomAEQAAEBAAAAAAAAAAAA
+AAAA/9j/4AAQSkZJRgABAQEASABIAAD/4hscSUNDX1BST0ZJTEUAAQEAABsMYXBw
+bAIQAABtbnRyUkdCIFhZWiAH3QALAAUADwAzADFhY3NwQVBQTAAAAAAAAAAAAAAA
+AAAAAAAAAAAAAAAAAAAA9tYAAQAAAADTLWFwcGwAAAAAAAAAAAAAAAAAAAAAAAAA
+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABFkZXNjAAABUAAAAGJkc2NtAAAB
+tAAABA5jcHJ0AAAFxAAAACN3dHB0AAAF6AAAABRyWFlaAAAF/AAAABRnWFlaAAAG
+EAAAABRiWFlaAAAGJAAAABRyVFJDAAAGOAAACAxhYXJnAAAORAAAACB2Y2d0AAAO
+ZAAABhJuZGluAAAUeAAABj5jaGFkAAAauAAAACxtbW9kAAAa5AAAAChiVFJDAAAG
+OAAACAxnVFJDAAAGOAAACAxhYWJnAAAORAAAACBhYWdnAAAORAAAACBkZXNjAAAA
+AAAAAAhEaXNwbGF5AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
+AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbWx1
+YwAAAAAAAAAhAAAADGhySFIAAAAUAAABnGtvS1IAAAAMAAABsG5iTk8AAAASAAAB
+vGlkAAAAAAASAAABzmh1SFUAAAAUAAAB4GNzQ1oAAAAWAAAB9GRhREsAAAAcAAAC
+CnVrVUEAAAAcAAACJmFyAAAAAAAUAAACQml0SVQAAAAUAAACVnJvUk8AAAASAAAC
+am5sTkwAAAAWAAACfGhlSUwAAAAWAAACkmVzRVMAAAASAAACamZpRkkAAAAQAAAC
+qHpoVFcAAAAMAAACuHZpVk4AAAAOAAACxHNrU0sAAAAWAAAC0npoQ04AAAAMAAAC
+uHJ1UlUAAAAkAAAC6GZyRlIAAAAWAAADDG1zAAAAAAASAAADImNhRVMAAAAYAAAD
+NHRoVEgAAAAMAAADTGRlREUAAAAQAAADWGVuVVMAAAASAAADaHB0QlIAAAAYAAAD
+enBsUEwAAAASAAADkmVsR1IAAAAiAAADpHN2U0UAAAAQAAADxnRyVFIAAAAUAAAD
+1mphSlAAAAAOAAAD6nB0UFQAAAAWAAAD+ABMAEMARAAgAHUAIABiAG8AagBpzuy3
+7AAgAEwAQwBEAEYAYQByAGcAZQAtAEwAQwBEAEwAQwBEACAAVwBhAHIAbgBhAFMA
+egDtAG4AZQBzACAATABDAEQAQgBhAHIAZQB2AG4A/QAgAEwAQwBEAEwAQwBEAC0A
+ZgBhAHIAdgBlAHMAawDmAHIAbQQaBD4EOwRMBD4EQAQ+BDIEOAQ5ACAATABDAEQg
+DwBMAEMARAAgBkUGRAZIBkYGKQBMAEMARAAgAGMAbwBsAG8AcgBpAEwAQwBEACAA
+YwBvAGwAbwByAEsAbABlAHUAcgBlAG4ALQBMAEMARCAPAEwAQwBEACAF5gXRBeIF
+1QXgBdkAVgDkAHIAaQAtAEwAQwBEX2mCcgAgAEwAQwBEAEwAQwBEACAATQDgAHUA
+RgBhAHIAZQBiAG4A6QAgAEwAQwBEBCYEMgQ1BEIEPQQ+BDkAIAQWBBoALQQ0BDgE
+QQQ/BDsENQQ5AEwAQwBEACAAYwBvAHUAbABlAHUAcgBXAGEAcgBuAGEAIABMAEMA
+RABMAEMARAAgAGUAbgAgAGMAbwBsAG8AcgBMAEMARAAgDioONQBGAGEAcgBiAC0A
+TABDAEQAQwBvAGwAbwByACAATABDAEQATABDAEQAIABDAG8AbABvAHIAaQBkAG8A
+SwBvAGwAbwByACAATABDAEQDiAOzA8cDwQPJA7wDtwAgA78DuAPMA70DtwAgAEwA
+QwBEAEYA5AByAGcALQBMAEMARABSAGUAbgBrAGwAaQAgAEwAQwBEMKsw6TD8ACAA
+TABDAEQATABDAEQAIABhACAAQwBvAHIAZQBzAAB0ZXh0AAAAAENvcHlyaWdodCBB
+cHBsZSBJbmMuLCAyMDEzAABYWVogAAAAAAAA81IAAQAAAAEWz1hZWiAAAAAAAABq
+egAAPKoAAAYFWFlaIAAAAAAAAGhwAACq+AAAH7dYWVogAAAAAAAAI+wAABheAACt
+cWN1cnYAAAAAAAAEAAAAAAUACgAPABQAGQAeACMAKAAtADIANgA7AEAARQBKAE8A
+VABZAF4AYwBoAG0AcgB3AHwAgQCGAIsAkACVAJoAnwCjAKgArQCyALcAvADBAMYA
+ywDQANUA2wDgAOUA6wDwAPYA+wEBAQcBDQETARkBHwElASsBMgE4AT4BRQFMAVIB
+WQFgAWcBbgF1AXwBgwGLAZIBmgGhAakBsQG5AcEByQHRAdkB4QHpAfIB+gIDAgwC
+FAIdAiYCLwI4AkECSwJUAl0CZwJxAnoChAKOApgCogKsArYCwQLLAtUC4ALrAvUD
+AAMLAxYDIQMtAzgDQwNPA1oDZgNyA34DigOWA6IDrgO6A8cD0wPgA+wD+QQGBBME
+IAQtBDsESARVBGMEcQR+BIwEmgSoBLYExATTBOEE8AT+BQ0FHAUrBToFSQVYBWcF
+dwWGBZYFpgW1BcUF1QXlBfYGBgYWBicGNwZIBlkGagZ7BowGnQavBsAG0QbjBvUH
+BwcZBysHPQdPB2EHdAeGB5kHrAe/B9IH5Qf4CAsIHwgyCEYIWghuCIIIlgiqCL4I
+0gjnCPsJEAklCToJTwlkCXkJjwmkCboJzwnlCfsKEQonCj0KVApqCoEKmAquCsUK
+3ArzCwsLIgs5C1ELaQuAC5gLsAvIC+EL+QwSDCoMQwxcDHUMjgynDMAM2QzzDQ0N
+Jg1ADVoNdA2ODakNww3eDfgOEw4uDkkOZA5/DpsOtg7SDu4PCQ8lD0EPXg96D5YP
+sw/PD+wQCRAmEEMQYRB+EJsQuRDXEPURExExEU8RbRGMEaoRyRHoEgcSJhJFEmQS
+hBKjEsMS4xMDEyMTQxNjE4MTpBPFE+UUBhQnFEkUahSLFK0UzhTwFRIVNBVWFXgV
+mxW9FeAWAxYmFkkWbBaPFrIW1hb6Fx0XQRdlF4kXrhfSF/cYGxhAGGUYihivGNUY
++hkgGUUZaxmRGbcZ3RoEGioaURp3Gp4axRrsGxQbOxtjG4obshvaHAIcKhxSHHsc
+oxzMHPUdHh1HHXAdmR3DHeweFh5AHmoelB6+HukfEx8+H2kflB+/H+ogFSBBIGwg
+mCDEIPAhHCFIIXUhoSHOIfsiJyJVIoIiryLdIwojOCNmI5QjwiPwJB8kTSR8JKsk
+2iUJJTglaCWXJccl9yYnJlcmhya3JugnGCdJJ3onqyfcKA0oPyhxKKIo1CkGKTgp
+aymdKdAqAio1KmgqmyrPKwIrNitpK50r0SwFLDksbiyiLNctDC1BLXYtqy3hLhYu
+TC6CLrcu7i8kL1ovkS/HL/4wNTBsMKQw2zESMUoxgjG6MfIyKjJjMpsy1DMNM0Yz
+fzO4M/E0KzRlNJ402DUTNU01hzXCNf02NzZyNq426TckN2A3nDfXOBQ4UDiMOMg5
+BTlCOX85vDn5OjY6dDqyOu87LTtrO6o76DwnPGU8pDzjPSI9YT2hPeA+ID5gPqA+
+4D8hP2E/oj/iQCNAZECmQOdBKUFqQaxB7kIwQnJCtUL3QzpDfUPARANER0SKRM5F
+EkVVRZpF3kYiRmdGq0bwRzVHe0fASAVIS0iRSNdJHUljSalJ8Eo3Sn1KxEsMS1NL
+mkviTCpMcky6TQJNSk2TTdxOJU5uTrdPAE9JT5NP3VAnUHFQu1EGUVBRm1HmUjFS
+fFLHUxNTX1OqU/ZUQlSPVNtVKFV1VcJWD1ZcVqlW91dEV5JX4FgvWH1Yy1kaWWlZ
+uFoHWlZaplr1W0VblVvlXDVchlzWXSddeF3JXhpebF69Xw9fYV+zYAVgV2CqYPxh
+T2GiYfViSWKcYvBjQ2OXY+tkQGSUZOllPWWSZedmPWaSZuhnPWeTZ+loP2iWaOxp
+Q2maafFqSGqfavdrT2una/9sV2yvbQhtYG25bhJua27Ebx5veG/RcCtwhnDgcTpx
+lXHwcktypnMBc11zuHQUdHB0zHUodYV14XY+dpt2+HdWd7N4EXhueMx5KnmJeed6
+RnqlewR7Y3vCfCF8gXzhfUF9oX4BfmJ+wn8jf4R/5YBHgKiBCoFrgc2CMIKSgvSD
+V4O6hB2EgITjhUeFq4YOhnKG14c7h5+IBIhpiM6JM4mZif6KZIrKizCLlov8jGOM
+yo0xjZiN/45mjs6PNo+ekAaQbpDWkT+RqJIRknqS45NNk7aUIJSKlPSVX5XJljSW
+n5cKl3WX4JhMmLiZJJmQmfyaaJrVm0Kbr5wcnImc951kndKeQJ6unx2fi5/6oGmg
+2KFHobaiJqKWowajdqPmpFakx6U4pammGqaLpv2nbqfgqFKoxKk3qamqHKqPqwKr
+davprFys0K1ErbiuLa6hrxavi7AAsHWw6rFgsdayS7LCszizrrQltJy1E7WKtgG2
+ebbwt2i34LhZuNG5SrnCuju6tbsuu6e8IbybvRW9j74KvoS+/796v/XAcMDswWfB
+48JfwtvDWMPUxFHEzsVLxcjGRsbDx0HHv8g9yLzJOsm5yjjKt8s2y7bMNcy1zTXN
+tc42zrbPN8+40DnQutE80b7SP9LB00TTxtRJ1MvVTtXR1lXW2Ndc1+DYZNjo2WzZ
+8dp22vvbgNwF3IrdEN2W3hzeot8p36/gNuC94UThzOJT4tvjY+Pr5HPk/OWE5g3m
+lucf56noMui86Ubp0Opb6uXrcOv77IbtEe2c7ijutO9A78zwWPDl8XLx//KM8xnz
+p/Q09ML1UPXe9m32+/eK+Bn4qPk4+cf6V/rn+3f8B/yY/Sn9uv5L/tz/bf//cGFy
+YQAAAAAAAwAAAAJmZgAA8qcAAA1ZAAAT0AAACg52Y2d0AAAAAAAAAAAAAwEAAAIA
+AAAIACQAVwCkAQYBRgGTAe8CTAK0AycDoAQnBLoFWAYABrUHeAhGCRsJ+ArhC9IM
+zg3RDxQQaBG8ExkUdhXZF0kYuBotG6YdKx6vIDghyiNgJPomkygwKdUrZSzsLnUv
+9zF5Mvk0bzXjN084sToMO2M8tD3+P0VAhUHFQvlEHkVFRmpHkUi2SdxLAUwmTUlO
+bU+PULFR01L2VBlVPFZSV2pYf1mWWq1bw1zZXe5fAmAWYSliPGNOZGFldGaBZ4Bo
+gmmDaoRrhmyJbYpujG+OcJFxk3KVc5d0m3WVdnJ3UHgteQt56nrIe6Z8hn1nfkh/
+KoANgPGB1oK7g5+EhYVxhmOHX4hniXuKoYvXjR2Ob4/PkTySkJOylNaV+JcbmECZ
+ZpqOm7mc6Z4cn1KgjaHKovikDqUmpj+nWah3qZiqvKvlrRKuQ694sLGx67MftFC1
+frart9W4/boku0q8b72Vvr2/5cEPwjbDUcRhxWPGVsc7yBLI3MmbylXLDcvFzILN
+Rs4Rzt/PrdB80UrSGdLn07PUf9VJ1hLW2teZ2FHZBtm82nTbLtvo3KXdYt4h3uDf
+n+Bf4R/h3+Kc41bkDuTD5XPmIObL53LoGOi86WTqD+rC63XsKOzd7ZLuSO7/77jw
+c/Ev8ezywfOp9JL1dvZa9z/4Kvkf+iP7QvyG/gv//wAAAAcAHgBKAIsA4wEqAW4B
+wAIZAnQC2gNHA70EQQTSBW0GEQa9B3QINgkACdUKrQuODIENlg7MEAARPBJ6E7oV
+AxZPF6MY+BpUG7QdGh6GH/IhZCLWJE0lxycvKJMp9ytXLLMuCy9gMLAx+DM8NHc1
+rTbeOAo5MDpWO3c8kD2dPqw/ukDKQdlC6UP5RQpGGkcqSD1JTkpgS3FMg02UTp5P
+qVCyUbtSxlPQVNlV4lbqV/NY+1oDWwtcFF0dXiFfIWAfYR1iG2MZZBZlE2YPZwpo
+BWkAaftq9WvwbOdt2G7Ib7ZwpHGQcntzZHRLdTF2Fnb6d954wnmmeod7Z3xKfS5+
+FX8Cf/OA6oHpgvCD/YUShi2HTYhuiYuKp4vEjOKOAY8hkEORZpKNk7WU4JYNlzyY
+ZZmHmqqbzJzxnhefP6BpoZaixqP5pS6mZqegqNqqFKtOrIatvq72sCyxZLKbs9W1
+D7ZLt4m4x7oBuzq8cL2jvtG/+cEbwjbDTMRcxWnGcsdtyFrJQ8oryxPL+8zizcjO
+rs+T0HjRXtJD0yTUAdTd1bnWlNdv2ErZJdn/2tnbstyM3WbeQN8b3/fg1OGx4o3j
+auRH5STmAebd57nolOlp6j3rEevl7Lvtku5q70TwIPD98dzyu/Oc9I71lPas99X5
+C/pG+3n8mf2c/oD/Sf//AAAABQAWADUAZACkAPUBLQFqAbACAAJTArADFgOBA/UE
+cAT1BYMGHAa+B2UIEwjGCX4KQwsqDCYNJg4lDy4QNxFHElcTbhSGFaUWxxfxGRka
+SBt5HK0d4x8bIEQhaiKNI7Ak0yXwJwsoISk1KkArSCxKLUcuQS82MCoxHDIGMukz
+yTSqNY02bzdQODM5FDn1Otc7uDyaPXw+Xj9AQCJBBUHpQs5Ds0SYRX5GY0dISCxJ
+EEn1StlLvEyhTYZOaU9IUCdRBlHlUsRTolSBVV5WO1cZV/ZY01mvWo1baVxCXRtd
+817MX6Rge2FSYihi/mPTZKllfmZTZyhn+mjLaZxqbWs9bA1s3G2rbnlvRXAScN5x
+qXJ1cztz/3TBdYN2Q3cCd794e3kyeed6m3tKe/h8rH1xflp/R4A0gSKCEIL/g+2E
+2oXHhrOHnYiIiXCKaotpjGiNaI5pj2mQaJFmkmKTXZRVlUyWQZdEmFOZZ5p7m5Gc
+pp26ns2f3aDrofejAKQHpR6mU6ePqMyqC6tNrJGt2q8osHmxzrMntIO13LckuGi5
+prrcvAu9Mr5Sv2zAgMGRwp/DrcS4xcLGy8fWyOLJ78r+zA/NI846z1PQb9GN0rLT
+2dUB1irXU9h92ana1twF3TXeZ9+b4O/iheQo5d/nv+nQ7CHuuPGn9N/4XPwV//8A
+AG5kaW4AAAAAAAAGNgAAmj0AAFllAABRRwAAjYQAACXWAAAXCgAAUA0AAFQ5AAKK
+PQACRR4AAYzMAAMBAAACAAAACwAiAD0AWgB3AJUAswDRAPABEAEwAVEBcgGUAa8B
+ywHoAgYCJAJDAmMCgwKjAsQC5gMIAysDTgNxA5UDugPfBAQEKgRQBHcEngTGBO8F
+GAVBBWsFmAXHBfYGJgZXBooGvQbyBycHXweXB9IIDghMCI0IzwkTCVkJoQnsCjgK
+hwrXCykLgQveDDsMmgz6DVwNwA4lDowO9Q9gD8wQOhCqERwRjxIEEnoS8hNyE/IU
+dRT5FX8WBxaRFx0XrBg8GM8ZZBn7GpQbLxvLHGwdGR3GHnYfKB/cIJEhSiIEIsAj
+fiQ/JQIlxyaNJ1koRyk3KisrISwaLRYuFC8TMBUxGDIdMyM0LDU6Nkc3UThWOVI6
+RTsvPA885j22PoA/RkAIQMVBgEJRQ0JEM0UnRh1HE0gLSQNJ+0rzS+lM303UTshP
+u1CuUaZSwFPaVPVWEVctWEhZYlp7W5JcqF27Xs5f32DwYgBjFmQzZVJmdmecaMdp
+9WsmbFptkW7JcANxPXJ5c7R08HY6d5F4+np5fBR90H+2gcGD5YYNiCqKLYwnjiSQ
+JJIolDKWQ5hbmn2cpp7voV6jzKY4qKKrCq1yr9yySbS5ty65sLxFvvHBt8SXx43K
+lM2L0F/TN9YQ2Orbwt6W4WjkOOa26PrrVO258B7yevTC9uv46fq6/Fj9uv7p//8A
+AAANACcARgBnAIcAqADKAOwBDwEyAVcBfAGfAb4B3QH+Ah8CQQJkAogCrALRAvYD
+HANDA2oDkgO6A+MEDAQ2BGEEjAS4BOUFEgVABW4FoQXUBgkGPgZ1Bq4G5wcjB2AH
+nwffCCMIaAiwCPoJRwmWCegKPQqTCuwLRwurDA8MdgzeDUcNsw4gDo8O/w9yD+YQ
+WxDTEUwRxxJEEsITRhPMFFQU3xVrFfkWiRccF7EYSBjhGXwaGhq5G1ob/RymHVQe
+BB63H2wgJCDeIZsiWyMeI+MkqiV0JkEnDyfnKMQppSqJK3IsXi1PLkUvPzA9MT8y
+RDNMNFo1bDZ+N5E4oTmuOrc7uzy5PbM+qD+aQIpBd0JoQ11EVUVORkhHREhBST5K
+PEs6TDhNNk40TzNQMVEvUjlTSFRYVWpWfFePWKNZtlrJW9xc7l4AXxJgI2E1YkZj
+WWRuZYRmnme5aNdp9msYbDttYG6Gb6xw03H6cyJ0SnV0dqN31XkKekN7gXzFfhF/
+ZIDBgiaDlIULhomIDomzi3KNNI76kMOSkpRlljyYGJn3m9mdv5+6obujv6XIp9Wp
+56v9rhiwNrJZtH62pLjMuvW9Ib9RwYPDusX0yDTKd8zDzybRi9Pz1lrYwdsl3Yjf
+6eJK5KrnCukv6y7tFu7n8KryZ/Qr9gT4BPpD/OP//wAAABIANQBbAIMArADVAP4B
+KQFVAYMBqwHRAfgCIQJKAnUCoALNAvoDKQNYA4gDuQPqBB0EUASEBLkE7wUmBV4F
+mgXYBhgGWgadBuIHKgd0B8EIEAhjCLkJEwlxCdIKNwqfCwoLewvzDG4M6w1qDe0O
+cQ75D4MQEBCgETIRxxJeEvgTlBQyFNIVdRYaFsIXbRgbGMwZfxo2Gu8bqhxpHS8d
++B7DH5IgZCE5IhIi7iPNJK8llSZ9J2koXClSKkwrSSxLLVAuWi9nMHgxjTKlM8A0
+5TYNNzk4aTmdOtY8FD1YPqA/7UE+QptEBEVxRuZIY0nrS4BNIU7RUIxSF1NkVLJW
+AldUWKhZ/1tbXLleHV+FYPFiYmO6ZRBmaGfBaRxqe2vdbURur3AgcZdzE3SUdfp3
+VniyehB7b3zQfjV/nYEKgnyD9IVyhvWIfonTix2MaI2zjv+QSZGTktyUI5VplqyX
+75kvmm+brpzsni6fgqDbojqjoaUQpoioC6mZqzGs1K6AsDKx6rOmtWi3Lrj3usC8
+i75VwB/B6MOvxXTHN8j5yrrMec4uz+TRm9NU1Q3WyNiD2j7b+d20327hKeLj5J7m
+Ked+6M7qF+tZ7JHtuu7V7+fw4/Hb8r/zoPRw9UH1//a993P4I/jU+Xj6HfrA+1z7
++PyS/Sf9vP5Q/uD/b///AABzZjMyAAAAAAABDEIAAAXe///zJgAAB5IAAP2R///7
+ov///aMAAAPcAADAbG1tb2QAAAAAAAAGEAAAnKUAAAAAw7GoAAAAAAAAAAAAAAAA
+AAAAAAD/4QCARXhpZgAATU0AKgAAAAgABQESAAMAAAABAAEAAAEaAAUAAAABAAAA
+SgEbAAUAAAABAAAAUgEoAAMAAAABAAIAAIdpAAQAAAABAAAAWgAAAAAAAABIAAAA
+AQAAAEgAAAABAAKgAgAEAAAAAQAAADugAwAEAAAAAQAAAFMAAAAA/9sAQwACAQEC
+AQECAgECAgICAgMFAwMDAwMGBAQDBQcGBwcHBgYGBwgLCQcICggGBgkNCQoLCwwM
+DAcJDQ4NDA4LDAwL/9sAQwECAgIDAgMFAwMFCwgGCAsLCwsLCwsLCwsLCwsLCwsL
+CwsLCwsLCwsLCwsLCwsLCwsLCwsLCwsLCwsLCwsLCwsL/8AAEQgAUwA7AwEiAAIR
+AQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMC
+BAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNicoIJ
+ChYXGBkaJSYnKCkqNDU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3
+eHl6g4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS
+09TV1tfY2drh4uPk5ebn6Onq8fLz9PX29/j5+v/EAB8BAAMBAQEBAQEBAQEAAAAA
+AAABAgMEBQYHCAkKC//EALURAAIBAgQEAwQHBQQEAAECdwABAgMRBAUhMQYSQVEH
+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
+DyXQOcA=
+=x0WA
+-----END PGP PUBLIC KEY BLOCK-----
+
+pub   rsa4096 2015-11-15 [SC]
+      FFA9129A180D765B7A5BEA1C9B432B27D1BA20D7
+uid           [desconocida] Fredrik Roubert <fredrik@roubert.name>
+sig          C191C1EE0DED33EA 2015-11-23  [ID de usuario no encontrado]
+sig          216D7E92EB61819E 2015-11-25  [ID de usuario no encontrado]
+sig          1C2C9D2A7564DC9F 2015-12-02  [ID de usuario no encontrado]
+sig          A42898C74BF155DB 2015-12-03  [ID de usuario no encontrado]
+sig 3        C44AB8B850327DF9 2015-11-15  [ID de usuario no encontrado]
+sig          4719E4FC1E16C930 2015-12-02  [ID de usuario no encontrado]
+sig          4484F5552D1E8BB4 2015-12-02  [ID de usuario no encontrado]
+sig          6C6580E77BD756C4 2015-12-02  [ID de usuario no encontrado]
+sig          7F61756177978F76 2015-12-08  [ID de usuario no encontrado]
+sig          47712171F2ED62FB 2016-04-06  [ID de usuario no encontrado]
+sig 2        80D88B22D4330331 2015-11-21  [ID de usuario no encontrado]
+sig 3        9C187BA29B2157F8 2015-12-01  [ID de usuario no encontrado]
+sig 3        6DFD2ACE211BAAD0 2015-11-23  [ID de usuario no encontrado]
+sig 3        4445C665FFAD9AE0 2015-11-23  [ID de usuario no encontrado]
+sig 3        2DFF526BB17F76C6 2016-06-11  [ID de usuario no encontrado]
+sig 3        9B432B27D1BA20D7 2015-11-15  Fredrik Roubert <fredrik@roubert.name>
+uid           [desconocida] Fredrik Roubert <roubert@google.com>
+sig          C191C1EE0DED33EA 2015-11-23  [ID de usuario no encontrado]
+sig          216D7E92EB61819E 2015-11-25  [ID de usuario no encontrado]
+sig          1C2C9D2A7564DC9F 2015-12-02  [ID de usuario no encontrado]
+sig          A42898C74BF155DB 2015-12-03  [ID de usuario no encontrado]
+sig 3        C44AB8B850327DF9 2015-11-15  [ID de usuario no encontrado]
+sig          4719E4FC1E16C930 2015-12-02  [ID de usuario no encontrado]
+sig          4484F5552D1E8BB4 2015-12-02  [ID de usuario no encontrado]
+sig          6C6580E77BD756C4 2015-12-02  [ID de usuario no encontrado]
+sig          7F61756177978F76 2015-12-08  [ID de usuario no encontrado]
+sig          47712171F2ED62FB 2016-04-06  [ID de usuario no encontrado]
+sig 2        80D88B22D4330331 2015-11-21  [ID de usuario no encontrado]
+sig 3        9C187BA29B2157F8 2015-12-01  [ID de usuario no encontrado]
+sig 3        6DFD2ACE211BAAD0 2015-11-23  [ID de usuario no encontrado]
+sig 3        4445C665FFAD9AE0 2015-11-23  [ID de usuario no encontrado]
+sig 3        2DFF526BB17F76C6 2016-06-11  [ID de usuario no encontrado]
+sig 3        9B432B27D1BA20D7 2015-11-15  Fredrik Roubert <fredrik@roubert.name>
+sub   rsa4096 2015-11-15 [E]
+sig          9B432B27D1BA20D7 2015-11-15  Fredrik Roubert <fredrik@roubert.name>
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+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
+=vIM2
+-----END PGP PUBLIC KEY BLOCK-----
+
+pub   rsa4096 2018-06-28 [SC]
+      827320CB5E847C916CF49D06147473802F35F6CB
+uid           [ultimate] Jeff Genovy <jefgen@microsoft.com>
+sig 3        147473802F35F6CB 2019-12-04  Jeff Genovy <jefgen@microsoft.com>
+uid           [ultimate] Jeff Genovy <Jeff.Genovy@microsoft.com>
+sig 3        147473802F35F6CB 2019-12-04  Jeff Genovy <jefgen@microsoft.com>
+sub   rsa4096 2018-06-28 [E]
+sig          147473802F35F6CB 2018-06-28  Jeff Genovy <jefgen@microsoft.com>
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+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
+TMuS5W4GIP4f7uR1uQ==
+=Veoq
+-----END PGP PUBLIC KEY BLOCK-----
+pub   rsa4096 2020-02-24 [SC] [caduca: 2021-02-23]
+      4569BBC09DA846FC91CBD21CE1BBA44593CF2AE0
+uid        [  absoluta ] Steven R. Loomis (codesign-qormi) <srloomis@us.ibm.com>
+sig 3        E1BBA44593CF2AE0 2020-02-24  Steven R. Loomis (codesign-qormi) <srloomis@us.ibm.com>
+sig          44CE7BF2825EA2CD 2020-02-28  ICU Project @IBM (International Components for Unicode Development at IBM) <icuintl@us.ibm.com>
+uid        [  absoluta ] Steven R. Loomis (qormi signing key) <srl295@gmail.com>
+sig 3        E1BBA44593CF2AE0 2020-02-24  Steven R. Loomis (codesign-qormi) <srloomis@us.ibm.com>
+sig          44CE7BF2825EA2CD 2020-02-28  ICU Project @IBM (International Components for Unicode Development at IBM) <icuintl@us.ibm.com>
+sub   rsa2048 2020-02-24 [E] [caduca: 2021-02-23]
+sig          E1BBA44593CF2AE0 2020-02-24  Steven R. Loomis (codesign-qormi) <srloomis@us.ibm.com>
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+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
+=DEHc
+-----END PGP PUBLIC KEY BLOCK-----
+
+pub   rsa3072 2020-10-14 [SC]
+      0E51E7F06EF719FBD072782A5F56E5AFA63CCD33
+uid           [ultimate] Craig Cornelius (For use with ICU releases) <ccornelius@google.com>
+sig 3        5F56E5AFA63CCD33 2020-10-14  Craig Cornelius (For use with ICU releases) <ccornelius@google.com>
+sig 3        9B432B27D1BA20D7 2020-10-14  Fredrik Roubert <fredrik@roubert.name>
+sub   rsa3072 2020-10-14 [E]
+sig          5F56E5AFA63CCD33 2020-10-14  Craig Cornelius (For use with ICU releases) <ccornelius@google.com>
+
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+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
+=FdGa
+-----END PGP PUBLIC KEY BLOCK-----

README.md

@@ -0,0 +1,41 @@
+#  International Components for Unicode
+
+This is the repository for the [International Components for Unicode](https://icu.unicode.org/).
+The ICU project is under the stewardship of [The Unicode Consortium](https://www.unicode.org).
+
+- Source: https://github.com/unicode-org/icu
+- Bugs: https://unicode-org.atlassian.net/projects/ICU
+- API Docs: https://unicode-org.github.io/icu-docs/
+- User Guide: https://unicode-org.github.io/icu/
+
+![ICU Logo](./tools/images/iculogo_64.png)
+
+### 🔴🔴🔴 Special Notice About Branch Renaming 🔴🔴🔴
+Around March 24-25, 2021 we renamed the `master` branch to `main`. You may need to rename your branch in your local git repo and change your normal git command to reflect this change. See also https://github.com/github/renaming
+
+### Build Status (`main` branch)
+
+Build | Status
+------|-------
+GitHub Actions | [![GHA CI](https://github.com/unicode-org/icu/workflows/GHA%20CI/badge.svg)](https://github.com/unicode-org/icu/actions?query=workflow%3A%22GHA+CI%22)
+Azure Pipelines | [![Build Status](https://dev.azure.com/ms/icu/_apis/build/status/unicode-org/CI?branchName=main)](https://dev.azure.com/ms/icu/_build/latest?definitionId=360&branchName=main)
+Azure Pipelines (Exhaustive Tests) | [![Build Status](https://dev.azure.com/ms/icu/_apis/build/status/unicode-org/CI-Exhaustive-Main?branchName=main)](https://dev.azure.com/ms/icu/_build/latest?definitionId=361&branchName=main)
+Azure Pipelines (Valgrind ICU4C) | [![Build Status](https://dev.azure.com/ms/icu/_apis/build/status/unicode-org/CI-Valgrind?branchName=main)](https://dev.azure.com/ms/icu/_build/latest?definitionId=364&branchName=main)
+Fuzzing | [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/icu.svg)](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:icu)
+
+
+### Subdirectories and Information
+
+- [`icu4c/`](./icu4c/) [ICU for C/C++](./icu4c/readme.html)
+- [`icu4j/`](./icu4j/) [ICU for Java](./icu4j/readme.html)
+- [`tools/`](./tools/) Tools
+- [`vendor/`](./vendor/) Vendor dependencies
+
+### License
+
+Please see [./icu4c/LICENSE](./icu4c/LICENSE) (C and J are under an identical license file.)
+
+> Copyright © 2016 and later Unicode, Inc. and others. All Rights Reserved.
+Unicode and the Unicode Logo are registered trademarks 
+of Unicode, Inc. in the U.S. and other countries.
+[Terms of Use and License](http://www.unicode.org/copyright.html)

WORKSPACE

@@ -0,0 +1,5 @@
+# © 2021 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
+# This file tells Bazel where the root directory of the project is.
+# "Target" and file paths in Bazel BUILD files are relative to this root directory.

docs/404.html

@@ -0,0 +1,28 @@
+---
+layout: default
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+<style type="text/css" media="screen">
+  .container {
+    margin: 10px auto;
+    max-width: 600px;
+    text-align: center;
+  }
+  h1 {
+    margin: 30px 0;
+    font-size: 4em;
+    line-height: 1;
+    letter-spacing: -1px;
+  }
+</style>
+
+<div class="container">
+  <h1>404</h1>
+
+  <p><strong>Page not found :(</strong></p>
+  <p>The requested page could not be found.</p>
+</div>

docs/Gemfile

@@ -0,0 +1,37 @@
+# © 2020 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
+source "https://rubygems.org"
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+
+# gem "jekyll", "~> 3.8.7"
+
+# This is the default theme for new Jekyll sites. You may change this to anything you like.
+gem "minima", "~> 2.5"
+# If you aren't using GitHub Pages, then uncomment out the line above that starts with
+# 'gem "jekyll"' and then comment out the line below that starts with 'gem "github-pages"'.
+# To upgrade, run `bundle update github-pages`.
+gem "github-pages", "~> 213", group: :jekyll_plugins
+gem "just-the-docs"
+# If you have any plugins, put them here!
+group :jekyll_plugins do
+  gem "jekyll-feed", "~> 0.12"
+end
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", "~> 1.2"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
+

docs/_config.yml

@@ -0,0 +1,99 @@
+# © 2020 and later: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+
+title: ICU Documentation
+email: icu-support@icu-project.org
+description: >- # this means to ignore newlines until "baseurl:"
+  ICU is a mature, widely used set of C/C++ and Java libraries providing Unicode
+  and Globalization support for software applications. The ICU User Guide provides
+  documentation on how to use ICU.
+
+baseurl: "/icu" # the subpath for the site
+url: "https://unicode-org.github.io" # the base hostname & protocol for your site
+
+twitter_username: unicode
+github_username:  unicode-org
+
+remote_theme: pmarsceill/just-the-docs
+
+# GitHub uses its own markdown renderer called CommonMarkGhPages.
+#
+# To use this we'd need to set the following options:
+#     markdown: CommonMarkGhPages
+#     Plugins:
+#       jekyll-commonmark-ghpages
+#  
+#     commonmark:
+#       options: ["SMART", "FOOTNOTES"]
+#       extensions: ["strikethrough", "autolink", "table", "tagfilter"]
+#
+# However, it doesn't work well with Jekyll and the Just-The-Docs theme,
+# and causes too many formatting problems. Additionally, it also doesn't
+# have any support for auto-generating a Table of Contents (TOC) section
+# for a page. Due to these reasons, we instead use the recommended
+# markdown renderer for Jekyll, called kramdown.
+#
+markdown: kramdown
+
+# Notes on plugins:
+#  - GitHub Pages ignores all plugins included in the Gemfile.
+#    - Only the ones listed in the _config.yml file (this file) are used.
+#  - There is a very limited set of plugins that GH Pages supports (for security
+#    reasons). The listing is here: https://pages.github.com/versions
+#  - The jekyll-sitemap plugin generates a "sitemap.xml" for search engines.
+#  - We need the "jemoji" plugin for rendering emoji like ":point_right:".
+plugins:
+  - jekyll-remote-theme
+  - jekyll-sitemap
+  - jemoji
+
+search_enabled: true
+
+# Color scheme currently only supports "dark" or nil (light).
+color_scheme: nil
+
+# Aux links for the upper right navigation
+aux_links:
+  "API Docs":
+    - "https://unicode-org.github.io/icu-docs"
+  "ICU on GitHub":
+    - "https://github.com/unicode-org/icu"
+  "ICU Home Page":
+    - "http://site.icu-project.org/"
+  "Unicode Home Page":
+    - "https://www.unicode.org"
+
+# Makes Aux links open in a new tab.
+aux_links_new_tab: true
+
+# Add a "Back to top" link at the bottom of each page.
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# Enable heading anchors
+heading_anchors: true
+
+# Footer content: appears at the bottom of every page after the main content.
+footer_content: "&copy; 2016 and later: Unicode, Inc. and others. License &amp; terms of use: <a href=\"http://www.unicode.org/copyright.html\">http://www.unicode.org/copyright.html</a>"
+
+# Footer content: Add a "Edit this page on GitHub" link.
+# Note: I think this would be better at the *top* of the page, but it isn't possible to do that by default with just-the-docs.
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub."
+gh_edit_repository: "https://github.com/unicode-org/icu"
+# NOTE: Since we serve the docs out of the "docs" folder, we need to include that here even though
+# it is technically *not* part of the branch name.
+gh_edit_branch: "main/docs"
+# Can be "tree" or "edit". Edit takes the user to jump into the editor immediately.
+gh_edit_view_mode: "tree"
+
+# Exclude from processing.
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+exclude:
+  - Gemfile
+  - Gemfile.lock
+
+# Google Analytics
+ga_tracking: UA-7670256-1
+ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings

docs/_sass/color_schemes/light.scss

@@ -0,0 +1,8 @@
+// © 2020 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+
+// Increase the side bar width as some of the page titles don't fit in the default size.
+$nav-width: 284px;
+
+// Increase the main content area width as some tables assume a larger size.
+$content-width: 900px;

docs/ide4c/vscode/README.md

@@ -0,0 +1,23 @@
+<!--- © 2020 and later: Unicode, Inc. and others. ---> 
+<!--- License & terms of use: http://www.unicode.org/copyright.html --->
+
+# Configuring VS Code for ICU4C
+
+  - Create a `.vscode` folder in icu4c/source
+  - Copy the `tasks.json`, `launch.json` and `c_cpp_properties.json` files into
+    the `.vscode` folder.
+  - To test only specific test targets, specify them under `args` in
+    `launch.json`.
+  - To adjust the parallelism when building, adjust the `args` in `tasks.json`.
+    - `-l20` tells VSCode to not launch jobs if the system load average is above
+      20 (note that the [system load
+      average](https://en.wikipedia.org/wiki/Load_(computing)) is *not* a CPU
+      usage percentage).
+    - `-j24` limits the number of jobs launched in parallel to 24. The system
+      load average takes a while to respond, reducing this number helps the
+      initial bad system performance when a new build is launched.
+
+NOTE:
+Run the
+[`./runConfigureICU` command](https://unicode-org.github.io/icu/userguide/icufaq)
+before building `icu4c` from VSCode.

docs/ide4c/vscode/c_cpp_properties.json

@@ -0,0 +1,21 @@
+{
+    "configurations": [
+        {
+            "name": "Linux",
+            "includePath": [
+                "${workspaceFolder}/tools/toolutil",
+                "${workspaceFolder}/tools/ctestfw",
+                "${workspaceFolder}/common",
+                "${workspaceFolder}/i18n"
+            ],
+            "defines": [
+                "U_DISABLE_RENAMING=1"
+            ],
+            "compilerPath": "/usr/bin/clang",
+            "cStandard": "c11",
+            "cppStandard": "c++17",
+            "intelliSenseMode": "clang-x64"
+        }
+    ],
+    "version": 4
+}

docs/ide4c/vscode/launch.json

@@ -0,0 +1,102 @@
+// © 2020 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "intltest Launch",
+            "type": "cppdbg",
+            "request": "launch",
+            "targetArchitecture": "x64",
+            "program": "${workspaceFolder}/test/intltest/intltest",
+            "environment": [
+                {
+                    "name": "LD_LIBRARY_PATH", // Use "DYLD_LIBRARY_PATH" for mac osx.
+                    "value": "${workspaceRoot}/lib:${workspaceRoot}/stubdata:${workspaceRoot}/tools/ctestfw"
+                },
+                {
+                    "name": "ICU_DATA",
+                    "value": "${workspaceRoot}/data/out"
+                }
+            ],
+            "args": [ // Here you add which test cases you want to run, leaving it empty will run all the test cases.
+                // Examples:
+                // "rbbi/RBBITest",
+                // "format/NumberFormatTest"
+            ],
+            "stopAtEntry": false, // If you want to add a break point in the beginning of the program (i.e. test cases).
+            "cwd": "${workspaceFolder}/test/intltest",
+            "externalConsole": false, //set to true to see output in an external terminal instead
+            "MIMode": "gdb", // Use "lldb" for mac osx.
+            "logging": {
+                "trace": true,
+                "traceResponse": true,
+                "engineLogging": true,
+                "programOutput": true
+            },
+            "preLaunchTask": "buildTest"
+        },
+        {
+            "name": "cintltst Launch",
+            "type": "cppdbg",
+            "request": "launch",
+            "targetArchitecture": "x64",
+            "program": "${workspaceFolder}/test/cintltst/cintltst",
+            "environment": [
+                {
+                    "name": "LD_LIBRARY_PATH", // Use "DYLD_LIBRARY_PATH" for mac osx.
+                    "value": "${workspaceRoot}/lib:${workspaceRoot}/stubdata:${workspaceRoot}/tools/ctestfw"
+                },
+                {
+                    "name": "ICU_DATA",
+                    "value": "${workspaceRoot}/data/out"
+                }
+            ],
+            "args": [ // Here you add which test cases you want to run, leaving it empty will run all the test cases.
+                // "/tsutil/cstrcase" // Just for example.
+            ],
+            "stopAtEntry": false, // If you want to add a break point in the beginning of the program (i.e. test cases).
+            "cwd": "${workspaceFolder}",
+            "externalConsole": false, //set to true to see output in an external terminal instead
+            "MIMode": "gdb", // Use "lldb" for mac osx.
+            "logging": {
+                "trace": true,
+                "traceResponse": true,
+                "engineLogging": true,
+                "programOutput": true
+            },
+            "preLaunchTask": "buildTest"
+        },
+        {
+            "name": "iotest Launch",
+            "type": "cppdbg",
+            "request": "launch",
+            "targetArchitecture": "x64",
+            "program": "${workspaceFolder}/test/iotest/iotest",
+            "environment": [
+                {
+                    "name": "LD_LIBRARY_PATH", // Use "DYLD_LIBRARY_PATH" for mac osx.
+                    "value": "${workspaceRoot}/lib:${workspaceRoot}/stubdata:${workspaceRoot}/tools/ctestfw"
+                },
+                {
+                    "name": "ICU_DATA",
+                    "value": "${workspaceRoot}/data/out"
+                }
+            ],
+            "args": [ // Here you add which test cases you want to run, leaving it empty will run all the test cases.
+                // "/datadriv" // Just for example.
+            ],
+            "stopAtEntry": false, // If you want to add a break point in the beginning of the program (i.e. test cases).
+            "cwd": "${workspaceFolder}",
+            "externalConsole": false, //set to true to see output in an external terminal instead
+            "MIMode": "gdb", // Use "lldb" for mac osx.
+            "logging": {
+                "trace": true,
+                "traceResponse": true,
+                "engineLogging": true,
+                "programOutput": true
+            },
+            "preLaunchTask": "buildTest"
+        }
+    ]
+}

docs/ide4c/vscode/tasks.json

@@ -0,0 +1,37 @@
+// © 2020 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Makefile", // You can choose your own label.
+            "type": "shell",
+            "command": "make",
+            // Make this the default build command.
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "presentation": {
+                "reveal": "always"
+            },
+            // You can pass all the building arguments here.
+            "args": [
+                "all",
+                "--debug", // Enable debug mode.
+                "-j24", // Launch no more than 24 jobs in parallel
+                "-l20" // Stop launching jobs if system load average is too high
+            ]
+        },
+        {
+            "label": "buildTest", // for building test cases before running it.
+            "command": "make", // Could be any other shell command
+            "args": [
+                "tests",
+                "-j24", // Launch no more than 24 jobs in parallel
+                "-l20" // Stop launching jobs if system load average is too high
+            ],
+            "type": "shell"
+        }
+    ]
+}

docs/index.md

@@ -0,0 +1,26 @@
+---
+layout: default
+title: ICU Documentation
+nav_order: 100
+description: ICU Documentation
+---
+
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# ICU Documentation
+
+[![ICU logo](https://github.com/unicode-org/icu-docs/raw/main/img/iculogo_64.png)](https://icu.unicode.org/)
+
+## ICU User Guide
+
+The [ICU User Guide](./userguide) provides information on i18n topics for which ICU has services, and
+includes details that go beyond the C, C++, and Java API docs (and avoids some duplication between them).
+
+This is the new home of the User Guide (since 2020 August).
+
+## ICU team member pages
+
+Other documentation pages here are written by and for team members.

docs/processes/fuzzer_targets.md

@@ -0,0 +1,156 @@
+<!--
+© 2019 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+Developing Fuzzer Targets for ICU APIs
+======================================
+
+This documents describes how to develop a [fuzzer](https://opensource.google.com/projects/oss-fuzz)
+target for an ICU API and its integration into the ICU build process.
+
+### Directory and naming conventions
+
+Fuzzer targets are exclusively in directory
+[`source/test/fuzzer/`](https://github.com/unicode-org/icu/tree/main/icu4c/source/test/fuzzer)
+and end with `_fuzzer.cpp`. Only files with such ending are recognized and executed as fuzzer
+targets by the OSS-Fuzz system.
+
+### General structure of a fuzzer target
+
+As a minimum, a fuzzer target contains the function
+
+
+```
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size) {
+  ...
+}
+```
+
+This function is expected and invoked by the fuzzer system. The `data` parameter contains the
+fuzzer-controlled data of size `size` bytes. Part or all of this data is then passed into the
+ICU API under test.
+
+Fuzzer target
+[`collator_rulebased_fuzzer.cpp`](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/fuzzer/collator_rulebased_fuzzer.cpp)
+illustrates the basic elements.
+
+```
+// © 2019 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
+
+#include <cstring>
+
+#include "fuzzer_utils.h"
+#include "unicode/coll.h"
+#include "unicode/localpointer.h"
+#include "unicode/locid.h"
+#include "unicode/tblcoll.h"
+
+IcuEnvironment* env = new IcuEnvironment();
+
+extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size) {
+  UErrorCode status = U_ZERO_ERROR;
+
+  size_t unistr_size = size/2;
+  std::unique_ptr<char16_t[]> fuzzbuff(new char16_t[unistr_size]);
+  std::memcpy(fuzzbuff.get(), data, unistr_size * 2);
+  icu::UnicodeString fuzzstr(false, fuzzbuff.get(), unistr_size);
+
+  icu::LocalPointer<icu::RuleBasedCollator> col1(
+      new icu::RuleBasedCollator(fuzzstr, status));
+
+  return 0;
+}
+```
+
+The ICU API under test is the `RuleBasedCollator(const UnicodeString &rules, UErrorCode &status)`
+constructor. The code interprets the fuzzer data as UnicodeString and passes it to the constructor.
+And that is all. Specific error handling or return value verification is not required because the
+fuzzer will detect all memory issues by means of memory/address sanitizer findings.
+
+### Makefile.in changes
+
+ICU fuzzer targets are built and executed by the OSS-Fuzz project. On side of ICU they are compiled
+to assure that the code is syntactically correct and, as a sanity check, executed in the most basic
+manner, i.e. with minimal testdata and without ASAN or MSAN analysis.
+
+Add the new fuzzer target to the list of targets in the `FUZZER_TARGETS` variable in
+[`Makefile.in`](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/fuzzer/Makefile.in).
+The new fuzzer target will then be built and executed as part of a normal ICU4C unit test run. Note
+that each fuzzer target becomes executable on its own. As such it is linked with the code in
+`fuzzer_driver.cpp`, which contains the `main()` function.
+
+### Fuzzer seed corpus
+
+Any fuzzer seed data for a fuzzer target goes into a file with name `<fuzzer_target>_seed_corpus.txt`.
+In many cases the input parameter of the ICU API under test is of type `UnicodeString`, in case
+of which the seed data should be in UTF-16 format. As an example,see
+[collator_rulebased_fuzzer_seed_corpus.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/fuzzer/collator_rulebased_fuzzer_seed_corpus.txt).
+
+### Guidelines and tips
+
+*   Leave all randomness to the fuzzer. If a random selection of any kind is needed (e.g., of a
+    locale), then use bytes from the fuzzer data to make the selection
+    ([example](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/fuzzer/break_iterator_fuzzer.cpp)).
+*   In many cases ICU unit tests can provide seed data or at least ideas for seed data. If the API
+    under test requires a Unicode string then make sure that the seed data is in UTF-16 encoding.
+    This can be achieved with e.g. the 'iconv' command or using an editor that saves text in UTF-16.
+
+### How to locally reproduce fuzzer findings
+
+At this time reproduction of fuzzer findings requires Docker installed on the local machine and the
+OSS-Fuzz project downloaded in a local git client.
+
+1.  Install Docker (Ubuntu):
+
+    ```
+    sudo apt install docker
+    ```
+2.  Download OSS-Fuzz, switch into directory oss-fuzz/
+
+    In a git client directory, download the fuzzer system.
+
+    ```
+    git clone https://github.com/google/oss-fuzz.git
+    cd oss-fuzz/
+    ```
+3.  Build the Docker image for ICU.
+    In some setups root permissions may be required to connect to the Docker.
+
+    ```
+    [sudo] python infra/helper.py build_image icu
+    ```
+    A prompt will appear: `Pull latest base images (compiler/runtime)? (y/N)`
+    Respond: 'N'. If you are curious then respond with 'y' (won't hurt).
+4.  Build the ICU fuzzers:
+
+    ```
+    [sudo] python infra/helper.py build_fuzzers --sanitizer [address | memory | undefined] icu
+    ```
+    Check that the fuzzer targets were built successfully: ```ls -l build/out/icu```
+
+5.   Reproduce the fuzzer finding.
+     First, get the testdata the fuzzer used when finding the issue. In the fuzzer bug report look
+     for 'Reproducer Testcase', a click on the link will download the testdata. Then execute
+
+     ```
+     [sudo] python infra/helper.py reproduce icu <icu_fuzzer> <testdata>
+     ```
+     Concrete example:
+
+     ```
+     sudo python infra/helper.py reproduce icu uregex_open_fuzzer  ~/Downloads/clusterfuzz-testcase-minimized-uregex_open_fuzzer-5732067058384896
+     ```
+
+**Limitations:** When reproducing a fuzzer finding in the way outlined above the fuzzer environment
+will use the current ICU trunk from https://github.com/unicode-org/icu.git. Thus it is not possible
+to modify the code to try out a possible fix. What can be done is to redirect Docker to download ICU
+from a forked ICU repository. Open the file oss-fuzz/projects/icu/Dockerfile and adjust the line
+with `git clone --depth 1 https://github.com/unicode-org/icu.git icu` accordingly. Then modify
+the code in the forked repository and follow the steps above beginning with step 3, create a Docker
+image.
+
+This of course is still a tedious way of reproducing and working on a fuzzer finding. Ticket
+[ICU-20734](https://unicode-org.atlassian.net/browse/ICU-20734) aims to introduce a fuzzer driver
+that can reproduce certain fuzzer findings in a local ICU workspace.

docs/processes/release/tasks/announce.md

@@ -0,0 +1,143 @@
+---
+layout: default
+title: Announcements
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 10
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Announcements
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## First milestone/candidate for a release
+
+We write drafts of announcements in the ["ICU announcements" Google
+doc](https://docs.google.com/document/d/1rSVKZaus2K3rF66bMfDjYZnA2KTSJZUBz4C58GQMHsQ/edit).
+
+When there is no section yet for the upcoming release, then copy the whole
+section from one of the previous two full releases and adjust the version
+numbers everywhere in the copied headings and text.
+
+### Announcement for a release candidate
+
+Adjust the release candidate announcement subsection with a very brief summary
+gleaned from the download page.
+
+Share the draft as a link to the doc heading with the ICU team, invite comments
+and edits.
+
+When ready, send to the mailing lists as indicated in the doc. Make sure to use
+bcc as noted for the "announce" lists.
+
+### Announcement for a new major version
+
+Adjust the final-release announcement subsection with a very brief summary
+gleaned from the download page. Adjust the blog & tweet texts as well.
+
+Share the draft as a link to the doc heading with the ICU team, invite comments
+and edits.
+
+Share the draft as a link with the Unicode editorial committee, invite comments,
+discuss, adjust as agreed.
+
+When ready, send to the mailing lists as indicated in the doc. Make sure to use
+bcc as noted for the "announce" lists.
+
+Notify Rick McGowan for the Unicode blog posting and Ken Lunde for tweeting.
+
+Notify Ken Whistler (Unicode) to update the ICU version & date on
+<https://www.unicode.org/releases/>
+
+Put a News item on the ICU project site.
+
+### Announcement for a maintenance update
+
+Same as for a release candidate, but start by copying the section for the last
+maintenance update in the doc.
+
+## Update the reference for ICU in the external sites
+
+**For freshmeat.net**
+
+1.  <http://www.freshmeat.net/>
+2.  Login under the correct account.
+3.  I usually search for: icu unicode
+4.  Click on the project returned
+5.  Under the 'project' drop down, choose 'Add release'
+6.  We have (thankfully) only one branch of development- choose Default
+7.  Release info
+    *   release focus: Choose the one which best fits
+    *   Version
+    *   Changes: be VERY brief, and include links if needed.
+        Please read the other ICU4C/ICU4J updates to get an idea for how we are
+        wording these. DO NOT use bulleted lists. DO use short 'sentences'.
+        Remember they can go to the release list and/or bug DB for the full
+        scoop!
+        Put the URL to the 'release notes' (i.e.
+        http://oss.software.ibm.com/icu/download/(version)/ ) in the changes
+        list.
+    *   tar/gz, zip: Put the FULL URLs to the actual files, here
+    *   Changelog: Leave BLANK. This is for a single page of ALL release changes
+        (Actually: http://oss.software.ibm.com/icu/download/ fits this fairly
+        well.)
+    *   License - leave at MIT/X
+    *   mailing list: I set this to the main mailing list page.
+        (http://oss.software.ibm.com/icu/archives/)
+    Click 'go on..'
+8.  PREVIEW.
+    Very important- Check:
+    *   SPELLING
+    *   links!!!!! Make sure they go where we want
+    *   accuracy - version number is OK?
+    Remember that this is an important PR face for ICU4C and ICU4J.
+9.  Submit!
+
+That's it. Submissions take some time (<24 hrs) to go on. I guess they check the
+accuracy as well- not sure here. (Steven Loomis, 2001-06-14)
+
+**Other sites**:
+
+[slashdot](http://slashdot.org/), [newsforge](http://newsforge.com/),
+[developerWorks unicode zone](http://www.ibm.com/developerworks/unicode/),
+[developerWorks open-source
+zone](http://www.ibm.com/developerworks/opensource/), [developerWorks java
+zone](http://www.ibm.com/developerworks/java/) (send email to `dWnews <at>
+us.ibm.com`)
+
+[ICU sourceforge News](http://sourceforge.net/projects/icu) - login here, go to
+News, Admin, and submit a news item as an administrator.
+
+---
+
+#### LanguageTech Net News (tm)
+
+"LanguageTech Net News" features the latest news for language technology and
+multilingual computing. It is prepared from materials compiled and maintained by
+the research editors at "[MultiLingual Computing &
+Technology](http://www.multilingual.com/)" and the Language Technology Research
+Center.
+
+Press releases and submissions are always welcomed and encouraged. Please send
+e-mail to [news@multilingual.com](mailto:news@multilingual.com), faxes to
+208-263-6310 and postal mail to MultiLingual Computing, Inc., 319 North First
+Avenue, Sandpoint, ID 83864 USA, or call 208-263-8178.
+
+To view archived issues of "LanguageTech Net News" visit
+<http://www.multilingual.com/>.
+
+To subscribe to "LanguageTech Net News" go to
+<http://www.multilingual.com/multilingualpress/> or send an e-mail to
+[news-l-subscribe@multilingual.com](mailto:news-l-subscribe@multilingual.com).

docs/processes/release/tasks/build.md

@@ -0,0 +1,115 @@
+---
+layout: default
+title: Build Updates
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 30
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Build Updates
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Regenerate configure
+
+Don't forget to re-run and check in the configure file along with configure.in.
+This is normally supposed to be done when configure.in or aclocal.m4 are
+modified. It also should be done whenever the version numbers change in
+**uvernum.h**
+
+On a Linux system,
+
+```sh
+cd icu4c/source
+autoconf
+```
+
+Review the changes to configure, most commonly just an updated ICU version
+number. Sometimes there are differences due to different versions of the
+autoconf tool being used.
+
+## Update urename.h
+
+Update urename.h to catch all possible ICU4C library exports (especially on
+non-Windows systems that tend to ignore export qualifiers). See
+[icu4c/source/tools/genren/README](https://github.com/unicode-org/icu/blob/main/icu4c/source/tools/genren/README).
+
+Diff the new one with the previous one; there are typically a few bad #defines
+in there.
+
+You are looking to make sure that the defines all are correct exported symbols
+and that the Perl script hasn't inadvertently grabbed extraneous text. Each of
+the defines should be of the format "uxxxx_NamingConvention". If not then you
+need to determine if it's a script issue or a poorly named method.
+
+Also, please look out for this type of message: "\***\*\* WARNING Bad namespace
+(not 'icu') on ShoeSize::ShoeSize()**" - it probably means that there is a class
+not defined inside the "icu" namespace. Consider adding **U_NAMESPACE_BEGIN**
+and **U_NAMESPACE_END** around the class and member definitions.
+
+## Update the pool bundles
+
+*Obsolete for ICU 64+*: The pool bundles are no longer checked in. Instead,
+they are built on the fly. (And smaller if the data is filtered.)
+
+The locale data resource bundles use pool.res bundles (one per bundle tree) for
+sharing most of their resource table key strings. We should update the pool
+bundles once per release, or when we get new data from CLDR, or change the tree
+or key structure, to capture the changing set of key strings.
+
+1.  Build ICU4C
+2.  Check the date and size of the old pool bundles, for comparison later
+    1.  `~/icu/mine/src$ find icu4c -name 'pool.res' -exec ls -l '{}' \;`
+3.  Temporarily modify the data makefile: s/usePoolBundle/writePoolBundle/
+    1.  If you are not on Windows, you probably need to make other changes to
+        the Makefile as well. See
+        [ICU-8101](https://unicode-org.atlassian.net/browse/ICU-8101) (contains
+        a data/Makefile patch; use the latest version there)
+    2.  I like to make a copy the Makefile, then change it, save that for
+        possible reuse, and later copy the original back.
+    3.  Try to patch it in rather than redoing it manually:
+        `~/icu/mine/bld/icu4c/data$ patch -p0 <
+        ~/Downloads/Makefile-writePoolBundle.patch`
+4.  Rebuild the data (make sure it actually gets rebuilt: cd data, make clean,
+    make)
+5.  Copy all of the pool.res files like this
+    1.  Linux ICU 63, from inside the build output's data directory:
+    2.  ICUDT=icudt63l
+    3.  cp out/build/$ICUDT/pool.res ../../../src/icu4c/source/data/locales
+    4.  cp out/build/$ICUDT/lang/pool.res ../../../src/icu4c/source/data/lang
+    5.  cp out/build/$ICUDT/region/pool.res
+        ../../../src/icu4c/source/data/region
+    6.  cp out/build/$ICUDT/zone/pool.res ../../../src/icu4c/source/data/zone
+    7.  cp out/build/$ICUDT/curr/pool.res ../../../src/icu4c/source/data/curr
+    8.  cp out/build/$ICUDT/unit/pool.res ../../../src/icu4c/source/data/unit
+6.  Double-check the date and size of the old pool bundles. Sizes are usually a
+    few % higher than before, due to increased CLDR data.
+7.  Revert the data makefile change (copy the original back, if you kept a copy)
+8.  Rebuild the data (make sure it actually gets rebuilt: make clean, make)
+9.  Build ICU4C & run tests
+10. Rebuild the ICU4J data .jar files
+    1.  See
+        [icu4c/source/data/icu4j-readme.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/icu4j-readme.txt)
+    2.  And/or see "update Java data files" in
+        [icu4c/source/data/unidata/changes.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt)
+
+If there are new bundle trees that should use pool.res files (like the "unit"
+tree in ICU 54 ticket
+[ICU-11092](https://unicode-org.atlassian.net/browse/ICU-11092)), then first
+modify the data makefiles (Windows and Linux) to add the new pool.res to the
+appropriate file lists and initially add --writePoolBundle which at the end also
+needs to be turned into --usePoolBundle. Or, simpler, initially copy (svn cp)
+the parent tree's pool bundle, and update it later (maybe during release task
+work).

docs/processes/release/tasks/copy-shared-tests.md

@@ -0,0 +1,24 @@
+---
+layout: default
+title: Copy Shared Tests
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 40
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Copy Shared Tests
+
+Certain tests are structured so that they can be shared between CLDR and ICU.
+That allows the tests to be run in CLDR earlier in the development process. The
+tests include:
+
+*   LocaleMatcherTest
+*   TransformTest (to be cleaned up)
+
+Copy all of these from CLDR to ICU, and sanity check the differences, then check
+in.

docs/processes/release/tasks/docs.md

@@ -0,0 +1,405 @@
+---
+layout: default
+title: APIs & Docs
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 20
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# APIs & Docs
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Update API status comments
+
+### ICU4C
+
+1.  **Note: for ICU4C 49m2 or later, will require Doxygen 1.7.5.1 or later (
+    see** [ICU-8862](https://unicode-org.atlassian.net/browse/ICU-8862) **).**
+    On Linux with debian style package management,
+
+    `sudo apt-get install doxygen`
+
+    Or, to install manually
+    1.  To update Doxygen, first [download binary or source release
+        here](http://doxygen.org/download.html#latestsrc)
+    2.  Unpack the release, and run something like<br>
+        "`configure --prefix /usr/local`" (to install into /usr/local/bin etc)<br>
+        (Note for the binary release, 'configure' just builds an installer.)
+    3.  Run "`make install`" with appropriate permission (perhaps
+        "`sudo make install`".)
+    4.  Verify that '`doxygen --version`' gives the correct number.
+
+2.  Update the API documentation in all header files (.h file) to have correct
+    @draft/@stable/@deprecated labels.
+3.  Update docmain.h
+4.  ./configure
+5.  make doc
+6.  Follow instructions in
+    [tools/release/java/readme.txt](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/main/tools/release/java/readme.txt)
+    to generate API status change report.
+7.  Make sure that ICU headers work with U_HIDE_DRAFT_API and other such
+    switches.
+8.  Verify that U_DRAFT and U_STABLE match the @draft and @stable tags (same for
+    other such pairs declaration macro vs. tag).
+    1.  For example, on Linux:
+    2.  grep --recursive --include="\*.h" --exclude-dir=".svn" -e "@deprecated"
+        -A 5 . > at-deprecated.txt
+    3.  grep --recursive --include="\*.h" --exclude-dir=".svn" -e "U_DEPRECATED"
+        -B 5 -A 1 . > u_deprecated.txt
+    4.  Do this for draft, deprecated, obsolete, internal.
+    5.  For @stable, we either verify by cleaning up all others or we need to
+        write a script.
+
+### ICU4J
+
+Update the API documentation to have correct @draft/@stable/@deprecated labels.
+See the [User Guide, ICU Architectural Design, ICU API
+compatibility](https://unicode-org.github.io/icu/userguide/icu/design#icu-api-compatibility).
+
+On ICU4J, run
+[com.ibm.icu.dev.tool.docs.CheckTags](https://github.com/unicode-org/icu/blob/main/icu4j/tools/build/src/com/ibm/icu/dev/tool/docs/CheckTags.java)
+(see file for instructions). This requires a JDK with javadoc available. The
+tool will need to change to reflect the release number to search for.
+
+To check the API status changes, run the ant target "apireport" to generate the
+report since the previous official release.
+
+Make sure **@internal APIs** are also marked as @deprecated:
+
+```
+* @internal
+* @deprecated This API is ICU internal only.
+@Deprecated
+```
+
+---
+
+## Promote draft APIs to stable
+
+APIs previously introduced as @draft are reviewed for every new release. The
+current policy is to keep @draft status at least in one release cycle. For
+example, a new @draft API introduced in ICU 60 will be kept @draft in ICU 61.
+Then the API will be reviewed by ICU technical committee before ICU 62 release
+and the API can be promoted to @stable status.
+
+### **ICU4C**
+
+Andy's method (from email 2019-sep-05):
+
+*   Creation of the promotion spreadsheet was done by hand. It's something of an
+    iterative process.
+*   Start by making a copy of the previous release spread sheet, to get the
+    format, and probable entries for older @draft items that are perpetually
+    being held back.
+*   Do the API promotion - search the sources for @draft, and make a best guess
+    at what to promote. Add entries to the spread sheet as you go. Note any
+    items you're not sure about.
+*   Run the API change report tool, see what looks inconsistent, fix up the
+    sources and rerun as needed. Deleted functions will first show up here, and
+    are added to the spread sheet.
+*   Cross-check the API change report and the spread sheet.
+*   The whole thing takes a bit of time to do.
+
+### **ICU4J**
+
+1.  Create a new GitHub branch.
+2.  Run next ant target: `$ ant draftAPIsTSV`
+3.  This **ant** target generates a tab-separated values file at
+    icu4j/out/draftAPIs.tsv.
+4.  Import the TSV file to Google spread sheet - for example, [ICU4J 61 Draft
+    API
+    Promotion](https://docs.google.com/spreadsheets/d/135RDyY6cWKBBvNuVE9ne8HfsItZu_CvLh47hKjr3UqM/edit#gid=1384666589).
+    *   Create the spreadsheet in the shared ***ICU Projects*** folder.
+5.  Review all APIs introduced in 2 releases ago or older. For example, 59 or
+    older for ICU 61 release.
+    *   Any API added 2 or more releases ago is a candidate for promotion.
+    *   Newer APIs should be left in @draft state.
+6.  Check each API entry has a corresponding approved API proposal. For example,
+    [ICU 59 API proposal
+    status](https://docs.google.com/document/d/12dHTG3e9WXb7C1Xdc2bcXE0BK8f6IoufoUAPcz4ZT2I/edit).
+    Note: An API proposal might have been created before the API proposal doc
+    version, so you may need to look at older version of API proposal status
+    doc.
+7.  Mark APIs proposed for promotion, and add note in the spread sheet.
+8.  Update API comments in ICU4J source code. In this case, @draft is replaced
+    with @stable (do not change ICU version, for example, "@draft ICU 59" will
+    be changed to "@stable ICU 59").
+9.  Run next ant target to generate an API change report html: `$ ant apireport`
+10. Review the report, sent the report file and the link of the spread sheet to
+    ICU technical committee members for review.
+11. Once ICU TC approves the proposed change, create a pull request (PR), wait
+    for review, and merge the branch into the main branch.
+
+---
+
+## Update the API Change Report
+
+### ICU4C
+
+This work is done in the root of icu4c:
+
+1.  Update the API documentation in all header files (.h file) to have correct
+    @draft/@stable/@deprecated/@obsolete labels.
+2.  Update docmain.h with additions or removals as needed.
+3.  `source/configure`
+4.  `make doc`
+5.  Follow instructions in
+    [tools/release/java/readme.txt](https://github.com/unicode-org/icu/blob/main/tools/release/java/readme.txt).
+
+### ICU4J
+
+This work is done in the root of icu4j:
+
+1.  Make sure JAVA_HOME is set to JDK 8. This report creation fails with JDK 11.
+    For example, in Linux:
+    *   `export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64`
+2.  Then run ant task "clean" and "apireport" at <icu4j_root>:
+    *   `ant clean apireport`
+3.  Above will produce API change report file
+    <code><icu4j_root>/<b>out</b>/icu4j_compare_xxx_yyy.html</code>
+4.  Make sure there are any new doc tag errors are reported. (As of ICU 4.4,
+    ArabicShaping constants do not have proper tags - otherwise, clean)
+5.  Copy generated report file to `<icu4j_root>/APIChangeReport.html` and check
+    it in.
+
+Once official release version is shipped, we need to keep API signature
+information file for next iteration. This is not done for milestone releases,
+only after the final official release.
+
+1.  Run ant task "gatherapi" at <icu4j_root>
+2.  Above will produce API signature information file
+    <icu4j_root>/out/icu4jxx.api2.gz
+3.  Copy icu4jxxapi2.gz to <icu4j_root>/tools/build and add it to the repository
+
+---
+
+## Check in API signature data file (ICU4J)
+
+Once APIs are frozen for a reference release, we should check in the API
+signature data file into the repository. The data file will be used for future
+API change report.
+
+1.  Run ant task "gatherapi" at <icu4j_root>
+2.  The output file icu4j<ver>.api3.gz is created in <icu4j_root>/out directory.
+3.  Copy the output .gz file to <icu4j_root>/tools directory and check in the
+    file to the repository.
+4.  You may delete very old versions of the API signature files. Keeping 10
+    versions to the latest should be good enough.
+
+Note: This task is only necessary for reference releases, because we won't
+change public APIs in maintenance releases. The API signature file for an ICU4J
+version is generated and checked into trunk just before ***maint-xx*** branch is
+created for the major version, so we can keep track of API changes in
+maintenance releases of the major version (A maintenance release should have no
+API changes although).
+
+---
+
+## Verify that @draft is surrounded by #ifndef U_HIDE_DRAFT_API etc
+
+In ICU4C, we want every (consecutive group of) `@draft` API to be surrounded by
+`#ifndef U_HIDE_DRAFT_API`. This allows users to `-DU_HIDE_DRAFT_API` to make
+sure they don't use unstable API.
+
+```
+#ifndef U_HIDE_DRAFT_API
+/** @draft ICU 51 */
+U_CAPI u_newFunction1();
+/** @draft ICU 51 */
+U_CAPI u_newFunction2();
+#endif  // U_HIDE_DRAFT_API
+```
+
+Same for `@deprecated` & <code>#ifndef U_HIDE_<b>DEPRECATED</b>_API</code> ..
+`#endif // U_HIDE_DEPRECATED_API`
+
+Same for `@internal` & <code>#ifndef U_HIDE_<b>INTERNAL</b>_API</code> ..
+`#endif // U_HIDE_INTERNAL_API`
+
+Same for `@system` & <code>#ifndef U_HIDE_<b>SYSTEM</b>_API</code> ..
+`#endif // U_HIDE_SYSTEM_API`
+
+Same for `@obsolete` & <code>#ifndef U_HIDE_<b>OBSOLETE</b>_API</code> ..
+`#endif // U_HIDE_OBSOLETE_API`
+
+### Caution
+
+*   We cannot #ifndef-guard virtual methods because that makes the vtable
+    incompatible.
+    *   // Cannot use #ifndef U_HIDE_DRAFT_API for the following draft method
+        since it is virtual.
+*   When you #ifndef-guard enum constants, normally the following unguarded ones
+    (e.g., a _COUNT or _LIMIT) should retain the same numeric values as if the
+    guard was absent.
+
+<span style="background-color:yellow">For more details (and cautions) see the
+Coding Guidelines section [C/C++ Hiding Un-@stable
+APIs](https://unicode-org.github.io/icu/userguide/dev/codingguidelines#cc-hiding-un-stable-apis).</span>
+
+### Task
+
+a) For each of these API status tags, for each API that is tagged with it,
+verify that the API is surrounded by the appropriate #ifndef..#endif.
+
+Note: It is best to not use one single guard for APIs with different ICU
+versions, since they will become stable and thus lose their guards at different
+times. Use one #ifndef..#endif guard per API status and ICU version.
+
+b) For each of these U_HIDE_..._API guards, verify that it only and exactly
+surrounds APIs with the corresponding status tag. In particular, make sure that
+U_HIDE_DRAFT_API does not surround (newly) @stable API.
+
+We don't have tools for this. <span style="background-color:yellow">One approach
+is to</span> use "grep" or similar on the public *common*, *i18n*, *io* header
+files. Use grep options like -A 3, -B 2 and -C 3 for context After, Before, and
+Around the matching line. <span style="background-color:yellow">A better
+approach if you have the tools available is to use a programming-oriented text
+editor that can do (a) powerful regex search across (b) multiple files in
+several specified directories, and (c) display the matched lines in context such
+that (d) they or their context can be edited in place; an example of such a tool
+on macOS is BBEdit. This permits a comprehensive search using an expression such
+as
+"(U_HIDE_\[A-Z_\]+)|(@draft)|(@deprecated)|(@obsolete)|(@system)|(@internal)|(@preview)"
+which permits relatively easy checking for correct enclosure of status tags in
+conditionals.</span>
+
+<span style="background-color:yellow">As part of this, you may need to run side
+searches, for example to verify that no conditionalized type, function or value
+is used by an unconditionalized portion of a header file.</span>
+
+<span style="background-color:yellow">There is no magic bullet; however you
+carry out this step, it will require several hours of going through the
+grep/regex results and manually checking for correct enclosure, checking that
+conditionalized values are not needed elsewhere, etc.</span>
+
+---
+
+## Update udraft.h, usystem.h, uintrnl.h, uobslete.h and udeprctd.h
+
+*Ignore this step for ICU49 and later. In ICU 49 and above, these header files
+and the gendraft/genheaders.pl tool are gone. (Ticket
+[ICU-8571](https://unicode-org.atlassian.net/browse/ICU-8571))*
+
+Instructions ***for ICU4C 4.8.x and earlier***:
+
+1.  make doc
+2.  `cd source/tools/gendraft ; make install-headers`
+3.  Double check the modified files in <icu>/source/common/unicode folder and
+    commit.
+
+---
+
+## Compare ICU4J APIs with JDK
+
+Run the ICU4J versus JDK API comparison tool against the target JDK (anything
+that will come out before our next release, basically) with the tool
+[com.ibm.icu.dev.tool.docs.ICUJDKCompare](https://github.com/unicode-org/icu/blob/main/icu4j/tools/build/src/com/ibm/icu/dev/tool/docs/ICUJDKCompare.java)
+and make sure ICU4J adequately covers the JDK API for the classes we replicate.
+
+---
+
+## Build API documentations
+
+### **ICU4C**
+
+Build the API documentation pages for the new release. Run Doxygen to create the
+javadoc files. Create icu4c-X_X_X-docs.zip
+
+**Note: for ICU4C 49m2 or later, requires Doxygen 1.7.5.1 or later ( see
+[ICU-8862](https://unicode-org.atlassian.net/browse/ICU-8862) )**
+
+#### Create the ICU4C docs zip file:
+
+1.  Go to .../icu4c/source
+2.  Generate the API document pages:<br>
+    `make doc-searchengine`
+3.  The generated API docs are in <path>/icu4c/source/doc/html/<br>
+    `cd <path>/icu4c/source/doc/html/`
+4.  Create a zip file, e.g.,<br>
+    `tar cvfz /tmp/icu4c641.tar.gz * # '641' needs to be replaced by the respective release label.`
+5.  ~~Upload this zip file to the GitHub release page. For the live API docs, see below.~~
+
+#### Create a PR for ICU4C docs using the docs zip file
+
+1.  Follow directions in [How to update ICU docs](https://unicode-org.github.io/icu-docs/HOWTO-Update.html)
+
+    a. First, bring the `main` branch of your icu-docs local copy up to date.
+
+    b. Create and switch to a feature branch based of the latest `main`.  Ex: `git checkout -b ICU-<TICKET-NUMBER>`.
+
+    c. Copy the zip file into your local copy of icu-docs into `apidoc/released/icu4c`
+    (or `apidoc/dev/icu4c` if not a release)
+
+    d. Unzip the file, replacing all documentation. Ex: `tar xvfz /tmp/icu4c641.tar.gz`
+
+    e. Remove the zip file
+
+    f. `git add .`
+
+    g. `git commit -m "ICU-<TICKET-NUMBER> Update ICU4C API reference docs for
+    XX.Y"`<br>
+    Example: [ICU-21546 Update ICU4C API reference docs for 69.1](https://github.com/unicode-org/icu-docs/pull/25)
+
+    h. `git push origin ICU-<TICKET-NUMBER>`
+
+    i. Create Pull Request from your personal github fork of icu-docs from your newly-pushed branch `ICU-<TICKET-NUMBER>` with a destination of
+    the `unicode-org/icu-docs` repo's `main` branch
+
+    j. Request review
+
+Note: This is also referenced below [Upload API documentations](docs.md#upload-api-documentations) for how to make the API docs public.
+
+### 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:
+
+```
+ant releaseDocs
+```
+
+#### Alternative method:
+
+**Note:** JCite must be installed for building ICU4J documentation:
+<https://icu.unicode.org/setup/java/ant#TOC-Building-ICU4J-API-Reference-Document-with-JCite>
+
+Use the release target
+
+```
+ant releaseVer
+```
+
+which generate all release files.
+
+*   Upload the output files including icu4j-docs.jar to the release page first,
+*   Then update the live API docs from the generated docs.jar.
+
+See [Upload API documentations](docs.md#upload-api-documentations) below for how to make the API docs public.
+
+### Upload API documentations
+
+See <https://unicode-org.github.io/icu-docs/HOWTO-Update.html> for instructions
+to upload to <https://unicode-org.github.io/icu-docs/>
+
+### Update the Readme.html for GA
+
+If there are any last second changes:
+
+*   Make sure to document especially items that affect software that is
+    currently compiled with the previous version of ICU.
+*   Update build/installation instructions as necessary.

docs/processes/release/tasks/healthy-code.md

@@ -0,0 +1,557 @@
+---
+layout: default
+title: Healthy Code
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 50
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Healthy Code
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Check for ClassID in new class hierarchies
+
+Check that there are no "poor man's RTTI" methods in new class hierarchies.
+
+After ICU 50: New class hierarchies should not declare getDynamicClassID() at
+all. UObject has a dummy implementation for it.
+
+ICU 4.6..50: New class hierarchies used UOBJECT_DEFINE_NO_RTTI_IMPLEMENTATION.
+See Normalizer2 for an example declaration and implementation that satisfies the
+virtual-function override without adding new ClassID support.
+
+We do need to keep and add "poor man's RTTI" in old classes, and in new classes
+extending existing class hierarchies (where parent classes have @stable RTTI
+functions). (For example, a new Format subclass.)
+
+One easy way to check for this is to search through the API change report and
+look for "UClassID" or similar.
+
+*   Latest trunk report:
+    [icu/icu4c/APIChangeReport.html](https://github.com/unicode-org/icu/blob/main/icu4c/APIChangeReport.html)
+*   ~~The automated build system creates a new report:
+    <https://cldr-build.unicode.org/jenkins/job/icu/job/icu-apidocs/>~~
+    *   Click "ICU4C API Change Report vs Latest"
+*   Old: was http://bugs.icu-project.org/trac/build/icu4cdocs
+    *   Go into the latest successful build, the report is an attachment there.
+    *   Download the style sheet next to it:
+        https://github.com/unicode-org/icu/blob/main/icu4c/icu4c.css
+
+---
+
+## ~~Check for non-ascii characters in ICU4C source files \[obsolete\]~~
+
+~~Note: ICU4C and ICU4J source files are UTF-8. The ASCII check is no longer
+appropriate for them.~~
+
+```sh
+cd icu4c/source
+find . \( -name "*.[ch]" -or -name "*.cpp" \) -exec grep -PHn [^[:ascii:]] {} \;
+```
+
+---
+
+## Check source files for valid UTF-8 and correct text file line endings
+
+Verify that all source and text files in the repository have plain LF line
+endings.
+
+To do this on Linux, In an up-to-date git workspace,
+
+```sh
+cd icu/icu4c/source
+tools/icu-file-utf8-check.py          # reports problems
+```
+
+The same python script from the icu4c tools will also check icu4j
+
+```sh
+cd icu/icu4j
+../icu4c/source/tools/icu-file-utf8-check.py
+```
+
+To double-check the line endings, the following grep will find all text files
+containing \\r characters. Do not run from Windows, where \\r\\n line endings
+are expected.
+
+```sh
+cd icu
+grep -rPIl "\r" *
+```
+
+Even when run from Mac or Linux, some WIndows specific files (.bat, etc) will be
+found by this check. This is OK.
+
+## ~~Check UTF-8 file properties \[obsolete\]~~
+
+*Note: As of ICU 63, the project moved from svn to GitHub. SVN file properties
+are no longer relevant.*
+
+<span style="color:red">**Note: As of ICU 59, ICU4C source files are UTF-8
+encoded, and have the svn mime-type property "text/plain;charset=utf-8". They
+must not have a BOM.**</span>
+
+This is checked by the above task, *Check svn properties, valid UTF-8 and text
+file line endings.*
+
+The bomfix.py script, formerly used for this task, must *not* be run over the
+ICU4C sources
+
+<span style="color:red">**~~Note: This task is only applicable to ICU4C. ICU4J
+.java source files are encoded by UTF-8, but must be without UTF-8
+BOM.~~**</span>
+
+~~Check that the following match: Files marked as UTF-8 vs. Files beginning with
+the UTF-8 signature byte sequence ("BOM").~~
+
+~~Run:~~
+
+<pre><code><s>cd {icu}/icu4c</s>
+<s>python ../tools/release/c/bomfix.py</s></code></pre>
+
+---
+
+## Clean up import statements
+
+The Eclipse IDE provides a feature which allow you to organize import statements
+for multiple files. Right click on projects/source folders/files, you can select
+\[Source\] - \[Organize Imports\] which resolve all wildcard imports and sort
+the import statements in a consistent order. (Note: You may experience OOM
+problem when your run this for projects/folders which contain many files. In
+this case, you may need to narrow a selection per iteration.)
+
+---
+
+## Check library dependencies
+
+***ICU 64+ (2019+): Done automatically by a build bot, at least in one of the
+two modes (debug/release), ok to skip as BRS task.***
+
+We want to keep dependencies between .c/.cpp/.o files reasonable, both between
+and inside ICU's libraries.
+
+On Linux, run
+[source/test/depstest/depstest.py](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/depstest/dependencies.py),
+for example:
+```sh
+~/icu/mine/src/icu4c/source/test/depstest$ ./depstest.py ~/icu/mine/dbg/icu4c
+```
+
+Do this twice: Once for a release build (optimized) and once for a debug build
+(unoptimized). They pull in slightly different sets of standard library symbols
+(see comments in dependencies.txt).
+
+If everything is fine, the test will print "OK: Specified and actual
+dependencies match." If not...
+
+*Get changes reviewed by others, including Markus; including changes in
+dependencies.txt, .py scripts, or ICU4C code.*
+
+At first, the test will likely complain about .o files not listed in its
+dependencies.txt or, if files were removed, the other way around. Try to add
+them to groups or create new groups as appropriate.
+
+As a rule, smaller groups with fewer dependencies are preferable. If public API
+(e.g., constructing a UnicodeString via conversion) is not needed inside ICU
+(e.g., unistr_cnv), make its library depend on its new group.
+
+If the test prints "Info: group icuplug does not need to depend on platform"
+then the plug-in code is disabled, as is the default since ICU 56. Consider
+enabling it for dependency checking, but make sure to revert that before you
+commit changes!
+
+There are usually other "Info" messages where the tool thinks that dependencies
+on system symbols are not needed. These are harmless, that is, don't try to
+remove them: They are needed or not needed based on the compiler flags used. If
+you remove them, then you will likely cause an error for someone with different
+flags. Also, in an unoptimized build you only get half as many info messages.
+You get more in an optimized build because more system stuff gets inlined.
+
+The test might complain "is this a new system symbol?" We should be careful
+about adding those. For example, we must not call printf() from library code,
+nor the global operator new.
+
+The test might complain that some .o file "imports
+`icu_48::UnicodeString::UnicodeString(const char *)` but does not depend on
+unistr_cnv.o". This probably means that someone passes a simple `"string literal"`
+or a `char *` into a function that takes a UnicodeString, which invokes the
+default-conversion constructor. We do not want that! In most cases, such code
+should be fixed. Only implementations
+of API that require conversion should depend on it; for example, group
+formattable_cnv depends on group unistr_cnv, but then nothing inside ICU depends
+on that.
+
+---
+
+## Verify proper memory allocation functions
+
+Verify the following for library code (common, i18n, layout, ustdio). The
+requirement is for ICU's memory management to be customizable by changing
+cmemory.h and the common base class.
+
+**Note:** The requirement remains. The techniques to fix issues are valid.
+***For testing**, see the section "Check library dependencies" above.*
+
+*   No raw malloc/free/realloc but their uprv_ versions.
+*   All C++ classes must inherit the common base class UObject or UMemory
+    *   But not for mixin/interface classes (pure virtual, no data members, no
+        constructors) because that would break the single-inheritance model.
+    *   Also not for pure-static classes (used for name scoping) declare but
+        don't implement a private default constructor to prevent instantiation.
+    *   Simple struct-like C++ classes (and structs) that do not have
+        constructors, destructors, and virtual methods, need not inherit the
+        base class but must then be allocated with uprv_malloc.
+*   All simple types (UChar, int32_t, pointers(!), ...) must be allocated with
+    uprv_malloc and released with uprv_free.
+*   For Testing that this is the case, on Linux
+    *   run the Perl script ICUMemCheck.pl. Follow the instructions in the
+        script. The script is in in the ICU4C sources at
+        source/tools/memcheck/ICUMemCheck.pl.
+    *   also, depstest.py will show an error message if the global operator new
+        is used (see section about checking dependencies)
+*   For testing that this is the case, on Windows:
+    *   Don't bother, as of Nov, 2004. Failures appear in many dozens of files
+        from the mixin class destructors. Do the check on Linux. But, for
+        reference, here are the old instructions.
+        *   Make sure that in `uobject.h` `UObject::new` and `delete` are
+            defined by default. Currently, this means to grep to see that
+            `U_OVERRIDE_CXX_ALLOCATION` is defined to 1 (in `pwin32.h` for
+            Windows).
+        *   Check the \*.obj's for linkage to the global (non-UObject::)
+            operators new/delete; see uobject.cpp for details.
+        *   Global `new` must never be imported. Global `delete` will be
+            imported and used by empty-virtual destructors in interface/mixin
+            classes. However, they are not called because implementation classes
+            always derive from UMemory. No other functions must use global
+            delete.
+        *   There are now (2002-dec-17) definitions in `utypes.h` for global
+            new/delete, with inline implementations that will always crash.
+            These global new/delete operators are only defined for code inside
+            the ICU4C libraries (but must be there for all of those). See ticket
+            #2581.
+        *   If a global new/delete is used somewhere, then change the class
+            inheritance and/or use uprv_malloc/free until no global new/delete
+            are used in the libraries (and the tests still pass...). See the
+            User Guide Coding Guidelines for details.
+
+---
+
+## Run static code analysis tools
+
+(Purify, Boundary Checker, valgrind...)
+
+Make sure we fixed all the memory leak problems that were discovered when
+running these tools.
+
+Build ICU with debug information. On Linux,
+
+```sh
+runConfigureICU --enable-debug --disable-release Linux
+```
+
+Run all of the standard tests under valgrind. For intltest, for example,
+
+```sh
+cd <where ever>/source/test/intltest
+LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH  valgrind  ./intltest
+```
+
+You can grab the command line for running the tests from the output from "make
+check", and then just insert "valgrind" before the executable.
+
+---
+
+## Check the code coverage numbers
+
+Our goal is that all releases go out to the public with 100% API test and at
+least 85% code coverage.
+
+---
+
+## Test ICU4C headers
+
+### Test ICU4C public headers
+
+Testing external dependencies in header files:
+
+(on Unixes) Prerequisite: Configure with --prefix
+(../icu4c/source/runConfigureICU Linux --prefix=/some/temp/folder) and do 'make
+install'. Then set the PATH so that the installed icu-config script can be
+found. (export PATH=/some/temp/folder/**bin**:$PATH)
+
+Then go to the 'icu4c/test/hdrtst' directory (note: not 'source/test/hdrtst')
+and do 'make check'. This will attempt to compile against each header file
+individually to make sure there aren't any problems. Output looks like this, if
+no error springs up all is in order.
+
+~~If a C++ file fails to compile as a C file, add it to the 'cxxfiles.txt'
+located in the hdrtst directory.~~
+
+<span style="color:red">**As of ICU 65, the hdrtst is now run as part of the
+regular CI builds, and the C++ headers are now guarded with the macro
+"U_SHOW_CPLUSPLUS_API".**</span>
+
+There is no longer any "cxxfiles.txt" file. Instead the public C++ headers are
+all guarded with the macro "U_SHOW_CPLUSPLUS_API" which is set to 1 by default
+if __cplusplus is defined. Users of ICU can explicitly set the macro before
+including any ICU headers if they wish to only use the C APIs. Any new public
+C++ header needs to be similarly guarded with the macro, though this should be
+caught in the CI builds for a pull-request before it is merged.
+
+Run this test with all the uconfig.h variations (see below).
+
+```sh
+ctest unicode/docmain.h
+ctest unicode/icudataver.h
+ctest unicode/icuplug.h
+```
+
+### Test ICU4C internal headers
+
+Run the following script straight from the source tree (from inside the "source"
+folder, not on the top level), no need to build nor install.
+
+For a new release, also look for new tools and tests and add their folders to
+the script. You can ignore messages stating that no '\*.h' files were found in a
+particular directory.
+
+The command line is simply
+
+```sh
+~/git.icu/icu4c/source$ test/hdrtst/testinternalheaders.sh
+```
+
+See https://unicode-org.atlassian.net/browse/ICU-12141 "every header file should
+include all other headers if it depends on definitions from them"
+
+<span style="color:red">**As of ICU 68, the internal header test is now
+automated as part of Travis CI.**</span>
+
+---
+
+## Test uconfig.h variations
+
+Test ICU completely, and run the header test (above) with:
+
+1.  **none** of the 'UCONFIG_NO_XXX' switches turned on (i.e., the normal case)
+2.  **all** of the 'UCONFIG_NO_XXX' switches turned on (set to 1)
+3.  For each switch, test once with **just** that one switch on. But note the
+    exception regarding [UCONFIG_NO_CONVERSION test](healthy-code.md) below.
+
+(See
+[common/unicode/uconfig.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/unicode/uconfig.h)
+for more documentation.)
+
+There is a script available which will automatically test ICU in this way on
+UNIXes, it lives in:
+[tools/release/c/uconfigtest.sh](https://github.com/unicode-org/icu/blob/main/tools/release/c/uconfigtest.sh).
+See docs at top of script for information.
+
+<span style="background-color:yellow">When guard conditionals (e.g. #ifndef
+U_HIDE_INTERNAL_API) are removed because they cause header test failures, please
+note in the header file the reason that guard conditionals cannot be used in
+that location, or they will lkeiely be re-added in the future.
+
+---
+
+## Test C++ Namespace Use
+
+Verify that ICU builds without enabling the default use of the ICU namespace. To
+test on Linux,
+
+```sh
+./runConfigureICU Linux CXXFLAGS="-DU_USING_ICU_NAMESPACE=0"
+make check
+```
+
+Any problems will show up as compilation errors.
+
+When definitions outside the ICU C++ namespace refer to ICU C++ classes, those
+need to be qualified with "`icu::`", as in "`icu::UnicodeString`". In rare
+cases, a C++ type is also visible in C code (e.g., ucol_imp.h has definitions
+that are visible to cintltst) and then we use `U_NAMESPACE_QUALIFIER` which is
+defined to be empty when compiling for C.
+
+The automated build system should have a machine that sets both
+`-DU_USING_ICU_NAMESPACE=0` and `-DU_CHARSET_IS_UTF8=1`.
+
+---
+
+## Test UCONFIG_NO_CONVERSION
+
+Make sure that the ICU4C common and i18n libraries build with
+UCONFIG_NO_CONVERSION set to 1. We cannot do this as part of "Test uconfig.h
+variations" because the test suites cannot be built like this, but the library
+code must support it.
+
+The simplest is to take an ICU4C workspace, modify uconfig.h *==temporarily==*
+by changing the value of UCONFIG_NO_CONVERSION to 1, and do "make -j 6" (not
+"make check" or "make tests"). Verify that the stubdata, common & i18n libraries
+build fine; layout should build too but toolutil will fail, that's expected.
+
+Fix any stubdata/common/i18n issues, revert the UCONFIG_NO_CONVERSION value, and
+verify that it still works with the normal setting.
+
+If this breaks, someone probably inadvertently uses the `UnicodeString(const char *)` constructor.
+See the "Check library dependencies" section.
+
+---
+
+## Test U_CHARSET_IS_UTF8
+
+Verify that ICU builds with default charset hardcoded to UTF-8. To test on
+Linux,
+
+```sh
+./runConfigureICU Linux CPPFLAGS="-DU_CHARSET_IS_UTF8=1"
+make -j6 check
+```
+
+Any problems will show up as compilation or test errors.
+
+Rather than setting the CPPFLAGS, you can also temporarily add `#define
+U_CHARSET_IS_UTF8 1` in unicode/platform.h before it gets its default
+definition, or modify the default definition there. (In ICU 4.8 and earlier,
+this flag was in unicode/utypes.h.)
+
+This works best on a machine that is set to use UTF-8 as its system charset,
+which is not possible on Windows.
+
+The automated build system should have a machine that sets both
+`-DU_USING_ICU_NAMESPACE=0` and `-DU_CHARSET_IS_UTF8=1`.
+
+---
+
+## Test U_OVERRIDE_CXX_ALLOCATION=0
+
+Verify that ICU builds with U_OVERRIDE_CXX_ALLOCATION=0 on Linux. Problems will
+show as build failures.
+
+```sh
+CPPFLAGS="-DU_OVERRIDE_CXX_ALLOCATION=0" ./runConfigureICU Linux
+make clean
+make -j12 check
+```
+
+## ~~Test ICU_USE_THREADS=0 \[Obsolete\]~~
+
+***Only necessary up to ICU4C 49.***
+
+*   ICU 50m1 removes ICU_USE_THREADS from the runtime code (ticket
+    [ICU-9010](https://unicode-org.atlassian.net/browse/ICU-9010)).
+*   It is still possible to build and test intltest with ICU_USE_THREADS=0 but
+    not nearly as important.
+*   In ICU 50m1, the `--disable-threads` configure option is gone. If you want
+    to test with ICU_USE_THREADS=0 then temporarily change this flag in
+    intltest.h or in the intltest Makefile.
+
+Verify that ICU builds and tests with threading disabled. To test on Linux,
+
+```sh
+./runConfigureICU Linux --disable-threads
+make check
+```
+
+---
+
+## Test ICU4C Samples and Demos
+
+To build the ICU4C samples on Windows with Visual Studio, use the following
+steps:
+
+*   Open the "allinone" solution file located under
+    "source\\allinone\\allinone.sln".
+*   Build the Debug/Release + x86/x64 configurations (all 4 configurations).
+    *   Make sure the generated data file (ex: "icu4c\\bin\\icudt64.dll") is not
+        stub data, it should be ~26MB.
+*   Open the "all" Solution file located under "source\\samples\\all\\all.sln".
+*   Build both x86 and x64 using the "Batch Build" option. This is located under
+    the menu Build > Batch Build.
+    *   Click the "Select All" button.
+    *   Click the "Build" button.
+    *   If Visual Studio returns errors using the Batch Build option, build each
+        configuration individually instead.
+*   The samples should all build cleanly with no errors.
+
+To test the sample programs, run the "source\\samples\\all\\samplecheck.bat"
+script for each configuration, and ensure that they are successful.
+
+## **Test ICU4C Demos via Docker**
+
+See <https://github.com/unicode-org/icu-demos/blob/main/icu-kube/README.md>
+
+---
+
+## **Test ICU4J Web Demos via Docker**
+
+See: <https://github.com/unicode-org/icu-demos/blob/main/icu4jweb/README.md>
+
+---
+
+## Test ICU4J Demos
+
+These are the demo applets, see above for the icu4jweb demos.
+
+To test ICU4J demo applications, cd to ICU4J directory and build and run the
+demo.
+
+```sh
+$ cd icu4j
+$ ant jarDemos
+$ java -jar icu4jdemos.jar
+```
+
+Above command invokes GUI demo applications. As such it has to connect to a
+X-Server. The easiest way is to run via e.g. remote desktop on the machine on
+which it is executed instead of in a ssh shell.
+
+The demos include calendar, charset detection, holidays, RBNF and
+transliterator. Check if each application is working OK.
+
+To check ICU4J samples, open Eclipse workspace and import icu4j-samples project
+from directory <icu4j_root>/samples. Make sure these sample code has no build
+issues. Also run sample code with main and see if each sample code runs.
+
+---
+
+## Test, exhaustive mode, C & J
+
+For ICU4J,
+
+```sh
+$ ant exhaustiveCheck
+```
+
+For ICU4C, testing with an optimized build will help reduce the elapsed time
+required for the tests to complete.
+
+```sh
+$ make -j6 check-exhaustive
+```
+
+---
+
+## Test ICU4C with the Thread Sanitizer
+
+The build bots run the thread sanitizer on the most interesting multithreaded
+tests. These instructions run the sanitizer on the entire test suite. The clang
+compiler is required.
+
+```sh
+$ CPPFLAGS=-fsanitize=thread LDFLAGS=-fsanitize=thread ./runConfigureICU --enable-debug --disable-release Linux --disable-renaming
+$ make clean
+$ make -j6 check
+```

docs/processes/release/tasks/index.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Release & Milestone Tasks
+parent: Contributors
+nav_order: 10
+has_children: true
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Release & Milestone Tasks

docs/processes/release/tasks/integration.md

@@ -0,0 +1,468 @@
+---
+layout: default
+title: Integration Tests
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 60
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Integration Tests
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Run ICU4J Locale Service Provider tests
+
+JDK 6 introduced the locale service provider interface. ICU4J release include a
+special jar file (icu4j-localespi.jar) implementing the locale service provider
+interface.
+
+The test case for the ICU4J locale service provider requires JRE 6 or later
+version. Otherwise, there is no extra settings except for the standard ant set
+up ( necessary. To run the test cases, use ant with the top-level build.xml with
+target "localespiCheck"
+
+```sh
+$ ant localespiCheck
+```
+
+You should get the output like below -
+
+```
+...
+build:
+
+_runLocalespiCheck:
+     [java] TestAll {
+     [java]   BreakIteratorTest {
+     [java]     TestGetInstance (7.581s) Passed
+     [java]     TestICUEquivalent (0.832s) Passed
+     [java]   } (8.669s) Passed
+     [java]   CollatorTest {
+     [java]     TestGetInstance (0.900s) Passed
+     [java]     TestICUEquivalent (0.040s) Passed
+     [java]   } (0.966s) Passed
+     [java]   CurrencyNameTest {
+     [java]     TestCurrencySymbols (2.682s) Passed
+     [java]   } (2.683s) Passed
+     [java]     DateFormatSymbolsTest {
+     [java]     TestGetInstance (0.348s) Passed
+     [java]     TestICUEquivalent (0.207s) Passed
+     [java]     TestNynorsk (0.000s) Passed
+     [java]     TestSetSymbols (0.071s) Passed
+     [java]   } (0.631s) Passed
+     [java]   DateFormatTest {
+     [java]     TestGetInstance (0.456s) Passed
+     [java]     TestICUEquivalent (0.113s) Passed
+     [java]     TestThaiDigit (0.000s) Passed
+     [java]   } (0.571s) Passed
+     [java]   DecimalFormatSymbolsTest {
+     [java]     TestGetInstance (0.098s) Passed
+     [java]     TestICUEquivalent (0.000s) Passed
+     [java]     TestSetSymbols (0.000s) Passed
+     [java]   } (0.099s) Passed
+     [java]   LocaleNameTest {
+     [java]     TestCountryNames (2.500s) Passed
+     [java]     TestLanguageNames (14.262s) Passed
+     [java]   TestVariantNames (8.638s) Passed
+     [java]   } (25.402s) Passed
+     [java]   NumberFormatTest {
+     [java]     TestGetInstance (0.266s) Passed
+     [java]     TestICUEquivalent (0.209s) Passed
+     [java]   } (0.475s) Passed
+     [java]   TimeZoneNameTest {
+     [java]     TestTimeZoneNames (17.766s) Passed
+     [java]   } (17.766s) Passed
+     [java] } (57.268s) Passed
+     [java]
+     [java] Test cases taking excessive time (>10s):
+     [java] TestAll/LocaleNameTest/TestLanguageNames (14.262s)
+     [java] TestAll/TimeZoneNameTest/TestTimeZoneNames (17.766s)
+     [java]
+
+BUILD SUCCESSFUL
+Total time: 1 minute 46 seconds
+```
+
+---
+
+## Run ICU4J Test cases with JDK TimeZone
+
+ICU4J provides an option to alter TimeZone implementation to use the JRE's own
+implementation. The test cases used for this is the regular ICU4J unit test
+suite, except forcing ICU4J to use JRE TimeZone by special system property -
+com.ibm.icu.util.TimeZone.DefaultTimeZoneType=JDK.
+
+To run the test, you have to apply the latest time zone patch from a JRE vendor,
+because some test cases are sensitive to actual time zone transitions. For
+Oracle JRE, you should go to the J2SE download page
+<http://www.oracle.com/technetwork/java/javase/downloads/index.html> and
+download the latest JDK DST Timezone Update Tool and apply the patch to your
+local JRE.
+
+To run the test case, you just need to invoke the ant target "jdktzCheck".
+
+```sh
+$ ant jdktzCheck
+```
+
+**Note:** You might not be able to get the update tool matching the tzdata
+version used by ICU. In this case, some test cases may reports failures.
+Unfortunately, you have to walk though the failures to see if they are expected
+or not manually in this case.
+
+---
+
+## Verify the Eclipse ICU4J plug-in
+
+1.  Make sure the Eclipse ICU4J plug-in binaries are successfully produced.
+2.  Run the ICU4J plug-in test cases.
+3.  Update license files, build version strings for the new release.
+
+---
+
+## Run Tests Without ICU Data
+
+### ICU4C
+
+ICU data should be removed, so that tests cannot access it. Both cintltst and
+intltest should be run with -w option and they should not crash. Every crash
+should be investigated and fixed.
+
+To do this, build and test normally, then replace the ICU data shared library
+with the stubdata library and run the tests again with the -w option.
+
+Using an in-source build on Linux:
+
+```sh
+cd icu4c/source
+./runConfigureICU Linux
+make -j2 check
+rm lib/libicudata.so*
+cp -P stubdata/libicudata.so* lib/
+cd test/intltest
+INTLTEST_OPTS=-w make check
+cd ../cintltst
+CINTLTST_OPTS=-w make check
+```
+
+For debugging (for example using gdb) you cannot use `make check`. You need
+to set the `LD_LIBRARY_PATH` for the lib folder and then run
+`./cintltst -w` or `./intltest -w` etc. in the debugger.
+Example (in-source build on Linux):
+```sh
+cd test/cintltst
+export LD_LIBRARY_PATH=../../lib:../../tools/ctestfw
+./cintltst -w
+```
+
+### ICU4J
+
+ICU4J has the test target for this, but does not work as designed for now. For
+now, this task is not required for ICU4J.
+
+---
+
+## Verify that ICU4C tests pass without collation rule strings
+
+***ICU4C 53 and later***
+
+Background: [ICU-10636](https://unicode-org.atlassian.net/browse/ICU-10636)
+
+### Rebuild ICU data without collation rule strings
+
+#### ICU 64+
+
+You need to configure ICU with a data filter config file that removes collation
+rule strings.
+
+The file syntax is nicer with hjson rather than json.
+
+```sh
+sudo apt install python3-pip
+pip3 install hjson
+```
+
+Use an `~/icu/coll-norules.hjson` config file like this:
+
+```
+{
+  resourceFilters: [
+    {
+      categories: [
+        coll_tree
+      ]
+      rules: [
+        -/UCARules
+        -/collations/*/Sequence
+      ]
+    }
+  ]
+}
+```
+
+Configure ICU using this file:
+
+```sh
+ICU_DATA_FILTER_FILE=~/icu/coll-norules.hjson ... runConfigureICU ...
+```
+
+Run "make clean" (or delete just the collation .res files), then test as below.
+
+#### ICU 54..63
+
+This should work: `make GENRBOPTS='-k --omitCollationRules'` (-k is --strict)
+
+For ICU 54..63, I went into the build output folder and did:
+
+```sh
+cd data
+ICUDT=icudt63l
+rm out/build/$ICUDT/coll/*.res
+make GENRBOPTS='-k --omitCollationRules'
+```
+
+If this does not work, then add this option to the configure'd data/Makefile,
+see ticket [ICU-10636](https://unicode-org.atlassian.net/browse/ICU-10636).
+
+### Run the tests with data-errors-as-warnings
+
+`INTLTEST_OPTS=-w CINTLTST_OPTS=-w make -j5 check`
+
+See that they pass, or fix them to pass. See ticket #10636 test code changes for
+examples.
+
+---
+
+## Test ICU4J with only little-endian ICU4C data
+
+*Only available since ICU 54.*
+
+#### With ICU 64 and later:
+
+*   Reconfigure ICU4C with
+    <code><b>ICU_DATA_BUILDTOOL_OPTS=--include_uni_core_data</b>
+    ./runConfigureICU Linux</code> or similar
+    *   Should be little-endian for coverage
+*   Clean and build ICU4C: `make -j6 check`
+*   Make a clean directory for testing
+    *   Find the .data file in the build output area, e.g.,
+        `icu4c/source/data/out/tmp/icudt64l.dat`
+    *   Create a temporary directory such as `mkdir -p /tmp/icu4j_data_test`
+    *   Copy the .`dat` file to the new directory.
+*   Build and test ICU4J without its own data: `ant clean && ant
+    -Dicu4c.data.path=/tmp/icu4j_data_test check`
+    *   The configuration option sets the `ICUConfig.properties` data path
+    *   Verify that all tests pass.
+    *   If you get very many test failures, double-check that you enabled
+        unicore data in the ICU4C build (see first step).
+
+#### With ICU 55 through ICU 63:
+
+*   Rebuild ICU4C with <code>make <b>INCLUDE_UNI_CORE_DATA=1</b> check</code> or
+    similar, and provide a path only for the .dat file.
+    *   Should be little-endian for coverage
+    *   Find the .data file in the build output area, e.g.,
+        `data/out/tmp/icudt59l.dat`
+    *   Create a temporary directory such as `mkdir -p
+        /tmp/icu/build/data/out/tmp`
+    *   Copy the .`dat` file to the new directory.
+*   Build and test ICU4J without its own data: `ant clean && ant
+    -Dicu4c.data.path=/tmp/icu/build/data/out/tmp check`
+    *   The configuration option sets the `ICUConfig.properties` data path
+    *   Verify that all tests pass.
+
+#### ICU 54 method:
+
+In `icu4j-core/src/com/ibm/icu/ICUConfig.properties` set
+`com.ibm.icu.impl.ICUBinary.dataPath` to a list of paths with all of the ICU4C
+data (should be little-endian for coverage), with a path to where the .dat file
+is and a path to the source/data/in files for data that is hardcoded in ICU4C
+and therefore not in the .dat file (e.g., uprops.icu).
+
+Change `com.ibm.icu.impl.ICUData.logBinaryDataFromInputStream` to `true`, maybe
+set a breakpoint where such a message is logged.
+
+Run all of the ICU4J tests, maybe in the debugger for the breakpoint, or look
+for logger output to the console.
+
+Revert your config changes.
+
+## Build and run testmap
+
+Build and run the source/test/testmap project. (There is currently no Windows
+project defined for it.)
+
+```sh
+$ cd <root of your ICU build tree>
+$ CONFIG_FILES=test/testmap/Makefile CONFIG_HEADERS= ./config.status
+$ cd test/testmap
+$ make check
+```
+
+---
+
+## Verify XLIFF conversion
+
+<span style="background-color:orange">**Note:** The following instruction does not work. Please read the comments with
+orange background. There are some issues in the current ICU XLIFF tools and the
+test case below. See the comments in
+[ticket ICU-6383](https://unicode-org.atlassian.net/browse/ICU-6383).</span>
+
+Instructions for verifying the XLIFF conversion tools.
+
+*   Convert icu/source/test/testdata/ra.txt to XLIFF
+
+    `genrb -s icu/source/test/testdata -d icu/source/test/testdata/ -x -l en ra.txt`
+
+    <span style="background-color:orange">-d icu/source/test/testdata/ overwrite
+    the existing ra.xlf. Specify another directory.</span>
+
+    <span style="background-color:orange">ra.txt has the top level item "ra",
+    which is supposed to be the content language. Thus, with -l en, you'll get a
+    warning - "The top level tag in the resource and language specified are not
+    the same. Please check the input." We should use "-l ra" here.</span>
+
+*   Verify that the ra.xlf produced is identical to the one in CVS HEAD (except
+    for generation date)
+
+    <span style="background-color:orange">If you use "-l ra" above, you'll get
+    <file .... source-language = "ra" .... />, which is different from ra.xlf in
+    the repository. Also, new line codes is broken for imported contents.</span>
+
+*   Convert icu/source/test/testdata/ra.xlf back to ICU format
+
+    `java -cp icu4j/classes com.ibm.icu.dev.tool.localeconverter.XLIFF2ICUConverter -d . -t ra ra.xlf`
+
+    <span style="background-color:orange">The option "-t ra" does not work,
+    because ra.xlf does not contain target language data. Use "-c ra"
+    instead.</span>
+
+*   Verify that the ra.txt produced is identical to the one in CVS HEAD (except
+    for generation date)
+
+    <span style="background-color:orange">You cannot expect the generated ra.txt
+    exactly matches the original one because of table item re-ordering, new line
+    code changes, and explicit resource types (e.g. "ra {" vs. "ra:table
+    {").</span>
+*   Go through the steps given in
+    <http://icu.sourceforge.net/docs/papers/localize_with_XLIFF_and_ICU.pdf>
+
+---
+
+## Test sample and demo programs
+
+Build and run all of the sample and demo apps that are included with ICU, on
+each of the reference platforms. A list of them is in the
+[readme](http://icu.sanjose.ibm.com/internal/checklist/icu-progs-list.html).
+Also see the build system.
+
+Another worthy test: Test suites and demos *from the previous release* should
+also compile and run with the libraries of the current release, at least when
+certain #defines are set (unless they test APIs that are deprecated and have
+been removed since)!
+
+---
+
+## Test data portability
+
+Test if the data portability (under common endianness & charset family) is ok.
+On the ICU build server, you would use the "Build from source .dat archive"
+option. When it's not available, you would do the following:
+
+1.  Build ICU4C on Win32.
+2.  Copy the icu/source/data/out/icudt<data_version>l.dat file into
+    icu/source/data/in
+3.  Delete non-essential directories from icu/source/data.
+4.  Package up a clean copy of ICU for a non-Windows machine, like Linux on x86.
+5.  Build ICU on the non-Windows machine from the newly created package.
+6.  Run all tests on that non-Windows machine.
+
+---
+
+## Run the environment tests
+
+Run
+[environmentTest.sh](https://github.com/unicode-org/icu/blob/main/tools/release/c/environmentTest.sh)
+on a Linux machine which has many (all possible?) POSIX locales installed. This
+test verifies that the ICU test suite will work regardless of a user's default
+locale and timezone. This test should be run on a fast machine with several CPU
+cores. This will take a long time to run. Here are the steps to run the test.
+
+1.  cd icu4c/source/
+2.  ./runConfigureICU Linux
+3.  make check
+4.  cd ../../tools/release/c/
+5.  ./environmentTest.sh
+6.  Wait a while for the tests to finish. The logs will be written in each test
+    directory. e.g. icu4c/source/test/intltest/intltest-\*.txt. A message will
+    be printed from each spawned test script when it finishes.
+7.  grep the logs for any test failures when the tests are done.
+
+---
+
+## Run Thread Sanitizer tests
+
+Thread sanitizer testing is one of the standard Travis builds. If it is passing
+there, nothing further is required.
+
+To run manually, on a Linux system with clang,
+
+```sh
+cd icu4c/source
+CPPFLAGS=-fsanitize=thread LDFLAGS=-fsanitize=thread ./runConfigureICU --enable-debug --disable-release Linux
+make clean
+make -j6 check
+```
+
+Errors are displayed at the point they occur, and stop further testing.
+
+---
+
+## Run Address Sanitizer tests
+
+Address sanitizer testing is included in the standard Linux with Clang Travis
+builds. If it is passing there, nothing further is required.
+
+To run manually, on a Linux system with clang,
+
+```sh
+cd icu4c/source
+CPPFLAGS=-fsanitize=address LDFLAGS=-fsanitize=address ./runConfigureICU --enable-debug --disable-release Linux
+make clean
+make -j6 check
+```
+
+Memory leaks are summarized at the end. Other errors are displayed at the point
+they occur, and stop further testing.
+
+---
+
+## ICU4J Serialization Compatibility Test Data
+
+The regular ICU4J unit test includes serialization compatibility tests. The test
+case creates an ICU service object from serialized data created by a former
+version of ICU. When we prepare a new release, the serialization compatibility
+test data should be created and checked in for future testing. This task is
+usually done just before publishing release candidate.
+
+1.  Run regular ICU4J unit tests - `ant check`
+2.  Make sure the unit tests pass successfully.
+3.  Run - `ant serialTestData`
+4.  Copy a folder with ICU version (e.g. ICU_61.1) generated under <icu4j
+    root>/out/serialTestData to <icu4j
+    root>/main/tests/core/src/com/ibm/icu/dev/test/serializable/data.
+5.  You may delete older serialization test data from the directory (but keep
+    the oldest one - ICU_3.6).
+6.  Run `ant check` again before committing the changes.

docs/processes/release/tasks/legal/find_textfiles

@@ -0,0 +1,131 @@
+#!/usr/bin/perl -w 
+#
+# Copyright (C) 2012, 2017: Unicode, Inc. and others.
+# License & terms of use: http://www.unicode.org/copyright.html
+#
+#####################################################################
+# Name          : find_textfiles                                    #
+# Full path     : /home/umesh/bin/find_textfiles                    #
+# Type          : Perl Script. Needs Perl 5.                        #
+# Description   : Finds the text files under a directory            #
+#                 Prunes CVS directories if -nocvs is provided      #
+#                 Prunes RCS directories if -norcs is provided      #
+#                 Prunes SCCS directories if -nosccs is provided    #
+# Author        : Umesh Nair (umesh@google.com)                     #
+#                                                                   #
+#-------------------------------------------------------------------#
+# Maintenance Block:                                                #
+# Date            Changed by        Description                     #
+# ----            ----------        -----------                     #
+# May 2000        Umesh Nair        Initial version of the script   #
+# Mar 2002        Umesh Nair        Added -h option                 #
+# May 2008        Umesh Nair        Added -nosvn and -novc          #
+#                                                                   #
+#####################################################################
+
+use strict;
+use File::Find;
+
+my ($skipCvs, $skipRcs, $skipSccs, $skipSvn, $skipVc, $skipEclipse) = (0, 0, 0, 0, 0);
+my $help = 0;
+
+while ((defined $ARGV[0]) and ($ARGV[0] =~ /\A\-/)) {
+   my $option = shift;
+   chomp $option;
+   ($skipCvs = 1) if ($option =~ /nocvs/);
+   ($skipSccs = 1) if ($option =~ /nosccs/);
+   ($skipSvn = 1) if ($option =~ /nosvn/);
+   ($skipVc = 1) if ($option =~ /novc/);
+   ($skipEclipse = 1) if ($option =~ /noeclipse/);
+   ($help = 1) if ($option =~ /h/);
+}
+
+if ($help) {
+    exec "pod2man $0 | nroff -man |". ($ENV{"PAGER"} || 'more -s');
+}
+
+if (@ARGV == 0) {
+   find (\&wanted, '.');
+} else {
+   find (\&wanted, @ARGV);
+}
+
+sub wanted {
+  unless (($skipVc and (/\.vcproj$/ or /\.vcxproj$/ or /\.sln$/ or /\.dsp$/ or /\.dsw$/ or /\.filters$/))
+    or ($skipEclipse and (/\.project$/ or /\.classpath$/ or /\.prefs$/ or /\.launch$/))) {
+    print "$File::Find::name\n" if (-f and -T );
+  }
+  ($File::Find::prune = 1) 
+    if (
+        ($skipCvs and /^CVS$/) or
+        ($skipRcs and /^RCS$/) or
+        ($skipSccs and /^SCCS$/) or
+        ($skipSvn and /^\.svn$/) 
+       );
+}
+
+__END__
+
+=head1 NAME
+
+find_textfiles - Finds the text files under a directory
+
+=head1 SYNOPSIS
+
+find_textfiles [C<-nocvs>] [C<-norcs>] [C<-nosccs>]  [C<-nosvn>]  [C<-novc>] [C<-noeclipse>] [ dir1 [ dir2 ] .... ]
+
+find_textfiles [C<-h>]
+
+=head1 DESCRIPTION
+
+This script recursively searches the specified directories (current
+directory if no parameter is passed) for text files, and lists the
+filenames on the standard output, one file per line.
+
+The directories named 'CVS', 'RCS' and 'SCCS' may be skipped by
+specifying the switches -nocvs, -norcs and -nosccs respectively.
+
+=head1 OPTIONS
+
+=over 4
+
+=item C<-h> 
+
+Displays this help document.
+
+=item C<-nocvs>
+
+Prunes all directories named 'CVS' and everything under that.
+
+=item C<-norcs>
+
+Prunes all directories named 'RCS' and everything under that.
+
+=item C<-nosccs>
+
+Prunes all directories named 'SCCS' and everything under that.
+
+=item C<-nosvn>
+
+Prunes all directories named '.svn' and everything under that.
+
+=item C<-novc>
+
+Excludes all VC++ files, i.e., *.vcproj, *vcxproj, *.dsw, *.dsp, *.filters.
+
+=item C<-noeclipse>
+
+Excludes all Eclipse files, i.e., .project, .classpath, *.prefs, *.launch.
+
+=back
+
+=head1 SEE ALSO
+
+find_binaries
+
+=head1 AUTHOR
+
+Umesh Nair, 2000.
+
+=cut
+

docs/processes/release/tasks/legal/index.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Legalities
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 70
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Legalities
+
+## 1. Scan for Copyright notices
+
+Check source and data files, especially newly contributed ones, to make sure the
+proper copyright notice is in place. For example,
+
+```
+© 2016 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html#License
+```
+
+Scan the source code to make sure that every file that was touched recently has
+the current year in the copyright statement. See the [ICU Copyright
+Scanner](../../../copyright-scan.md) page and follow the link to the scripts and
+the readme.
+
+Scan the source code to include third-party company names in copyright notices
+if necessary.
+
+~~Scan for text files that do not contain the word "Copyright": find_textfiles
+-nosvn -novc -noeclipse | xargs grep -i -L Copyright (See the find_textfiles
+Perl script attached to this page.) There are files without word "Copyright" in
+ICU source repository including some test data files (no comment syntax defined
+for these test data files), Unicode data files, tzcode source files and others.
+Review the output file list and determine if each of them should have ICU
+copyright statement or not.~~ ***The script [find_textfiles](find_textfiles)
+associated with this document is not maintained. Use the ICU Copyright Scanner
+above instead.***
+
+## 2. Update license files
+
+Check ICU, Unicode and other license terms. Make sure these files are up to
+date. The [Unicode data and software license
+term](http://www.unicode.org/copyright.html) is updated annually (usually year
+number only). The easiest way to get the updated license is to do View Source on
+unicode.org/copyright.html and scroll down to the plaintext version of the
+software license ("Exhibit A").
+
+See [svn changeset r39632](https://github.com/unicode-org/icu/commit/0001f6c5e92f6f3a8d66c7dbc47cc24df7633a71)
+for an example; there should be only two files to update.

docs/processes/release/tasks/miscellaneous.md

@@ -0,0 +1,110 @@
+---
+layout: default
+title: Miscellaneous
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 80
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Miscellaneous
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Complete code reviews
+
+Nag all the reviewers to finish reviewing the code and change the status of
+bugs.
+
+---
+
+## Check in serialization compatibility test data
+
+ICU4J unit test contains serialization compatibility test cases. When a new
+reference version is released, we build serialized object data with the version
+and use it for future testing.
+
+1.  Run "ant serialTestData" at ICU4J root directory
+2.  The target generates test data and runs some serialization test cases.
+3.  Once you confirm the test runs clean, copy
+    `out/serialTestData/ICU_<version>` to
+    `main/tests/core/src/com/ibm/icu/dev/test/serializable/data/ICU_<version>`.
+
+---
+
+## Release ticket
+
+After every milestone (GA / RC / Milestone-N) is completed, create a new release
+ticket in ICU Jira.
+The release ticket is used for BRS tasks, such as version update, tagging new version,
+merging post RC fixes from trunk and others.
+
+---
+
+## Check integrity of Jira issues in commit messages
+
+Every commit being shipped in the next ICU release should be labeled with a Jira
+ticket that is marked as fixed with the correct fix version. Further, there
+should be no Jira tickets marked as fixed with the current fixVersion that do
+not have commits. To check this, run the following tool:
+
+<https://github.com/unicode-org/icu/tree/main/tools/commit-checker>
+
+Follow the instructions in the README file to generate the report and send it
+for review.
+
+---
+
+## Fix Mis-ticketted commits
+
+If the commit checker tool above reports any malformed commit messages, it might
+mean that a bad commit made its way onto ICU main branch. To fix this, a rebase
+is required. Since rebases can be disruptive, confirm with ICU-TC before
+performing one. If ICU-TC agrees to perform a rebase, initiate the process as
+follows:
+
+$ git checkout main; git pull --ff-only upstream main
+
+$ git rebase -i --preserve-merges latest
+
+Note: although tempting, please do not use --committer-date-is--author-date. It
+changes the order of commits in ways we don't want to do.
+
+In the interactive rebase window, choose commit messages to rewrite using the
+"reword" option. Save and exit the interactive screen, and then edit each commit
+message.
+
+When ready, force-push the main branch to your fork and give ICU-TC a day or two
+to review. Before force-pushing to upstream, create a new branch on upstream
+with the latest commit on the old main branch; name it something like
+"pre63-old-main".  When ready, disable branch protection on main, force-push,
+and then reapply branch protection. Create a new branch named something like
+"pre63-new-main" to allow users to easily switch between the two heads.
+
+Send an email to icu-support explaining the change and how to deal with it. You
+can use [this email](https://sourceforge.net/p/icu/mailman/message/36426642/) as
+a model.
+
+---
+
+## Scrub closed issues in code
+
+(1) Search for "TODO(12345)" to detect TODO items for closed issues.
+
+(2) Do the same for logKnownIssue. (the data related logKnownIssues are often
+addressed during CLDR data integration)
+
+If the TODO or logKnownIssue references a closed issue, if the problem is fixed,
+remove the TODO/logKnownIssue, or if the problem is not fixed, open a new issue
+and update the reference in the code.

docs/processes/release/tasks/publish/index.md

@@ -0,0 +1,525 @@
+---
+layout: default
+title: Publish
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 90
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Publish
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Create a release branch in GitHub
+
+Once the branch is created, only changes necessary for the target release are
+merged in from the trunk.
+
+---
+
+## Upgrade LocaleExplorer and other demos/samples
+
+... to the ICU project site.
+
+Build the icuapps module following the README's. Update code and/or docs as
+needed. "Reference" platforms for icuapps are: RedHat Linux and win32. On Linux,
+icuapps is built against the "make install "'ed ICU. So, run ICU4C's configure
+with --prefix=/some/where pointing to where ICU4C should be installed, and also
+follow icuapps's README.
+
+Install the new locale explorer and other demos/samples onto the public demo
+hosting site.
+
+---
+
+## ICU Collation Demo
+
+Update the ICU collation demo's `index.html` with the new ICU version’s
+available collators.
+
+1.  Do a clean build (configure, make clean, make install, make check).
+    1.  Otherwise, the data build may not pick up a new locale into the
+        coll/res_index.txt file.
+2.  Run [icu-demos >
+    webdemo/collation/build.sh](https://github.com/unicode-org/icu-demos/blob/main/webdemo/collation/build.sh)
+    (after modifying it for your system).
+3.  Copy-paste the output `available-collators.txt` into `index.html`.
+    1.  Or, easier: Use a GUI difftool (e.g., meld) to compare the two and move
+        the changes into index.html.
+    2.  `meld webdemo/collation/index.html ../available-collators.txt`
+4.  See for example the changes for
+    [ICU-11355](https://unicode-org.atlassian.net/browse/ICU-11355)
+
+For details see the comments at the start of the build.sh file.
+
+---
+
+## Repository Branch and Tags
+
+⚠ Careful! The following examples contain specific version, revision and ticket
+numbers. Adjust them for the current release! Easiest: Paste into an editor,
+fix, then paste into the terminal.
+
+### Creating Maintenance Branch.
+
+Sanity check: Update to the latest repository revision. (Main branch if you
+copy from main, maintenance branch if you copy from there.)
+
+```sh
+git checkout main 
+git pull upstream main 
+git log -n1 
+commit bcd0... (HEAD -> main, upstream/main, ...)
+```
+
+Ensure that your local branch is in sync with the upstream branch. Make sure you
+are checking the upstream remote, and not your fork!
+
+Build & test ICU4C & ICU4J on your machine.
+
+Create the maintenance branch from the current known good main ref.
+
+```sh
+git checkout -b maint/maint-63 
+git push -u upstream maint/maint-63
+```
+
+#### Tagging
+
+Use the GitHub GUI to create both the "release" and the "tag" at the same time:
+
+<https://github.com/unicode-org/icu/releases/new>
+
+Fill in the tag name, such as "release-63-rc" or "release-63-1", and make the
+target the "maint/maint-xx" branch (such as maint/maint-63).
+
+Set the title to "ICU 63 RC" or "ICU 63.1". Fill in the description using the
+text from the announcement email. (You can also look at previous releases and
+possibly re-use some of the generic text, such as links to the API docs, etc.)
+
+Your screen should look like this:
+
+![image](maint-63-rc-screenshot.png)
+
+For the release candidate tag, please check the box that says "Pre-Release".
+
+We no longer need to add the note about Git LFS files, as GitHub now includes
+them in the auto-generated .zip downloads.
+
+Click the "Publish Release" button to make the tag.
+
+Note: The "latest" tag is no longer updated. It was agreed by the ICU-TC to be
+deleted around the 64.2 time-frame, as it doesn't work well with with Git. (You
+need to force-push the new tag, and if somebody has already cloned the
+repository, they might have something different for the "latest" tag).
+A possible future alternative might be a sym-link folder, or HTTP redirect that
+points to the latest release.
+
+#### Maintenance release
+
+Create the maintenance release tag from the maintenance branch, as above.
+
+Update the "latest" tag.
+
+### ~~ICU 58 and earlier~~
+
+~~Tag related svn files, for **icu**, **icu4j** and (for final releases)
+**tools** file trees. We tag the tools tree so that we can reproduce the Unicode
+tools that were used for the Unicode data files in this release.~~
+
+~~For a Release Candidate, just tag, don't branch, and only tag icu & icu4j.~~
+
+~~For the final release, branch then tag. Copy the trunk to maint/maint-4-8 and
+copy that to tags/release-4-8. Specify the source revision explicitly via -r so
+that you don't inadvertently pick up an unexpected changeset. Make sure that the
+trunk at the source revision is good.~~
+
+~~We do not tag the data & icuapps trees. Steven Loomis writes on 2011-may-23:~~
+
+> ~~My thought had been (in the CVS days) to take a 'snapshot' of these items.
+> However, in SVN all you need is a date or a revision number (such as
+> r30140).~~
+
+> ~~So, probably, we don't need to tag these two (icuapps or data).~~
+
+> ~~Tools are more important because those tools are actually used in the
+> release.~~
+
+### Create ICU download page
+
+Create the download page before the first milestone, if we have one, or before
+the release candidate.
+
+Log into the ICU homepage Google Site. (If you don't have write access, ask one
+of the editors to grant you access.)
+
+Verify that there is not already a page for the upcoming release: Either via the
+sitemap, or on the bottom of the main download page where it says something like
+"Subpages (27): View All".
+
+Copy the download page for the last release: Go to that page, gear menu, Copy
+page; "Name your page" using just the major version number for now (e.g., "61")
+so that the page URL is just that number, select "Put page under Downloading
+ICU", click the red COPY button.
+
+Adjust the new page as needed: Change the title to "Download ICU 61 Release
+Candidate" (with the right version number...), remove contents specific to the
+previous release, update all version numbers, update all links.
+
+Put a big, bold+italics, red warning at the top like "This version has not been
+released yet. Use it for testing but not in production!"
+
+Save the page. It is generally a good idea to save frequently. For further
+edits, simply go back into edit mode. (Keyboard shortcut 'e' for edit, ctrl+s
+for save.)
+
+Add new contents for the upcoming release: Grab some text from the sibling
+Unicode and CLDR release notes, look at the proposal status doc for this
+release, make a pass through the api/enhancement tickets fixed in this release
+or under reviewing/reviewfeedback.
+
+Look at the download pages of the last two releases for templates for things
+like a Migration Issues section etc.
+
+Ask everyone on the team to add stuff & details.
+
+**Once the page has been created and various people are invited to edit it,
+everyone should keep editing short so that the page is not locked for others for
+long periods of time.**
+
+### Maintenance release
+
+For a maintenance release, look at the ICU 60 page which includes 60.2.
+
+---
+
+## Milestone on the main download page
+
+We had the following HTML on the main download page for ICU 4.8M1 = 4.7.1:
+
+```html
+<h3 style="background-color:rgb(102, 102, 102);color:white;margin-bottom:0pt;margin-top:12pt;padding-left:0.75em;font-size:1em;font-family:Arial,Helvetica,sans-serif">Development Milestones</h3>
+<table border="0"><p style="font-size:10pt;font-family:Arial,Helvetica,sans-serif">Development milestone versions of ICU can be downloaded below. A development milestone is a stable snapshot build for next ICU major version.  These binaries and source code are provided for evaluation purpose and should be not be used in production environments.  New APIs or features in a milestone release might be changed or removed without notice.&nbsp;</p>
+<tbody>
+<tr>
+<td style="width:105px;height:16px">&nbsp;<b>Release</b></td>
+<td style="width:792px;height:16px">&nbsp;<b>Major Changes<br>
+</b></td>
+</tr>
+<tr>
+<td style="width:105px;height:29px">&nbsp;<a href="https://sites.google.com/site/icusite/download/471">4.8M1 (4.7.1)</a><br>
+</td>
+<td style="width:792px;height:29px">&nbsp;CLDR 1.9.1+, Parent locale override, Dictionary type trie, Alphabetic index (C), Compound text encoding (C), JDK7 Locale conversion (J)<br>
+</td>
+</tr>
+</tbody>
+</table>
+</span><br>
+```
+
+---
+
+## Upload Release Source / Binaries
+
+Download Directories are located at, for example,
+`icu-project.org:/home/htdocs/ex/files/icu4c/4.4.2`
+corresponding to <http://download.icu-project.org/ex/files/icu4c/4.4.2/>
+Look at previous releases for an example.
+
+### Java Source/Bin:
+
+Follow instructions here: [Building ICU4J Release Files](../release-build.md)
+
+### C source/binary:
+
+<span style="background:yellow">***WORK IN PROGRESS***</a>
+
+#### Source and Linux Binaries:
+
+Important: this step works with Unix make + docker.
+
+First, install *docker* and *docker-compose. D*o not proceed until *docker run
+hello-world* works!
+
+```sh
+$ git clone https://github.com/unicode-org/icu-docker.git
+$ cd icu-docker/src
+$ git clone --branch release-64-rc --depth 1 https://github.com/unicode-org/icu.git
+$ cd icu
+$ git lfs fetch
+$ git lfs checkout
+$ cd ../..
+$ less [README.md](https://github.com/unicode-org/icu-docker/blob/main/README.md)  # Follow these instructions.
+```
+
+*   Source and binaries are created in ./dist/.
+*   The names [don't match what's needed on
+    output](https://github.com/unicode-org/icu-docker/issues/1) so be sure to
+    rename.
+
+**Note:** If you only want to make a source tarball (.tgz/.zip), then you can
+run \`make dist\`.
+
+*   This will produce a source tarball and will include a pre-compiled .dat file
+    under icu4c/source/data/in/.
+*   Note: This tarball will also omit all of the data sub-directories containing
+    locale data.
+*   Note that the source is taken from the git repository itself, and not your
+    local checkout. (Thus it will exclude any local uncommitted changes).
+
+#### Windows Binary:
+
+*   Manual process:
+    *   Build with MSVC x64 Release. (See the ICU
+        [readme.html](https://github.com/unicode-org/icu/blob/main/icu4c/readme.html)
+        file for details).
+    *   Open a command prompt.
+        ```
+        cd C:\icu\icu4c\ (or wherever you have ICU located).
+        powershell
+        Set-ExecutionPolicy -Scope Process Unrestricted
+        .\packaging\distrelease.ps1 -arch x64
+        ```
+        This will produce the file "source\dist\icu-windows.zip", which will
+        need to be renamed before uploading.
+        *   For example, the binaries for ICU4C v61.1 generated with VS2017 were
+            named "icu4c-61_1-Win64-MSVC2017.zip".
+        *   Note: As of ICU 68, the pre-built binaries use MSVC2019 instead of
+            MSVC2017.
+*   Using the output from the build bots:
+    *   Navigate to the GitHub page for the commits on the
+        `maint/maint-<version>` branch.
+        *   Ex: https://github.com/unicode-org/icu/commits/maint/maint-64
+    *   Click on the green check mark (✔) on the most recent/last commit. (It
+        might be a red X if the builds failed, hopefully not).
+        *   This will open up a pop-up with links to various CI builds.
+    *   Click on one of the various links that says "Details" for the Azure CI
+        builds.
+        *   This will open up the GitHub overview of the build status.<br>
+            ![image](azure-ci-builds.png)<br>
+    *   Click on the link "View more details on Azure Pipelines" link.
+        *   This will take you to the actual Azure CI build page.
+    *   On the top right of the page there should be a button titled
+        "Artifacts". Click this and it should show a drop-down with various ZIP
+        files that you can download.<br>
+        ![image](azure-ci-builds-artifacts.png)<br>
+    *   The ZIP may automatically download for you.
+    *   However, if you are signed-in to visualstudio.com then you might see a
+        dialog titled "Artifacts explorer".
+    *   In this case click on the name, then the "..." button to download the
+        zip file.<br>
+        ![image](azure-ci-builds-artifacts-download.png)<br>
+    *   Download both the x64 (64-bit) and x86 (32-bit) ZIP files.
+    *   For each architecture:
+        *   Extract the Zip file. (It will have a name like
+            "20190829.6_ICU4C_MSVC_x64_Release.zip").
+        *   Navigate into the folder with the same name.
+        *   Rename the file "icu-windows.zip" to the appropriate name:
+            *   Ex: The x64 zip for version 64.1 was named
+                "icu4c-64_1-Win64-MSVC2017.zip"
+            *   Ex: The x86 zip for version 64.1 was named
+                "icu4c-64_1-Win32-MSVC2017.zip"
+            *   Note: Note: As of ICU 68, the pre-built binaries use MSVC2019
+                instead of MSVC2017.
+        *   Note: For RC releases the name looked like this:
+            "icu4c-64rc-Win64-MSVC2017.zip"
+*   ~~AIX Bin:~~ (AIX is broken and ignored for now.)
+    *   ~~login to gcc119.fsffrance.org and copy the ICU4C source archive
+        created above to there.~~
+    *   ~~$ gzip -dc icu4c-XXX-src.tgz | tar xf -~~
+    *   ~~$ cd icu~~
+    *   ~~$ PATH=/opt/IBM/xlC/13.1.3/bin:$PATH source/runConfigureICU AIX~~
+    *   ~~(The above command line doesn't actually work, see [ICU Ticket
+        ICU-13639](https://unicode-org.atlassian.net/browse/ICU-13639) for a
+        workaround.)~~
+    *   ~~$ gmake DESTDIR=/tmp/icu releaseDist~~
+    *   ~~That last step will create a directory in **/tmp/icu** - zip that up
+        to make the release.~~
+    *   ~~In case /tmp happens to be full, see the [mailing list
+        archive](https://sourceforge.net/p/icu/mailman/message/36275940/) for
+        advice.~~
+
+#### Output of icuexportdata:
+
+This step publishes pre-processed Unicode property data, which may be ingested by downstream clients such as ICU4X.
+
+*   Using the output from the build bots:
+    *   Navigate to the Azure Pipelines artifacts as described in the previous section
+    *   Download the files named *icuexportdata_uprops_full.zip* and *icuexportdata_uprops_sample.zip*
+
+### Signing archives and creating checksums:
+
+#### Step 1. PGP files:
+
+Sign all archives created above with your own personal PGP key. This creates a
+file with .asc as the suffix.
+
+```sh
+$ gpg --armor --detach-sign icu4c-xxx-xxx.zip
+# To verify
+$ gpg --verify icu4c-xxx-xxx.zip.asc
+```
+
+#### Step 2. MD5 files:
+
+Use md5sum or [cfv](http://cfv.sf.net) to create [md5](https://en.wikipedia.org/wiki/MD5) hash sums for three groups of files:
+
+*   icu4j (all files),
+*   icu4c (source),
+*   icu4c (binaries).
+
+Using md5sum to create and verify the checksum files:
+
+<pre><code><b><b>md5sum source1 source2 ... sourceN &gt; icu4c_sources.md5</b></b> # To verifymd5sum -c icu4c_sources.md5 
+</code></pre>
+
+Alternatively, use cfv to create and verify md5 files:
+
+```sh
+cfv -t md5 -C -f icu-……-src.md5 somefile.zip somefile.tgz …
+# To verify 
+cfv -f icu-……-src.md5
+```
+
+#### Step 3. SHASUM512.txt
+
+Create an additional hash sum file SHASUM512.txt file with:
+
+```sh
+shasum -a 512 *.zip *.tgz | tee SHASUM512.txt
+```
+
+This file should also be GPG signed. Check the .asc with \`gpg verify\`.
+
+### Update the Download Page Gadgets
+
+Update the gadgets on the download page to point at the new URL for the
+binaries.
+
+1.  Edit the download page.
+2.  Click on the Gadget area.
+3.  Click on the "gear" icon.
+4.  Update the URL field with the new URL.
+    1.  For example: The ICU4C 63.1 Binaries URL was:
+        <http://apps.icu-project.org/icu-jsp/downloadSection.jsp?ver=63.1&base=c&svn=release-63-1>
+
+#### Check the ICU public site for the new release
+
+Make sure that, aside from download pages, homepages, news items, feature lists
+and feature comparisons, etc. are updated. Upload the new API references. Update
+the User Guide.
+
+#### Update the Trac release number list for ICU4C and ICU4J. <<?? STILL VALID ??>>
+
+Update the ICU release number list by going to "Admin>Versions" in Trac, and add
+the new ICU version.
+
+#### Post-release cleanup
+
+*   Cleanup the milestone in the ICU Trac. Move left over items to future
+    milestones. Close the milestone.
+*   Look for TODO comments in the source code and file new tickets as required.
+*   Delete and retag
+    [latest](http://source.icu-project.org/repos/icu/tags/latest/) (**ONLY**
+    after GA release, including maintenance!) << IS THIS STILL VALID WITH GIT?
+    >>
+
+---
+
+## Update online demos
+
+Update online demos/tools to the latest version:
+
+*   ICU demos (eg <https://icu4c-demos.unicode.org/icu-bin/idnbrowser>)
+*   CLDR Survey tool (eg <http://unicode.org/cldr/apps/about.jsp>)
+*   Unicode Utilities (eg <http://unicode.org/cldr/utility/character.jsp>)
+
+### Online information update
+
+Collation and [comparison](../../../../charts/comparison/index.md) charts need
+to be updated. See [charts/Performance & Size](../../../../charts/index.md).
+
+### Old sensitive tickets
+
+Unset the "sensitive" flag on old tickets. For example, on tickets that were
+fixed two or more releases ago.
+
+[Sample ticket query for ICU 65, for tickets fixed in 63 or
+earlier](https://unicode-org.atlassian.net/issues/?jql=project%20%3D%20ICU%20AND%20Level%3DSensitive%20AND%20fixVersion%20not%20in%20(65.1%2C%2064.2%2C%2064.1)%20AND%20status%3DDone).
+Adjust the fixVersion selection as appropriate. Check the list in the ICU
+meeting.
+
+Check duplicates and fixedbyotherticket! Keep the "sensitive" flag on tickets
+that were closed as duplicates of other tickets that are not yet fixed or have
+been fixed only very recently.
+
+For removing the flag:
+
+*   Enter bulk edit. Select all query results.
+*   Uncheck duplicates of unfixed or too-recent tickets.
+*   Edit fields:
+    *   Security Level = None
+    *   Add label "was_sensitive"
+    *   No notification emails
+*   Confirm bulk edit.
+
+---
+
+## Punt tickets
+
+Double-check that tickets with commits in this release are closed/fixed. Close
+as needed. (Hopefully none misticketed at this point...)
+
+Then punt remaining tickets marked for this release:
+
+1.  In Jira, search for all tickets with Project=ICU, Fix Version=<this
+    release>, Status≠Done.
+2.  Go to Bulk Edit ("..." menu in the upper right corner)
+3.  Select all
+4.  Edit fields:
+    1.  Fix Version: replace all with "future"
+    2.  Labels: add "punt<this release>" (e.g., "punt63")
+    3.  No email notifications
+5.  Confirm bulk edit
+6.  Send a courtesy email to the team with a Jira query URL for the
+    Label="punt<this release>" tickets.
+
+After punting, please also update the "To-Do for Next ICU Release" widget on
+Jira.
+
+1.  Open <https://unicode-org.atlassian.net/issues/?filter=10007>
+2.  Use the drop-down to change the fix version to the next ICU version
+3.  Click "Save" next to the filter title
+
+## Update readme
+
+Update [ICU4C
+readme.html](https://github.com/unicode-org/icu/blob/main/icu4c/readme.html)
+and [ICU4J
+readme.html](https://github.com/unicode-org/icu/blob/main/icu4j/readme.html)
+before every milestone (GA / RC / Milestone-N). Make sure the following items
+are up to date.
+
+*   Release version
+*   Last update date
+*   Description - descriptions for GA, RC and Milesone-N are already included in
+    the readme file.
+    *   Comment/uncomment parts as appropriate.
+    *   If the readme should remain the same between milestones, we can skip
+        directly to the GA description. Otherwise, pick the right one for the
+        release type.
+    *   **Since ICU 67, we have skipped from GA to GA**, without marking &
+        unmarking the readme specifically for the release candidate.
+*   Build steps - make sure supported compiler versions are up to date

docs/processes/release/tasks/release-build.md

@@ -0,0 +1,213 @@
+---
+layout: default
+title: Release Build
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 100
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Release Build
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Building ICU4J Release Files
+
+<span style="color:red">*Note: This instruction is reviewed for ICU4J 69.1. Some
+description may not apply to previous ICU releases. ICU4J library (as of ICU 69)
+supports JRE 7 or later Java runtime environment. To avoid the Java's system
+library class's backward compatibility problem, ICU4J binary files must be
+compiled with Java system libraries from JRE 7.*</span>
+
+## Prerequisites
+
+*   Java SE Development Kit 8 (to run ant, javac, javadoc..)
+*   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
+
+*   Maven Ant Tasks 2.1.3 (GA only) \[<http://maven.apache.org/ant-tasks>\]
+    (Note: This is component is no longer maintained, and ICU project should
+    update the process in near future)
+*   gpg (GNU Privacy Guard)
+    *   ICU Project PGP key (icuintl@us.ibm.com - [published to MIT key
+        server](https://pgp.mit.edu/pks/lookup?op=vindex&search=0x44CE7BF2825EA2CD))
+*   Sonatype Nexus Repository Manager account for managing artifacts
+    com.ibm.icu.\* on OSSRH (Reference: [OSSRH
+    Guide](http://central.sonatype.org/pages/ossrh-guide.html))
+
+    <span style="color:red">*Note: Contact Yoshito for the PGP key and Sonatype
+    account.*</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.
+    *   `release.file.ver` is used as a part of build output file name.
+    *   `api.doc.version` is used for the API document title
+    *   `mavne.pom.ver` is used in pom.xml when release files are uploaded to
+        OSSRH
+
+        For ICU 69.1 GA, the contents of the properties file should be:
+        ```
+        api.report.version = 69
+        api.report.prev.version = 68
+        release.file.ver = 69_1
+        api.doc.version = 69.1
+        maven.pom.ver = 69.1
+        ```
+
+*   Create `build-local.properties` in the ICU4J root directory
+
+*   Edit `build-local.properties` to add a property - `java7.bootclasspath
+    (java6.bootclasspath for ICU57 to ICU62)`
+
+    The value of javaX.bootclasspath should include JRE's system library path. A
+    set of jar files included in the system library path may vary depending on
+    JRE vendor (Oracle, OpenJDK and IBM use different set of jars) and version.
+    The easiest way to get the system library path is to run a simple Java
+    program on the target JRE.
+
+        System.out.println(System.getProperty("sun.boot.class.path"));
+
+    For example, the values on my Linux system (Ubuntu) look like below:
+
+        java7.bootclasspath=/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/resources.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/rt.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/sunrsasign.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jsse.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jce.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/charsets.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jfr.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/classes
+
+    One Windows system, path separator back slash '\\' should be replaced with
+    forward slash '/'. For example:
+
+        java7.bootclasspath=C:/jdk/oracle/7u80/jre/lib/resources.jar;C:/jdk/oracle/7u80/jre/lib/rt.jar;C:/jdk/oracle/7u80/jre/lib/sunrsasign.jar;C:/jdk/oracle/7u80/jre/lib/jsse.jar;C:/jdk/oracle/7u80/jre/lib/jce.jar;C:/jdk/oracle/7u80/jre/lib/charsets.jar;C:/jdk/oracle/7u80/jre/lib/jfr.jar;C:/jdk/oracle/7u80/jre/classes
+
+### Additional Configuration for GA
+
+*   Add 2 more properties to `build-local.properties`
+    *   `maven-ant-tasks.jar` - Specify the path to the Maven Ant Tasks jar
+        file.
+    *   `gpg.user` - Specify the ICU Project PGP key user name
+
+    For example, build-local.properties look like below:
+
+    ```
+    java7.bootclasspath=/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/resources.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/rt.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/sunrsasign.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jsse.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jce.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/charsets.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/lib/jfr.jar:/home/yoshito/jdk/oracle/jdk1.7.0_80/jre/classes
+    maven-ant-tasks.jar = /home/yoshito/java-libs/maven-ant-tasks/maven-ant-tasks-2.1.3.jar
+    gpg.user = ICU Project
+    ```
+
+    <span style="color:red">*Note: Maven Ant Tasks is no longer maintained. ICU team should find out another method to publish ICU artifacts to the repository (ticket [ICU-12811](https://unicode-org.atlassian.net/browse/ICU-12811)).*</span>
+
+*   Create maven local setting file `$HOME/.m2/settings.xml` if absent. Then add
+    the Sonatype Nexus Repository Manager account information in the file. For
+    example:
+    ```xml
+    <settings>
+      <servers>
+        <server>
+          <id>icu4j-releases</id>
+          <username>yumaoka</username>
+          <password>OSSRH-SonaType-Password</password>
+        </server>
+        <server>
+          <id>icu4j-snapshots</id>
+          <username>yumaoka</username>
+          <password>OSSRH-SonaType-Password</password>
+        </server>
+      </servers>
+    </settings>
+    ```
+
+### Building Release Files for Milestones/Release Candidates
+
+1. Checkout tagged version - Use clean checkout of Git (SVN up to ICU62) tag
+   (e.g. release-61-0-1, release-61-rc..) for building release files.
+2. Run `$ ant releaseVer` - This build target generates ICU release files with
+   version number in a folder `release` under the ICU4J root directory.
+
+   This ant target prints out warning messages as below if the build system is
+   not properly configured.
+   ```
+   _verify_config_for_release:
+      [echo] ################################################################
+      [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
+   Total time: 5 minutes 31 seconds
+   ```
+   If you see such warnings at the end of build log, fix the issue and run the
+   target again.
+3. Upload all files generated under the `release` directory to the ICU site.
+
+## Building Release Files for Final Release (GA)
+
+A final (official) release files will be posted to the Maven Central Repository
+as well as the ICU project site. The build target `releaseFinal` generates all
+necessary files for the Maven repository and upload them after regular release
+build target is executed.
+1. Checkout tagged version - Use clean checkout of Git (SVN up to ICU62) tag
+   (e.g. release-61-1, release-61-2) for building release files.
+2. Run `$ ant releaseVer` once to make sure there are no build configuration
+   issues. Run `$ ant clean` to clean up build.
+3. \[Optional\] In the next step, the build target invokes gpg to generate
+   signature of build output files. gpg will request you to type in the
+   passphrase for the ICU Project (icuintl@us.ibm.com) PGP key once. gpg
+   pinentry is used for this purpose, but it may not work well on some systems
+   when pgp was invoked from ant (such as Mac OS X). If this is the case, you
+   would want to run gpg-agent to cache passphrase. More specifically, once you
+   set up gpg-agent, run `$ gpg -ab -u "ICU Project" foo.txt` to sign arbitrary
+   file. This operation will prompt you to type in the ICU Project key's
+   passphrase and cache it. So it does not need to ask you to type passphrase
+   again while running the ant release target.
+4. Run `$ ant releaseFinal` . This target generates release files for ICU site,
+   as well as files for Maven Central Repository, then upload the files to OSSRH
+   staging repository. You should see build log as below at the end.
+   ```
+      [deploy] Transferring 37K from icu4j-releases
+      [deploy] Uploaded 37K
+      [deploy] Uploading: com/ibm/icu/icu4j-localespi/61.1/icu4j-localespi-61.1-sources.jar.asc to repository icu4j-releases at https://oss.sonatype.org/service/local/staging/deploy/maven2
+      [deploy] Transferring 0K from icu4j-releases
+      [deploy] Uploaded 0K
+      [deploy] Uploading: com/ibm/icu/icu4j-localespi/61.1/icu4j-localespi-61.1-javadoc.jar to repository icu4j-releases at https://oss.sonatype.org/service/local/staging/deploy/maven2
+      [deploy] Transferring 22K from icu4j-releases
+      [deploy] Uploaded 22K
+      [deploy] Uploading: com/ibm/icu/icu4j-localespi/61.1/icu4j-localespi-61.1-javadoc.jar.asc to repository icu4j-releases at https://oss.sonatype.org/service/local/staging/deploy/maven2
+      [deploy] Transferring 0K from icu4j-releases
+      [deploy] Uploaded 0K
+
+   BUILD SUCCESSFUL
+   Total time: 6 minutes 19 seconds
+   ```
+   After the successful target execution, copy files generated under `release`
+   directory and upload them to ICU site.
+5. Log on to [OSSRH Nexus Repository Manager](https://oss.sonatype.org/). Select
+   "Staging Repositories" under "Build Promotion" on the left navigation pane,
+   then type "com.ibm.icu" on the search field on the upper right corner. You
+   should find a repository entry corresponding to the one just uploaded. Select
+   the entry, and sanity check content. Once you confirm the contents, click
+   "Close" on the menu. If the repository is closed successfully, you can
+   "Release" after that. The release operation will promote the staging
+   repository to production. It usually takes 20 to 30 minutes.
+
+![image](NexusRepoMan.png)

docs/processes/release/tasks/standards.md

@@ -0,0 +1,99 @@
+---
+layout: default
+title: Standards Update
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 110
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Standards Updates
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Time Zones
+
+Make sure the timezone (Olson) data is up to date.
+
+Olson timezone data should be regularly updated in the trunk. If the data is out
+of date, follow the instruction described in the
+[readme](https://github.com/unicode-org/icu-data/blob/main/tzdata/readme.txt)
+file.
+
+Once the timezone resource file is generated by the process above, the file
+should be checked into
+[zoneinfo64.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/misc/zoneinfo64.txt)
+in the trunk.
+
+## Unicode
+
+### Update Unicode Data
+
+See the [Unicode Update page](../../unicode-update.md) for an overview, and the
+[change log for Unicode updates](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt)
+for details.
+
+### Update script code enums
+
+Starting with ICU 55, we do not add UScriptCode constants for new scripts any more
+until they are encoded in Unicode,
+or can be assumed to be encoded in the next Unicode version.
+
+Script enum constant names want to follow the Unicode script property value aliases,
+which are assigned only when the scripts are encoded.
+When we encode scripts early and guess wrong, then we have confusing enum constants
+and have sometimes added aliases.
+
+Normally, we add script codes during the ICU update for a Unicode beta,
+at the same time as we add new API constants for new Unicode blocks and
+for new values of other supported properties.
+
+Variant script codes like Latf and Aran that are not subject to separate encoding
+can be added at any time.
+(For example, Aran could be added as USCRIPT_ARABIC_NASTALIQ.)
+
+We add script codes used in CLDR or in the spoof checker.
+This includes combination/alias codes like Hanb and Jamo.
+See https://unicode.org/reports/tr35/#unicode_script_subtag_validity
+and look for "alias" on https://unicode.org/iso15924/iso15924-codes.html
+
+We add special Z* script codes like Zsye.
+
+For new script codes see https://www.unicode.org/iso15924/codechanges.html
+Check for recent changes with the code highlighted in the left column and
+"Add" in the right column.
+
+Update script code enums with new codes from ISO 15924, send a notice for them
+as public API (born `@stable`) to the icu-design list.
+
+See details in the
+[change log for Unicode updates](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt).
+
+## CLDR
+
+### Sync ICU with CLDR and tag CLDR.
+
+Update ICU data from CLDR, tag CLDR. Instructions
+[here](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/cldr-icu-readme.txt).
+
+### Update MeasureUnit Code
+
+<https://github.com/unicode-org/icu/blob/main/docs/processes/release/tasks/updating-measure-unit.md>
+
+## ISO 4217 numeric codes
+
+Make sure the ISO 4217 numeric code mapping data is up to date.
+
+See the instruction in
+<https://github.com/unicode-org/icu/blob/main/tools/currency/readme.txt>

docs/processes/release/tasks/updating-measure-unit.md

@@ -0,0 +1,150 @@
+---
+layout: default
+title: Updating MeasureUnit with new CLDR data
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 120
+---
+
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Updating MeasureUnit with new CLDR data
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+This document explains how to update the C++ and Java version of the MeasureUnit
+class with new CLDR data.
+
+Code is generated by running MeasureUnitTest.java unit tests, which writes
+generated code to System.out. Two ways to access this:
+
+1. Within **eclipse**:
+   - Open MeasureUnitTest.java, run it by clicking on the green play button on
+     menu bar.
+   - Copy the generated code from the eclipse console to the clipboard.
+
+2. With **ant**:
+   - Run: `ant checkTest
+     -Dtestclass='com.ibm.icu.dev.test.format.MeasureUnitTest'`
+   - Open the checkTest output: `out/junit-results/checkTest/html/index.html`
+   - Navigate to "System.out" at the bottom of the MeasureUnitTest page to find
+     the generated code, and copy to the clipboard.
+
+After syncing CLDR data with ICU do the following. This documentation assumes
+that you are updating the MeasureUnit clases for ICU 68.
+
+* Check out
+  $GIT_ROOT/icu4j/main/tests/core/src/com/ibm/icu/dev/test/format/MeasureUnitTest.java
+* Open MeasureUnitTest.java.
+* Find the `testZZZ` test, its code should all be commented out. This test will
+  execute last and will run the desired code.
+
+    Make sure DRAFT_VERSIONS at top of MeasureUnitTest.java is set correctly.
+    These are the ICU versions that have draft methods.
+
+## Update MeasureUnit.java
+
+* Change `testZZZ` to run `generateConstants(“68”); // ICU 68.`
+* Run MeasureUnitTest.java, copy the generated code (see instructions above).
+* Open MeasureUnit.java:
+  $GIT_ROOT/icu4j/main/classes/core/src/com/ibm/icu/util/MeasureUnit.java
+* Look for line containing:
+
+  `// Start generated MeasureUnit constants`
+* Look for line containing:
+
+  `// End generated MeasureUnit constants`
+* Replace all the generated code in between with the contents of the clipboard
+* Run the MeasureUnitTest.java to ensure that the new code is backward
+  compatible. These compatibility tests are called something like
+  `TestCompatible65`, which tests backward compatibility with ICU 65.
+* Create a compatibility test for ICU 68. Change `testZZZ` to run
+  `generateBackwardCompatibilityTest(“68”)`
+* Run tests.
+* Copy generated test (see instructions above) into MeasureUnitTest.java
+* Run tests again to ensure that new code is backward compatible with itself
+
+## Update ICU4C
+
+* checkout ICU4C
+
+### Update measunit.h
+
+* Change testZZZ to run `generateCXXHConstants(“68”); // ICU 68`.
+* Run MeasureUnitTest.java, copy the generated code (see instructions above).
+* Open $GIT_ROOT/icu4c/source/i18n/unicode/measunit.h. Look for line containing:
+
+  `// Start generated createXXX methods`
+* Look for line:
+
+  `// End generated createXXX methods`
+* Replace all the generated code in between with the contents of the clipboard
+
+### Update measunit.cpp
+
+* Change testZZZ to run generateCXXConstants();
+* Run MeasureUnitTest.java, copy the generated code (see instructions above).
+* Open $GIT_ROOT/icu4c/source/i18n/measunit.cpp. Look for line containing:
+
+  `// Start generated code for measunit.cpp`
+* Look for lines
+
+  `// End generated code for measunit.cpp`
+* Replace all the generated code in between with the contents of the clipboard
+
+### Run C++ tests
+
+* Run `./intltest format/MeasureFormatTest` from `test/intltest` to ensure new
+  code is backward compatible.
+* Create a compatibility test for ICU 68. Change `testZZZ` in eclipse to run
+  `generateCXXBackwardCompatibilityTest(“68”)`
+* Run tests.
+* Copy generated test (see instructions above) into
+  $GIT_ROOT/icu4c/source/test/intltest/measfmttest.cpp. Make other necessary
+  changes to make test compile. You can find these changes by searching for
+  `TestCompatible65()`
+* Run tests again to ensure that new code is backward compatible with itself
+
+## Finishing changes
+
+These last changes are necessary to permanently record the ICU version number of
+any new measure units. Without these changes any new functions for this release
+will be considered new for the next release too.
+
+* Change `testZZZ` to run `updateJAVAVersions(“68”);`
+* Run MeasureUnitTest.java, copy the generated code (see instructions above).
+* Append the clipboard contents to the values of the JAVA_VERSIONS variable
+  near the top of MeasureUnitTest.java.
+
+  **Important:** what you are copying are just the new functions for the current
+  ICU version, in this case 68. Therefore append, do not replace.
+
+## Updating units.txt and unitConstants
+
+The standard ldml2icu process is used to update ICU's resource files (see
+[cldr-icu-readme.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/cldr-icu-readme.txt)).
+CLDR's units.xml defines conversion rates in terms of some constants defined in
+`unitConstants`.
+
+For efficiency and simplicity, ICU does not read `unitConstants` from the
+resource file. If any new constants are added, some code changes would be
+needed. This would be caught by `testUnitConstantFreshness` unit test in
+`units_test.cpp`.
+
+They are hard-coded:
+* Java: `UnitConverter.java` has the constant names in
+  `UnitConverter.Factor.addEntity()` and constant values in
+  `UnitConverter.Factor.getConversionRate()`.
+* C++: `units_converter.cpp` has the constant names in
+  `addSingleFactorConstant()`, with the constant values in `double
+  constantsValues[]` in the `units_converter.h` header file.

docs/processes/release/tasks/versions.md

@@ -0,0 +1,324 @@
+---
+layout: default
+title: Version Numbers
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 140
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Version Numbers
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## ICU Version Number
+
+For reference, see the section in the User Guide about Version numbers here:
+
+<https://unicode-org.github.io/icu/userguide/icu/design#version-numbers-in-icu>
+
+### ICU Version Number for Front load, RC and GA tasks
+
+The process of releasing a new ICU version (E.G. ICU 70.1) is divided in three phases:
+* Front loading tasks
+* Release Candidate (RC) tasks
+* General Availability (GA) tasks
+
+As of ICU 70, the ICU Version number changes for each of these tasks.
+
+When "front loading" tasks, the version number will consist of a Major number, Minor number, and a Patch number. 
+For example: ICU version 70.0.1
+
+For the RC and GA tasks, the ICU version number will consist of a Major number and a Minor number.
+For example: ICU version 70.1
+
+This means that when updating from the front load tasks to the RC tasks, files such as 
+[icu4c/source/common/unicode/uvernum.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/unicode/uvernum.h)
+need to be correspondingly updated. See below for more files to be updated and steps to be followed.
+
+
+### ICU Data
+
+[icu4c/source/data/misc/icuver.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/misc/icuver.txt)
+needs to be updated with the correct version number for ICU and its data.
+
+#### Since ICU 68
+
+In
+[tools/cldr/cldr-to-icu/build-icu-data.xml](https://github.com/unicode-org/icu/blob/main/tools/cldr/cldr-to-icu/build-icu-data.xml)
+edit `<property name="icuVersion" value="67.1.0.0"/>` and `<property
+name="icuDataVersion" value="67.1.0.0"/>`.
+
+The CLDR-to-ICU converter will then generate icuver.txt with the new version
+numbers.
+
+Run the converter, or coordinate with the person who will run it.
+
+#### Until ICU 67 (inclusive)
+
+Edit icuver.txt directly.
+
+### ICU4C
+
+1.  The instructions for updating the version number are in
+    [icu4c/source/common/unicode/uvernum.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/unicode/uvernum.h).
+2.  [icu4c/source/stubdata/stubdata.vcxproj](https://github.com/unicode-org/icu/blob/main/icu4c/source/stubdata/stubdata.vcxproj)
+    and
+    [icu4c/source/data/makedata.mak](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/makedata.mak)
+    may also need to updated with the correct version for icudt.
+3.  After uvernum.h is updated, the Windows project files should be updated by
+    running the UNIX makefile target '**update-windows-makefiles**' in
+    icu/source.
+    *   You will need to rerun "./configure" first though before you can run the
+        command "make update-windows-makefiles".
+    *   Note: You can use MSYS+MinGW to run the UNIX makefile on Windows
+        platforms as well.
+4.  As well, the ICU4C "configure" script should be updated so that it reflects
+    the latest version number.
+    *   Note: When updating the version number in the configure files be careful
+        not to just blindly search-and-replace the version number.
+        For example, there are lines like this: "As of ICU 62, both C and C++
+        files require them" which need to have the exact version number
+        retained.
+
+### ICU4J
+
+Since ICU4J 4.6, you can quickly check the current version information by
+running jar main in icu4j.jar. For example,
+
+```sh
+$ java -jar icu4j.jar
+```
+
+prints out -
+
+<pre>
+International Component for Unicode for Java 4.8
+Implementation Version: 4.8
+Unicode Data Version: 6.0
+CLDR Data Version: 2.0
+Time Zone Data Version: 2011g
+</pre>
+
+For updating ICU version numbers, follow the steps below.
+
+1. [icu4j/main/shared/build/common.properties](https://github.com/unicode-org/icu/blob/main/icu4j/main/shared/build/common.properties)
+
+    *   icu4j.spec.version: This is API spec version, therefore, 2-digit major
+        version only. The version number won't be changed for maintenance
+        releases. (e.g. "55")
+    *   icu4j.impl.version: This version is used for the actual release version,
+        including maintenance release numbers. (e.g. "55.1"). Note: We do not
+        use .0 - For example, ICU4J 54.1 uses "54.1", instead of "54.1.0" For
+        milestone 1, use <major>.0.1 (e.g. 60.0.1).
+    *   icu4j.data.version: This version number is corresponding to the data
+        structure, therefore, won't be changed in maintenance releases. Use
+        2-digit number used by the data path. (e.g. "55")
+    *   \[*Not applicable for ICU4J 60+*\] current.year: Some build script embed
+        the year taken from this into a copyright template. Make sure this value
+        is updated to the current year for a new release (also applicable to a
+        maintenance release).
+
+2. icu4j/build.properties (For API change report and release target)
+
+    *   api.report.version: 2 digit release number. Note: If necessary, we may
+        include maintenance release number. (e.g "54", "481")
+    *   api.report.prev.version: The previous version compared against the current
+        version. (e.g. "46")
+    *   release.file.ver: This string is used for files names. For milestone
+        releases, use <2-digit major version> + "m" + <milestone number>, e.g.
+        "55m1". For release candidate, use <2-digit major version> + "rc", e.g.
+        54rc. For official releases, use full version numbers using under bar as the
+        separator, e.g. "54_1", "54_1_1".
+    *   api.doc.version: The version displayed in API reference doc - use full
+        version number such as "60.1" for official and RC releases, "60 Milestone 1" for
+        milestone 1.
+    *   maven.pom.ver: The version used in ICU pom.xml files. Use full version
+        number such as "60.1" for official releases, "61.1-SNAPSHOT" until 61.1
+        release, after 60.1.
+
+3. [icu4j/main/classes/core/src/com/ibm/icu/util/VersionInfo.java](https://github.com/unicode-org/icu/blob/main/icu4j/main/classes/core/src/com/ibm/icu/util/VersionInfo.java)
+
+    There is a static block starting at line 501 (as of 54.1) in the source file -
+
+    <pre>
+    /**
+     * Initialize versions only after MAP_ has been created
+     */
+    static {
+        UNICODE_1_0 = getInstance(1, 0, 0, 0);
+        UNICODE_1_0_1 = getInstance(1, 0, 1, 0);
+        UNICODE_1_1_0 = getInstance(1, 1, 0, 0);
+        UNICODE_1_1_5 = getInstance(1, 1, 5, 0);
+        UNICODE_2_0 = getInstance(2, 0, 0, 0);
+        UNICODE_2_1_2 = getInstance(2, 1, 2, 0);
+        UNICODE_2_1_5 = getInstance(2, 1, 5, 0);
+        UNICODE_2_1_8 = getInstance(2, 1, 8, 0);
+        UNICODE_2_1_9 = getInstance(2, 1, 9, 0);
+        UNICODE_3_0 = getInstance(3, 0, 0, 0);
+        UNICODE_3_0_1 = getInstance(3, 0, 1, 0);
+        UNICODE_3_1_0 = getInstance(3, 1, 0, 0);
+        UNICODE_3_1_1 = getInstance(3, 1, 1, 0);
+        UNICODE_3_2 = getInstance(3, 2, 0, 0);
+        UNICODE_4_0 = getInstance(4, 0, 0, 0);
+        UNICODE_4_0_1 = getInstance(4, 0, 1, 0);
+        UNICODE_4_1 = getInstance(4, 1, 0, 0);
+        UNICODE_5_0 = getInstance(5, 0, 0, 0);
+        UNICODE_5_1 = getInstance(5, 1, 0, 0);
+        UNICODE_5_2 = getInstance(5, 2, 0, 0);
+        UNICODE_6_0 = getInstance(6, 0, 0, 0);
+        UNICODE_6_1 = getInstance(6, 1, 0, 0);
+        UNICODE_6_2 = getInstance(6, 2, 0, 0);
+        UNICODE_6_3 = getInstance(6, 3, 0, 0);
+        UNICODE_7_0 = getInstance(7, 0, 0, 0);
+    <b>
+        ICU_VERSION = getInstance(54, 1, 0, 0);
+        ICU_DATA_VERSION = ICU_VERSION;</b>
+        UNICODE_VERSION = UNICODE_7_0;
+
+        UCOL_RUNTIME_VERSION = getInstance(8);
+        UCOL_BUILDER_VERSION = getInstance(9);
+        UCOL_TAILORINGS_VERSION = getInstance(1);
+    }
+    </pre>
+
+    In the same file, starting at line 164 (as of 54.1) -
+
+    <pre>
+    /**
+     * Data version string for ICU's internal data.
+     * Used for appending to data path (e.g. icudt43b)
+     * @internal
+     * @deprecated This API is ICU internal only.
+     */
+    @Deprecated
+    public static final String <b>ICU_DATA_VERSION_PATH = "54b";</b>
+    </pre>
+
+4. [icu4j/pom.xml](http://source.icu-project.org/repos/icu/trunk/icu4j/pom.xml)
+    (before ICU4J 60 only)
+
+    <pre>
+    <groupId>com.ibm.icu</groupId>
+    <artifactId>icu4j</artifactId>
+    <version><b>55-SNAPSHOT</b></version>
+    <name>ICU4J</name>
+    </pre>
+
+    Only for the final release (including maintenance release), update the <version>
+    item to the actual release version (e.g. "54.1", "4.8.1") Otherwise, use (next
+    ver)-SNAPSHOT. (e.g. "55-SNAPSHOT").
+
+5. Time Bombs (before ICU4J 52)
+
+    ***Note: We no longer use time bombs since ICU4J 52. In the trunk,
+    logKnownIssue() is used for skipping known test failures. The new scheme no
+    longer depends on the current ICU4J version, so there are no updates
+    necessary in test codes when version number is updated. See [Skipping Known
+    Test Failures](../../../setup/eclipse/time.md) for more details.***
+
+    There might be some test cases intentionally skipped for the current ICU4J
+    version. When ICU4J version is updated, these time bombed test cases may
+    show up. In this case, you should:
+
+    *   Inform the list of failing test cases because of the version change to
+        icu-core ML - ask if someone has plan to fix them.
+    *   File a ticket if a time bomb does not have any corresponding Jira ticket
+        and put the ticket number as comment
+    *   Move the time bomb version to the next milestone.
+
+    The time bomb looks like below -
+
+    <pre>
+    if (<b>isICUVersionBefore(49, 1)</b>) { // ICU-6806
+        logln(showOrderComparison(uLocale, style1, style2, order1, order2));
+    } else {
+        errln(showOrderComparison(uLocale, style1, style2, order1, order2));
+    }
+    </pre>
+
+    Note: ICU4J time bomb - Before
+    [ICU-7973](https://unicode-org.atlassian.net/browse/ICU-7973), we used to
+    use skipIfBeforeICU(int,int,int).
+
+    When a test case with time bomb still fails before a major release, the time
+    bomb may be moved to the version before the first milestone of the next
+    major release stream. For example, the time bomb (49,1) is not yet resolved
+    before ICU4J 49 release, it should be updated to (50,0,1). This will prevent
+    the error test case showing up during 49 maintenance releases, and appear
+    before the first milestone of 50.0.1.
+
+6. ICU4J Eclipse plug-in version (Eclipse release only)
+
+   ICU4J Eclipse plug-in use the standard Eclipse versioning scheme -
+   X.Y.Z.v<build date>, for example, com.ibm.icu_4.2.1.v20100412.jar. By
+   default, the build script compose the version string from
+   icu4j.plugin.impl.version.string property in
+   [eclipse-build/build.properties](https://github.com/unicode-org/icu/blob/main/icu4j/eclipse-build/build.properties)
+   with current date at the build time. However, when we tag a version, we want
+   to freeze the build date part. To force a fixed version string, we add a
+   property - icu4j.eclipse.build.version.string in the build.properties. For
+   example, see
+   [tags/release-4-4-2-eclipse37-20110208/eclipse-build/build.properties](http://source.icu-project.org/repos/icu/tags/icu4j/release-4-4-2-eclipse37-20110208/eclipse-build/build.properties).
+
+7. [DebugUtilitiesData.java](https://github.com/unicode-org/icu/blob/main/icu4j/main/tests/core/src/com/ibm/icu/dev/test/util/DebugUtilities.java)
+
+    This file is automatically generated when data is generated for ICU4J. The
+    ICU4C version number string should be check to ensure that the correct
+    version number is being used. public static final String
+    ICU4C_VERSION="50.0.2"; Note: The ICU4C version number string in this JAVA
+    file is not really used for anything except for a few logln method calls.
+    Perhaps this member is not really needed.
+
+## Data Versions
+
+Make sure data file versions (for **data contents**) are properly assigned.
+
+If any of the data files in the
+[/icu/source/data/](https://github.com/unicode-org/icu/tree/main/icu4c/source/data)
+directory has changed **MANUALLY**, upgrade the version number accordingly as
+well. If the contents of a resource bundle has changed, then increase the
+version number (at least the minor version field). The CLDR generated data
+should have the correct number. **Note** from Markus (20090514, ICU 4.2
+timeframe): Most data files automatically get their version numbers set by the
+LDML2ICUConverter, from CLDR version numbers. It is not clear what, if anything,
+needs to be done for this task.
+
+The ICU4J data files depend on the ICU4C data files. Thus, in order to
+regenerate the updated ICU4J data files, you will first need to update the ICU4C
+data files version.
+
+Once the ICU4C data files are updated, follow the instructions in the Readme
+file here:
+<https://github.com/unicode-org/icu/blob/main/icu4c/source/data/icu4j-readme.txt>
+
+## Data File *Format* Versions
+
+Make sure data file **format** versions are updated. See
+<https://unicode-org.github.io/icu/userguide/icu_data/#icu-data-file-formats>
+
+For Unicode data files, it is also useful to look at recent tools-tree changes:
+[icu/commits/main/tools/unicode](https://github.com/unicode-org/icu/commits/main/tools/unicode)
+
+If the format of a binary data file has changed, upgrade the format version in
+the UDataInfo header for that file. Better: Change the format version
+immediately when the format is changed. The change must be made in both the
+producer/generator and consumer/runtime code.
+
+It is desirable to maintain backward compatibility, but sometimes impractical.
+Update the major version number for incompatible changes. Runtime code should
+permit higher minor version numbers for supported major versions.
+
+We rarely use the third and fourth version number fields, except for UTrie (only
+version 1, not UTrie2) parameters that don't really change.

docs/processes/rules_update.md

@@ -0,0 +1,286 @@
+<!--
+Copyright (C) 2016 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+Updating ICU's built-in Break Iterator rules
+============================================
+
+Here are instructions for updating ICU's built-in break iterator rules, for Grapheme, Word, Line and Sentence breaks.
+
+The ICU rules implement the boundary behavior from Unicode [UAX-14](https://www.unicode.org/reports/tr14/) and [UAX-29](https://www.unicode.org/reports/tr29/), with tailorings from CLDR and some ICU-specific enhancements. ICU rules updates are needed in response to changes from Unicode or CLDR, or for bug fixes. Often ideas for CLDR or UAX updates are prototyped in ICU first, before becoming official.
+
+This is not a cook book process. Familiarity with ICU break iterator behavior and rules is needed. Sets of break rules often interact in subtle and difficult to understand ways. Expect some bumps.
+
+### Have clear specifications for the change.
+
+The changes will typically come from a proposed update to Unicode UAX 29 or UAX 14,
+or from CLDR based tailorings to these specifications.
+
+As an example, see [CLDR proposal for Extended Indic Grapheme Clusters](https://github.com/unicode-org/cldr/tree/main/common/properties/segments).
+
+Often ICU will implement draft versions of proposed specification updates, to check that they are complete and consistent, and to identify any issues before they are released.
+
+### Files that typically will need to be updated:
+
+
+| File                                |  Contents |
+|-------------------------------------|--------------------------
+| icu/icu4c/source/...
+| .../test/testdata/rbbitst.txt       | Data driven test file. Typically the first to be updated.
+| .../data/brkitr/rules/*.txt         | Main break rule files.
+| .../test/intltest/rbbitst.cpp       | Monkey Test Rules (as code; also called the 'original' or 'old' monkey test).
+| .../test/testdata/break_rules/*.txt | Monkey Test Rules (as data; also called the 'new' or 'rule-based' monkey test).
+| .../test/testdata/*BreakTest.txt    | Unicode Supplied Test Files.
+|||
+| icu/icu4j/...
+| .../main/shared/data/icudata.jar        | Data jar, includes break rules. Derived from ICU4C.
+| .../main/tests/core/src/com/ibm/icu/dev/test/rbbi/rbbitst.txt         | Test data, copied from ICU4C.
+| .../main/tests/core/src/com/ibm/icu/dev/test/rbbi/break_rules/*       | Monkey test rules, copied from ICU4C.
+| .../main/tests/core/src/com/ibm/icu/dev/test/rbbi/RBBITestMonkey.java | Monkey test w rules as code. Port from ICU4C.
+
+
+### ICU4C
+
+The rule updates are done first for ICU4C, and then ported (code changes) or moved (data changes) to ICU4J. This order is easiest because the the break rule source files are part of the ICU4C project, as is the rule builder.
+
+1.  **Add basic tests**` to icu4c/source/test/testdata/rbbitst.txt`
+
+    This file contains data driven tests, which are basically text strings marked up with their expected break positions. The test syntax is documented in the file itself.
+
+    Add tests to to spot check the basics of the changes, to verify that some simple, straight forward cases work as expected. There is no need to thoroughly check corner cases; the goal at this step is a quick sanity check that will fail before the rule update and pass afterwards.
+
+    The [Unicode Utilities](http://www.unicode.org/cldr/utility/) can be very helpful at this point, for showing what characters
+    match a UnicodeSet expression, and for listing the properties of a particular character.
+
+    Tests added for the above example:
+
+         #
+         #  ICU-13637 and CLDR-10994 - Indic Grapheme Cluster Boundary changes to support aksaras
+         #      New rule: LinkingConsonant ExtCccZwj* Virama ExtCccZwj* × LinkingConsonant
+         #      Sample Chars: LinkingConsonant: \u0915
+         #                    Virama:           \u094d    [also Extend]
+         #                    ExtCccZWJ:        \u0308
+         #                    Extend but not ExtCCCZWJ   \u093A
+         <char>
+         <data>•\u0915\u094d\u0915•</data>
+         <data>•\u0915\u0308\u0308\u094d\u0308\u0308\u0915•</data>
+         <data>•\u0915\u0308\u0308\u094d\u0308\u0308•\u0041•</data>
+         <data>•\u0915\u0308\u0308\u094d\u093A\u093A•\u0915•</data>
+
+    Two copies of the test file exist in the ICU repository, one for C++ and one for Java. There are two because
+    there is no common place that will always be present and that the two build systems can both access.
+
+    The two should be identical. Verify this before starting to make changes. If they differ, it
+    probably means that some earlier change to ICU4C was not fully ported to ICU4J, and this
+    needs to be resolved before proceeding.
+
+        diff icu4c/source/test/testdata/rbbitst.txt icu4j/main/tests/core/src/com/ibm/icu/dev/test/rbbi/rbbitst.txt
+
+    Should show no differrence.
+
+
+2.  **Run the ICU4C break iterator tests**, and verify that the newly added tests fail as expected.
+    (We haven't updated the rules yet)
+
+            cd icu/icu4c/source
+            make -j6 check
+
+    To run just the RBBI Tests (you will be doing this a lot)
+
+            cd test/intltest
+            LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH  ./intltest rbbi
+
+    A snippet from the test output, showing one of many expected failures:
+
+            === Handling test: rbbi: ===
+            rbbi {
+            TestExtended {
+            code    alpha extend alphanum type word sent line name
+            ------------------------------------------------ 0
+                915     1      0        1   Lo   LE   LE   AL DEVANAGARI LETTER KA
+                94d     0      1        0   Mn Extend   EX   CM DEVANAGARI SIGN VIRAMA
+            ------------------------------------------------ 2
+                915     1      0        1   Lo   LE   LE   AL DEVANAGARI LETTER KA
+                    Forward Iteration, break found, but not expected.  Pos=   2  File line,col=  175,  21
+                    Reverse Itertion, break found, but not expected.  Pos=   2  File line,col=  175,  21
+
+3.  **Update the main rule file for the break iterator type in question.**
+
+    For this example, the rule file is `icu4c/source/data/brkitr/rules/char.txt`.
+    (If the change is for word or line break, which have multiple rule files for tailorings, only update the root file at this time.)
+
+    Start by looking at how existing similar rules are being handled, and also refer to the ICU user guide section on [Break Rules](../userguide/boundaryanalysis/break-rules.md) for an explanation of rule syntax and behavior.
+
+    The transformation from UAX or CLDR style rules to ICU rules can be non-trivial. Sources of difficulties include:
+
+    -  All ICU rules run in parallel, while UAX/CLDR rules are applied sequentially, stopping after the first match. The ICU rules sometimes require extra logic to prevent a later rule from preempting an earlier rule. This can be quite tricky to express.
+
+    -  ICU rules match a run of text that does not have boundaries in its interior (unless the rule contains a "hard break", represented by a '/'. UAX and CLDR rules, on the other hand, tell whether a single text position is or is not a break, with the rule expressing pre and post context around that position. This transformation is generally not hard, and the ICU form  of the rules is often simpler.
+
+
+4.  **Rebuild the ICU data with the updated rules.**
+
+        cd icu4c/source/data
+        make
+
+5.  **Rerun the data-driven test**, `rbbi/TestExtended`. With luck, it may pass. Failures fall into two classes:
+
+    - The newly added test failed. Either something is wrong with the test cases, or something is wrong with the rule updates.
+
+    - A previously existing test started failing. Examine the test case; it probably conflicts with the new rules. Either change the expected boundaries, or change the test string to something that generates the previous boundaries. Or remove the test. Whatever seems most sensible.
+
+    Fix any failures before proceeding. Don't try to run other tests yet; a large number of failures are very likely.
+
+6.  **Run any relevant Unicode test data.** ICU's copies of the test files are here:
+
+            icu4c/source/test/testdata/GraphemeBreakTest.txt
+            icu4c/source/test/testdata/LineBreakTest.txt
+            icu4c/source/test/testdata/SentenceBreakTest.txt
+            icu4c/source/test/testdata/WordBreakTest.txt
+
+    If the update includes new versions of any of these files, copy them to the above locations.
+
+    To run the test:
+
+            cd icu4c/source/test/intltest
+            LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH  ./intltest rbbi/RBBITest/TestUnicodeFiles
+
+    The test files are from the Unicode Consortium. The official, released versions are at https://www.unicode.org/Public/UCD/latest/ucd/auxiliary/. The files are copied, unmodified, into the ICU source tree to make them accessible to the ICU tests.
+
+    If the update is for a new Unicode version, or for a new CLDR tailoring of the root Unicode rules, it should include updated test data files. If they're missing, ask whoever is requesting or providing the updated rules for help. The test data is generated by CLDR tooling.
+
+    Copy any new Unicode test data files to their location in icu, and rerun the test.
+
+    Historically, failures have roughly equal chance of being problems with the test data or problems with the ICU rules. In either event, track down and fix any problems before proceeding.
+
+    *Note:* Known issues with the test data file are accounted for in the test code, in the function `RBBITest::testCaseIsKnownIssue()` in the file `rbbitst.cpp`. Test cases are skipped when ICU behavior has been patched or enhanced for some reason, relative to standard Unicode behavior.
+
+7.  **Other Break Iterator Tests, except for Monkey Tests**
+
+            cd icu4c/source/test/intltest
+            LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH  ./intltest rbbi
+
+    This runs all of the RBBI tests, including the Monkey tests. For this step, ignore Monkey failures, and track down and fix any others.
+
+    There is a real mish-mash of old tests, checking random bits of hard coded data.
+
+8.  **Monkey Tests**
+
+    Monkey testing compares the breaking behavior of the main ICU RBBI implementation with that of a reference implementation, using random data.
+
+    Monkey testing has proved to be by far the most effective way to check obscure edge and corner case behavior, to the point that it no longer seems worth while to hand-write more than fairly basic test cases.
+
+    ICU has two independent RBBI monkey tests. The original one implements the break rules directly in code. The algorithm sticks pretty close to that of the Unicode UAX specifications. The original monkey test checks only the root break iterator behavior, not any tailorings.
+
+    The newer, data-driven monkey test takes its reference rules from test data files, instead of hard coding them. It covers tailorings. Its algorithm differs somewhat from that of the UAX specifications, in that the rules match runs of text rather than testing pre or post context around a potential break. (This was intended as a first step in driving a revised algorithm back to the specifications, a task that hasn't yet happened.)
+
+    The original plan was to retire the old monkey test in favor of the newer data-driven one, but each tends to uncover problems that the other misses, so they both remain.
+
+9.  **Original Monkey Test**
+
+    To run the test:
+
+            LD_LIBRARY_PATH=../../lib:../../stubdata:../../tools/ctestfw:$LD_LIBRARY_PATH  ./intltest rbbi/RBBITest/TestMonkey@"type=char loop=-1"
+
+            Test parameters (following the '@'
+            seed=nnnnn        Random number starting seed.
+                              Setting the seed allows errors to be reproduced.
+            loop=nnn          Looping count.  Controls running time.
+                              -1:  run forever.
+                               0 or greater:  run length.
+
+            type = char | word | line | sent | title
+
+    Updating the test with new or revised rules requires changing the test source code, in `icu4c/source/test/intltest/rbbitst.cpp`. Look for the classes RBBICharMonkey, RBBIWordMonkey, RBBISentMonkey and RBBILineMonkey. The body of each class tracks the corresponding UAX-14 or UAX-29 specifications in defining the character classes and break rules.
+
+    After making changes, as a final check, let the test run for an extended period of time, on the order of several hours.
+    Run it from a terminal, and just interrupt it (Ctrl-C) when it's gone long enough.
+
+10. **New Monkey Test**
+
+    To run the test:
+
+            intltest rbbi/RBBIMonkeyTest/testMonkey@rules=grapheme.txt,loop=-1
+
+    The @rules parameter is the test rules file to run; test rules files are located in the directory `icu4c/source/test/testdata/break_rules`
+
+    The test should initially fail, because ICU's library rules have been updated (steps 3 and 4), but the reference rules used
+    by this test have not yet been.
+
+    Make the updates to the test rules and re-run. The rule syntax is described in
+    [icu4c/source/test/testdata/break_rules/README.md](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/testdata/break_rules/README.md)
+    The test reference rules are in this same directory.
+
+    Again, after everything appears to be working, let the test run for an extended length of time. Long runs are especially important with the more complex break rule sets, such as line break.
+
+11. **Tailorings**
+
+    If this is an update to word or line break root behavior, the rule changes must be propagated from from the root rule files to the tailored files, for both the main rules (source/data/brkitr/rules/*) and the monkey test rules (source/test/testdata/break_rules/*).
+
+    The easiest and safest way to do this is to create a patch file of the diffs to the root rule file, typically using `git diff`.
+    Apply it to the various tailorings of the break type being updated.
+
+    Merge conflicts when applying the patch would indicate that the same rules modified by the new change were also modified in the tailoring. When this happens, you just have to dig in and understand the intent of the rules and the tailoring were, and figure out what makes sense. Fortunately, conflicts are not common.
+
+    As with the main rules, after everything appears to be working, run the rule based monkey test for an extended period of time (with loop=-1).
+
+### ICU4J
+
+1.  **Copy the Data Driven Test File to ICU4J**
+
+    Copy the file `rbbitst.txt` from ICU4C to ICU4J, and run the Java test. It should fail until the rules are updated.
+
+            cd <top level icu directory>
+            cp icu4c/source/test/testdata/rbbitst.txt icu4j/main/tests/core/src/com/ibm/icu/dev/test/rbbi/rbbitst.txt
+
+    Run the test from Eclipse.
+
+    Navigate to `/icu4j-core-tests/src/com/ibm/icu/dev/test/rbbi/RBBITestExtended.java`.
+
+    Select the `TestExtended()` function in the source code, right-click it and choose "Run As Junit Test".
+
+    Errors (expected because the break rules have not yet been updated) should show the failing line in `rbbitst.txt`. For example:
+
+            java.lang.AssertionError: Forward Iteration, break found, but not expected.  Pos=2  File line,col= 175, 21
+
+2.  **Refresh ICU4J data from ICU4C**.
+
+    This will bring over the updated break rules, refreshing the file `main/shared/data/icudata.jar`. Follow the instructions from `icu4c/source/data/icu4j-readme.txt`.
+
+    Rerun the ICU4J tests. `TestExtended` should now pass. Others may start failing.
+
+3.  **Port the code-based Monkey Test changes from ICU4C**
+
+    ICU4C file to port from: `source/test/intltest/rbbitst.cpp`
+
+    ICU4J file to port to: `main/tests/core/src/com/ibm/icu/dev/test/rbbi/RBBITestMonkey.java`
+
+    To conveniently run the individual tests, look for the test functions `TestCharMonkey()`, `TestWordMonkey()`, etc. in `RBBITestMonkey.java`.
+
+    Test parameters are passed via the Eclipse Run Configuration settings, arguments tab, VM parameters.  For example,
+
+            -ea -Dseed=554654 -Dloop=1
+
+    When the test appears to be working, run for an extended time (with -Dloop=-1).
+
+4.  **New (rule driven) Monkey Test**
+
+    Copy the updated monkey test rules from ICU4C and run the test.**
+
+    ICU4C directory, to copy from: `source/test/testdata/break_rules/`
+
+    ICU4J directory, to copy to: `main/tests/core/src/com/ibm/icu/dev/test/rbbi/break_rules/`
+
+    Then rerun the rule based monkey test, in the file `main/tests/core/src/com/ibm/icu/dev/test/rbbi/RBBIMonkeyTest.java`. Find the test function `TestMonkey()`; it include comments describing how to run it with parameters from Eclipse.
+
+    Run the test(s) for the changed rules for an extended amount of time (with Dloop=-1).
+
+
+
+
+
+
+
+
+

docs/processes/unicode-update.md

@@ -0,0 +1,157 @@
+---
+layout: default
+title: Unicode Update
+parent: Release & Milestone Tasks
+grand_parent: Contributors
+nav_order: 130
+---
+
+<!--
+© 2021 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Unicode Update
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+The International Components for Unicode (ICU) implement the Unicode Standard
+and many of its Standard Annexes and Technical Standards,
+and are updated to each new Unicode version.
+Usually, the ICU team participates in the Unicode beta process by
+updating to a beta snapshot of the new Unicode version and testing it thoroughly.
+In the past, this has sometimes uncovered problems that could be
+fixed before the release of the new Unicode version.
+
+(Note that ICU does not provide any access to Unihan data,
+mostly because of low demand and the large size of the Unihan data.)
+
+## Update process
+
+For the last several updates, there is a
+[change log for Unicode updates](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/unidata/changes.txt).
+
+For each new Unicode version, during the beta period,
+*   Copy the change log for the previous version to the top of this file.
+*   Adjust the versions, tickets, URLs, and paths.
+*   Work through the steps listed in the log, top to bottom, adjusting the log as necessary.
+*   Report problems to the UTC and/or CLDR and/or ICU.
+
+Before the data is final, “turn the crank” several more times,
+using appropriate subsets of the steps.
+
+At the start of the process, most of the Unicode data files are copied into the ICU repository, either
+without modification or, for some files, with comments removed and lines merged
+to reduce their size.
+
+Some of the data files are not part of the Unicode release but are output from
+various Unicode Tools, as noted in the change log.
+(See also https://github.com/unicode-org/unicodetools)
+
+Note: We have looked at using the [UCD XML](https://www.unicode.org/ucd/#UCDinXML) files,
+but decided against it and instead developed a simpler format for a combined Unicode data file.
+See https://icu.unicode.org/design/props/ppucd#TOC-Why-not-UCD-XML-files-
+(There was an outdated, experimental, partial UCD XML parser here:
+<https://github.com/unicode-org/icu-docs/tree/main/design/properties/genudata>)
+
+The ICU Unicode tools parse the text files, process the data somewhat, and write
+binary data for runtime use. Most of these tools live in a
+[source tree](https://github.com/unicode-org/icu/tree/main/tools/unicode) separate
+from the ICU4C/ICU4J sources, and link with ICU4C.
+
+The following steps are necessarily manual:
+
+*   New property values and properties need to be reviewed.
+*   For new property values, enum constants are added to the API.
+*   For new properties, APIs are added and the tools are modified to write the
+    additional data into new fields in the data structures; sometimes new data
+    structures need to be developed for new properties.
+*   Some properties are not exposed via simple, direct data access APIs but
+    in more high-level APIs (like case mapping and normalization functions).
+*   Sometimes changes in which property aliases are canonical vs. actual aliases
+    require manual changes to helper files or tools.
+
+New properties (whether they are supported via dedicated API or not) should be added to the
+[Properties User Guide chapter](https://unicode-org.github.io/icu/userguide/strings/properties).
+
+### Bazel build process
+
+The tools for building ICU data for Unicode properties are in a separate subtree of the ICU repo.
+They depend on parts of the ICU libraries and generate files that go back into the source tree
+in order to make updated properties available to higher-level parts of the library and tools.
+
+In the past, we boot-strapped this by doing a `make install` on ICU with the old data,
+using cmake to build the tools, running some of the tools with their output
+going back into the source tree, rebuilding ICU and the tools, running more tools, etc.
+
+This was very manual and cumbersome.
+
+Instead, starting with ICU 70 (2021),
+we now use the [Bazel build system](https://bazel.build/) to build only small parts of the libraries,
+just enough to build and run the initial tools.
+We still need a layer outside of Bazel in order to copy the tool output into the source tree,
+because Bazel on its own does not allow modifying the source tree.
+We use a shell script to automate alternately building tools and copying files.
+
+This simplifies the process.
+
+It should also make it much easier to customize Unicode properties,
+for example by patching ppucd.txt with real properties for PUA (private use) characters.
+
+Finally, it should make it easier to modify the binary data file format for a property
+because we build the library code that depends on the data only after generating that data.
+
+For the initial setup of this Bazel build system for ICU see
+https://unicode-org.atlassian.net/browse/ICU-21117 “sane build system for Unicode data”
+
+This was completed while working on
+https://unicode-org.atlassian.net/browse/ICU-21635 “Unicode 14”
+
+#### Bazel setup
+
+It should be possible to run the `bazel` command directly,
+but the Bazel team recommends using the `bazelisk` wrapper.
+It downloads and runs the latest version of Bazel, or,
+if the root folder contains a .bazelisk file with an entry like
+```
+USE_BAZEL_VERSION=3.7.1
+```
+then it downloads that specific version. If there are any incompatible changes in Bazel behavior,
+then this insulates us from those.
+
+We do have an $ICU_SRC/.bazeliskrc file with such a line.
+Consider running `bazelisk --version` outside of the $ICU_SRC folder
+to find out the latest `bazel` version, and copying that version number into the config file.
+(Revert if you find incompatibilities, or, better, update our build & config files.)
+
+Right in $ICU_SRC we also have a file called WORKSPACE which tells Bazel that
+our repo root is also the root of its build system.
+We build library “targets” relative to that. For example,
+`//icu4c/source/common:normalizer2` refers to the cc_library named `normalizer2` in
+$ICU_SRC/icu4c/source/common/BUILD .
+
+## Testing
+
+The ICU test suites include some tests for Unicode data. Some just check the
+data from the API against the original .txt files. Some tests simply check for
+certain hardcoded values, which have to be updated when those values change
+deliberately. Other tests perform consistency checks between some properties, or
+between different implementations.
+
+There is a program as a part of CLDR that uses regular expressions to test the
+segmentation rules and properties (LineBreak, WordBreak, etc). That is, there is
+a regular expression corresponding to each of the rules, and a brute force
+evaluation of them. That is used to generate the tables and test data. The
+segmentation rules in ICU are later modified by hand to match the
+specifications. That has to be done by hand, because there are some areas where
+the rules don't correspond 1:1 with the spec. There are a series of ICU
+consistency tests for those rules. ICU also includes regression tests with
+"golden files" that are used to detect unanticipated side effects of revisions
+to the rules.

docs/userguide/assets/features_locales.svg

@@ -0,0 +1,5 @@
+<!--
+© 2019 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+<svg version="1.1" viewBox="0.0 0.0 600.0 400.0" fill="none" stroke="none" stroke-linecap="square" stroke-miterlimit="10" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg"><clipPath id="p.0"><path d="m0 0l600.0 0l0 400.0l-600.0 0l0 -400.0z" clip-rule="nonzero"/></clipPath><g clip-path="url(#p.0)"><path fill="#000000" fill-opacity="0.0" d="m0 0l600.0 0l0 400.0l-600.0 0z" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m48.0 352.0l528.0 0" fill-rule="evenodd"/><path stroke="#000000" stroke-width="2.0" stroke-linejoin="round" stroke-linecap="butt" d="m48.0 352.0l528.0 0" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m48.0 352.0l0 -328.0" fill-rule="evenodd"/><path stroke="#000000" stroke-width="2.0" stroke-linejoin="round" stroke-linecap="butt" d="m48.0 352.0l0 -328.0" fill-rule="evenodd"/><path fill="#000000" fill-opacity="0.0" d="m48.0 352.0l192.0 0l0 40.0l-192.0 0z" fill-rule="evenodd"/><path fill="#000000" d="m58.765625 384.04l0 -17.1875l2.265625 0l0 15.15625l8.46875 0l0 2.03125l-10.734375 0zm12.378906 -6.21875q0 -3.46875 1.921875 -5.125q1.609375 -1.390625 3.921875 -1.390625q2.5625 0 4.1875 1.6875q1.625 1.6875 1.625 4.640625q0 2.40625 -0.71875 3.78125q-0.71875 1.375 -2.09375 2.140625q-1.375 0.765625 -3.0 0.765625q-2.625 0 -4.234375 -1.671875q-1.609375 -1.6875 -1.609375 -4.828125zm2.171875 0q0 2.390625 1.03125 3.578125q1.046875 1.1875 2.640625 1.1875q1.5625 0 2.609375 -1.1875q1.046875 -1.203125 1.046875 -3.65625q0 -2.3125 -1.0625 -3.5q-1.046875 -1.1875 -2.59375 -1.1875q-1.59375 0 -2.640625 1.1875q-1.03125 1.1875 -1.03125 3.578125zm20.082031 1.65625l2.078125 0.265625q-0.34375 2.15625 -1.75 3.375q-1.390625 1.203125 -3.4375 1.203125q-2.546875 0 -4.109375 -1.671875q-1.546875 -1.671875 -1.546875 -4.78125q0 -2.015625 0.671875 -3.53125q0.671875 -1.515625 2.03125 -2.265625q1.359375 -0.765625 2.96875 -0.765625q2.03125 0 3.3125 1.03125q1.296875 1.03125 1.65625 2.90625l-2.046875 0.328125q-0.296875 -1.265625 -1.046875 -1.890625q-0.734375 -0.640625 -1.796875 -0.640625q-1.59375 0 -2.59375 1.15625q-0.984375 1.140625 -0.984375 3.609375q0 2.5 0.953125 3.640625q0.96875 1.140625 2.515625 1.140625q1.234375 0 2.0625 -0.765625q0.84375 -0.765625 1.0625 -2.34375zm12.0 3.03125q-1.171875 0.984375 -2.265625 1.40625q-1.078125 0.40625 -2.3125 0.40625q-2.046875 0 -3.15625 -1.0q-1.09375 -1.0 -1.09375 -2.5625q0 -0.921875 0.40625 -1.671875q0.421875 -0.75 1.09375 -1.203125q0.671875 -0.46875 1.515625 -0.703125q0.625 -0.15625 1.875 -0.3125q2.5625 -0.3125 3.765625 -0.734375q0.015625 -0.421875 0.015625 -0.546875q0 -1.28125 -0.609375 -1.8125q-0.796875 -0.71875 -2.390625 -0.71875q-1.5 0 -2.203125 0.53125q-0.703125 0.515625 -1.046875 1.84375l-2.0625 -0.28125q0.28125 -1.328125 0.921875 -2.140625q0.640625 -0.8125 1.859375 -1.25q1.21875 -0.453125 2.828125 -0.453125q1.59375 0 2.59375 0.375q1.0 0.375 1.46875 0.953125q0.46875 0.5625 0.65625 1.4375q0.09375 0.53125 0.09375 1.9375l0 2.8125q0 2.9375 0.140625 3.71875q0.140625 0.78125 0.53125 1.5l-2.203125 0q-0.328125 -0.65625 -0.421875 -1.53125zm-0.171875 -4.71875q-1.15625 0.46875 -3.453125 0.796875q-1.296875 0.1875 -1.84375 0.421875q-0.53125 0.234375 -0.828125 0.6875q-0.28125 0.453125 -0.28125 1.0q0 0.84375 0.625 1.40625q0.640625 0.5625 1.875 0.5625q1.21875 0 2.171875 -0.53125q0.953125 -0.53125 1.390625 -1.453125q0.34375 -0.71875 0.34375 -2.109375l0 -0.78125zm5.3476562 6.25l0 -17.1875l2.109375 0l0 17.1875l-2.109375 0zm13.910156 -4.015625l2.171875 0.28125q-0.515625 1.90625 -1.90625 2.96875q-1.390625 1.046875 -3.5625 1.046875q-2.734375 0 -4.34375 -1.671875q-1.59375 -1.6875 -1.59375 -4.734375q0 -3.140625 1.609375 -4.875q1.625 -1.734375 4.203125 -1.734375q2.5 0 4.078125 1.703125q1.59375 1.703125 1.59375 4.78125q0 0.1875 -0.015625 0.5625l-9.28125 0q0.109375 2.046875 1.15625 3.140625q1.046875 1.09375 2.609375 1.09375q1.15625 0 1.96875 -0.609375q0.828125 -0.609375 1.3125 -1.953125zm-6.9375 -3.40625l6.953125 0q-0.140625 -1.5625 -0.796875 -2.359375q-1.0 -1.21875 -2.609375 -1.21875q-1.453125 0 -2.453125 0.984375q-0.984375 0.96875 -1.09375 2.59375zm10.910156 3.703125l2.09375 -0.328125q0.171875 1.25 0.96875 1.921875q0.8125 0.671875 2.25 0.671875q1.453125 0 2.15625 -0.59375q0.703125 -0.59375 0.703125 -1.390625q0 -0.71875 -0.625 -1.125q-0.421875 -0.28125 -2.15625 -0.71875q-2.3125 -0.578125 -3.21875 -1.0q-0.890625 -0.4375 -1.359375 -1.1875q-0.453125 -0.765625 -0.453125 -1.671875q0 -0.828125 0.375 -1.53125q0.390625 -0.71875 1.046875 -1.1875q0.484375 -0.359375 1.328125 -0.609375q0.859375 -0.265625 1.828125 -0.265625q1.46875 0 2.578125 0.421875q1.109375 0.421875 1.625 1.15625q0.53125 0.71875 0.734375 1.921875l-2.0625 0.28125q-0.140625 -0.96875 -0.8125 -1.5q-0.671875 -0.546875 -1.90625 -0.546875q-1.453125 0 -2.078125 0.484375q-0.625 0.484375 -0.625 1.125q0 0.40625 0.265625 0.734375q0.25 0.34375 0.8125 0.5625q0.3125 0.125 1.859375 0.546875q2.234375 0.59375 3.109375 0.984375q0.890625 0.375 1.390625 1.109375q0.515625 0.71875 0.515625 1.796875q0 1.046875 -0.625 1.9843Line truncated

docs/userguide/boundaryanalysis/break-rules.md

@@ -0,0 +1,473 @@
+---
+layout: default
+title: Break Rules
+nav_order: 1
+parent: Boundary Analysis
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Break Rules
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Introduction
+
+ICU locates boundary positions within text by means of rules, which are a form
+of regular expressions. The form of the rules is similar, but not identical,
+to the boundary rules from the Unicode specifications
+[[UAX-14](https://www.unicode.org/reports/tr14/), 
+[UAX-29](https://www.unicode.org/reports/tr29/)], and there is a reasonably close
+correspondence between the two.
+
+Taken as a set, the ICU rules describe how to move forward to the next boundary,
+starting from a known boundary.
+ICU includes rules for the standard boundary types (word, line, etc.).
+Applications may also create customized break iterators from their own rules.
+
+ICU's built-in rules are located at
+[icu/icu4c/source/data/brkitr/rules/](https://github.com/unicode-org/icu/tree/main/icu4c/source/data/brkitr/rules).
+These can serve as examples when writing your own, and as starting point for
+customizations.
+
+### Rule Tutorial
+
+Rules most commonly describe a range of text that should remain together,
+unbroken. For example, this rule
+
+```
+    [\p{Letter}]+;
+```
+
+matches a run of one or more letters, and would cause them to remain unbroken.
+
+The part within `[`brackets`]` follows normal ICU [UnicodeSet pattern syntax](../strings/unicodeset.md).
+
+The qualifier, '`+`' in this case, can be one of
+
+| Qualifier | Meaning                  |
+| --------- | ------------------------ |
+| empty     | Match exactly once       |
+| `?`       | Match zero or one time   |
+| `+`       | Match one or more times  |
+| `*`       | Match zero or more times |
+
+#### Variables
+
+A variable names a set or rule sub-expression. They are useful for documenting
+what something represents, and for simplifying complex expressions by breaking
+them up.
+
+"Variable" is something if a misnomer; they cannot be reassigned, but are more
+of a constant expression.
+
+They start with a '`$`', both in the definition and use.
+
+```
+    # Variable Definition
+    $ASCIILetNum = [A-Za-z0-9];
+    # Variable Use
+    $ASCIILetNum+;
+```
+
+#### Comments and Semicolons
+
+'`#`' begins a comment, which extends to the end of a line.
+
+Comments may stand alone, or appear after another statement on a line.
+
+All rule statements or expressions are terminated by semicolons.
+
+#### Chained Matching
+
+Most ICU rule sets use the concept of "chained matching". The idea is that
+complete match can be composed from multiple pieces, with each piece coming from
+an individual rule of a rule set.
+
+This idea is unique to ICU break rules, it is not a concept found in other
+regular expression based matchers. Some of the Unicode standard break rules
+would be difficult to implement without it.
+
+Starting with an example,
+
+```
+    !!chain;
+    word_char = [\p{Letter}];
+    word_joiner = [_-];
+    $word_char+;
+    $word_char $word_joiner $word_char;
+```
+
+These rules will match "`abc`", "`hello_world`", `"hi-there"`,
+"`a-bunch_of-joiners-here`".
+
+They will not match "`-abc`", "`multiple__joiners`", "`tail-`"
+
+A full match is composed of pieces or submatches, possibly from different rules,
+with adjacent submatches linked by at least one overlapping character.
+
+In the example below, matching "`hello_world`",
+
+* '`1`' shows matches of the first rule, `word_char+`
+
+* '`2`' shows matches of the second rule, `$word_char $word_joiner $word_char`
+
+```
+      hello_world
+      11111 11111
+          222
+```
+
+There is an overlap of the matched regions, which causes the chaining mechanism
+to join them into a single overall match.
+
+The mechanism is a good match to, for example, [Unicode's word break
+rules](http://www.unicode.org/reports/tr29/#Word_Boundary_Rules), where rules
+WB5 through WB13 combine to piece together longer words from multiple short
+segments.
+
+`!!chain;` enables chaining in a rule set. It is disabled by default for back
+compatibility—very old versions of ICU did not support it, and it was
+originally introduced as an option.
+
+#### Parentheses and Alternation
+
+Rule expressions can contain parentheses and '`|`' operators, representing
+alternation or "or" operations. This follows conventional regular expression
+behavior.
+
+For example, the following would match a simplified identifier:
+
+```
+    $Letter ($Letter | $Digit)*;
+```
+
+#### String and Character Literals
+
+Similarly to common regular expressions, literal characters that do not have
+other special meaning represent themselves. So the rule
+
+```
+    Hello;
+```
+
+would match the literal input "`Hello`".
+
+In practice, nearly all break rules are composed from `[`sets`]` based on Unicode
+character properties; literal characters in rules are very rare.
+
+To prevent random typos in rules from being treated as literals, use this
+option:
+
+```
+    !!quoted_literals_only;
+```
+
+With the option, the naked `Hello` becomes a rule syntax error while a quoted
+`"hello"` still matches a literal hello.
+
+`!!quoted_literals_only` is strongly recommended for all rule sets. The random
+typo problem is very real, and surprisingly hard to recognize and debug.
+
+#### Explicit Break Rules
+
+A rule containing a slash (`/`) will force a boundary when it matches, even when
+other rules or chaining would otherwise lead to a longer match. Also called Hard
+Break Rules, these have the form
+
+```
+    pre-context / post-context;
+```
+
+where the pre and post-context look like normal break rules. Both the pre and
+post context are required, and must not allow a zero-length match. There should
+be no overlap between characters that end a match of the pre-context and those
+that begin a match of the post-context.
+
+Chaining into a hard break rule operates normally. There is no chaining out of a
+hard break rule; when the post-context matches a break is forced immediately.
+
+Note: future versions of ICU may loosen the restrictions on explicit break
+rules. The behavior of rules with missing or overlapping contexts is subject to
+change.
+
+#### Chaining Control
+
+Chaining into a rule can be dis-allowed by beginning that rule with a '`^`'. Rules
+so marked can begin a match after a preceding boundary or at the start of text,
+but cannot extend a match via chaining from another rule.
+
+~~The !!LBCMNoChain; statement modifies chaining behavior by preventing chaining
+from one rule to another from occurring on any character whose Line Break
+property is Combining Mark. This option is subject to change or removal, and
+should not be used in general. Within ICU, it is used only with the line break
+rules. We hope to replace it with something more general.~~
+
+> :point_right: **Note**: `!!LBCMNoChain` is deprecated, and will be removed
+> completely from a future version of ICU.
+
+## Rule Status Values
+
+Break rules can be tagged with a number, which is called the *rule status*.
+After a boundary has been located, the status number of the specific rule that
+determined the boundary position is available to the application through the
+function `getRuleStatus()`.
+
+For the predefined word boundary rules, status values are available to
+distinguish between boundaries associated with words, numbers, and those around
+spaces or punctuation. Similarly for line break boundaries, status values
+distinguish between mandatory line endings (new line characters) and break
+opportunities that are appropriate points for line wrapping. Refer to the ICU
+API documentation for the C header file `ubrk.h` or to Java class
+`RuleBasedBreakIterator` for a complete list of the predefined boundary
+classifications.
+
+When creating custom sets of break rules, integer status values can be
+associated with boundary rules in whatever way will be convenient for the
+application. There is no need to remain restricted to the predefined values and
+classifications from the standard rules.
+
+It is possible for a set of break rules to contain more than a single rule that
+produces some boundary in an input text. In this event, `getRuleStatus()` will
+return the numerically largest status value from the matching rules, and the
+alternate function `getRuleStatusVec()` will return a vector of the values from
+all of the matching rules.
+
+In the source form of the break rules, status numbers appear at end of a rule,
+and are enclosed in `{`braces`}`.
+
+Hard break rules that also have a status value place the status at the end, for
+example
+
+```
+    pre-context / post-context {1234};
+```
+
+### Word Dictionaries
+
+For some languages that don't normally use spaces between words, break iterators
+are able to supplement the rules with dictionary based breaking. Some languages,
+Thai or Lao, for example, use a dictionary for both word and line breaking.
+Others, such as Japanese, use a dictionary for word breaking, but not for line
+breaking.
+
+To enable dictionary use,
+
+1. The break rules must select, as unbroken chunks, ranges of text to be passed
+   off to the word dictionary for further subdivision.
+2. The break rules must define a character class named `$dictionary` that
+   contains the characters (letters) to be handled by the dictionary.
+
+The dictionary implementation, on receiving a range of text, will map it to a
+specific dictionary based on script, and then delegate to that dictionary for
+subdividing the range into words.
+
+See, for example, this snippet from the [line break rules](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/brkitr/rules/line.txt):
+
+```
+    #  Dictionary character set, for triggering language-based break engines. Currently
+    #  limited to LineBreak=Complex_Context (SA).
+    $dictionary = [$SA];
+```
+
+## Rule Options
+
+| Option          | Description |
+| --------------- | ----------- |
+| `!!chain`       |  Enable rule chaining. Default is no chaining. |
+| `!!forward`     |  The rules that follow are for forward iteration. Forward rules are now the only type of rules needed or used.   |
+
+### Deprecated Rule Options
+
+| Deprecated Option          | Description |
+| --------------- | ----------- |
+| ~~`!!reverse`~~     | ~~*[deprecated]* The rules that follow are for reverse iteration. No longer needed; any rules in a Reverse rule section are ignored.~~ |
+| ~~`!!safe_forward`~~ | ~~*[deprecated]* The rules that follow are for safe forward iteration. No longer needed; any rules in such a section are ignored.~~ |
+| ~~`!!safe_reverse`~~ | ~~*[deprecated]* The rules that follow are for safe reverse iteration. No longer needed; any rules in such a section are ignored.~~ |
+| ~~`!!LBCMNoChain`~~ | ~~*[deprecated]* Disable chaining when the overlap character matches `\p{Line_Break=Combining_Mark}`~~ |
+
+## Rule Syntax
+
+Here is the syntax for the boundary rules. (The EBNF Syntax is given below.)
+
+| Rule Name | Rule Values | Notes |
+| ---------- | ----------- | ----- |
+| rules | statement+ | |
+| statement | assignment \| rule \| control |
+| control | (`!!forward` \| `!!reverse` \| `!!safe_forward` \| `!!safe_reverse` \| `!!chain`) `;`
+| assignment | variable `=` expr `;` | 5 |
+| rule | `^`? expr (`{`number`}`)? `;` | 8,9 |
+| number | [0-9]+ | 1 |
+| break-point | `/` | 10 |
+| expr | expr-q \| expr `\|` expr \| expr expr | 3 |
+| expr-q | term \| term `*` \| term `?` \| term `+` |
+| term | rule-char \| unicode-set \| variable \| quoted-sequence \| `(` expr `)` \| break-point |
+| rule-special | *any printing ascii character except letters or numbers* \| white-space |
+| rule-char | *any non-escaped character that is not rule-special* \| `.` \| *any escaped character except* `\p` *or* `\P` |
+| variable | `$` name-start-char name-char* | 7 |
+| name-start-char | `_` \| \p{L} |
+| name-char | name-start-char \| \\p{N} |
+| quoted-sequence | `'` *(any char except single quote or line terminator or two adjacent single quotes)*+ `'` |
+| escaped-char | *See “Character Quoting and Escaping” in the [UnicodeSet](../strings/unicodeset.md) chapter* |
+| unicode-set | See [UnicodeSet](../strings/unicodeset.md) | 4 |
+| comment | unescaped `#` *(any char except new-line)** new-line | 2 |
+| s | unescaped \p{Z}, tab, LF, FF, CR, NEL | 6 |
+| new-line | LF, CR, NEL | 2 |
+
+### Rule Syntax Notes
+
+1. The number associated with a rule that actually determined a break position
+   is available to the application after the break has been returned. These
+   numbers are *not* Perl regular expression repeat counts.
+
+2. Comments are recognized and removed separately from otherwise parsing the
+   rules. They may appear wherever a space would be allowed (and ignored.)
+
+3. The implicit concatenation of adjacent terms has higher precedence than the
+   `|` operation. "`ab|cd`" is interpreted as "`(ab)|(cd)`", not as "`a(b|c)d`" or
+   "`(((ab)|c)d)`"
+
+4. The syntax for [unicode-set](../strings/unicodeset.md) is defined (and parsed) by the `UnicodeSet` class.
+   It is not repeated here.
+
+5. For `$`variables that will be referenced from inside of a `UnicodeSet`, the
+   definition must consist only of a Unicode Set. For example, when variable `$a`
+   is used in a rule like `[$a$b$c]`, then this definition of `$a` is ok:
+   “`$a=[:Lu:];`” while this one “`$a=abcd;`” would cause an error when `$a` was
+   used.
+
+6. Spaces are allowed nearly anywhere, and are not significant unless escaped.
+   Exceptions to this are noted.
+
+7. No spaces are allowed within a variable name. The variable name `$dictionary`
+   is special. If defined, it must be a Unicode Set, the characters of which
+   will trigger the use of word dictionary based boundaries.
+
+8. A leading `^` on a rule prevents chaining into that rule. It can only match
+   immediately after a preceding boundary, or at the start of text.
+
+9. `{`nnn`}` appearing at the end of a rule is a Rule Status number, not a repeat
+   count as it would be with conventional regular expression syntax.
+
+10. A `/` in a rule specifies a hard break point. If the rule matches, a
+    boundary will be forced at the position of the `/` within the match.
+
+### EBNF Syntax used for the RBBI rules syntax description
+
+| syntax | description |
+| -- | ------------------------- |
+| a? | zero or one instance of a |
+| a+ | one or more instances of a |
+| a* | zero or more instances of a |
+| a \| b | either a or b, but not both |
+| `a` "`a`" | the literal string between the quotes or displayed as `monospace` |
+
+## Planned Changes and Removed or Deprecated Rule Features
+
+1. Reverse rules could formerly be indicated by beginning them with an
+   exclamation `!`. This syntax is deprecated, and will be removed from a
+   future version of ICU.
+
+2. `!!LBCMNoChain` was a global option that specified that characters with the
+   line break property of "Combining Character" would not participate in rule
+   chaining. This option was always considered internal, is deprecated and will
+   be removed from a future version of ICU.
+
+3. Naked rule characters. Plain text, in the context of a rule, is treated as
+   literal text to be matched, much like normal regular expressions. This turns
+   out to be very error prone, has been the source of bugs in released versions
+   of ICU, and is not useful in implementing normal text boundary rules. A
+   future version will reject literal text that is not escaped.
+
+4. Exact reverse rules and safe forward rules: planned changes to the break
+   engine implementation will remove the need for exact reverse rules and safe
+   forward rules.
+
+5. `{bof}` and `{eof}`, appearing within `[`sets`]`, match the beginning or ending of
+   the input text, respectively. This is an internal (not documented) feature
+   that will probably be removed in a future version of ICU. They are currently
+   used by the standard rules for word, line and sentence breaking. An
+   alternative is probably needed. The existing implementation is incomplete.
+
+## Additional Sample Code
+
+**C/C++**
+See [icu/source/samples/break/](https://github.com/unicode-org/icu/tree/main/icu4c/source/samples/break/)
+in the ICU source distribution for code samples showing the use of ICU boundary analysis.
+
+## Details about Dictionary-Based Break Iteration
+
+> :point_right: **Note**: This section below is originally from August 2012.
+> It is probably out of date, for example `brkfiles.mk` does not exist anymore.
+
+Certain Unicode characters have a "dictionary" bit set in the break iteration
+rules, and text made up of these characters cannot be handled by the rules-based
+break iteration code for lines or words. Rather, they must be handled by a
+dictionary-based approach. The ICU approach is as follows:
+
+Once the Dictionary bit is detected, the set of characters with that bit is
+handed off to "dictionary code." This code then inspects the characters more
+carefully, and splits them by script (Thai, Khmer, Chinese, Japanese, Korean).
+If text in this script has not yet been handled, it loads the appropriate
+dictionary from disk, and initializes a specialized "BreakEngine" class for that
+script.
+
+There are three such specialized classes: Thai, Khmer and CJK.
+
+Thai and Khmer use very similar approaches. They look through a dictionary that
+is not weighted by word frequency, and attempt to find the longest total "match"
+that can be made in the text.
+
+For Chinese and Japanese text, on the other hand, we have a unified dictionary
+(due to the fact that both use some of the same characters, it is difficult to
+distinguish them) that contains information about word frequencies. The
+algorithm to match text then uses dynamic programming to find the set of breaks
+it considers "most likely" based on the frequency of the words created by the
+breaks. This algorithm could also be used for Thai and Khmer, but we do not have
+sufficient data to do so. This algorithm could also be used for Korean, but once
+again we do not have the data to do so.
+
+Code of interest is in `source/common/dictbe.{h, cpp}`, `source/common/brkeng.{h,
+cpp}`, `source/common/dictionarydata.{h, cpp}`. The dictionaries use the `BytesTrie`
+and `UCharsTrie` as their data store. The binary form of these dictionaries is
+produced by the `gendict` tool, which has source in `source/tools/gendict`.
+
+In order to add new dictionary implementations, a few changes have to be made.
+First, you should create a new subclass of `DictionaryBreakEngine` or
+`LanguageBreakEngine` in `dictbe.cpp` that implements your algorithm. Then, in
+`brkeng.cpp`, you should add logic to create this dictionary break engine if we
+strike the appropriate script - which should only be 3 or so lines of code at
+the most. Lastly, you should add the correct data file. If your data is to be
+represented as a `.dict` file - as is recommended, and in fact required if you
+don't want to make substantial code changes to the engine loader - you need to
+simply add a file in the correct format for gendict to the `source/data/brkitr`
+directory, and add its name to the list of `BRK_DICT_SOURCE` in
+`source/data/brkitr/brkfiles.mk`. This will cause your dictionary (say, `foo.txt`)
+to be added as a `UCharsTrie` dictionary with the name foo.dict. If you want your
+dictionary to be a `BytesTrie` dictionary, you will need to specify a transform
+within the `Makefile`. To do so, find the part of `source/data/Makefile.in` and
+`source/data/makedata.mak` that deals with `thaidict.dict` and `khmerdict.dict` and
+add a similar set of lines for your script. Lastly, in
+`source/data/brkitr/root.txt`, add a line to the dictionaries `{}` section of the
+form:
+
+```
+    shortscriptname:process(dependency){"dictionaryname.dict"}
+```
+
+For example, for Katakana:
+
+```
+    Kata:process(dependency){"cjdict.dict"}
+```
+
+Make sure to add appropriate tests for the new implementation.

docs/userguide/boundaryanalysis/index.md

@@ -0,0 +1,544 @@
+---
+layout: default
+title: Boundary Analysis
+nav_order: 1300
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Boundary Analysis
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview of Text Boundary Analysis
+
+Text boundary analysis is the process of locating linguistic boundaries while
+formatting and handling text. Examples of this process include:
+
+1. Locating appropriate points to word-wrap text to fit within specific margins
+   while displaying or printing.
+
+2. Locating the beginning of a word that the user has selected.
+
+3. Counting characters, words, sentences, or paragraphs.
+
+4. Determining how far to move the text cursor when the user hits an arrow key
+    (Some characters require more than one position in the text store and some
+    characters in the text store do not display at all).
+
+5. Making a list of the unique words in a document.
+
+6. Figuring out if a given range of text contains only whole words.
+
+7. Capitalizing the first letter of each word.
+
+8. Locating a particular unit of the text (For example, finding the third word
+    in the document).
+
+The `BreakIterator` classes were designed to support these kinds of tasks. The
+BreakIterator objects maintain a location between two characters in the text.
+This location will always be a text boundary. Clients can move the location
+forward to the next boundary or backward to the previous boundary. Clients can
+also check if a particular location within a source text is on a boundary or
+find the boundary which is before or after a particular location.
+
+## Four Types of BreakIterator
+
+ICU `BreakIterator`s can be used to locate the following kinds of text boundaries:
+
+1. Character Boundary
+
+2. Word Boundary
+
+3. Line-break Boundary
+
+4. Sentence Boundary
+
+Each type of boundary is found in accordance with the rules specified by Unicode
+Standard Annex #29, *Unicode Text Segmentation*
+(<https://www.unicode.org/reports/tr29/> ) or Unicode Standard Annex #14, *Unicode
+Line Breaking Algorithm* (<https://www.unicode.org/reports/tr14/>)
+
+### Character Boundary
+
+The character-boundary iterator locates the boundaries according to the rules
+defined in <http://www.unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries>.
+These boundaries try to match what a user would think of as a "character"—a
+basic unit of a writing system for a language—which may be more than just a
+single Unicode code point.
+
+The letter `Ä`, for example, can be represented in Unicode either with a single
+code-point value or with two code-point values (one representing the `A` and
+another representing the umlaut `¨`). The character-boundary iterator will treat
+either representation as a single character.
+
+End-user characters, as described above, are also called grapheme clusters, in
+an attempt to limit the confusion caused by multiple meanings for the word
+"character".
+
+### Word Boundary
+
+The word-boundary iterator locates the boundaries of words, for purposes such as
+double click selection or "Find whole words" operations.
+
+Words boundaries are identified according to the rules in
+<https://www.unicode.org/reports/tr29/#Word_Boundaries>, supplemented by a word
+dictionary for text in Chinese, Japanese, Thai or Khmer. The rules used for
+locating word breaks take into account the alphabets and conventions used by
+different languages.
+
+Here's an example of a sentence, showing the boundary locations that will be
+identified by a word break iterator:
+
+> :point_right: **Note**: TODO: An example needs to be added here.
+
+### Line-break Boundary
+
+The line-break iterator locates positions that would be appropriate points to
+wrap lines when displaying the text. The boundary rules are define here:
+<https://www.unicode.org/reports/tr14/>
+
+This example shows the differences in the break locations produced by word and
+line break iterators:
+
+> :point_right: **Note**: TODO: An example needs to be added here.
+
+### Sentence Boundary
+
+A sentence-break iterator locates sentence boundaries according to the rules
+defined here: <https://www.unicode.org/reports/tr29/#Sentence_Boundaries>
+
+## Dictionary-Based BreakIterator
+
+Some languages are written without spaces, and word and line breaking requires
+more than rules over character sequences. ICU provides dictionary support for
+word boundaries in Chinese, Japanese, Thai, Lao, Khmer and Burmese.
+
+Use of the dictionaries is automatic when text in one of the dictionary
+languages is encountered. There is no separate API, and no extra programming
+steps required by applications making use of the dictionaries.
+
+## Usage
+
+To locate boundaries in a document, create a BreakIterator using the
+`BreakIterator::create***Instance` family of methods in C++, or the `ubrk_open()`
+function (C), where "`***`" is `Character`, `Word`, `Line` or `Sentence`,
+depending on the type of iterator wanted. These factory methods also take a
+parameter that specifies the locale for the language of the text to be processed.
+
+When creating a `BreakIterator`, a locale is also specified, and the behavior of
+the BreakIterator obtained may be specialized in some way for that locale. For
+most locales the default break iterator behavior is used.
+
+Applications also may register customized BreakIterators for use in specific
+locales. Once such a break iterator has been registered, any requests for break
+iterators for that locale will return copies of the registered break iterator.
+
+ICU may cache service instances. Therefore, registration should be done during
+startup, before opening services by locale ID.
+
+In the general-usage-model, applications will use the following basic steps to
+analyze a piece of text for boundaries:
+
+1. Create a `BreakIterator` with the desired behavior
+
+2. Use the `setText()` method to set the iterator to analyze a particular piece
+   of text.
+
+3. Locate the desired boundaries using the appropriate combination of `first()`,
+   `last()`, `next()`, `previous()`, `preceding()`, and `following()` methods.
+
+The `setText()` method can be called more than once, allowing reuse of a
+BreakIterator on new pieces of text. Because the creation of a `BreakIterator` can
+be relatively time-consuming, it makes good sense to reuse them when practical.
+
+The iterator always points to a boundary position between two characters. The
+numerical value of the position, as returned by `current()` is the zero-based
+index of the character following the boundary. Thus a position of zero
+represents a boundary preceding the first character of the text, and a position
+of one represents a boundary between the first and second characters.
+
+The `first()` and `last()` methods reset the iterator's current position to the
+beginning or end of the text (the beginning and the end are always considered
+boundaries). The `next()` and `previous()` methods advance the iterator one boundary
+forward or backward from the current position. If the `next()` or `previous()`
+methods run off the beginning or end of the text, it returns DONE. The `current()`
+method returns the current position.
+
+The `following()` and `preceding()` methods are used for random access, to move the
+iterator to an arbitrary position within the text. Since a BreakIterator always
+points to a boundary position, the `following()` and `preceding()` methods will
+never set the iterator to point to the position specified by the caller (even if
+it is, in fact, a boundary position). `BreakIterator` will, however, set the
+iterator to the nearest boundary position before or after the specified
+position.
+
+`isBoundary()` returns true if the specified position is a boundary.
+
+### Thread Safety
+
+`BreakIterator`s are not thread safe. This is inherit in their design—break
+iterators are stateful, holding a reference to and position in the text, meaning
+that a single instance cannot operate in parallel on multiple texts.
+
+For concurrent break iteration, each thread must use its own break iterator.
+These can be obtained by creating separate break iterators of the desired type,
+or by initially creating a main break iterator and then creating a clone for
+each thread.
+
+### Line Breaking Strictness, a CSS Property
+
+CSS has the concept of "[Line Breaking
+Strictness](https://www.w3.org/TR/css-text-3/#line-break-property)". This
+property specifies the strictness of line-breaking rules applied within an
+element: especially how wrapping interacts with punctuation and symbols. ICU
+line break iterators can choose a strictness using locale tags:
+
+| Locale       | Behavior    |
+| ------------ | ----------- |
+| `en@lb=strict` <br/> `ja@lb=strict`  | Breaks text using the most stringent set of line-breaking rules |
+| `en@lb=normal` <br/> `ja@lb=normal`  | Breaks text using the most common set of line-breaking rules. |
+| `en@lb=loose`  <br/> `ja@lb=loose`   | Breaks text using the least restrictive set of line-breaking rules. Typically used for short lines, such as in newspapers. |
+
+### Sentence Break Filters
+
+Sentence breaking can return false positives - an indication that sentence ends
+in an incorrect position - in the presence of abbreviations. For example,
+consider the sentence
+
+> In the meantime Mr. Weston arrived with his small ship.
+
+Default sentence break shows a false boundary following the "Mr."
+
+ICU includes lists of common abbreviations that can be used to filter, to
+ignore, these false sentence boundaries. Filtering is enabled by the presence of
+the `ss` locale tag when creating the break iterator.
+
+| Locale           | Behavior                                                |
+| ---------------- | ------------------------------------------------------- |
+| `en`             |  no filtering                                           |
+| `en@ss=standard` |  Filter based on common English language abbreviations. |
+| `es@ss=standard` |  Filter with common Spanish abbreviations.              |
+
+Abbreviation lists are available (as of ICU 64) for English, German, Spanish,
+French, Italian and Portuguese.
+
+## Accuracy
+
+ICU's break iterators are based on the default boundary rules described in the
+Unicode Standard Annexes [14](https://www.unicode.org/reports/tr14/) and
+[29](https://www.unicode.org/reports/tr29/). These are relatively
+simple boundary rules that can be implemented efficiently, and are sufficient
+for many purposes and languages. However, some languages and applications will
+require a more sophisticated linguistic analysis of the text in order to find
+boundaries with good accuracy. Such an analysis is not directly available from
+ICU at this time.
+
+Break Iterators based on custom, user-supplied boundary rules can be created and
+used by applications with requirements that are not met by the standard default
+boundary rules.
+
+## BreakIterator Boundary Analysis Examples
+
+### Print out all the word-boundary positions in a UnicodeString
+
+**In C++:**
+
+```c++
+void listWordBoundaries(const UnicodeString& s) {
+    UErrorCode status = U_ZERO_ERROR;
+    BreakIterator* bi = BreakIterator::createWordInstance(Locale::getUS(), status);
+    bi->setText(s);
+    int32_t p = bi->first();
+    while (p != BreakIterator::DONE) {
+        printf("Boundary at position %d\n", p);
+        p = bi->next();
+    }
+    delete bi;
+}
+```
+
+**In C:**
+
+```c
+void listWordBoundaries(const UChar* s, int32_t len) {
+    UBreakIterator* bi;
+    int32_t p;
+    UErrorCode err = U_ZERO_ERROR;
+    bi = ubrk_open(UBRK_WORD, 0, s, len, &err);
+    if (U_FAILURE(err)) return;
+    p = ubrk_first(bi);
+    while (p != UBRK_DONE) {
+        printf("Boundary at position %d\n", p);
+        p = ubrk_next(bi);
+    }
+    ubrk_close(bi);
+}
+```
+
+### Get the boundaries of the word that contains a double-click position
+
+**In C++:**
+
+```c++
+void wordContaining(BreakIterator& wordBrk,
+        int32_t idx,
+        const UnicodeString& s,
+        int32_t& start,
+        int32_t& end) {
+    // this function is written to assume that we have an
+    // appropriate BreakIterator stored in an object or a
+    // global variable somewhere-- When possible, programmers
+    // should avoid having the create() and delete calls in
+    // a function of this nature.
+    if (s.isEmpty())
+        return;
+    wordBrk.setText(s);
+    start = wordBrk.preceding(idx + 1);
+    end = wordBrk.next();
+    // NOTE: for this and similar operations, use preceding() and next()
+    // as shown here, not following() and previous(). preceding() is
+    // faster than following() and next() is faster than previous()
+    // NOTE: By using preceding(idx + 1) above, we're adopting the convention
+    // that if the double-click comes right on top of a word boundary, it
+    // selects the word that _begins_ on that boundary (preceding(idx) would
+    // instead select the word that _ends_ on that boundary).
+}
+```
+
+**In C:**
+
+```c
+void wordContaining(UBreakIterator* wordBrk,
+    int32_t idx,
+    const UChar* s,
+    int32_t sLen,
+    int32_t* start,
+    int32_t* end,
+    UErrorCode* err) {
+    if (wordBrk == NULL || s == NULL || start == NULL || end == NULL) {
+        *err = U_ILLEGAL_ARGUMENT_ERROR;
+        return;
+    }
+    ubrk_setText(wordBrk, s, sLen, err);
+    if (U_SUCCESS(*err)) {
+        *start = ubrk_preceding(wordBrk, idx + 1);
+        *end = ubrk_next(wordBrk);
+    }
+}
+```
+
+### Check for Whole Words
+
+Use the following to check if a range of text is a "whole word":
+
+**In C++:**
+
+```c++
+UBool isWholeWord(BreakIterator& wordBrk,
+    const UnicodeString& s,
+    int32_t start,
+    int32_t end) {
+    if (s.isEmpty())
+        return FALSE;
+    wordBrk.setText(s);
+    if (!wordBrk.isBoundary(start))
+        return FALSE;
+    return wordBrk.isBoundary(end);
+}
+```
+
+**In C:**
+
+```c
+UBool isWholeWord(UBreakIterator* wordBrk,
+    const UChar* s,
+    int32_t sLen,
+    int32_t start,
+    int32_t end,
+    UErrorCode* err) {
+    UBool result = FALSE;
+    if (wordBrk == NULL || s == NULL) {
+        *err = U_ILLEGAL_ARGUMENT_ERROR;
+        return FALSE;
+    }
+    ubrk_setText(wordBrk, s, sLen, err);
+    if (U_SUCCESS(*err)) {
+        result = ubrk_isBoundary(wordBrk, start) && ubrk_isBoundary(wordBrk, end);
+    }
+    return result;
+}
+```
+
+Count the words in a document (C++ only):
+
+```c++
+int32_t containsLetters(RuleBasedBreakIterator& bi, const UnicodeString& s, int32_t start) {
+    bi.setText(s);
+    int32_t count = 0;
+    while (start != BreakIterator::DONE) {
+        int breakType = bi.getRuleStatus();
+        if (breakType != UBRK_WORD_NONE) {
+            // Exclude spaces, punctuation, and the like.
+            // A status value UBRK_WORD_NONE indicates that the boundary does
+            // not start a word or number.
+            //
+            ++count;
+        }
+        start = bi.next();
+    }
+    return count;
+}
+```
+
+The function `getRuleStatus()` returns an enum giving additional information on
+the text preceding the last break position found. Using this value, it is
+possible to distinguish between numbers, words, words containing kana
+characters, words containing ideographic characters, and non-word characters,
+such as spaces or punctuation. The sample uses the break status value to filter
+out, and not count, boundaries associated with non-word characters.
+
+### Word-wrap a document (C++ only)
+
+The sample function below wraps a paragraph so that each line is less than or
+equal to 72 characters. The function fills in an array passed in by the caller
+with the starting offsets of
+each line in the document. Also, it fills in a second array to track how many
+trailing white space characters there are in the line. For simplicity, it is
+assumed that an outside process has already broken the document into paragraphs.
+For example, it is assumed that every string the function is passed has a single
+newline at the end only.
+
+```c++
+int32_t wrapParagraph(const UnicodeString& s,
+                   const Locale& locale,
+                   int32_t lineStarts[],
+                   int32_t trailingwhitespace[],
+                   int32_t maxLines,
+                   UErrorCode &status) {
+
+    int32_t        numLines = 0;
+    int32_t        p, q;
+    const int32_t MAX_CHARS_PER_LINE = 72;
+    UChar          c;
+
+    BreakIterator *bi = BreakIterator::createLineInstance(locale, status);
+    if (U_FAILURE(status)) {
+        delete bi;
+        return 0;
+    }
+    bi->setText(s);
+
+
+    p = 0;
+    while (p < s.length()) {
+        // jump ahead in the paragraph by the maximum number of
+        // characters that will fit
+        q = p + MAX_CHARS_PER_LINE;
+
+        // if this puts us on a white space character, a control character
+        // (which includes newlines), or a non-spacing mark, seek forward
+        // and stop on the next character that is not any of these things
+        // since none of these characters will be visible at the end of a
+        // line, we can ignore them for the purposes of figuring out how
+        // many characters will fit on the line)
+        if (q < s.length()) {
+            c = s[q];
+            while (q < s.length()
+                   && (u_isspace(c)
+                       || u_charType(c) == U_CONTROL_CHAR
+                       || u_charType(c) == U_NON_SPACING_MARK
+            )) {
+                ++q;
+                c = s[q];
+            }
+        }
+
+        // then locate the last legal line-break decision at or before
+        // the current position ("at or before" is what causes the "+ 1")
+        q = bi->preceding(q + 1);
+
+        // if this causes us to wind back to where we started, then the
+        // line has no legal line-break positions. Break the line at
+        // the maximum number of characters
+        if (q == p) {
+            p += MAX_CHARS_PER_LINE;
+            lineStarts[numLines] = p;
+            trailingwhitespace[numLines] = 0;
+            ++numLines;
+        }
+        // otherwise, we got a good line-break position. Record the start of this
+        // line (p) and then seek back from the end of this line (q) until you find
+        // a non-white space character (same criteria as above) and
+        // record the number of white space characters at the end of the
+        // line in the other results array
+        else {
+            lineStarts[numLines] = p;
+            int32_t nextLineStart = q;
+
+            for (q--; q > p; q--) {
+                c = s[q];
+                if (!(u_isspace(c)
+                       || u_charType(c) == U_CONTROL_CHAR
+                       || u_charType(c) == U_NON_SPACING_MARK)) {
+                    break;
+                }
+            }
+            trailingwhitespace[numLines] = nextLineStart - q -1;
+            p = nextLineStart;
+           ++numLines;
+        }
+        if (numLines >= maxLines) {
+            break;
+        }
+    }
+    delete bi;
+    return numLines;
+}
+```
+
+Most text editors would not break lines based on the number of characters on a
+line. Even with a monospaced font, there are still many Unicode characters that
+are not displayed and therefore should be filtered out of the calculation. With
+a proportional font, character widths are added up until a maximum line width is
+exceeded or an end of the paragraph marker is reached.
+
+Trailing white space does not need to be counted in the line-width measurement
+because it does not need to be displayed at the end of a line. The sample code
+above returns an array of trailing white space values because an external
+rendering process needs to be able to measure the length of the line (without
+the trailing white space) to justify the lines. For example, if the text is
+right-justified, the invisible white space would be drawn outside the margin.
+The line would actually end with the last visible character.
+
+In either case, the basic principle is to jump ahead in the text to the location
+where the line would break (without taking word breaks into account). Then, move
+backwards using the preceding() method to find the last legal breaking position
+before that location. Iterating straight through the text with next() method
+will generally be slower.
+
+## ICU BreakIterator Data Files
+
+The source code for the ICU break rules for the standard boundary types is
+located in the directory
+[icu4c/source/data/brkitr/rules](https://github.com/unicode-org/icu/tree/main/icu4c/source/data/brkitr/rules).
+These files will be built, and the corresponding binary state tables
+incorporated into ICU's data, by the standard ICU4C build process.
+
+The dictionary word lists used by word break, and for some languages, line break
+are in
+[icu4c/source/data/brkitr/dictionaries](https://github.com/unicode-org/icu/tree/main/icu4c/source/data/brkitr/dictionaries).
+
+The same data is used by both ICU4C and ICU4J. In the normal ICU build process,
+the source data is processed into a binary form using ICU4C, and the resulting
+binary tables are incorporated into ICU4J.

docs/userguide/collation/api.md

@@ -0,0 +1,711 @@
+---
+layout: default
+title: API Details
+nav_order: 6
+parent: Collation
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Collation API Details
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+This section describes some of the usage conventions for the ICU Collation
+Service API.
+
+## Collator Instantiation
+
+To use the Collation Service, you must instantiate a `Collator`. The
+Collator defines the properties and behavior of the sort ordering. The Collator
+can be repeatedly referenced until all collation activities have been performed.
+The Collator can then be closed and removed.
+
+### Instantiating the Predefined Collators
+
+ICU comes with a large set of already predefined collators that are suited for
+specific locales. Most of the ICU locales have a predefined collator. In the worst
+case, the CLDR default set of rules,
+which is mostly equivalent to the UCA default ordering (DUCET), is used.
+The default sort order itself is designed to work well for many languages.
+(For example, there are no tailorings for the standard sort orders for
+English, German, French, etc.)
+
+To instantiate a predefined collator, use the APIs `ucol_open`, `createInstance` and
+`getInstance` for C, C++ and Java codes respectively. The C API takes a locale ID
+(or language tag) string argument, C++ takes a Locale object, and Java takes a
+Locale or ULocale.
+
+For some languages, multiple collation types are available; for example,
+"de-u-co-phonebk" / "de@collation=phonebook". They can be enumerated via
+`Collator::getKeywordValuesForLocale()`. See also the list of available collation
+tailorings in the online [ICU Collation
+Demo](https://icu4c-demos.unicode.org/icu-bin/collation.html).
+
+Starting with ICU 54, collation attributes can be specified via locale keywords
+as well, in the old locale extension syntax ("el@colCaseFirst=upper") or in
+language tag syntax ("el-u-kf-upper"). Keywords and values are case-insensitive.
+
+See the [LDML Collation spec, Collation
+Settings](http://www.unicode.org/reports/tr35/tr35-collation.html#Collation_Settings),
+and the [data
+file](https://github.com/unicode-org/cldr/blob/main/common/bcp47/collation.xml) listing
+the valid collation keywords and their values. (The deprecated attributes
+kh/colHiraganaQuaternary and vt/variableTop are not supported.)
+
+For the [old locale extension
+syntax](http://www.unicode.org/reports/tr35/tr35.html#Old_Locale_Extension_Syntax),
+the data file's alias names are used (first alias, if defined, otherwise the
+name): "de@collation=phonebook;colCaseLevel=yes;kv=space"
+
+For the language tag syntax, the non-alias names are used, and "true" values can
+be omitted: "de-u-co-phonebk-kc-kv-space"
+
+This example demonstrates the instantiation of a collator.
+
+**C:**
+
+```c
+UErrorCode status = U_ZERO_ERROR;
+UCollator *coll = ucol_open("en_US", &status);
+if(U_SUCCESS(status)) {
+    /* close the collator*/
+    ucol_close(coll);
+}
+```
+
+**C++:**
+
+```c++
+UErrorCode status = U_ZERO_ERROR;
+Collator *coll = Collator::createInstance(Locale("en", "US"), status);
+if(U_SUCCESS(status)) {
+    //close the collator
+    delete coll;
+}
+```
+
+**Java:**
+
+```java
+Collator col = null;
+try {
+    col = Collator.getInstance(Locale.US);
+} catch (Exception e) {
+    System.err.println("English collation creation failed.");
+    e.printStackTrace();
+}
+```
+
+### Instantiating Collators Using Custom Rules
+
+If the ICU predefined collators are not appropriate for your intended usage, you
+can define your own set of rules and instantiate a collator that uses them. For more
+details, please see [the section on collation customization](customization/index).
+
+This example demonstrates the instantiation of a collator.
+
+**C:**
+
+```c
+UErrorCode status = U_ZERO_ERROR;
+U_STRING_DECL(rules, "&9 < a, A < b, B < c, C; ch, cH, Ch, CH < d, D, e, E", 52);
+UCollator *coll;
+
+U_STRING_INIT(rules, "&9 < a, A < b, B < c, C; ch, cH, Ch, CH < d, D, e, E", 52);
+coll = ucol_openRules(rules, -1, UCOL_ON, UCOL_DEFAULT_STRENGTH, NULL, &status);
+if(U_SUCCESS(status)) {
+    /* close the collator*/
+    ucol_close(coll);
+}
+```
+
+**C++:**
+
+```c++
+UErrorCode status = U_ZERO_ERROR;
+UnicodeString rules(u"&9 < a, A < b, B < c, C; ch, cH, Ch, CH < d, D, e, E");
+Collator *coll = new RuleBasedCollator(rules, status);
+if(U_SUCCESS(status)) {
+    //close the collator
+    delete coll;
+}
+```
+
+**Java:**
+
+```java
+RuleBasedCollator coll = null;
+String ruleset = "&9 < a, A < b, B < c, C; ch, cH, Ch, CH < d, D, e, E";
+try {
+    coll = new RuleBasedCollator(ruleset);
+} catch (Exception e) {
+    System.err.println("Customized collation creation failed.");
+    e.printStackTrace();
+}
+```
+
+## Compare
+
+Two of the most used functions in ICU collation API, `ucol_strcoll` and `ucol_getSortKey`, have their counterparts in both Win32 and ANSI APIs:
+
+ICU C             | ICU C++                     | ICU Java                   | ANSI/POSIX | WIN32
+----------------- | --------------------------- | -------------------------- | ---------- | -----
+`ucol_strcoll`    | `Collator::compare`         | `Collator.compare`         | `strcoll`  | `CompareString`
+`ucol_getSortKey` | `Collator::getSortKey`      | `Collator.getCollationKey` | `strxfrm`  | `LCMapString`
+&nbsp;            | `Collator::getCollationKey` | &nbsp;                     | &nbsp;     |
+
+For more sophisticated usage, such as user-controlled language-sensitive text
+searching, an iterating interface to collation is provided. Please refer to the
+section below on `CollationElementIterator` for more details.
+
+The `ucol_compare` function compares one pair of strings at a time. Comparing two
+strings is much faster than calculating sort keys for both of them. However, if
+comparisons should be done repeatedly on a very large number of strings, generating
+and storing sort keys can improve performance. In all other cases (such as quick
+sort or bubble sort of a
+moderately-sized list of strings), comparing strings works very well.
+
+The C API used for comparing two strings is `ucol_strcoll`. It requires two
+`UChar *` strings and their lengths as parameters, as well as a pointer to a valid
+`UCollator` instance. The result is a `UCollationResult` constant, which can be one
+of `UCOL_LESS`, `UCOL_EQUAL` or `UCOL_GREATER`.
+
+The C++ API offers the method `Collator::compare` with several overloads.
+Acceptable input arguments are `UChar *` with length of strings, or `UnicodeString`
+instances. The result is a member of the `UCollationResult` or `EComparisonResult` enums.
+
+The Java API provides the method `Collator.compare` with one overload. Acceptable
+input arguments are Strings or Objects. The result is an int value, which is
+less than zero if source is less than target, zero if source and target are
+equal, or greater than zero if source is greater than target.
+
+There are also several convenience functions and methods returning a boolean
+value, such as `ucol_greater`, `ucol_greaterOrEqual`, `ucol_equal` (in C)
+`Collator::greater`, `Collator::greaterOrEqual`, `Collator::equal` (in C++) and
+`Collator.equals` (in Java).
+
+### Examples
+
+**C:**
+
+```c
+UChar *s [] = { /* list of Unicode strings */ };
+uint32_t listSize = sizeof(s)/sizeof(s[0]);
+UErrorCode status = U_ZERO_ERROR;
+UCollator *coll = ucol_open("en_US", &status);
+uint32_t i, j;
+if(U_SUCCESS(status)) {
+  for(i=listSize-1; i>=1; i--) {
+    for(j=0; j<i; j++) {
+      if(ucol_strcoll(s[j], -1, s[j+1], -1) == UCOL_LESS) {
+        swap(s[j], s[j+1]);
+     }
+   }
+}
+ucol_close(coll);
+}
+```
+
+**C++:**
+
+```c++
+UnicodeString s [] = { /* list of Unicode strings */ };
+uint32_t listSize = sizeof(s)/sizeof(s[0]);
+UErrorCode status = U_ZERO_ERROR;
+Collator *coll = Collator::createInstance(Locale("en", "US"), status);
+uint32_t i, j;
+if(U_SUCCESS(status)) {
+  for(i=listSize-1; i>=1; i--) {
+    for(j=0; j<i; j++) {
+      if(coll->compare(s[j], s[j+1]) == UCOL_LESS) {
+        swap(s[j], s[j+1]);
+     }
+   }
+}
+delete coll;
+}
+```
+
+**Java:**
+
+```java
+String s [] = { /* list of Unicode strings */ };
+try {
+    Collator coll = Collator.getInstance(Locale.US);
+    for (int i = s.length - 1; i > = 1; i --) {
+        for (j=0; j<i; j++) {
+            if (coll.compare(s[j], s[j+1]) == -1) {
+                swap(s[j], s[j+1]);
+            }
+        }
+    }
+} catch (Exception e) {
+    System.err.println("English collation creation failed.");
+    e.printStackTrace();
+}
+```
+
+## GetSortKey
+
+The C API provides the `ucol_getSortKey` function, which requires (apart from a
+pointer to a valid `UCollator` instance), an original `UChar` pointer, together with
+its length. It also requires a pointer to a receiving buffer and its length.
+
+The C++ API provides the `Collator::getSortKey` method with similar parameters as
+the C version. It also provides `Collator::getCollationKey`, which produces a
+`CollationKey` object instance (a wrapper around a sort key).
+
+The Java API provides only the `Collator.getCollationKey` method, which produces a
+`CollationKey` object instance (a wrapper around a sort key).
+
+Sort keys are generally only useful in databases or other circumstances where
+function calls are extremely expensive. See [Sortkeys vs
+Comparison](concepts#sortkeys-vs-comparison).
+
+### Sort Key Features
+
+ICU writes sort keys as sequences of bytes.
+
+Each sort key ends with one 00 byte and does not contain any other 00 byte. The
+terminating 00 byte is included in the length of the sort key as returned by the
+API (unlike any other ICU API where terminating NUL bytes or characters are not
+counted as part of the length).
+
+Sort key byte sequences must be compared with an unsigned-byte comparison, as
+with `strcmp()`.
+
+Comparing the sort keys of two strings from the same collator yields the same
+ordering as using the collator to compare the two strings directly. That is:
+`strcmp(coll.getSortKey(str1), coll.getSortKey(str2))` is equivalent to
+`coll.compare(str1, str2)`.
+
+Sort keys from different collators (different locale or strength or any other
+attributes/settings) are not comparable.
+
+Sort keys can be "merged" as described in [UTS #10 Merging Sort
+Keys](http://www.unicode.org/reports/tr10/#Merging_Sort_Keys), via
+`ucol_mergeSortkeys()` or Java `CollationKey.merge()`.
+
+*   Since CLDR 1.9/ICU 4.6, the same effect can be achieved by concatenating
+    strings with U+FFFE between them. The concatenation has the same sort order
+    as the merged sort keys.
+*   However, it is not guaranteed that the sort key of the concatenated strings
+    is the same as the merged result of the individual sort keys. (That is,
+    merge(getSortKey(str1), getSortKey(str2)) may differ from getSortKey(str1 +
+    '\\uFFFE' + str2).)
+*   In particular, a future version of ICU is likely to generate shorter sort
+    keys when concatenating strings with U+FFFE between them (by using
+    compression across the U+FFFE weights).
+*   *The recommended way to achieve "merged" sorting is via strings with
+    U+FFFE.*
+
+Any further analysis or parsing of sort keys is not supported.
+
+Sort keys will change from one ICU version to another; therefore, if sort keys
+are stored in a database or other persistent storage, then each upgrade requires
+their regeneration.
+
+*   The details of the underlying data change with every Unicode and CLDR
+    version.
+*   Sort keys are also subject to enhancements and bug fixes in the builder and
+    implementation code.
+*   On the other hand, the sort *order* is much more stable. It is subject to
+    deliberate changes to the default Unicode collation order, which is kept
+    quite stable, and subject to deliberate changes in CLDR data as new data is
+    added and feedback on existing data is taken into account.
+
+Implementation notes: (Not supported as permanent constraints on sort keys)
+
+Byte 02 was unique as a merge separator for some versions of ICU before version
+ICU 53. Since ICU 53, 02 is also used in regular collation weights where there
+is no conflict (to expand the number of available short weights).
+
+Byte 01 has been unique as a level separator. This is not strictly necessary for
+non-primary levels. (A level's compressible "common" weight as its level
+separator would yield shorter sort keys.) However, the current implementation of
+`ucol_mergeSortkeys()` relies on it. (Also, test code currently examines sort keys
+for finding the strength of a comparison difference.) This may change in the
+future, especially if `ucol_mergeSortkeys()` were to become deprecated.
+
+Level separators are likely to be equivalent to single-byte weights (possibly
+compressible): Multi-byte level separators would noticeably lengthen sort keys
+for short strings.
+
+The byte values used in several ICU versions for sort keys and collation
+elements are documented in the [“Special Byte Values” design
+doc](https://icu.unicode.org/design/collation/bytes) on the ICU site.
+
+### Sort Key Output Buffer
+
+`ucol_getSortKey()` can operate in 'preflighting' mode, which returns the amount
+of memory needed to store the resulting sort key. This mode is automatically
+activated if the output buffer size passed is set to zero. Should the sort key
+become longer than the buffer provided, function again slips into preflighting
+mode. The overall performance is poorer than if the function is called with a
+zero output buffer. If the size of the sort key returned is greater than the
+size of the buffer provided, the content of the result buffer is undefined. In
+that case, the result buffer could be reallocated to its proper size and the
+sort key generator function can be used again.
+
+The best way to generate a series of sort keys is to do the following:
+
+1.  Create a big temporary buffer on the stack. Typically, this buffer is
+    allocated only once, and reused with every sort key generated. There is no
+    need to keep it as small as possible. A recommended size for the temporary
+    buffer is four times the length of the longest string processed.
+
+2.  Start the loop. Call `ucol_getSortKey()` to find out how big the sort key
+    buffer should be, and fill in the temporary buffer at the same time.
+
+3.  If the temporary buffer is too small, allocate or reallocate more space.
+    Fill in the sort key values in the overflow buffer.
+
+4.  Allocate the sort key buffer with the size returned by `ucol_getSortKey()` and
+    call `memcpy` to copy the sort key content from the temp buffer to the sort
+    key buffer.
+
+5.  Loop back to step 1 until you are done.
+
+6.  Delete the overflow buffer if you created one.
+
+### Example
+
+```c
+void GetSortKeys(const Ucollator* coll, const UChar*
+const *source, uint32_t arrayLength)
+{
+  char[1000] buffer; // allocate stack buffer
+  char* currBuffer = buffer;
+  int32_t bufferLen = sizeof(buffer);
+  int32_t expectedLen = 0;
+  UErrorCode err = U_ZERO_ERROR;
+
+  for (int i = 0; i < arrayLength; ++i) {
+    expectedLen = ucol_getSortKey(coll, source[i], -1, currBuffer, bufferLen);
+    if (expectedLen > bufferLen) {
+      if (currBuffer == buffer) {
+        currBuffer = (char*)malloc(expectedLen);
+      } else {
+        currBuffer = (char*)realloc(currBuffer, expectedLen);
+      }
+    }
+    bufferLen = ucol_getSortKey(coll, source[i], -1, currBuffer, expectedLen);
+  }
+  processSortKey(i, currBuffer, bufferLen);
+
+
+  if (currBuffer != buffer && currBuffer != NULL) {
+    free(currBuffer);
+  }
+}
+```
+
+> :point_right: **Note** Although the API allows you to call
+> `ucol_getSortKey` with `NULL` to see what the
+> sort key length is, it is strongly recommended that you NOT determine the length
+> first, then allocate and fill the sort key buffer. If you do, it requires twice
+> the processing since computing the length has to do the same calculation as
+> actually getting the sort key. Instead, the example shown above uses a stack buffer.
+
+### Using Iterators for String Comparison
+
+ICU4C's `ucol_strcollIter` API allows for comparing two strings that are supplied
+as character iterators (`UCharIterator`). This is useful when you need to compare
+differently encoded strings using `strcoll`. In that case, converting the strings
+first would probably be wasteful, since `strcoll` usually gives the result
+before whole strings are processed. This API is implemented only as a C function
+in ICU4C. There are no equivalent C++ or ICU4J functions.
+
+```c
+...
+/* we are arriving with two char*: utf8Source and utf8Target, with their
+* lengths in utf8SourceLen and utf8TargetLen
+*/
+    UCharIterator sIter, tIter;
+    uiter_setUTF8(&sIter, utf8Source, utf8SourceLen);
+    uiter_setUTF8(&tIter, utf8Target, utf8TargetLen);
+    compareResultUTF8 = ucol_strcollIter(myCollation, &sIter, &tIter, &status);
+...
+```
+
+### Obtaining Partial Sort Keys
+
+When using different sort algorithms, such as radix sort, sometimes it is useful
+to process strings only as much as needed to feed into the sorting algorithm.
+For that purpose, ICU provides the `ucol_nextSortKeyPart` API, which also takes
+character iterators. This API allows for iterating over subsequent pieces of an
+uncompressed sort key. Between calls to the API you need to save a 64-bit state.
+Following is an example of simulating a string compare function using the partial
+sort key API. Your usage model is bound to look much different.
+
+```c
+static UCollationResult compareUsingPartials(UCollator *coll,
+                                             const UChar source[], int32_t sLen,
+                                             const UChar target[], int32_t tLen,
+                                             int32_t pieceSize, UErrorCode *status) {
+  int32_t partialSKResult = 0;
+  UCharIterator sIter, tIter;
+  uint32_t sState[2], tState[2];
+  int32_t sSize = pieceSize, tSize = pieceSize;
+  int32_t i = 0;
+  uint8_t sBuf[16384], tBuf[16384];
+  if(pieceSize > 16384) {
+    *status = U_BUFFER_OVERFLOW_ERROR;
+    return UCOL_EQUAL;
+  }
+  *status = U_ZERO_ERROR;
+  sState[0] = 0; sState[1] = 0;
+  tState[0] = 0; tState[1] = 0;
+  while(sSize == pieceSize && tSize == pieceSize && partialSKResult == 0) {
+    uiter_setString(&sIter, source, sLen);
+    uiter_setString(&tIter, target, tLen);
+    sSize = ucol_nextSortKeyPart(coll, &sIter, sState, sBuf, pieceSize, status);
+    tSize = ucol_nextSortKeyPart(coll, &tIter, tState, tBuf, pieceSize, status);
+    partialSKResult = memcmp(sBuf, tBuf, pieceSize);
+  }
+
+  if(partialSKResult < 0) {
+      return UCOL_LESS;
+  } else if(partialSKResult > 0) {
+    return UCOL_GREATER;
+  } else {
+    return UCOL_EQUAL;
+  }
+}
+```
+
+### Other Examples
+
+A longer example is presented in the 'Examples' section. Here is an illustration
+of the usage model.
+
+**C:**
+
+```c
+#define MAX_KEY_SIZE 100
+#define MAX_BUFFER_SIZE 10000
+#define MAX_LIST_LENGTH 5
+const char text[] = {
+   "Quick",
+   "fox",
+   "Moving",
+   "trucks",
+   "riddle"
+};
+const UChar s [5][20];
+int i;
+int32_t length, expectedLen;
+uint8_t temp[MAX_BUFFER _SIZE];
+
+
+uint8_t *temp2 = NULL;
+uint8_t keys [MAX_LIST_LENGTH][MAX_KEY_SIZE];
+UErrorCode status = U_ZERO_ERROR;
+
+temp2 = temp;
+
+length = MAX_BUFFER_SIZE;
+for( i = 0; i < 5; i++)
+{
+   u_uastrcpy(s[i], text[i]);
+}
+UCollator *coll = ucol_open("en_US",&status);
+uint32_t length;
+if(U_SUCCESS(status)) {
+  for(i=0; i<MAX_LIST_LENGTH; i++) {
+    expectedLen = ucol_getSortKey(coll, s[i], -1,temp2,length );
+    if (expectedLen > length) {
+      if (temp2 == temp) {
+        temp2 =(char*)malloc(expectedLen);
+      } else {
+        temp2 =(char*)realloc(temp2, expectedLen);
+      }
+        length =ucol_getSortKey(coll, s[i], -1, temp2, expectedLen);
+    }
+    memcpy(key[i], temp2, length);
+  }
+}
+qsort(keys, MAX_LIST_LENGTH,MAX_KEY_SIZE*sizeof(uint8_t), strcmp);
+for (i = 0; i < MAX_LIST_LENGTH; i++) {
+  free(key[i]);
+}
+ucol_close(coll);
+```
+
+**C++:**
+
+```c++
+#define MAX_LIST_LENGTH 5
+const UnicodeString s [] = {
+  "Quick",
+  "fox",
+  "Moving",
+  "trucks",
+  "riddle"
+};
+CollationKey *keys[MAX_LIST_LENGTH];
+UErrorCode status = U_ZERO_ERROR;
+Collator *coll = Collator::createInstance(Locale("en_US"), status);
+uint32_t i;
+if(U_SUCCESS(status)) {
+  for(i=0; i<listSize; i++) {
+    keys[i] = coll->getCollationKey(s[i], -1);
+  }
+  qsort(keys, MAX_LIST_LENGTH, sizeof(CollationKey),compareKeys);
+  delete[] keys;
+  delete coll;
+}
+```
+
+**Java:**
+
+```java
+String s [] = {
+  "Quick",
+  "fox",
+  "Moving",
+  "trucks",
+  "riddle"
+};
+CollationKey keys[] = new CollationKey[s.length];
+try {
+    Collator coll = Collator.getInstance(Locale.US);
+    for (int i = 0; i < s.length; i ++) {
+        keys[i] = coll.getCollationKey(s[i]);
+    }
+
+    Arrays.sort(keys);
+}
+catch (Exception e) {
+    System.err.println("Error creating English collator");
+    e.printStackTrace();
+}
+```
+
+## Collation ElementIterator
+
+A collation element iterator can only be used in one direction. This is
+established at the time of the first call to retrieve a collation element. Once
+`ucol_next` (C), `CollationElementIterator::next` (C++) or
+`CollationElementIterator.next` (Java) are invoked,
+`ucol_previous` (C),
+`CollationElementIterator::previous` (C++) or `CollationElementIterator.previous`
+(Java) should not be used (and vice versa). The direction can be changed
+immediately after `ucol_first`, `ucol_last`, `ucol_reset` (in C),
+`CollationElementIterator::first`, `CollationElementIterator::last`,
+`CollationElementIterator::reset` (in C++) or `CollationElementIterator.first`,
+`CollationElementIterator.last`, `CollationElementIterator.reset` (in Java) is
+called, or when it reaches the end of string while traversing the string.
+
+When `ucol_next` is called at the end of the string buffer, `UCOL_NULLORDER` is
+always returned with any subsequent calls to `ucol_next`. The same applies to
+`ucol_previous`.
+
+An example of how iterators are used is the Boyer-Moore search implementation,
+which can be found in the samples section.
+
+### API Example
+
+**C:**
+
+```c
+UCollator         *coll = ucol_open("en_US",status);
+UErrorCode         status = U_ZERO_ERROR;
+UChar              text[20];
+UCollationElements *collelemitr;
+uint32_t           collelem;
+
+u_uastrcpy(text, "text");
+collelemitr = ucol_openElements(coll, text, -1, &status);
+collelem = 0;
+do {
+  collelem = ucol_next(collelemitr, &status);
+} while (collelem != UCOL_NULLORDER);
+
+ucol_closeElements(collelemitr);
+ucol_close(coll);
+```
+
+**C++:**
+
+```c++
+UErrorCode    status = U_ZERO_ERROR;
+Collator      *coll = Collator::createInstance(Locale::getUS(), status);
+UnicodeString text("text");
+CollationElementIterator *collelemitr = coll->createCollationElementIterator(text);
+uint32_t      collelem = 0;
+do {
+  collelem = collelemitr->next(status);
+} while (collelem != CollationElementIterator::NULLORDER);
+
+delete collelemitr;
+delete coll;
+```
+
+**Java:**
+
+```java
+try {
+    RuleBasedCollator coll = (RuleBasedCollator)Collator.getInstance(Locale.US);
+    String text = "text";
+    CollationElementIterator collelemitr = coll.getCollationElementIterator(text);
+    int collelem = 0;
+    do {
+        collelem = collelemitr.next();
+    } while (collelem != CollationElementIterator.NULLORDER);
+} catch (Exception e) {
+    System.err.println("Error in collation iteration");
+    e.printStackTrace();
+}
+```
+
+## Setting and Getting Attributes
+
+The general attribute setting APIs are `ucol_setAttribute` (in C) and
+`Collator::setAttribute` (in C++). These APIs take an attribute name and an
+attribute value. If the name and the value pass a syntax and range check, the
+property of the collator is changed. If the name and value do not pass a syntax
+and range check, however, the state is not changed and the error code variable
+is set to an error condition. The Java version does not provide general
+attribute setting APIs; instead, each attribute has its own setter API of
+the form `RuleBasedCollator.setATTRIBUTE_NAME(arguments)`.
+
+The attribute getting APIs are `ucol_getAttribute` (C) and `Collator::getAttribute`
+(C++). Both APIs require an attribute name as an argument and return an
+attribute value if a valid attribute name was supplied. If a valid attribute
+name was not supplied, however, they return an undefined result and set the
+error code. Similarly to the setter APIs for the Java version, no generic getter
+API is provided. Each attribute has its own setter API of the form
+`RuleBasedCollator.getATTRIBUTE_NAME()` in the Java version.
+
+## References
+
+1.  Ken Whistler, Markus Scherer: "Unicode Technical Standard #10, Unicode Collation
+    Algorithm" (<http://www.unicode.org/reports/tr10/>)
+
+2.  ICU Design doc: "Collation v2" (<https://icu.unicode.org/design/collation/v2>)
+
+3.  Mark Davis: "ICU Collation Design Document"
+    (<https://htmlpreview.github.io/?https://github.com/unicode-org/icu-docs/blob/main/design/collation/ICU_collation_design.htm>)
+
+3.  The Unicode Standard, chapter 5, "Implementation guidelines"
+    (<http://www.unicode.org/uni2book/ch05.pdf>)
+
+4.  Laura Werner: "Efficient text searching in Java: Finding the right string in
+    any language"
+    (<http://icu-project.org/docs/papers/efficient_text_searching_in_java.html>)
+
+5.  Mark Davis, Martin Dürst: "Unicode Standard Annex #15: Unicode Normalization
+    Forms" (<http://www.unicode.org/reports/tr15/>).

docs/userguide/collation/architecture.md

@@ -0,0 +1,579 @@
+---
+layout: default
+title: Architecture
+nav_order: 2
+parent: Collation
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Collation Service Architecture
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+This section describes the design principles, architecture and coding
+conventions of the ICU Collation Service.
+
+## Collator
+
+To use the Collation Service, a Collator must first be instantiated. An
+Collator is a data structure or object that maintains all of the property
+and state information necessary to define and support the specific collation
+behavior provided. Examples of properties described in the Collator are the
+locale, whether normalization is to be performed, and how many levels of
+collation are to be evaluated. Examples of the state information described in
+the Collator include the direction of a Collation Element Iterator (forward
+or backward) and the status of the last API executed.
+
+The Collator is instantiated either by referencing a locale or by defining a
+custom set of rules (a tailoring).
+
+The Collation Service uses the paradigm:
+
+1.  Open a Collator,
+
+2.  Use while necessary,
+
+3.  Close the Collator.
+
+Collator instances cannot be shared among threads. You should open them
+instead, and use a different collator for each separate thread. The safe clone
+function is supported for cloning collators in a thread-safe fashion.
+
+The Collation Service follows the ICU conventions for locale designation
+when opening collators:
+
+1.  NULL means the default locale.
+
+2.  The empty locale name ("") means the root locale.
+    The Collation Service adheres to the ICU conventions described in the
+    "[ICU Architectural Design](../design.md) " section of the users guide.
+    In particular:
+
+3.  The standard error code convention is usually followed. (Functions that do
+    not take an error code parameter do so for backward compatibility.)
+
+4.  The string length convention is followed: when passing a `UChar *`, the
+    length is required in a separate argument. If -1 is passed for the length,
+    it is assumed that the string is zero terminated.
+
+### Collation locale and keyword handling
+
+When a collator is created from a locale, the collation service (like all ICU
+services) must map the requested locale to the localized collation data
+available to ICU at the time. It does so using the standard ICU locale fallback
+mechanism. See the fallback section of the [locale
+chapter](../locale/index.md) for more details.
+
+If you pass a regular locale in, like "en_US", the collation service first
+searches with fallback for "collations/default" key. The first such key it finds
+will have an associated string value; this is the keyword name for the collation
+that is default for this locale. If the search falls all the way back to the
+root locale, the collation service will us the "collations/default" key there,
+which has the value "standard".
+
+If there is a locale with a keyword, like "de-u-co-phonebk" or "de@collation=phonebook", the
+collation service searches with fallback for "collations/phonebook". If the
+search is successful, the collation service uses the string value it finds to
+instantiate a Collator. If the search fails because no such key is present in
+any of ICU's locale data (e.g., "de@collation=funky"), the service returns a
+collator implementing the default tailoring of the locale.
+If the fallback is all the way to the root locale, then
+the return `UErrorCode` is `U_USING_DEFAULT_WARNING`.
+
+## Input values for collation
+
+Collation deals with processing strings. ICU generally requires that all the
+strings should be in UTF-16 format, and that all the required conversion should
+done before ICU functions are used. In the case of collation, there are APIs
+that can also take instances of character iterators (`UCharIterator`)
+or UTF-8 directly.
+
+Theoretically, character iterators can iterate strings
+in any encoding. ICU currently provides character iterator implementations for
+UTF-8 and UTF-16BE (useful when processing data from a big endian platform on an
+little endian machine). It should be noted, however, that using iterators for
+collation APIs has a performance impact. It should be used in situations when it
+is not desirable to convert whole strings before the operation - such as when
+using a string compare function.
+
+## Collation Elements
+
+As discussed in the introduction, there are many possible orderings for sorted
+text, depending on language and other factors. Ideally, there is a way to
+describe each ordering as a set of rules for calculating numeric values for each
+string of text. The collation process then becomes one of simply comparing these
+numeric values.
+
+This essentially describes the way the Collation Service works. To implement
+a particular sort ordering, first the relationship between each character or
+character sequence is derived. For example, a Spanish ordering defines the
+letter sequence "CH" to be between the letters "C" and "D". As also discussed in
+the introduction, to order strings properly requires that comparison of base
+letters must be considered separately from comparison of accents. Letter case
+must also be considered separately from either base letters or accents. Any
+ordering specification language must provide a way to define the relationships
+between characters or character sequences on multiple levels. ICU supports this
+by using "<" to describe a relationship at the primary level, using "<<" to
+describe a relationship at the secondary level, and using "<<<" to describe a
+relationship at the tertiary level. Here are some example usages:
+
+Symbol | Example  | Description
+------ | -------- | -----------
+`<`    | `c < ch` | Make a primary (base letter) difference between "c" and the character sequence "ch"
+`<<`   | `a << ä` | Make a secondary (accent) difference between "a" and "ä"
+`<<<`  | `a<<<A`  | Make a tertiary difference between "a" and "A"
+
+A more complete description of the ordering specification symbols and their
+meanings is provided in the section on Collation Tailoring.
+
+Once a sort ordering is defined by specifying the desired relationships between
+characters and character sequences, ICU can convert these relationships to a
+series of numerical values (one for each level) that satisfy these same
+relationships.
+
+This series of numeric values, representing the relative weighting of a
+character or character sequence, is called a Collation Element (CE).
+One possible encoding of a Collation Element is a 32-bit value consisting of
+a 16-bit primary weight, a 8-bit secondary weight,
+2 case bits, and a 6-bit tertiary weight.
+
+The sort weight of a string is represented by the collation elements of its
+component characters and character sequences. For example, the sort weight of
+the string "apple" would consist of its component Collation Elements, as shown
+here:
+
+"Apple" | "Apple" Collation Elements
+------- | --------------------------
+a       | `[1900.05.05]`
+p       | `[3700.05.05]`
+p       | `[3700.05.05]`
+l       | `[2F00.05.05]`
+e       | `[2100.05.05]`
+
+In this example, the letter "a" has a 16-bit primary weight of 1900 (hex), an
+8-bit secondary weight of 05 (hex), and a combined 8-bit case-tertiary weight of
+05 (hex).
+
+String comparison is performed by comparing the collation elements of each
+string. Each of the primary weights are compared. If a difference is found, that
+difference determines the relationship between the two strings. If no
+differences are found, the secondary weights are compared and so forth.
+
+With ICU it is possible to specify how many levels should be compared. For some
+applications, it can be desirable to compare only primary levels or to compare
+only primary and secondary levels.
+
+## Sort Keys
+
+If a string is to be compared thousands or millions of times,
+it can be more efficient to use sort keys.
+Sort keys are useful in situations where a large amount of data is indexed
+and frequently searched. The sort key is generated once and used in subsequent
+comparisons, rather than repeatedly generating the string's Collation Elements.
+The comparison of sort keys is a very efficient and simple binary compare of strings of
+unsigned bytes.
+
+An important property of ICU sort keys is that you can obtain the same results
+by comparing 2 strings as you do by comparing the sort keys of the 2 strings
+(provided that the same ordering and related collation attributes are used).
+
+An ICU sort key is a pre-processed sequence of bytes generated from a Unicode
+string. The weights for each comparison level are concatenated, separated by a
+"0x01" byte between levels.
+The entire sequence is terminated with a 0x00 byte for convenience in C APIs.
+(This 0x00 terminator is counted in the sort key length —
+unlike regular strings where the NUL terminator is excluded from the string length.)
+
+ICU actually compresses the sort keys so that they take the
+minimum storage in memory and in databases.
+
+<!-- TODO: (diagram was missing in Google Sites already)
+    The diagram below represents an uncompressed sort key in ICU for ease of understanding.  -->
+
+### Sort key size
+
+One of the more important issues when considering using sort keys is the sort
+key size. Unfortunately, it is very hard to give a fast exact answer to the
+following question: "What is the maximum size for sort keys generated for
+strings of size X". This problem is twofold:
+
+1.  The maximum size of the sort key depends on the size of the collation
+    elements that are used to build it. Size of collation elements vary greatly
+    and depends both on the alphabet in question and on the locale used.
+
+2.  Compression is used in building sort keys. Most 'regular' sequences of
+    characters produce very compact sort keys.
+
+If one is to assume the worst case and use too-big buffers, a lot of space will
+be wasted. However, if you use too-small buffers, you will lose performance if
+generated sort keys are longer than supplied buffers too often
+(and you have to reallocate for each of those).
+A good strategy
+for this problem would be to manually manage a large buffer for storing sortkeys
+and keep a list of indices to sort keys in this buffer (see the "large buffers"
+[Collation Example](examples#using-large-buffers-to-manage-sort-keys)
+for more details).
+
+Here are some rules of a thumb, please do not rely on them. If you are looking
+at the East Asian locales, you probably want to go with 5 bytes per code point.
+For Thai, 3 bytes per code point should be sufficient. For all the other locales
+(mostly Latin and Cyrillic), you should be fine with 2 bytes per code point.
+These values are based on average lengths of sort keys generated with tertiary
+strength. If you need quaternary and identical strength (you should not), add 3
+bytes per code point to each of these.
+
+### Partial sort keys
+
+In some cases, most notably when implementing [radix
+sorting](http://en.wikipedia.org/wiki/Radix_sort), it is useful to produce only
+parts of sort keys at a time. ICU4C 2.6+ provides an API that allows producing
+parts of sort keys (`ucol_nextSortKeyPart` API). These sort keys may or may not be
+compressed; that is, they may or may not be compatible with regular sort keys.
+
+### Merging sort keys
+
+Sometimes, it is useful to be able to merge sort keys. One example is having
+separate sort keys for first and last names. If you need to perform an operation
+that requires a sort key generated on the whole name, instead of concatenating
+strings and regenerating sort keys, you should merge the sort keys. The merging
+is done by merging the corresponding levels while inserting a terminator between
+merged parts. The reserved sort key byte value for the merge terminator is 0x02.
+For more details see [UCA section 1.6, Merging Sort
+Keys](http://www.unicode.org/reports/tr10/#Interleaved_Levels).
+
+*   C API: unicode/ucol.h `ucol_mergeSortkeys()`
+*   Java API: `com.ibm.icu.text.CollationKey merge(CollationKey source)`
+
+CLDR 1.9/ICU 4.6 and later map U+FFFE to a special collation element that is
+intended to allow concatenating strings like firstName+\\uFFFE+lastName to yield
+the same results as merging their individual sort keys.
+This has been fully implemented in ICU since version 53.
+
+### Generating bounds for a sort key (prefix matching)
+
+Having sort keys for strings allows for easy creation of bounds - sort keys that
+are guaranteed to be smaller or larger than any sort key from a give range. For
+example, if bounds are produced for a sortkey of string "smith", strings between
+upper and lower bounds with one level would include "Smith", "SMITH", "sMiTh".
+Two kinds of upper bounds can be generated - the first one will match only
+strings of equal length, while the second one will match all the strings with
+the same initial prefix.
+
+CLDR 1.9/ICU 4.6 and later map U+FFFF to a collation element with the maximum
+primary weight, so that for example the string "smith\\uFFFF" can be used as the
+upper bound rather than modifying the sort key for "smith".
+
+## Collation Element Iterator
+
+The collation element iterator is used for traversing Unicode string collation
+elements one at a time. It can be used to implement language-sensitive text
+search algorithms like Boyer-Moore.
+
+For most applications, the two API categories, compare and sort key, are
+sufficient. Most people do not need to manipulate collation elements directly.
+
+Example:
+
+Consider iterating over "apple" and "äpple". Here are sequences of collation
+elements:
+
+String 1 | String 1 Collation Elements
+-------- | ---------------------------
+a        | `[1900.05.05]`
+p        | `[3700.05.05]`
+p        | `[3700.05.05]`
+l        | `[2F00.05.05]`
+e        | `[2100.05.05]`
+
+String 2 | String 2 Collation Elements
+-------- | ---------------------------
+a        | `[1900.05.05]`
+\\u0308  | `[0000.9D.05]`
+p        | `[3700.05.05]`
+p        | `[3700.05.05]`
+l        | `[2F00.05.05]`
+e        | `[2100.05.05]`
+
+The resulting CEs are typically masked according to the desired strength, and
+zero CEs are discarded. In the above example, masking with 0xFFFF0000 (for primary strength)
+produces the results of NULL secondary and tertiary differences. The collator then
+ignores the NULL differences and declares a match. For more details see the
+paper "Efficient text searching in Java™: Finding the right string in any
+language" by Laura Werner (
+<http://icu-project.org/docs/papers/efficient_text_searching_in_java.html>).
+
+## Collation Attributes
+
+The Collation Service has a number of attributes whose values can be changed
+during run time. These attributes affect both the functionality and the
+performance of the Collation Service. This section describes these
+attributes and, where possible, their performance impact. Performance
+indications are only approximate and timings may vary significantly depending on
+the CPU, compiler, etc.
+
+Although string comparison by ICU and comparison of each string's sort key give
+the same results, attribute settings can impact the execution time of each
+method differently. To be precise in the discussion of performance, this section
+refers to the API employed in the measurement. The `ucol_strcoll` function is the
+API for string comparison. The `ucol_getSortKey` function is used to create sort
+keys.
+
+> :point_right: **Note** There is a special attribute value, `UCOL_DEFAULT`,
+> that can be used to set any attribute to its default value
+> (which is inherited from the UCA and the tailoring).
+
+### Attribute Types
+
+#### Strength level
+
+Collation strength, or the maximum collation level used for comparison, is set
+by using the `UCOL_STRENGTH` attribute. Valid values are:
+
+1.  `UCOL_PRIMARY`
+
+2.  `UCOL_SECONDARY`
+
+3.  `UCOL_TERTIARY` (default)
+
+4.  `UCOL_QUATERNARY`
+
+5.  `UCOL_IDENTICAL`
+
+#### French collation
+
+The `UCOL_FRENCH_COLLATION` attribute determines whether to sort the secondary
+differences in reverse order. Valid values are:
+
+1.  `UCOL_OFF` (default): compares secondary differences in the order they appear
+    in the string.
+
+2.  `UCOL_ON`: causes secondary differences to be considered in reverse order, as
+    it is done in the French language.
+
+#### Normalization mode
+
+The `UCOL_NORMALIZATION_MODE` attribute, or its alias `UCOL_DECOMPOSITION_MODE`,
+controls whether text normalization is performed on the input strings. Valid
+values are:
+
+1.  `UCOL_OFF` (default): turns off normalization check
+
+2.  `UCOL_ON` : normalization is checked and the collator performs normalization
+    if it is needed.
+
+X                     | FCD | NFC | NFD
+--------------------- | --- | --- | ---
+A-ring                | Y   | Y   |
+Angstrom              | Y   |     |
+A + ring              | Y   |     | Y
+A + grave             | Y   | Y   |
+A-ring + grave        | Y   |     |
+A + cedilla + ring    | Y   |     | Y
+A + ring + cedilla    |     |     |
+A-ring + cedilla      |     | Y   |
+
+With normalization mode turned on, the `ucol_strcoll` function slows down by 10%.
+In addition, the time to generate a sort key also increases by about 25%.
+
+#### Alternate handling
+
+This attribute allows shifting of the variable characters (usually spaces and
+punctuation, in the UCA also most symbols) from the primary to the quaternary
+strength level. This is set by using the `UCOL_ALTERNATE_HANDLING` attribute. For
+details see [UCA: Variable
+Weighting](http://www.unicode.org/reports/tr10/#Variable_Weighting), [LDML:
+Collation
+Settings](http://www.unicode.org/reports/tr35/tr35-collation.html#Collation_Settings),
+and [“Ignore Punctuation” Options](customization/ignorepunct.md).
+
+1.  `UCOL_NON_IGNORABLE` (CLDR/ICU default): variable characters are treated as
+    all the other characters
+
+2.  `UCOL_SHIFTED` (UCA default): all the variable characters will be ignored at
+    the primary, secondary and tertiary levels and their primary strengths will
+    be shifted to the quaternary level.
+
+#### Case Ordering
+
+Some conventions require uppercase letters to sort before lowercase ones, while
+others require the opposite. This attribute is controlled by the value of the
+`UCOL_CASE_FIRST`. The case difference in the UCA is contained in the tertiary
+weights along with other appearance characteristics (like circling of letters).
+The case-first attribute allows for emphasizing of the case property of the
+letters by reordering the tertiary weights with either upper-first, and/or
+lowercase-first. This difference gets the most significant bit in the weight.
+Valid values for this attribute are:
+
+1.  `UCOL_OFF` (default): leave tertiary weights unaffected
+
+2.  `UCOL_LOWER_FIRST`: causes lowercase letters and uncased characters to sort
+    before uppercase
+
+3.  `UCOL_UPPER_FIRST` : causes uppercase letters to sort first
+
+The case-first attribute does not affect the performance substantially.
+
+#### Case level
+
+When this attribute is set, an additional level is formed between the secondary
+and tertiary levels, known as the Case Level. The case level is used to
+distinguish large and small Japanese Kana characters. Case level could also be
+used in other situations. for example to distinguish certain Pinyin characters.
+Case level is controlled by `UCOL_CASE_LEVEL` attribute. Valid values for this
+attribute are
+
+1.  `UCOL_OFF` (default): no additional case level
+
+2.  `UCOL_ON` : adds a case level
+
+#### Hiragana Quaternary
+
+*This setting is deprecated and ignored in recent versions of ICU.*
+
+Hiragana Quaternary can be set to `UCOL_ON`, in which case Hiragana code points
+will sort before everything else on the quaternary level. If set to `UCOL_OFF`
+Hiragana letters are treated the same as all the other code points. This setting
+can be changed on run-time using the `UCOL_HIRAGANA_QUATERNARY_MODE` attribute.
+You probably won't need to use it.
+
+#### Variable Top
+
+Variable Top is a boundary which decides whether the code points will be treated
+as variable (shifted to quaternary level in the **shifted** mode) or
+non-ignorable. Special APIs are used for setting of variable top. It can
+basically be set either to a codepoint or a primary strength value.
+
+## Performance
+
+ICU collation is designed to be fast, small and customizable. Several techniques
+are used to enhance the performance:
+
+1.  Providing optimized processing for Latin characters.
+
+2.  Comparing strings incrementally and stopping at the first significant
+    difference.
+
+3.  Tuning to eliminate unnecessary file access or memory allocation.
+
+4.  Providing efficient preflight functions that allows fast sort key size
+    generation.
+
+5.  Using a single, shared copy of UCA in memory for the read-only default sort
+    order. Only small tailoring tables are kept in memory for locale-specific
+    customization.
+
+6.  Compressing sort keys efficiently.
+
+7.  Making the sort order be data-driven.
+
+In general, the best performance from the Collation Service is expected by
+doing the following:
+
+1.  After opening a collator, keep and reuse it until done. Do not open new
+    collators for the same sort order. (Note the restriction on
+    multi-threading.)
+
+2.  Use `ucol_strcoll` etc. when comparing strings. If it is necessary to
+    compare strings thousands or millions of times,
+    create the sort keys first and compare the sort keys instead.
+    Generating the sort keys of two strings is about 5-10
+    times slower than just comparing them directly.
+
+3.  Follow the best practice guidelines for generating sort keys. Do not call
+    `ucol_getSortKey` twice to first size the key and then allocate the sort key
+    buffer and repeat the call to the function to fill in the buffer.
+
+### Performance and Storage Implications of Attributes
+
+Most people use the default attributes when comparing strings or when creating
+sort keys. When they do want to customize the ordering, the most common options
+are the following :
+
+`UCOL_ALTERNATE_HANDLING == UCOL_SHIFTED`\
+Used to ignore space and punctuation characters
+
+`UCOL_ALTERNATE_HANDLING == UCOL_SHIFTED` **and** `UCOL_STRENGTH == UCOL_QUATERNARY`\
+Used to ignore the space and punctuation characters except when there are no previous letter, accent, or case/variable differences.
+
+`UCOL_CASE_FIRST == UCOL_LOWER_FIRST` **or** `UCOL_CASE_FIRST == UCOL_UPPER_FIRST`\
+Used to change the ordering of upper vs. lower case letters (as
+well as small vs. large kana)
+
+`UCOL_CASE_LEVEL == UCOL_ON` **and** `UCOL_STRENGTH == UCOL_PRIMARY`\
+Used to ignore only the accent differences.
+
+`UCOL_NORMALIZATION_MODE == UCOL_ON`\
+Force to always check for normalization. This
+is used if the input text may not be in FCD form.
+
+`UCOL_FRENCH_COLLATION == UCOL_OFF`\
+This is only useful for languages like French and Catalan that may turn this attribute on.
+(It is the default only for Canadian French ("fr-CA").)
+
+In String Comparison, most of these options have little or no effect on
+performance. The only noticeable one is normalization, which can cost 10%-40% in
+performance.
+
+For Sort Keys, most of these options either leave the storage alone or reduce
+it. Shifting can reduce the storage by about 10%-20%; case level + primary-only
+can decrease it about 20% to 40%. Using no French accents can reduce the storage
+by about 38% , but only for languages like French and Catalan that turn it on by
+default. On the other hand, using Shifted + Quaternary can increase the storage by
+10%-15%. (The Identical Level also increases the length, but this option is not
+recommended).
+
+> :point_right: **Note** All of the above numbers are based on
+> tests run on a particular machine, with a particular set of data.
+> (The data for each language is a large number of names
+> in that language in the format <first_name>, <last name>.)
+> The performance and storage may vary, depending on the particular computer,
+> operating system, and data.
+
+## Versioning
+
+Sort keys are often stored on disk for later reuse. A common example is the use
+of keys to build indexes in databases. When comparing keys, it is important to
+know that both keys were generated by the same algorithms and weightings.
+Otherwise, identical strings with keys generated on two different dates, for
+example, might compare as unequal. Sort keys can be affected by new versions of
+ICU or its data tables, new sort key formats, or changes to the Collator.
+Starting with release 1.8.1, ICU provides a versioning mechanism to identify the
+version information of the following (but not limited to),
+
+1.  The run-time executable
+
+2.  The collation element content
+
+3.  The Unicode/UCA database
+
+4.  The tailoring table
+
+The version information of Collator is a 32-bit integer. If a new version of ICU
+has changes affecting the content of collation elements, the version information
+will be changed. In that case, to use the new version of ICU collator will
+require regenerating any saved or stored sort keys.
+
+However, it is possible to modify ICU code or data without changing relevant version numbers,
+so it is safer to regenerate sort keys any time after any part of ICU has been updated.
+
+Since ICU4C 1.8.1.
+it is possible to build your program so that it uses more than one version of
+ICU (only in C/C++, not in Java). Therefore, you could use the current version
+for the features you need and use the older version for collation.
+
+## Programming Examples
+
+See the [Collation Examples](examples.md) chapter for an example of how to
+compare and create sort keys with the default locale in C, C++ and Java.

docs/userguide/collation/concepts.md

@@ -0,0 +1,831 @@
+---
+layout: default
+title: Concepts
+nav_order: 1
+parent: Collation
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Collation Concepts
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+The previous section demonstrated many of the requirements imposed on string
+comparison routines that try to correctly collate strings according to
+conventions of more than a hundred different languages, written in many
+different scripts. This section describes the principles and architecture behind
+the ICU Collation Service.
+
+## Sortkeys vs Comparison
+
+Sort keys are most useful in databases, where the overhead of calling a function
+for each comparison is very large.
+
+Generating a sort key from a Collator is many times more expensive than doing a
+compare with the Collator (for common use cases). That's if the two functions
+are called from Java or C. So for those languages, unless there is a very large
+number of comparisons, it is better to call the compare function.
+
+Here is an example, with a little back-of-the-envelope calculation. Let's
+suppose that with a given language on a given platform, the compare performance
+(CP) is 100 faster than sortKey performance (SP), and that you are doing a
+binary search of a list with 1,000 elements. The binary comparison performance
+is BP. We'd do about 10 comparisons, getting:
+
+compare: 10 \* CP
+
+sortkey: 1 \* SP + 10 \* BP
+
+Even if BP is free, compare would be better. One has to get up to where log2(n)
+= 100 before they break even.
+
+But even this calculation is only a rough guide. First, the binary comparison is
+not completely free. Secondly, the performance of compare function varies
+radically with the source data. We optimized for maximizing performance of
+collation in sorting and binary search, so comparing strings that are "close" is
+optimized to be much faster than comparing strings that are "far away". That
+optimization is important because normal sort/lookup operations compare close
+strings far more often -- think of binary search, where the last few comparisons
+are always with the closest strings. So even the above calculation is not very
+accurate.
+
+## Comparison Levels
+
+In general, when comparing and sorting objects, some properties can take
+precedence over others. For example, in geometry, you might consider first the
+number of sides a shape has, followed by the number of sides of equal length.
+This causes triangles to be sorted together, then rectangles, then pentagons,
+etc. Within each category, the shapes would be ordered according to whether they
+had 0, 2, 3 or more sides of the same length. However, this is not the only way
+the shapes can be sorted. For example, it might be preferable to sort shapes by
+color first, so that all red shapes are grouped together, then blue, etc.
+Another approach would be to sort the shapes by the amount of area they enclose.
+
+Similarly, character strings have properties, some of which can take precedence
+over others. There is more than one way to prioritize the properties.
+
+For example, a common approach is to distinguish characters first by their
+unadorned base letter (for example, without accents, vowels or tone marks), then
+by accents, and then by the case of the letter (upper vs. lower). Ideographic
+characters might be sorted by their component radicals and then by the number of
+strokes it takes to draw the character.
+An alternative ordering would be to sort these characters by strokes first and
+then by their radicals.
+
+The ICU Collation Service supports many levels of comparison (named "Levels",
+but also known as "Strengths"). Having these categories enables ICU to sort
+strings precisely according to local conventions. However, by allowing the
+levels to be selectively employed, searching for a string in text can be
+performed with various matching conditions.
+
+Performance optimizations have been made for ICU collation with the default
+level settings. Performance specific impacts are discussed in the Performance
+section below.
+
+Following is a list of the names for each level and an example usage:
+
+1.  Primary Level: Typically, this is used to denote differences between base
+    characters (for example, "a" < "b"). It is the strongest difference. For
+    example, dictionaries are divided into different sections by base character.
+    This is also called the level-1 strength.
+
+2.  Secondary Level: Accents in the characters are considered secondary
+    differences (for example, "as" < "às" < "at"). Other differences between
+    letters can also be considered secondary differences, depending on the
+    language. A secondary difference is ignored when there is a primary
+    difference anywhere in the strings. This is also called the level-2
+    strength.
+    Note: In some languages (such as Danish), certain accented letters are
+    considered to be separate base characters. In most languages, however, an
+    accented letter only has a secondary difference from the unaccented version
+    of that letter.
+
+3.  Tertiary Level: Upper and lower case differences in characters are
+    distinguished at the tertiary level (for example, "ao" < "Ao" < "aò"). In
+    addition, a variant of a letter differs from the base form on the tertiary
+    level (such as "A" and "Ⓐ"). Another example is the difference between large
+    and small Kana. A tertiary difference is ignored when there is a primary or
+    secondary difference anywhere in the strings. This is also called the
+    level-3 strength.
+
+4.  Quaternary Level: When punctuation is ignored (see Ignoring Punctuations
+    (§)) at level 1-3, an additional level can be used to distinguish words with
+    and without punctuation (for example, "ab" < "a-b" < "aB"). This difference
+    is ignored when there is a primary, secondary or tertiary difference. This
+    is also known as the level-4 strength. The quaternary level should only be
+    used if ignoring punctuation is required or when processing Japanese text
+    (see Hiragana processing (§)).
+
+5.  Identical Level: When all other levels are equal, the identical level is
+    used as a tiebreaker. The Unicode code point values of the NFD form of each
+    string are compared at this level, just in case there is no difference at
+    levels 1-4. For example, Hebrew cantillation marks are only distinguished
+    at this level. This level should be used sparingly, as only code point
+    value differences between two strings is an extremely rare occurrence.
+    Using this level substantially decreases the performance for
+    both incremental comparison and sort key generation (as well as increasing
+    the sort key length). It is also known as level 5 strength.
+
+## Backward Secondary Sorting
+
+Some languages require words to be ordered on the secondary level according to
+the *last* accent difference, as opposed to the *first* accent difference. This
+was previously the default for all French locales, based on some French
+dictionary ordering traditions, but is currently only applicable to Canadian
+French (locale **fr_CA**), for conformance with the [Canadian sorting
+standard](http://www.unicode.org/reports/tr10/#CanStd). The difference in
+ordering is only noticeable for a small number of pairs of real words. For more
+information see [UCA: Contextual
+Sensitivity](http://www.unicode.org/reports/tr10/#Contextual_Sensitivity).
+
+Example:
+
+Forward secondary | Backward secondary
+----------------- | ------------------
+cote              | cote
+coté              | côte
+côte              | coté
+côté              | côté
+
+## Contractions
+
+A contraction is a sequence consisting of two or more letters. It is considered
+a single letter in sorting.
+
+For example, in the traditional Spanish sorting order, "ch" is considered a
+single letter. All words that begin with "ch" sort after all other words
+beginning with "c", but before words starting with "d".
+
+Other examples of contractions are "ch" in Czech, which sorts after "h", and
+"lj" and "nj" in Croatian and Latin Serbian, which sort after "l" and "n"
+respectively.
+
+Example:
+
+Order without contraction | Order with contraction "lj" sorting after letter "l"
+------------------------- | ----------------------------------------------------
+la                        | la
+li                        | li
+lj                        | lk
+lja                       | lz
+ljz                       | lj
+lk                        | lja
+lz                        | ljz
+ma                        | ma
+
+Contracting sequences such as the above are not very common in most languages.
+
+> :point_right: **Note** Since ICU 2.2, and as required by the UCA,
+> if a completely ignorable code point
+> appears in text in the middle of contraction, it will not break the contraction.
+> For example, in Czech sorting, cU+0000h will sort as it were ch.
+
+## Expansions
+
+If a letter sorts as if it were a sequence of more than one letter, it is called
+an expansion.
+
+For example, in German phonebook sorting (de@collation=phonebook or BCP 47
+de-u-co-phonebk), "ä" sorts as though it were equivalent to the sequence "ae."
+All words starting with "ä" will sort between words starting with "ad" and words
+starting with "af".
+
+In the case of Unicode encoding, characters can often be represented either as
+pre-composed characters or in decomposed form. For example, the letter "à" can
+be represented in its decomposed (a+\`) and pre-composed (à) form. Most
+applications do not want to distinguish text by the way it is encoded. A search
+for "à" should find all instances of the letter, regardless of whether the
+instance is in pre-composed or decomposed form. Therefore, either form of the
+letter must result in the same sort ordering. The architecture of the ICU
+Collation Service supports this.
+
+## Contractions Producing Expansions
+
+It is possible to have contractions that produce expansions.
+
+One example occurs in Japanese, where the vowel with a prolonged sound mark is
+treated to be equivalent to the long vowel version:
+
+カアー<<< カイー and\
+キイー<<< キイー
+
+> :point_right: **Note** Since ICU 2.0 Japanese tailoring uses
+> [prefix analysis](http://www.unicode.org/reports/tr35/tr35-collation.html#Context_Sensitive_Mappings)
+> instead of contraction producing expansions.
+
+## Normalization
+
+In the section on expansions, we discussed that text in Unicode can often be
+represented in either pre-composed or decomposed forms. There are other types of
+equivalences possible with Unicode, including Canonical and Compatibility. The
+process of
+Normalization ensures that text is written in a predictable way so that searches
+are not made unnecessarily complicated by having to match on equivalences. Not
+all text is normalized, however, so it is useful to have a collation service
+that can address text that is not normalized, but do so with efficiency.
+
+The ICU Collation Service handles un-normalized text properly, producing the
+same results as if the text were normalized.
+
+In practice, most data that is encountered is in normalized or semi-normalized
+form already. The ICU Collation Service is designed so that it can process a
+wide range of normalized or un-normalized text without a need for normalization
+processing. When a case is encountered that requires normalization, the ICU
+Collation Service drops into code specific to this purpose. This maximizes
+performance for the majority of text that does not require normalization.
+
+In addition, if the text is known with certainty not to contain un-normalized
+text, then even the overhead of checking for normalization can be eliminated.
+The ICU Collation Service has the ability to turn Normalization Checking either
+on or off. If Normalization Checking is turned off, it is the user's
+responsibility to insure that all text is already in the appropriate form. This
+is true in a great majority of the world languages, so normalization checking is
+turned off by default for most locales.
+
+If the text requires normalization processing, Normalization Checking should be
+on. Any language that uses multiple combining characters such as Arabic, ancient
+Greek, Hebrew, Hindi, Thai or Vietnamese either requires Normalization Checking
+to be on, or the text to go through a normalization process before collation.
+
+For more information about Normalization related reordering please see
+[Unicode Technical Note #5](http://www.unicode.org/notes/tn5/) and
+[UAX #15.](http://www.unicode.org/reports/tr15/)
+
+> :point_right: **Note** ICU supports two modes of normalization: on and off.
+> Java.text.\* classes offer compatibility decomposition mode, which is not supported in ICU.
+
+## Ignoring Punctuation
+
+In some cases, punctuation can be ignored while searching or sorting data. For
+example, this enables a search for "biweekly" to also return instances of
+"bi-weekly". In other cases, it is desirable for punctuated text to be
+distinguished from text without punctuation, but to have the text sort close
+together.
+
+These two behaviors can be accomplished if there is a way for a character to be
+ignored on all levels except for the quaternary level. If this is the case, then
+two strings which compare as identical on the first three levels (base letter,
+accents, and case) are then distinguished at the fourth level based on their
+punctuation (if any). If the comparison function ignores differences at the
+fourth level, then strings that differ by punctuation only are compared as
+equal.
+
+The following table shows the results of sorting a list of terms in 3 different
+ways. In the first column, punctuation characters (space " ", and hyphen "-")
+are not ignored (" " < "-" < "b"). In the second column, punctuation characters
+are ignored in the first 3 levels and compared only in the fourth level. In the
+third column, punctuation characters are ignored in the first 3 levels and the
+fourth level is not considered. In the last column, punctuated terms are
+equivalent to the identical terms without punctuation.
+
+For more options and details see the [“Ignore Punctuation”
+Options](customization/ignorepunct.md) page.
+
+Non-ignorable | Ignorable and Quaternary strength | Ignorable and Tertiary strength
+------------- | --------------------------------- | -------------------------------
+black bird    | black bird                        | **black bird**
+black Bird    | black-bird                        | **black-bird**
+black birds   | blackbird                         | **blackbird**
+black-bird    | black Bird                        | black Bird
+black-Bird    | black-Bird                        | black-Bird
+black-birds   | blackBird                         | blackBird
+blackbird     | black birds                       | black birds
+blackBird     | black-birds                       | black-birds
+blackbirds    | blackbirds                        | blackbirds
+
+> :point_right: **Note** The strings with the same font format in the last column are
+compared as equal by ICU Collator.\
+> Since ICU 2.2 and as prescribed by the UCA, primary ignorable code points that
+> follow shifted code points will be completely ignored. This means that an accent
+> following a space will compare as if it was a space alone.
+
+## Case Ordering
+
+The tertiary level is used to distinguish text by case, by small versus large
+Kana, and other letter variants as noted above.
+
+Some applications prefer to emphasize case differences so that words starting
+with the same case sort together. Some Japanese applications require the
+difference between small and large Kana be emphasized over other tertiary
+differences.
+
+The UCA does not provide means to separate out either case or Kana differences
+from the remaining tertiary differences. However, the ICU Collation Service has
+two options that help in customize case and/or Kana differences. Both options
+are turned off by default.
+
+### CaseFirst
+
+The Case-first option makes case the most significant part of the tertiary
+level. Primary and secondary levels are unaffected. With this option, words
+starting with the same case sort together. The Case-first option can be set to
+make either lowercase sort before
+uppercase or uppercase sort before lowercase.
+
+Note: The case-first option does not constitute a separate level; it is simply a
+reordering of the tertiary level.
+
+ICU makes use of the following three case categories for sorting
+
+1.  uppercase: "ABC"
+
+2.  mixed case: "Abc", "aBc"
+
+3.  normal (lowercase or no case): "abc", "123"
+
+Mixed case is always sorted between uppercase and normal case when the
+"case-first" option is set.
+
+### CaseLevel
+
+The Case Level option makes a separate level for case differences. This is an
+extra level positioned between secondary and tertiary. The case level is used in
+Japanese to make the difference between small and large Kana more important than
+the other tertiary differences. It also can be used to ignore other tertiary
+differences, or even secondary differences. This is especially useful in
+matching. For example, if the strength is set to primary only (level-1) and the
+case level is turned on, the comparison ignores accents and tertiary differences
+except for case. The contents of the case level are affected by the case-first
+option.
+
+The case level is independent from the strength of comparison. It is possible to
+have a collator set to primary strength with the case level turned on. This
+provides for comparison that takes into account the case differences, while at
+the same time ignoring accents and tertiary differences other than case. This
+may be used in searching.
+
+Example:
+
+**Case-first off, Case level off**
+
+apple\
+ⓐⓟⓟⓛⓔ\
+Abernathy\
+ⒶⒷⒺⓇⓃⒶⓉⒽⓎ\
+ähnlich\
+Ähnlichkeit
+
+**Lowercase-first, Case level off**
+
+apple\
+ⓐⓟⓟⓛⓔ\
+ähnlich\
+Abernathy\
+ⒶⒷⒺⓇⓃⒶⓉⒽⓎ\
+Ähnlichkeit
+
+**Uppercase-first, Case level off**
+
+Abernathy\
+ⒶⒷⒺⓇⓃⒶⓉⒽⓎ\
+Ähnlichkeit\
+apple\
+ⓐⓟⓟⓛⓔ\
+ähnlich
+
+**Lowercase-first, Case level on**
+
+apple\
+Abernathy\
+ⓐⓟⓟⓛⓔ\
+ⒶⒷⒺⓇⓃⒶⓉⒽⓎ\
+ähnlich\
+Ähnlichkeit
+
+**Uppercase-first, Case level on**
+
+Abernathy\
+apple\
+ⒶⒷⒺⓇⓃⒶⓉⒽⓎ\
+ⓐⓟⓟⓛⓔ\
+Ähnlichkeit\
+ähnlich
+
+## Script Reordering
+
+Script reordering allows scripts and some other groups of characters to be moved
+relative to each other. This reordering is done on top of the DUCET/CLDR
+standard collation order. Reordering can specify groups to be placed at the
+start and/or the end of the collation order.
+
+By default, reordering codes specified for the start of the order are placed in
+the order given after several special non-script blocks. These special groups of
+characters are space, punctuation, symbol, currency, and digit. Script groups
+can be intermingled with these special non-script groups if those special groups
+are explicitly specified in the reordering.
+
+The special code `others` stands for any script that is not explicitly mentioned
+in the list. Anything that is after others will go at the very end of the list
+in the order given. For example, `[Grek, others, Latn]` will result in an
+ordering that puts all scripts other than Greek and Latin between them.
+
+### Examples:
+
+Note: All examples below use the string equivalents for the scripts and reorder
+codes that would be used in collator rules. The script and reorder code
+constants that would be used in API calls will be different.
+
+**Example 1:**\
+set reorder code - `[Grek]`\
+result - `[space, punctuation, symbol, currency, digit, Grek, others]`
+
+**Example 2:**\
+set reorder code - `[Grek]`\
+result - `[space, punctuation, symbol, currency, digit, Grek, others]`
+
+followed by: set reorder code - `[Hani]`\
+result -` [space, punctuation, symbol, currency, digit, Hani, others]`
+
+That is, setting a reordering always modifies
+the DUCET/CLDR order, replacing whatever was previously set, rather than adding
+on to it. In order to cumulatively modify an ordering, you have to retrieve the
+existing ordering, modify it, and then set it.
+
+**Example 3:**\
+set reorder code - `[others, digit]`\
+result - `[space, punctuation, symbol, currency, others, digit]`
+
+**Example 4:**\
+set reorder code - `[space, Grek, punctuation]`\
+result - `[symbol, currency, digit, space, Grek, punctuation, others]`
+
+**Example 5:**\
+set reorder code - `[Grek, others, Hani]`\
+result - `[space, punctuation, symbol, currency, digit, Grek, others, Hani]`
+
+**Example 6:**\
+set reorder code - `[Grek, others, Hani, symbol, Tglg]`\
+result - `[space, punctuation, currency, digit, Grek, others, Hani, symbol, Tglg]`
+
+followed by:\
+set reorder code - `[NONE]`\
+result - DUCET/CLDR
+
+**Example 7:**\
+set reorder code - `[Grek, others, Hani, symbol, Tglg]`\
+result - `[space, punctuation, currency, digit, Grek, others, Hani, symbol, Tglg]`
+
+followed by:\
+set reorder code - `[DEFAULT]`\
+result - original reordering for the locale which may or may not be DUCET/CLDR
+
+**Example 8:**\
+set reorder code - `[Grek, others, Hani, symbol, Tglg]`\
+result - `[space, punctuation, currency, digit, Grek, others, Hani, symbol, Tglg]`
+
+followed by:\
+set reorder code - `[]`\
+result - original reordering for the locale which may or may not be DUCET/CLDR
+
+**Example 9:**\
+set reorder code - `[Hebr, Phnx]`\
+result - error
+
+Beginning with ICU 55, scripts only reorder together if they are primary-equal,
+for example Hiragana and Katakana.
+
+ICU 4.8-54:
+
+*   Scripts were reordered in groups, each normally starting with a [Recommended
+    Script](http://www.unicode.org/reports/tr31/#Table_Recommended_Scripts).
+*   Reorder codes moved as a group (were “equivalent”) if their scripts shared a
+    primary-weight lead byte.
+*   For example, Hebr and Phnx were “equivalent” reordering codes and were
+    reordered together. Their order relative to each other could not be changed.
+*   Only any one code out of any group could be reordered, not multiple of the
+    same group.
+
+## Sorting of Japanese Text (JIS X 4061)
+
+Japanese standard JIS X 4061 requires two changes to the collation procedures:
+special processing of Hiragana characters and (for performance reasons) prefix
+analysis of text.
+
+### Hiragana Processing
+
+JIS X 4061 standard requires more levels than provided by the UCA. To offer
+conformant sorting order, ICU uses the quaternary level to distinguish between
+Hiragana and Katakana. Hiragana symbols are given smaller values than Katakana
+symbols on quaternary level, thus causing Hiragana sequences to sort before
+corresponding Katakana sequences.
+
+### Prefix Analysis
+
+Another characteristics of sorting according to the JIS X 4061 is a large number
+of contractions followed by expansions (see
+[Contractions Producing Expansions](#contractions-producing-expansions)).
+This causes all the Hiragana and Katakana codepoints to be treated as
+contractions, which reduces performance. The solution we adopted introduces the
+prefix concept which allows us to improve the performance of Japanese sorting.
+More about this can be found in the [customization
+chapter](customization/index.md) .
+
+## Thai/Lao reordering
+
+UCA requires that certain Thai and Lao prevowels be reordered with a code point
+following them. This option is always on in the ICU implementation, as
+prescribed by the UCA.
+
+This rule takes effect when:
+
+1.  A Thai vowel of the range \\U0E40-\\U0E44 precedes a Thai consonant of the
+    range \\U0E01-\\U0E2E
+    or
+
+2.  A Lao vowel of the range \\U0EC0-\\U0EC4 precedes a Lao consonant of the
+    range \\U0E81-\\U0EAE. In these cases the vowel is placed after the
+    consonant for collation purposes.
+
+> :point_right: **Note** There is a difference between java.text.\* classes and ICU in regard to Thai
+> reordering. Java.text.\* classes allow tailorings to turn off reordering by
+> using the '!' modifier. ICU ignores the '!' modifier and always reorders Thai
+> prevowels.
+
+## Space Padding
+
+In many database products, fields are padded with null. To get correct results,
+the input to a Collator should omit any superfluous trailing padding spaces. The
+problem arises with contractions, expansions, or normalization. Suppose that
+there are two fields, one containing "aed" and the other with "äd". German
+phonebook sorting (de@collation=phonebook or BCP 47 de-u-co-phonebk) will
+compare "ä" as if it were "ae" (on a primary level), so the order will be "äd" <
+"aed". But if both fields are padded with spaces to a length of 3, then this
+will reverse the order, since the first will compare as if it were one character
+longer. In other words, when you start with strings 1 and 2
+
+1  | a  | e  | d         | \<space\>
+-- | -- | -- | --------- | ---------
+2  | ä  | d  | \<space\> | \<space\>
+
+they end up being compared on a primary level as if they were 1' and 2'
+
+1' | a  | e  | d  | \<space\> | &nbsp;
+-- | -- | -- | -- | --------- | ---------
+2' | a  | e  | d  | \<space\> | \<space\>
+
+Since 2' has an extra character (the extra space), it counts as having a primary
+difference when it shouldn't. The correct result occurs when the trailing
+padding spaces are removed, as in 1" and 2"
+
+1" | a  | e  | d
+-- | -- | -- | --
+2" | a  | e  | d
+
+## Collator naming scheme
+
+***Starting with ICU 54, the following naming scheme and its API functions are deprecated.***
+Use `ucol_open()` with language tag collation keywords instead
+(see [Collation API Details](api.md)). For example,
+`ucol_open("de-u-co-phonebk-ka-shifted", &errorCode)` for German Phonebook order
+with "ignore punctuation" mode.
+
+When collating or matching text, a number of attributes can be used to affect
+the desired result. The following describes the attributes, their values, their
+effects, their normal usage, and the string comparison performance and sort key
+length implications. It also includes single-letter abbreviations for both the
+attributes and their values. These abbreviations allow a 'short-form'
+specification of a set of collation options, such as "UCA4.0.0_AS_LSV_S", which
+can be used to specific that the desired options are: UCA version 4.0.0; ignore
+spaces, punctuation and symbols; use Swedish linguistic conventions; compare
+case-insensitively.
+
+A number of attribute values are common across different attributes; these
+include **Default** (abbreviated as D), **On** (O), and **Off** (X). Unless
+otherwise stated, the examples use the UCA alone with default settings.
+
+> :point_right: **Note** In order to achieve uniqueness, a collator name always
+> has the attribute abbreviations sorted.
+
+### Main References
+
+1.  For a full list of supported locales in ICU, see [Locale
+    Explorer](https://icu4c-demos.unicode.org/icu-bin/locexp) , which also contains
+    an on-line demo showing sorting for each locale. The demo allows you to try
+    different attribute values, to see how they affect sorting.
+
+2.  To see tabular results for the UCA table itself, see the [Unicode Collation
+    Charts](http://www.unicode.org/charts/collation/) .
+
+3.  For the UCA specification, see [UTS #10: Unicode Collation
+    Algorithm](http://www.unicode.org/reports/tr10/) .
+
+4.  For more detail on the precise effects of these options, see [Collation
+    Customization](customization/index.md) .
+
+#### Collator Naming Attributes
+
+Attribute              | Abbreviation | Possible Values
+---------------------- | ------------ | ---------------
+Locale                 | L            | \<language\>
+Script                 | Z            | \<script\>
+Region                 | R            | \<region\>
+Variant                | V            | \<variant\>
+Keyword                | K            | \<keyword\>
+&nbsp;                 | &nbsp;       | &nbsp;
+Strength               | S            | 1, 2, 3, 4, I, D
+Case_Level             | E            | X, O, D
+Case_First             | C            | X, L, U, D
+Alternate              | A            | N, S, D
+Variable_Top           | T            | \<hex digits\>
+Normalization Checking | N            | X, O, D
+French                 | F            | X, O, D
+Hiragana               | H            | X, O, D
+
+#### Collator Naming Attribute Descriptions
+
+The **Locale** attribute is typically the most
+important attribute for correct sorting and matching, according to the user
+expectations in different countries and regions. The default UCA ordering will
+only sort a few languages such as Dutch and Portuguese correctly ("correctly"
+meaning according to the normal expectations for users of the languages).
+Otherwise, you need to supply the locale to UCA in order to properly collate
+text for a given language. Thus a locale needs to be supplied so as to choose a
+collator that is correctly **tailored** for that locale. The choice of a locale
+will automatically preset the values for all of the attributes to something that
+is reasonable for that locale. Thus most of the time the other attributes do not
+need to be explicitly set. In some cases, the choice of locale will make a
+difference in string comparison performance and/or sort key length.
+
+In short attribute names,
+`<language>_<script>_<region>_<variant>@collation=<keyword>` is
+represented by: `L<language>_Z<script>_R<region>_V<variant>_K<keyword>`. Not
+all the elements are required. Valid values for locale elements are general
+valid values for RFC 3066 locale naming.
+
+**Example:**\
+**Locale="sv" (Swedish)** "Kypper" < "Köpfe"\
+**Locale="de" (German)** "Köpfe" < "Kypper"
+
+The **Strength** attribute determines whether accents or
+case are taken into account when collating or matching text. ( (In writing
+systems without case or accents, it controls similarly important features). The
+default strength setting usually does not need to be changed for collating
+(sorting), but often needs to be changed when **matching** (e.g. SELECT). The
+possible values include Default (D), Primary (1), Secondary (2), Tertiary (3),
+Quaternary (4), and Identical (I).
+
+For example, people may choose to ignore accents or ignore accents and case when
+searching for text.
+
+Almost all characters are distinguished by the first three levels, and in most
+locales the default value is thus Tertiary. However, if Alternate is set to be
+Shifted, then the Quaternary strength (4) can be used to break ties among
+whitespace, punctuation, and symbols that would otherwise be ignored. If very
+fine distinctions among characters are required, then the Identical strength (I)
+can be used (for example, Identical Strength distinguishes between the
+**Mathematical Bold Small A** and the **Mathematical Italic Small A.** For more
+examples, look at the cells with white backgrounds in the collation charts).
+However, using levels higher than Tertiary - the Identical strength - result in
+significantly longer sort keys, and slower string comparison performance for
+equal strings.
+
+**Example:**\
+**S=1** role = Role = rôle\
+**S=2** role = Role < rôle\
+**S=3** role < Role < rôle
+
+The **Case_Level** attribute is used when ignoring accents
+**but not** case. In such a situation, set Strength to be Primary, and
+Case_Level to be On. In most locales, this setting is Off by default. There is a
+small string comparison performance and sort key impact if this attribute is set
+to be On.
+
+**Example:**\
+**S=1, E=X** role = Role = rôle\
+**S=1, E=O** role = rôle < Role
+
+The **Case_First** attribute is used to control whether
+uppercase letters come before lowercase letters or vice versa, in the absence of
+other differences in the strings. The possible values are Uppercase_First (U)
+and Lowercase_First (L), plus the standard Default and Off. There is almost no
+difference between the Off and Lowercase_First options in terms of results, so
+typically users will not use Lowercase_First: only Off or Uppercase_First.
+(People interested in the detailed differences between X and L should consult
+the [Collation Customization](customization/index.md) ).
+Specifying either L or U won't affect string comparison performance, but will
+affect the sort key length.
+
+**Example:**\
+**C=X or C=L** "china" < "China" < "denmark" < "Denmark"\
+**C=U** "China" < "china" < "Denmark" < "denmark"
+
+The **Alternate** attribute is used to control the handling of
+the so-called **variable **characters in the UCA: whitespace, punctuation and
+symbols. If Alternate is set to Non-Ignorable (N), then differences among these
+characters are of the same importance as differences among letters. If Alternate
+is set to Shifted (S), then these characters are of only minor importance. The
+Shifted value is often used in combination with Strength set to Quaternary. In
+such a case, white-space, punctuation, and symbols are considered when comparing
+strings, but only if all other aspects of the strings (base letters, accents,
+and case) are identical. If Alternate is not set to Shifted, then there is no
+difference between a Strength of 3 and a Strength of 4.
+
+For more information and examples, see
+[Variable_Weighting](http://www.unicode.org/reports/tr10/#Variable_Weighting) in
+the UCA.
+
+The reason the Alternate values are not simply On and Off is that
+additional Alternate values may be added in the future.
+
+The UCA option
+**Blanked** is expressed with Strength set to 3, and Alternate set to Shifted.
+
+The default for most locales is Non-Ignorable. If Shifted is selected, it may be
+slower if there are many strings that are the same except for punctuation; sort
+key length will not be affected unless the strength level is also increased.
+
+**Example:**\
+**S=3, A=N** di Silva < Di Silva < diSilva < U.S.A. < USA\
+**S=3, A=S** di Silva = diSilva < Di Silva < U.S.A. = USA\
+**S=4, A=S** di Silva < diSilva < Di Silva < U.S.A. < USA
+
+The **Variable_Top** attribute is only meaningful if the
+Alternate attribute is not set to Non-Ignorable. In such a case, it controls
+which characters count as ignorable. The \<hex\> value specifies the "highest"
+character sequence (in UCA order) weight that is to be considered ignorable.
+
+Thus, for example, if a user wanted white-space to be ignorable, but not any
+visible characters, then s/he would use the value Variable_Top=0020 (space). The
+digits should only be a single character. All characters of the same primary
+weight are equivalent, so Variable_Top=3000 (ideographic space) has the same
+effect as Variable_Top=0020.
+
+This setting (alone) has little impact on string comparison performance; setting
+it lower or higher will make sort keys slightly shorter or longer respectively.
+
+**Example:**\
+**S=3, A=S** di Silva = diSilva < U.S.A. = USA\
+**S=3, A=S, T=0020** di Silva = diSilva < U.S.A. < USA
+
+The **Normalization** setting determines whether
+text is thoroughly normalized or not in comparison. Even if the setting is off
+(which is the default for many locales), text as represented in common usage
+will compare correctly (for details, see [UTN
+#5](http://www.unicode.org/notes/tn5/)). Only if the accent marks are in
+non-canonical order will there be a problem. If the setting is On, then the best
+results are guaranteed for all possible text input.There is a medium string
+comparison performance cost if this attribute is On, depending on the frequency
+of sequences that require normalization. There is no significant effect on sort
+key length.If the input text is known to be in NFD or NFKD normalization forms,
+there is no need to enable this Normalization option.
+
+**Example:**\
+**N=X** ä = a + ◌̈ < ä + ◌̣ < ạ + ◌̈\
+**N=O** ä = a + ◌̈ < ä + ◌̣ = ạ + ◌̈
+
+Some **French** dictionary ordering traditions sort strings with
+different accents from the back of the string. This attribute is automatically
+set to On for the Canadian French locale (fr_CA). Users normally would not need
+to explicitly set this attribute. There is a string comparison performance cost
+when it is set On, but sort key length is unaffected.
+
+**Example:**\
+**F=X** cote < coté < côte < côté\
+**F=O** cote < côte < coté < côté
+
+Compatibility with JIS x 4061 requires the introduction of an
+additional level to distinguish **Hiragana** and Katakana characters. If
+compatibility with that standard is required, then this attribute is set On, and
+the strength should be set to at least Quaternary.
+
+This attribute is an implementation detail of the CLDR Japanese tailoring. The
+implementation might change to use a different mechanism to achieve the same
+Japanese sort order. Since ICU 50, this attribute is not settable any more.
+
+**Example:**\
+**H=X, S=4** きゅう = キュウ < きゆう = キユウ\
+**H=O, S=4** きゅう < キュウ < きゆう < キユウ
+
+> :point_right: **Note** If attributes in collator name are not overridden,
+> it is assumed that they are the same as for the given locale.
+> For example, a collator opened with an empty
+> string has the same attribute settings as **AN_CX_EX_FX_HX_KX_NX_S3_T0000**.*
+
+### Summary of Value Abbreviations
+
+Value         | Abbreviation
+------------- | ------------
+Default       | D
+On            | O
+Off           | X
+Primary       | 1
+Secondary     | 2
+Tertiary      | 3
+Quaternary    | 4
+Identical     | I
+Shifted       | S
+Non-Ignorable | N
+Lower-First   | L
+Upper-First   | U

docs/userguide/collation/customization/ignorepunct.md

@@ -0,0 +1,178 @@
+---
+layout: default
+title: Ignore Punctuation Options
+nav_order: 8
+parent: Collation
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# “Ignore Punctuation” Options
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+By default, spaces and punctuation characters add primary (base character)
+differences. Such characters sort less-than digits and letters. For example, the
+default collation yields “De Anza” < “de-luge” < “deanza”.
+
+UCA/CLDR/ICU provide several options for “ignore punctuation” collation
+settings, also known as Variable Weighting or Alternate Handling. These options
+change the sorting behavior of “variable” characters algorithmically. “Variable”
+characters are those with low (but non-zero) primary weights up to a threshold,
+the “variable top”. By default, CLDR and ICU treat spaces and punctuation as
+variable. (This can be changed via API.) The DUCET also includes most symbols.
+
+## Non-Ignorable
+
+The default behavior in CLDR & ICU, shown above, is to not ignore punctuation
+(alternate=non-ignorable) but to map variable characters to their normal primary
+collation elements.
+
+All of the following options cause variable characters to be ignored on levels
+1..3. Only when strings compare equal up to the tertiary level may variable
+characters make a difference, depending on the options.
+
+See also
+
+*   [UCA: Variable
+    Weighting](http://www.unicode.org/reports/tr10/#Variable_Weighting)
+*   [LDML: Setting
+    Options](https://htmlpreview.github.io/?https://github.com/unicode-org/cldr/blob/main/docs/ldml/tr35-collation.html#Setting_Options)
+
+Here is an overview of the sorting results with these options.
+
+Non-ignorable | Blanked      | Shifted | Shift-Trimmed | Variable-After
+------------- | ------------ | ------- | ------------- | --------------
+delug         | delug        | delug   | delug         | delug
+de-luge       | de-luge      | de-luge | *deluge*      | *deluge*
+delu-ge       | delu-ge (*)  | delu-ge | de-luge       | deluge-
+*deluge*      | *deluge* (*) | *deluge* | delu-ge     | delu-ge
+Deluge        | deluge- (*)  | deluge-  | deluge-     | de-luge
+deluge-       | Deluge       | Deluge   | Deluge      | Deluge
+
+Items with (*) compare equal to the preceding ones, and their relative order
+is arbitrary. These only occur in the Blanked column. This table shows the
+results of a stable sort algorithm with the non-ignorable column as input.
+
+## Blanked
+
+The simplest option is to “ignore punctuation” completely, as if all variable
+characters (and following combining marks) had been removed from the input
+strings before comparing them.
+
+For example: “De Anza” = “De-Anza” = “DeAnza”.
+
+In ICU, this option is selected with alternate=shifted and
+strength=primary|secondary|tertiary. (ICU does not support Blanked combined with
+strength=identical.)
+
+The implementation “blanks” out all weights of the variable characters’
+collation elements.
+
+*With all of the following options, variable characters are ignored on levels
+1..3 but add distinctions on level 4 (quaternary level).*
+
+## Shifted
+
+Among strings that compare tertiary-equal, that is, they contain the same
+letters, accents and casing:
+
+*   Sorts all variable characters less-than (before) regular characters.
+*   Appending a variable character makes a string sort *greater-than* the string
+    without it.
+*   *Inserting* a variable character makes a string sort *less-than* the string
+    without it.
+*   Inserting a variable character *earlier* in a string makes it sort
+    *less-than* inserting the variable character *later* in the string.
+
+The result is similar to [Merging Sort
+Keys](http://www.unicode.org/reports/tr10/#Merging_Sort_Keys) (with shorter
+prefixes sorting less-than longer ones), like in last-name+first-name sorting,
+except only among tertiary-equal strings.
+
+For example: “de-luge” < “delu-ge” < “deluge” < “deluge-”.
+
+In ICU, this option is selected with alternate=shifted and
+strength=quaternary|identical.
+
+The implementation “shifts” the primary weight p of the collation element \[p,
+s, t, q\] of each variable characters down three levels: \[0, 0, 0, p\]. Regular
+characters with primary collation elements get a high quaternary weight, higher
+than that of any variable character.
+
+Note that this behavior is different from collation on secondary and tertiary
+level, because normal collation elements get low secondary & tertiary weights
+but high quaternary weights. Adding an accent difference anywhere makes a string
+sort greater-than the string without it, and adding an accent difference earlier
+makes it sort greater-than adding it later. For example, “deanza” < “deanzä” <
+“deänza” < “dëanza”. (Compare the ‘ä’/‘ë’ positions here with the ‘-’ positions
+above.)
+
+## Shift-Trimmed
+
+*Note: This method is not currently implemented in ICU.*
+
+Among strings that compare tertiary-equal:
+
+*   Sorts variable characters sometimes less-than, sometimes greater-than
+    regular characters.
+*   Inserting a variable character anywhere makes a string sort *greater-than*
+    the string without it. (The string without variable characters gets an empty
+    quaternary level.)
+*   Inserting a variable character *earlier* in a string makes it sort
+    *less-than* inserting the variable character *later* in the string.
+
+For example: “deluge” < “de-luge” < “delu-ge” < “deluge-”.
+
+The Shift-Trimmed method works like Shifted, except that *trailing*
+high-quaternary weights (from regular characters) are removed (trimmed).
+Compared with Shifted, the Shift-Trimmed method sorts strings without variable
+characters before ones with variable characters added, rather than producing the
+equivalent of [Merging Sort
+Keys](http://www.unicode.org/reports/tr10/#Merging_Sort_Keys).
+
+Shift-Trimmed is more complicated to implement than all of the other options:
+When comparing strings, a lookahead (or equivalent) is needed to determine
+whether a non-variable character gets a zero quaternary weight (if no variables
+follow) or a high quaternary weight (if at least one variable follows). When
+building sort keys, trailing high/common quaternary weights are trimmed (backed
+out) at the end of the quaternary level.
+
+## Variable-After
+
+*Note: This method is not currently implemented in ICU.*
+
+Among strings that compare tertiary-equal:
+
+*   Sorts all variable characters greater-than (after) regular characters.
+*   Inserting a variable character anywhere makes a string sort *greater-than*
+    the string without it. (Like Shift-Trimmed.)
+*   Inserting a variable character *earlier* in a string makes it sort
+    *greater-than* inserting the variable character *later* in the string. (Like
+    accent differences.)
+
+For example: “deluge” < “deluge-” < “delu-ge” < “de-luge”.
+
+The implementation “shifts” the primary weight p of the collation element \[p,
+s, t, q\] of each variable characters down three levels: \[0, 0, 0, p\]. Regular
+characters with primary collation elements get a *low* quaternary weight,
+*lower* than that of any variable character. This is consistent with collation
+on secondary and tertiary levels but unlike [Merging Sort
+Keys](http://www.unicode.org/reports/tr10/#Merging_Sort_Keys).
+
+This method extends the [UCA well-formedness condition
+2](http://www.unicode.org/reports/tr10/#WF2) to apply to quaternary weights.
+(UCA versions before UCA 6.2 did not limit WF2 to secondary & tertiary weights,
+which meant that several of the Variable Weighting options technically created
+ill-formed quaternary weights.)

docs/userguide/collation/examples.md

@@ -0,0 +1,333 @@
+---
+layout: default
+title: Collation Examples
+nav_order: 7
+parent: Collation
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Collation Examples
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Simple Collation Sample Customization
+
+The following program demonstrates how to compare and create sort keys with
+default locale.
+
+In **C:**
+
+```c
+#include <stdio.h>
+#include <memory.h>
+#include <string.h>
+#include "unicode/ustring.h"
+#include "unicode/utypes.h"
+#include "unicode/uloc.h"
+#include "unicode/ucol.h"
+
+#define MAXBUFFERSIZE 100
+#define BIGBUFFERSIZE 5000
+
+UBool collateWithLocaleInC(const char* locale, UErrorCode *status)
+{
+    UChar         dispName    [MAXBUFFERSIZE]; 
+    int32_t       bufferLen   = 0;
+    UChar         source            [MAXBUFFERSIZE];
+    UChar         target            [MAXBUFFERSIZE];
+    UCollationResult result   = UCOL_EQUAL;
+    uint8_t             sourceKeyArray    [MAXBUFFERSIZE];
+    uint8_t             targetKeyArray    [MAXBUFFERSIZE]; 
+    int32_t       sourceKeyOut      = 0, 
+                targetKeyOut = 0;
+    UCollator     *myCollator = 0;
+    if (U_FAILURE(*status))
+    {
+        return FALSE;
+    }
+    u_uastrcpy(source, "This is a test.");
+    u_uastrcpy(target, "THIS IS A TEST.");
+    myCollator = ucol_open(locale, status);
+    if (U_FAILURE(*status)){
+        bufferLen = uloc_getDisplayName(locale, 0, dispName, MAXBUFFERSIZE, status);
+        /*Report the error with display name... */
+        fprintf(stderr,
+        "Failed to create the collator for : \"%s\"\n", dispName);
+        return FALSE;
+    }
+    result = ucol_strcoll(myCollator, source, u_strlen(source), target, u_strlen(target));
+    /* result is 1, secondary differences only for ignorable space characters*/
+    if (result != UCOL_LESS)
+    {
+        fprintf(stderr,
+        "Comparing two strings with only secondary differences in C failed.\n");
+        return FALSE;
+    }
+    /* To compare them with just primary differences */
+    ucol_setStrength(myCollator, UCOL_PRIMARY);
+    result = ucol_strcoll(myCollator, source, u_strlen(source), target, u_strlen(target));
+    /* result is 0 */
+    if (result != 0)
+    {
+        fprintf(stderr,
+        "Comparing two strings with no differences in C failed.\n");
+        return FALSE;
+    }
+
+    /* Now, do the same comparison with keys */
+    sourceKeyOut = ucol_getSortKey(myCollator, source, -1, sourceKeyArray, MAXBUFFERSIZE);
+    targetKeyOut = ucol_getSortKey(myCollator, target, -1, targetKeyArray, MAXBUFFERSIZE);
+    result = 0;
+    result = strcmp(sourceKeyArray, targetKeyArray);
+    if (result != 0)
+    {
+        fprintf(stderr,
+        "Comparing two strings with sort keys in C failed.\n");
+        return FALSE;
+    }
+    ucol_close(myCollator);
+    return TRUE;
+}
+```
+
+In **C++:**
+
+```c++
+#include <stdio.h>
+#include "unicode/unistr.h"
+#include "unicode/utypes.h"
+#include "unicode/locid.h"
+#include "unicode/coll.h"
+#include "unicode/tblcoll.h"
+#include "unicode/coleitr.h"
+#include "unicode/sortkey.h"
+UBool collateWithLocaleInCPP(const Locale& locale, UErrorCode& status)
+{
+    UnicodeString dispName; 
+    UnicodeString source("This is a test.");
+    UnicodeString target("THIS IS A TEST.");
+    Collator::EComparisonResult result    = Collator::EQUAL;
+    CollationKey sourceKey;
+    CollationKey targetKey; 
+    Collator      *myCollator = 0;
+    if (U_FAILURE(status))
+    {
+        return FALSE;
+    }
+    myCollator = Collator::createInstance(locale, status);
+    if (U_FAILURE(status)){
+        locale.getDisplayName(dispName);
+        /*Report the error with display name... */
+        fprintf(stderr,
+        "%s: Failed to create the collator for : \"%s\"\n", dispName);
+        return FALSE;
+    }
+    result = myCollator->compare(source, target);
+    /* result is 1, secondary differences only for ignorable space characters*/
+    if (result != UCOL_LESS)
+    {
+        fprintf(stderr,
+        "Comparing two strings with only secondary differences in C failed.\n");
+        return FALSE;
+    }
+    /* To compare them with just primary differences */
+    myCollator->setStrength(Collator::PRIMARY);
+    result = myCollator->compare(source, target);
+    /* result is 0 */
+    if (result != 0)
+    {
+        fprintf(stderr,
+        "Comparing two strings with no differences in C failed.\n");
+        return FALSE;
+    }
+    /* Now, do the same comparison with keys */
+    myCollator->getCollationKey(source, sourceKey, status);
+    myCollator->getCollationKey(target, targetKey, status);
+    result = Collator::EQUAL;
+
+    result = sourceKey.compareTo(targetKey);
+    if (result != 0)
+    {
+        fprintf(stderr,
+        "%s: Comparing two strings with sort keys in C failed.\n");
+        return FALSE;
+    }
+    delete myCollator;
+    return TRUE;
+}
+```
+
+### Main Function
+
+```c++
+extern "C" UBool collateWithLocaleInC(const char* locale, UErrorCode *status);
+int main()
+{
+   UErrorCode status = U_ZERO_ERROR;
+   fprintf(stdout, "\n");
+   if (collateWithLocaleInCPP(Locale("en", "US"), status) != TRUE)
+   {
+        fprintf(stderr,
+        "Collate with locale in C++ failed.\n");
+   } else 
+   {
+       fprintf(stdout, "Collate with Locale C++ example worked!!\n");
+   }
+   status = U_ZERO_ERROR;
+   fprintf(stdout, "\n");
+   if (collateWithLocaleInC("en_US", &status) != TRUE)
+   {
+        fprintf(stderr,
+        "%s: Collate with locale in C failed.\n");
+   } else 
+   {
+       fprintf(stdout, "Collate with Locale C example worked!!\n");
+   }
+   return 0;
+}
+```
+
+In **Java:**
+
+```java
+import com.ibm.icu.text.Collator;
+import com.ibm.icu.text.CollationElementIterator;
+import com.ibm.icu.text.CollationKey;
+import java.util.Locale;
+
+public class CollateExample
+{
+
+    public static void main(String arg[]) 
+    {
+        CollateExample example = new CollateExample();
+        try {
+            if (!example.collateWithLocale(Locale.US)) {
+                System.err.println("Collate with locale example failed.");
+            } 
+            else {
+                System.out.println("Collate with Locale example worked!!");
+            }
+        } catch (Exception e) {
+            System.err.println("Collating with locale failed");
+            e.printStackTrace();
+        }
+    }
+
+    public boolean collateWithLocale(Locale locale) throws Exception
+    {
+        String source = "This is a test.";
+        String target = "THIS IS A TEST.";
+        Collator myCollator = Collator.getInstance(locale);
+
+        int result = myCollator.compare(source, target);
+        // result is 1, secondary differences only for ignorable space characters
+        if (result >= 0) {
+            System.err.println(
+                "Comparing two strings with only secondary differences failed.");
+            return false;
+        }
+        // To compare them with just primary differences
+        myCollator.setStrength(Collator.PRIMARY);
+        result = myCollator.compare(source, target);
+        // result is 0
+        if (result != 0) {
+            System.err.println(
+                           "Comparing two strings with no differences failed.");
+            return false;
+        }
+        // Now, do the same comparison with keys
+        CollationKey sourceKey = myCollator.getCollationKey(source);
+        CollationKey targetKey = myCollator.getCollationKey(target);
+        result = sourceKey.compareTo(targetKey);
+        if (result != 0) {
+            System.err.println("Comparing two strings with sort keys failed.");
+            return false;
+        }
+        return true;
+    }   
+}
+```
+
+## Language-sensitive searching
+
+String searching is a well-researched area, and there are algorithms that can
+optimize the searching process. Perhaps the best is the Boyer-Moore method. For a
+full description of this concept, please see Laura
+Werner's text searching article for more details
+(<http://icu-project.org/docs/papers/efficient_text_searching_in_java.html>).
+
+However, implementing collation-based search with the Boyer-Moore method
+while getting correct results is very tricky, and ICU no longer uses this method
+(as of ICU4C 4.0 and ICU4J 53).
+
+Please see the [String Search Service](./string-search) chapter.
+
+## Using large buffers to manage sort keys
+
+A good solution for the problem of not knowing the sort key size in advance is
+to allocate a large buffer and store all the sort keys there, while keeping a
+list of indexes or pointers to that buffer.
+
+Following is sample code that will take a pointer to an array of UChar pointer,
+an array of key indexes. It will allocate and fill a buffer with sort keys and
+return the maximum size for a sort key. Once you have done this to your string,
+you just need to allocate a field of maximum size and copy your sortkeys from
+the buffer to fields.
+
+```c++
+uint32_t fillBufferWithKeys(UCollator *coll, UChar **source, uint32_t *keys,
+                            uint32_t sourceSize, uint8_t **buffer,
+                            uint32_t *maxSize, UErrorCode *status) 
+{
+  if(status == NULL || U_FAILURE(*status)) {
+    return 0;
+  }
+
+  uint32_t bufferSize = 16384;
+  uint32_t increment = 16384;
+  uint32_t currentOffset = 0;
+  uint32_t keySize = 0;
+  uint32_t i = 0;
+  *maxSize = 0;
+
+  *buffer = (uint8_t *)malloc(bufferSize * sizeof(uint8_t));
+  if(buffer == NULL) {
+    *status = U_MEMORY_ALLOCATION_ERROR;
+    return 0;
+  }
+
+  for(i = 0; i < sourceSize; i++) {
+    keys[i] = currentOffset;
+    keySize = ucol_getSortKey(coll, source[i], -1, *buffer+currentOffset, bufferSize-currentOffset);
+    if(keySize > bufferSize-currentOffset) {
+      *buffer = (uint8_t *)realloc(*buffer, bufferSize+increment);
+      if(buffer == NULL) {
+        *status = U_MEMORY_ALLOCATION_ERROR;
+        return 0;
+      }
+      bufferSize += increment;
+      keySize = ucol_getSortKey(coll, source[i], -1, *buffer+currentOffset, bufferSize-currentOffset);
+    }
+    /* here you can hook code that does something interesting with the keySize - 
+     * remembers the maximum or similar...
+     */
+    if(keySize > *maxSize) {
+      *maxSize = keySize;
+    }
+    currentOffset += keySize;
+  }
+
+  return currentOffset;
+}
+```

docs/userguide/collation/faq.md

@@ -0,0 +1,70 @@
+---
+layout: default
+title: Collation FAQ
+nav_order: 5
+parent: Collation
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Collation FAQ
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Q. Should I turn Full Normalization on all the time?
+
+**A.** You can if you want, but you don't typically need to. The key is that
+normalization for most characters is already built into ICU's collation by
+default. Everything that can be done without affecting performance is already
+there, and will work with most languages. So the normalization parameter in ICU
+really only changes whether full normalization is invoked.
+
+The outlying cases are situations where a language uses multiple accents
+(non-spacing marks) on the same base letter, such as Vietnamese or Arabic. In
+those cases, full normalization needs to be turned on. If you use the right
+locale (or language) when creating a collation in ICU, then full normalization
+will be turned on or off according to what the language typically requires.
+
+## Q. Are there any cases where I would want to override the Full Normalization setting?
+
+**A.** The only case where you really need to worry about that parameter is for
+very unusual cases, such as sorting an list containing of names according to
+English conventions, but where the list contains, for example, some Vietnamese
+names. One way to check for such a situation is to open a collator for each of
+the languages you expect to find, and see if any of them have the full
+normalization flags set.
+
+## Q. How can collation rules mimic word sorting?
+
+Word sort is a way of sorting where certain interpunction characters are
+completely ignored, while other are considered. An example of word sort below
+ignores hyphens and apostrophes:
+
+Word Sort | String Sort
+--------- | -----------
+billet    | bill's
+bills     | billet
+bill's    | bills
+cannot    | can't
+cant      | cannot
+can't     | cant
+con       | co-op
+coop      | con
+co-op     | coop
+
+This specific behavior can be mimicked using a tailoring that makes these
+characters completely ignorable. In this case, an appropriate rule would be
+`"&\\u0000 = '' = '-'"`.
+
+Please note that we don't think that such solution is correct, since different
+languages have different word elements. Instead one should use shifted mode for
+comparison.

docs/userguide/collation/index.md

@@ -0,0 +1,148 @@
+---
+layout: default
+title: Collation
+nav_order: 1200
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Collation
+
+## Overview
+
+Information is displayed in sorted order to enable users to easily find the
+items they are looking for. However, users of different languages might have
+very different expectations of what a "sorted" list should look like. Not only
+does the alphabetical order vary from one language to another, but it also can
+vary from document to document within the same language. For example, phonebook
+ordering might be different than dictionary ordering. String comparison is one
+of the basic functions most applications require, and yet implementations often
+do not match local conventions. The ICU Collation Service provides string
+comparison capability with support for appropriate sort orderings for each of
+the locales you need. In the event that you have a very unusual requirement, you
+are also provided the facilities to customize orderings.
+
+Starting in release 1.8, the ICU Collation Service is compliant to the Unicode
+Collation Algorithm (UCA) ([Unicode Technical Standard
+#10](http://www.unicode.org/reports/tr10/)) and based on the Default
+Unicode Collation Element Table (DUCET) which defines the same sort order as ISO
+14651.
+
+The ICU Collation Service also contains several enhancements that are not
+available in UCA. These have been adopted into the [CLDR Collation
+Algorithm](http://www.unicode.org/reports/tr35/tr35-collation.html#CLDR_Collation_Algorithm).
+For example:
+
+*   Additional case handling (as specified by CLDR): ICU allows case differences
+    to be ignored or flipped. Uppercase letters can be sorted before lowercase
+    letters, or vice-versa.
+*   Easy customization (as specified by CLDR): Services can be easily tailored
+    to address a wide range of collation requirements.
+*   The [default (root) sort
+    order](http://www.unicode.org/reports/tr35/tr35-collation.html#Root_Collation)
+    has been tailored slightly for improved functionality and performance.
+
+In other words, ICU implements the CLDR Collation Algorithm which is an
+extension of the Unicode Collation Algorithm (UCA) which is an extension of ISO
+14651.
+
+There are several benefits to using the collation algorithms defined in these
+standards, including:
+
+*   The algorithms have been designed and reviewed by experts in multilingual
+    collation, and therefore are robust and comprehensive.
+
+*   Applications that share sorted data but do not agree on how the data should
+    be ordered fail to perform correctly. By conforming to the CLDR/UCA/14651
+    standards for collation and using CLDR language-specific collation data,
+    independently developed applications sort data identically and perform
+    properly.
+
+In addition, Unicode contains a large set of characters. This can make it
+difficult for collation to be a fast operation or require collation to use
+significant memory or disk resources. The ICU collation implementation is
+designed to be fast, have a small memory footprint and be highly customizable.
+
+There are many challenges when accommodating the world's languages and writing
+systems and the different orderings that are used. However, the ICU Collation
+Service provides an excellent means for comparing strings in a locale-sensitive
+fashion.
+
+For example, here are some of the ways languages vary in ordering strings:
+
+*   The letters A-Z can be sorted in a different order than in English. For
+    example, in Lithuanian, "y" is sorted between "i" and "k".
+
+*   Combinations of letters can be treated as if they were one letter. For
+    example, in traditional Spanish "ch" is treated as a single letter, and
+    sorted between "c" and "d".
+
+*   Accented letters can be treated as minor variants of the unaccented letter.
+    For example, "é" can be treated equivalent to "e".
+
+*   Accented letters can be treated as distinct letters. For example, "Å" in
+    Danish is treated as a separate letter that sorts just after "Z".
+
+*   Unaccented letters that are considered distinct in one language can be
+    indistinct in another. For example, the letters "v" and "w" are two
+    different letters according to English. However, "v" and "w" are
+    traditionally considered variant forms of the same letter in Swedish.
+
+*   A letter can be treated as if it were two letters. For example, in German
+    phonebook (or "lists of names") order "ä" is compared as if it were "ae".
+
+*   Thai requires that the order of certain letters be reversed.
+
+*   Some French dictionary ordering traditions sort accents in backwards order,
+    from the end of the string. For example, the word "côte" sorts before "coté"
+    because the acute accent on the final "e" is more significant than the
+    circumflex on the "o".
+
+*   Sometimes lowercase letters sort before uppercase letters. The reverse is
+    required in other situations. For example, lowercase letters are usually
+    sorted before uppercase letters in English. Danish letters are the exact
+    opposite.
+
+*   Even in the same language, different applications might require different
+    sorting orders. For example, in German dictionaries, "öf" would come before
+    "of". In phone books the situation is the exact opposite.
+
+*   Sorting orders can change over time due to government regulations or new
+    characters/scripts in Unicode.
+
+To accommodate the many languages and differing requirements, ICU collation
+supports customizing sort orderings - also known as **tailoring**. More details
+regarding tailoring are discussed in the [Customization
+chapter.](customization/index.md)
+
+The basic ICU Collation Service is provided by two main categories of APIs:
+
+*   String comparison - most commonly used: APIs return result of comparing two
+    strings (greater than, equal or less than). This is used as a comparator
+    when sorting lists, building tree maps, etc.
+
+*   Sort key generation - used when a very large set of strings are
+    compared/sorted repeatedly: APIs return a zero-terminated array of bytes per
+    string known as a sort key. The keys can be compared directly using strcmp
+    or memcmp standard library functions, saving repeated lookup and computation
+    of each string's collation properties. For example, database applications
+    use index tables of sort keys to index strings quickly. Note, however, that
+    this only improves performance for large numbers of strings because sorting
+    via the comparison functions is very fast. For more information, see
+    [Sortkeys vs Comparison](concepts#sortkeys-vs-comparison).
+
+ICU provides an AlphabeticIndex API for generating language-appropriate
+sorted-section labels like in dictionaries and phone books.
+
+ICU also provides a higher-level [string search](string-search)
+API which can be used, for example, for case-insensitive or accent-insensitive
+search in an editor or in a web page. ICU string search is based on the
+low-level [collation element iteration](architecture).
+
+## Programming Examples
+
+Here are some [API usage conventions](api.md) for the ICU Collation Service
+APIs.

docs/userguide/collation/string-search.md

@@ -0,0 +1,337 @@
+---
+layout: default
+title: String Search
+nav_order: 4
+parent: Collation
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# String Search Service
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+String searching, also known as string matching, is a very important subject in
+the wider domain of text processing and analysis. Many software applications use
+the basic string search algorithm in the implementations on most operating
+systems. With the popularity of Internet, the quantity of available data from
+different parts of the world has increased dramatically within a short time.
+Therefore, a string search algorithm that is language-aware has become more
+important. A bitwise match that uses the `u_strstr` (C), `UnicodeString::indexOf`
+(C++) or `String.indexOf` (Java) APIs will not yield the correct result specific
+to a particular language's requirements. The APIs will not yield the correct
+result because all the issues that are important to language-sensitive collation
+are also applicable to text searching. The following lists those issues which
+are applicable to text searching:
+
+1.  Accented letters\
+    In English, accents are treated as minor variations of a letter. In French,
+    accented letters have much more significance as they can actually change the
+    meaning of a word. Very often, an accented letter is actually a distinct
+    letter. For example, letter 'å' (\\u00e5) may be just a letter 'a' with an
+    accent symbol to English speakers. However, it is actually a distinct letter
+    in Danish; in Danish searching for 'a' should generally not match 'å' and
+    vice versa. In some cases, such as in traditional German, an accented letter
+    is short-hand for something longer. In sorting, an 'ä' (\\u00e4) is treated
+    as 'ae'. Note that primary- and secondary-level distinctions for *searching*
+    may not be the same as those for sorting; in ICU, many languages provide a
+    special "search" collator with the appropriate level settings for search.
+
+2.  Conjoined letters\
+    Special handling is required when a single letter is treated equivalent to
+    two distinct letters and vice versa. For example, in German, the letter 'ß'
+    (\\u00df) is treated as 'ss' in sorting. Also, in most languages, 'æ'
+    (\\u00e6) is considered equivalent to the letter 'a' followed by the letter
+    'e'. Also, the ligatures are often treated as distinct letters by
+    themselves. For example, 'ch' is treated as a distinct letter between the
+    letter 'c' and the letter 'd' in Spanish.
+
+3.  Ignorable punctuation\
+    As in collation, it is important that the user is able to choose to ignore
+    punctuation symbols while the user searches for a pattern in the string. For
+    example, a user may search for "blackbird" and want to include entries such
+    as "black-bird".
+
+## ICU String Search Model
+
+The ICU string search service provides similar APIs to the other text iterating
+services. Allowing users to specify the starting position and direction within
+the text string to be searched. For more information, please see the [Boundary
+Analysis](../boundaryanalysis/index.md) chapter. The user can locate one or all
+occurrences of a pattern in a string. For a given collator, a pattern match is
+located at the offsets <start, end> in a string if the collator finds that the
+sub-string between the start and end is equal.
+
+The string search service supports two different types of canonical match
+behavior.
+
+Let S' be the sub-string of a text string S between the offsets start and end
+<start, end>.
+A pattern string P matches a text string S at the offsets <start, end> if
+
+1.  option 1. P matches some canonical equivalent string of S'. Suppose the
+    collator used for searching has a tertiary collation strength, all accents
+    are non-ignorable. If the pattern "a\\u0300" is searched in the target text
+    "a\\u0325\\u0300", a match will be found, since the target text is
+    canonically equivalent to "a\\u0300\\u0325"
+
+2.  option 2. P matches S' and if P starts or ends with a combining mark, there
+    exists no non-ignorable combining mark before or after S' in S respectively.
+    Following the example above, the pattern "a\\u0300" will not find a match in
+    "a\\u0325\\u0300", since there exists a non-ignorable accent '\\u0325' in
+    the middle of 'a' and '\\u0300'. Even with a target text of
+    "a\\u0300\\u0325" a match will not be found because of the non-ignorable
+    trailing accent \\u0325.
+
+One restriction is to be noted for option 1. Currently there are no composite
+characters that consists of a character with combining class greater than 0
+before a character with combining class equals to 0. However, if such a
+character exists in the future, the string search service may not work correctly
+with option 1 when such characters are encountered.
+
+Furthermore, option 1 could generate more than one "encompassing" matches. For
+example, in Danish, 'å' (\\u00e5) and 'aa' are considered equivalent. So the
+pattern "baad" will match "a--båd--man" (a--b\\u00e5d--man) at the start offset
+at 3 and the end offset 5. However, the start offset can be 1 or 2 and the end
+offset can be 6 or 7, because "-" (hyphen) is ignorable for a certain collation.
+The ICU implementation always returns the offsets of the shortest match
+sub-string. To be more exact, the string search added a "tightest" match
+condition. In other words, if the pattern matches at offsets <start, end> as
+well as offsets <start + 1, end>, the offsets <start, end> are not considered a
+match. Likewise, if the pattern matches at offsets <start, end> as well as
+offsets <start, end + 1>, the offsets <start, end + 1> are not considered a
+match. Therefore, when the option 1 is chosen in Danish collator, 'baad' will
+match in the string "a--båd--man" (a--b\\u00e5d--man) ONLY at offsets <3,5>.
+
+The default behavior is that described in option 2 above. To obtain the behavior
+described in option 1, you must set the normalization mode to ON in the collator
+used for search.
+
+> :point_right: **Note**: The "tightest match" behavior described above
+> is defined as "Minimal Match" in
+> [Section 8 Searching and Matching in UTS #10 Unicode Collation Collation Algorithm](http://www.unicode.org/reports/tr10/#Searching).
+> "Medial Match" and "Maximal Match" are not yet implemented by the ICU String Search service.
+
+The string search service also supports two varieties of “asymmetric search” as
+described in *[Section 8.2 Asymmetric Search in UTS #10 Unicode Collation
+Collation Algorithm](http://www.unicode.org/reports/tr10/#Asymmetric_Search)*.
+With asymmetric search, for example, unaccented characters are treated as
+“wildcards” that may match any character with the same primary weight, this
+behavior can be applied just to characters in the search pattern, or to
+characters in both the search pattern and the searched text. With the former
+behavior, searching with French behavior for 'e' might match 'e', 'è', 'é', 'ê',
+and so one, while search for 'é' would only match 'é'.
+
+Both a locale or collator can be used to specify the language-sensitive rules
+for searches. When a locale is specified, a collator will be created internally
+and the StringSearch instance that is created is responsible for the ownership
+of the collator. All the collation attributes will be considered during the
+string search operation. However, the users only can set the collator attributes
+using the collator APIs. Normalization is usually done within collation and the
+process is outside the scope of the string search service.
+
+As in other iterator interfaces, the string search service provides APIs to
+perform string matching for the first pattern occurrence, immediate next,
+previous match, and the last pattern occurrence. There are also options to allow
+for overlapping matching. For example, in English, if the string is "ababab" and
+the pattern is "abab", overlapping matching produces results of offsets <0, 3>
+and <2, 5>. Otherwise, the mutually exclusive matching produces the result
+offset <0, 3> only. To find a whole word match, the user can provide a
+locale-specific `BreakIterator` object to a `StringSearch` instance to correctly
+locate the word boundaries. For example, if "c" exists in the string "abc", a
+match is returned. However, the behavior can be overwritten by supplying a word
+`BreakIterator`.
+
+The minimum unit of match is aligned to an extended grapheme cluster in the ICU
+string search service implementation defined by [UAX #29 Unicode Text
+Segmentation](http://www.unicode.org/reports/tr29/). Therefore, all matches will
+begin and end on extended grapheme cluster boundaries. If the given input search
+pattern starts with non-base character, no matches will be returned.
+When there are contractions in the collation sequence and the contraction
+happens to span across the boundary of a match, it is not considered a match.
+For example, in traditional Spanish where 'ch' is a contraction, the "har"
+pattern will not match in the string "uno charo". Boundaries that are
+discontiguous contractions will yield a match result similar to those described
+above, where the end of the match returned will be one character before the
+immediate following base letter. In addition, only the first match will be
+located if a pattern contains only combining marks and the search string
+contains more than one occurrences of the pattern consecutively. For example, if
+the user searches for the pattern "´" (\\u00b4) in the string "A´´B",
+(A\\u00b4\\u00b4B) the result will be offsets <1, 2>.
+
+### Example
+
+**In C:**
+
+```c
+    char *tgtstr = "The quick brown fox jumps over the lazy dog.";
+    char *patstr = "fox";
+    UChar target[64];
+
+    UChar pattern[16];
+    int pos = 0;
+    UErrorCode status = U_ZERO_ERROR;
+    UStringSearch *search = NULL;
+
+    u_uastrcpy(target, tgtstr);
+    u_uastrcpy(pattern, patstr);
+
+
+    search = usearch_open(pattern, -1, target, -1, "en_US", 
+                          NULL, &status);
+
+
+    if (U_FAILURE(status)) {
+        fprintf(stderr, "Could not create a UStringSearch.\n");
+        return;
+    }
+
+    for(pos = usearch_first(search, &status);
+        U_SUCCESS(status) && pos != USEARCH_DONE;
+        pos = usearch_next(search, &status))
+    {
+        fprintf(stdout, "Match found at position %d.\n", pos);
+    }
+
+    if (U_FAILURE(status)) {
+        fprintf(stderr, "Error searching for pattern.\n");
+    }
+```
+
+**In C++:**
+
+```c++
+    UErrorCode status = U_ZERO_ERROR;
+    UnicodeString target("Jackdaws love my big sphinx of quartz.");
+    UnicodeString pattern("sphinx");
+    StringSearch search(pattern, target, Locale::getUS(), NULL, status);
+
+
+    if (U_FAILURE(status)) {
+        fprintf(stderr, "Could not create a StringSearch object.\n");
+        return;
+    }
+
+    for(int pos = search.first(status);
+        U_SUCCESS(status) && pos != USEARCH_DONE;
+        pos = search.next(status))
+    {
+        fprintf(stdout, "Match found at position %d.\n", pos);
+    }
+
+    if (U_FAILURE(status)) {
+        fprintf(stderr, "Error searching for pattern.\n");
+    }
+```
+
+**In Java:**
+
+```java
+    StringCharacterIterator target = new StringCharacterIterator(
+                                         "Pack my box with five dozen liquor jugs.");
+    String pattern = "box";
+
+    try {
+        StringSearch search = new StringSearch(pattern, target, Locale.US);
+
+
+        for(int pos = search.first();
+            pos != StringSearch.DONE;
+            pos = search.next())
+        {
+            System.out.println("Match found for pattern at position " + pos); 
+        }
+    } catch (Exception e) {
+        System.err.println("StringSearch failure: " + e.toString());
+    }
+```
+
+## Performance and Other Implications
+
+The ICU string search service is designed to be on top of the ICU collation
+service. Therefore, all the performance implications that apply to a collator
+are also applicable to the string search service. To obtain the best
+performance, use the default collator attributes described in the Performance
+and Storage Implications on Attributes section in the [Collation Service
+Architecture](architecture#performance-and-storage-implications-of-attributes)
+chapter. In addition, users need to be aware of
+the following `StringSearch` specific considerations:
+
+### Search Algorithm
+
+ICU4C (C/C++) releases up to 3.8 used the Boyer-Moore search algorithm in the string
+search service. There were some known issues in these previous releases.
+(See ICU tickets [ICU-5024](https://unicode-org.atlassian.net/browse/ICU-5024),
+[ICU-5382](https://unicode-org.atlassian.net/browse/ICU-5382),
+[ICU-5420](https://unicode-org.atlassian.net/browse/ICU-5420)).
+
+In ICU4C 4.0, the string search service was updated to use a simple linear search
+algorithm, which locates a match by shifting a cursor in the target text one by one,
+and these issues were fixed.
+
+In ICU4C 4.0.1, the Boyer-Moore search code was reintroduced as a separate API with
+technology preview status. However, in ICU4C 51.1, this was removed.
+(See ICU ticket [ICU-9573](https://unicode-org.atlassian.net/browse/ICU-9573)).
+
+Similarly, in ICU4J 53 (Java) the Boyer-Moore search algorithm was replaced by the
+simple linear search algorithm, ported from ICU4C. (See ICU ticket [ICU-6288](https://unicode-org.atlassian.net/browse/ICU-6288)).
+
+The Boyer-Moore search algorithm is based on automata or combinatorial properties of strings and
+pre-processes the pattern and known to be much faster than the linear search
+when search pattern length is longer. According to performance evaluation
+between these two implementations, the Boyer-Moore search is faster than the
+linear search when the pattern text is longer than 3 or 4 characters.
+However, it is very tricky to get correct results with a collation-based Boyer-Moore search.
+
+### Change Iterating Direction
+
+The ICU string search service provides a set of very dynamic APIs that allow
+users to change the iterating direction randomly. For example, users can search
+for a particular word going forward by calling the `usearch_next` (C),
+`StringSearch::next` (C++) or `StringSearch.next` (Java) APIs and then search
+backwards at any point of the search operation by calling the `usearch_previous`
+(C), `StringSearch::previous` (C++) or `StringSearch.previous` (Java) APIs. Another
+way to change the iterating direction is by calling the `usearch_reset` (C),
+`StringSearch::previous` (C++) or `StringSearch.previous` (Java) APIs. Though the
+direction change can occur without calling the reset APIs first, this operation
+comes with a reduction in speed.
+
+> :point_right: **Note**: The backward search is not available with the
+> ICU4C Boyer-Moore search technology preview introduced in ICU4C 4.0.1
+> and only available with the linear search implementation.
+
+### Thai and Lao Character Boundaries
+
+In collation, certain Thai and Lao vowels are swapped with the next character.
+For example, the text string "A ขเ" (A \\u0e02\\u0e40) is processed internally
+in collation as
+"A เข" (A \\u0e40\\u0e02). Therefore, if the user searches for the pattern "Aเ"
+(A\\u0e40) in "A ขเ" (A \\u0e02\\u0e40) the string search service will match
+starting at offset 0. Since this normalization process is internal to collation,
+there is no notification that the swapping has happened. The return result
+offsets in this example will be <0, 2> even though the range would encompass one
+extra character.
+
+### Case Level Search
+
+Case level string search is currently done with the strength set to tertiary.
+When searching with the strength set to primary and the case level attribute
+turned on, results given may not be correct. The case level attribute is
+different from tertiary strength in that accents are ignored but case
+differences are not. Suppose you wanted to search for “A” in the text
+“ABC\\u00C5a”. The match found should be at 0 and 3 if using the case level
+attribute. However, searching with the case level attribute turned on finds
+matches at 0, 3, and 4, which includes the lower case 'a'. To ensure that case
+level differences are not ignored, string search must be done with at least
+tertiary strength.

docs/userguide/conversion/compression.md

@@ -0,0 +1,107 @@
+---
+layout: default
+title: Compression
+nav_order: 4
+parent: Conversion
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Compression
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview of SCSU
+
+Compressing Unicode text for transmission or storage results in minimal
+bandwidth usage and fewer storage devices. The compression scheme compresses
+Unicode text into a sequence of bytes by using characteristics of Unicode text.
+The compressed sequence can be used on its own or as further input to a general
+purpose file or disk-block based compression scheme. Note that the combination
+of the Unicode compression algorithm plus disk-block based compression produces
+better results than either method alone.
+
+Strings in languages using small alphabets contain runs of characters that are
+coded close together in Unicode. These runs are typically interrupted only by
+punctuation characters, which are themselves coded in proximity to each other in
+Unicode (usually in the Basic Latin range).
+
+For additional detail about the compression algorithm, which has been approved
+by the Unicode Consortium, please refer to [Unicode Technical Report #6 (A
+Standard Compression Scheme for
+Unicode)](https://www.unicode.org/reports/tr6/).
+
+The Standard Compression Scheme for Unicode (SCSU) is used to:
+
+*   express all code points in Unicode
+
+*   approximate the storage size of traditional character sets
+
+*   facilitate the use of short strings
+
+*   provide transparency for characters between `U+0020`-`U+00FF`, as well as `CR`, `LF`
+    and `TAB`
+
+*   support very simple decoders
+
+*   support simple as well as sophisticated encoders
+
+It does not attempt to avoid the use of control bytes (including `NUL`) in the
+compressed stream.
+
+The compression scheme is mainly intended for use with short to medium length
+Unicode strings. The resulting compressed format is intended for storage or
+transmission in bandwidth limited environments. It can be used stand-alone or as
+input to traditional general purpose data compression schemes. It is not
+intended as processing format or as general purpose interchange format.
+
+## BOCU-1
+
+A MIME compatible encoding called BOCU-1 is also available in ICU. Details about
+this encoding can be found in the [Unicode Technical Note
+#6](https://www.unicode.org/notes/tn6/). Both SCSU and BOCU-1 are IANA
+registered names.
+
+## Usage
+
+The compression service in ICU is a part of Conversion framework, and follows
+the semantics of converters. For more information on how to use ICU's conversion
+service, please refer to the Usage Model section in the [Using
+Converters](converters.md) chapter.
+
+```c++
+uint16_t germanUTF16[]={
+    0x00d6, 0x006c, 0x0020, 0x0066, 0x006c, 0x0069, 0x0065, 0x00df, 0x0074
+};
+
+uint8_t germanSCSU[]={
+    0xd6, 0x6c, 0x20, 0x66, 0x6c, 0x69, 0x65, 0xdf, 0x74
+};
+char target[100];
+UChar uTarget[100];
+UErrorCode status = U_ZERO_ERROR;
+UConverter *conv;
+int32_t len;
+
+/* set up the SCSU converter */
+conv = ucnv_open("SCSU", &status);
+assert(U_SUCCESS(status));
+
+/* compress the string using SCSU */
+len = ucnv_fromUChars(conv, target, 100, germanUTF16, -1, &status);
+assert(U_SUCCESS(status));
+
+len = ucnv_toUChars(conv, uTarget, 100, germanSCSU, -1, &status);
+
+/* close the converter */
+ucnv_close(conv);
+```

docs/userguide/conversion/converters.md

@@ -0,0 +1,835 @@
+---
+layout: default
+title: Converter
+nav_order: 1
+parent: Conversion
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Using Converters
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+When designing applications around Unicode characters, it is sometimes required
+to convert between Unicode encodings or between Unicode and legacy text data.
+The vast majority of modern Operating Systems support Unicode to some degree,
+but sometimes the legacy text data from older systems need to be converted to
+and from Unicode. This conversion process can be done with an ICU converter.
+
+## ICU converters
+
+ICU provides comprehensive character set conversion services, mapping tables,
+and implementations for many encodings. Since ICU uses Unicode (UTF-16)
+internally, all converters convert between UTF-16 (with the endianness according
+to the current platform) and another encoding. This includes Unicode encodings.
+In other words, internal text is 16-bit Unicode, while "external text" used as
+source or target for a conversion is always treated as a byte stream.
+
+ICU converters are available for a wide range of encoding schemes. Most of them
+are based on mapping table data that is handled by few generic implementations.
+Some encodings are implemented algorithmically in addition to (or instead of)
+using mapping tables, especially Unicode encodings. The partly or entirely
+table-based encoding schemes include: All ICU converters map only single Unicode
+character code points to and from single codepage character code points. ICU
+converters **do not** deal directly with combining characters, bidirectional
+reordering, or Arabic shaping, for example. Such processes, if required, must be
+handled separately. For example, while in Unicode, the ICU BiDi APIs can be used
+for bidirectional reordering after a conversion to Unicode or before a
+conversion from Unicode.
+
+ICU converters are not designed to perform any encoding autodetection. This
+means that the converters do not autodetect "endianness", the 6 Unicode encoding
+signatures, or the Shift-JIS vs. EUC-JP, etc. There are two exceptions: The
+UTF-16 and UTF-32 converters work according to Unicode's specification of their
+Character Encoding Schemes, that is, they read the BOM to figure out the actual
+"endianness".
+
+The ICU mapping tables mostly come from an [IBM® codepage
+repository](http://www.ibm.com/software/globalization/cdra). For non-IBM
+codepages, there is typically an equivalent codepage registered with this
+repository. However, the textual data format (.ucm files) is generic, and data
+for other codepage mapping tables can also be added.
+
+## Using the Default Codepage
+
+ICU has code to determine the default codepage of the system or process. This
+default codepage can be used to convert `char *` strings to and from Unicode.
+
+Depending on system design, setup and APIs, it may not always be possible to
+find a default codepage that fully works as expected. For example,
+
+1.  On Windows there are three encodings in use at the same time. Unicode
+    (UTF-16) is always used inside of Windows, while for `char *` encodings there
+    are two classes, called "ANSI" and "OEM" codepages. ICU will use the ANSI
+    codepage. Note that the OEM codepage is used by default for console window
+    output.
+
+2.  On some UNIX-type systems, non-standard names are used for encodings, or
+    non-standard encodings are used altogether. Although ICU supports over 200
+    encodings in its standard build and many more aliases for them, it will not
+    be able to recognize such non-standard names.
+
+3.  Some systems do not have a notion of a system or process codepage, and may
+    not have APIs for that.
+
+If you have means of detecting a default codepage name that are more appropriate
+for your application, then you should set that name with `ucnv_setDefaultName()`
+as the first ICU function call. This makes sure that the internally cached
+default converter will be instantiated from your preferred name.
+
+Starting in ICU 2.0, when a converter for the default codepage cannot be opened,
+a fallback default codepage name and converter will be used. On most platforms,
+this will be US-ASCII. For z/OS (OS/390), ibm-1047,swaplfnl is the default
+fallback codepage. For AS/400 (iSeries), ibm-37 is the default fallback
+codepage. This default fallback codepage is used when the operating system is
+using a non-standard name for a default codepage, or the converter was not
+packaged with ICU. The feature allows ICU to run in unusual computing
+environments without completely failing.
+
+## Usage Model
+
+A "Converter" refers to the C structure "UConverter". Converters are cheap to
+create. Any data that is shared between converters of the same kind (such as the
+mappings, the name and the properties) are automatically cached and shared in
+memory.
+
+### Converter Names
+
+Codepages with encoding schemes have been given many names by various vendors
+and platforms over the years. Vendors have different ways specify which codepage
+and encoding are being used. IBM uses a CCSID (Coded Character Set IDentifier).
+Windows uses a CPID (CodePage IDentifier). Macintosh has a TextEncoding. Many
+Unix vendors use [IANA](http://www.iana.org/assignments/character-sets)
+character set names. Many of these names are aliases to converters within ICU.
+
+In order to help identify which names are recognized by certain platforms, ICU
+provides several converter alias functions. The complete description of these
+functions can be found in the [ICU API Reference](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/ucnv_8h.html) .
+
+| Function Names | Short Description |
+| -------------- | ----------------- |
+| `ucnv_countAvailable`, `ucnv_getAvailableName` | Get a list of available converter names that can be opened. |
+| `ucnv_openAllNames` | Get a list of all known converter names. |
+| `ucnv_getName` | Get the name of an open converter. |
+| `ucnv_countAliases`, `ucnv_getAlias` | Get the list of aliases for the specified converter. |
+| `ucnv_countStandards`, `ucnv_getStandard` | Get the list of known standards. |
+| `ucnv_openStandardNames` | Get a filtered list of aliases for a converter that is known by the specified standard. |
+| `ucnv_getStandardName` | Get the preferred alias name specified by a given standard. |
+| `ucnv_getCanonicalName` | Get the converter name from the alias that is recognized by the specified standard. |
+| `ucnv_getDefaultName` | Get the default converter name that is currently used by ICU and the operating system. |
+| `ucnv_setDefaultName` | Use this function to override the default converter name. |
+
+Even though IANA specifies a list of aliases, it usually does not specify the
+mappings or the actual character set for the aliases. Sometimes vendors will map
+similar glyph variants to different Unicode code points or sometimes they will
+assign completely different glyphs for the same codepage code point. Because of
+these ambiguities, you can sometimes get `U_AMBIGUOUS_ALIAS_WARNING` for the
+returned `UErrorCode` when more than one converter uses the requested alias. This
+is only a warning, and the results can still be used. This UErrorCode value is
+just a reminder that you may not get what you expected. The above functions can
+help you to determine which converter you actually wanted.
+
+EBCDIC based converters do have the option to swap the newline and linefeed
+character mappings. This can be useful when transferring EBCDIC documents
+between z/OS (MVS, os/390 and the rest of the zSeries family) and another EBCDIC
+machine like OS/400 on iSeries. The ",swaplnlf" or `UCNV_SWAP_LFNL_OPTION_STRING`
+from ucnv.h can be appended to a converter alias in order to achieve this
+behavior. You can view other available options in ucnv.h.
+
+You can always skip many of these aliasing and mapping problems by just using
+Unicode.
+
+### Creating a Converter
+
+There are four ways to create a converter:
+
+1.  **By name**: Converters can be created using different types of names. No
+    distinction is made when the converter is created, as to which name is being
+    employed. There are many types of aliases possible. Among these are
+    [IANA](http://www.iana.org/assignments/character-sets) ("shift_jis",
+    "koi8-r", or "iso-8859-3"), host specific names ("cp1252" which is the name
+    for a Microsoft® Windows™ or a similar IBM® codepage). Finally, ICU's own
+    internal canonical names for a converter can be used. These include "UTF-8"
+    or "ISO-8859-1" for built-in conversion types, and names such as
+    "ibm-949_P110-2000" (Shift-JIS with '\\' <-> '¥' mapping) or
+    "ibm-949_P11A-2000" (Shift-JIS with '\\' <-> '\\' mapping) for data-file
+    based conversions.
+    
+    ```c
+    UConverter *conv = ucnv_open("shift_jis", &myError);
+    ```
+
+    As a convenience, converter names can be passed in as Unicode. (for example,
+    if a user passed in the string from a Unicode-based user interface).
+    However, the actual names are restricted to an invariant ASCII/EBCDIC
+    subset.
+
+    ```c
+    UChar *name = ...; UConverter *conv = ucnv_openU(name, &myError);
+    ```
+
+    Converter names are case-insensitive. In addition, beginning with ICU 3.6,
+    leading zeroes are ignored in sequences of digits (if further digits
+    follow), and all non-alphanumeric characters are ignored. Thus the strings
+    "UTF-8", "utf_8", "u\*T@f08" and "Utf 8" are equivalent. (Before ICU 3.6,
+    leading zeroes were not ignored, and only spaces, dashes and underscores
+    were ignored.) The `ucnv_compareNames()` function provides such string
+    comparisons.
+
+    Unlike the names of resources or other types of ICU data, converter names
+    can **not** be qualified with a path that indicates the directory or common
+    data file containing the corresponding converter data. The requested
+    converter's data must be present either in the main ICU data library or as a
+    separate file located in the ICU data directory. However, you can always
+    create a package of converters with pkgdata and open a converter from the
+    package with `ucnv_openPackage()`
+
+    ```c
+    UConverter *conv = ucnv_openPackage("./myPackage.dat", "customConverter", &myError);
+    ```
+
+2.  **By number**: The design of the ICU is to accommodate codepages provided by
+    different vendors. For example, the IBM CDRA (Character Data Representation
+    Architecture which is an IBM architecture that defines a set of identifiers)
+    has an ID type called the CCSID (Coded Character Set Identifier). The ICU
+    API for opening a codepage by number must be given a vendor along with the
+    number. Currently, only IBM (`UCNV_IBM`) is supported. For example, the US
+    EBCDIC codepage (IBM #37) can be opened with the following code:
+
+    ```c
+    ucnv_openCCSID(37, UCNV_IBM, &myErr);
+    ```
+
+3.  **By iteration**: An application might not know ahead of time which codepage
+    to use, and thus might need to query ICU to determine the entire list of
+    installed converters. The ICU returns a list of its canonical (internal)
+    names. From each names, the standard IANA name can be determined, and also a
+    list of aliases which point to that name can be determined. For example, ICU
+    might return among the canonical names "ibm-367". That name itself may or
+    may not provide the application or its users with the information needed.
+    (367 is actually the decimal form of a number that is calculated by
+    appending certain hex digits together.) However, the IANA name can be
+    requested from this canonical name, which should return something like
+    "us-ascii". The alias list for ibm-367 can be iterated over as well, which
+    returns additional names like "ascii", "646", "ansi_x3.4-1968" etc. If this
+    is not sufficient information, once a converter is opened, it can be queried
+    for its type, min and max char size, etc. This information is not available
+    without actually opening the converter (a fairly lightweight process.)
+
+    ```c
+    /* Returns count of the number of available names */
+    int count = ucnv_countAvailable();
+    /* get the canonical name of the 36th available converter */
+    const char *convName1 = ucnv_getAvailableName(36);
+    /* get the 3rd alias for a given codepage. */
+    const char *asciiAlias = ucnv_getAlias("ibm-367", 3, &myError);
+    /* Get the IANA name of the converter */
+    const char *ascii = ucnv_getStandardName("ibm-367", "IANA");
+    /* Get the one of the non preferred IANA name of the converter. */
+    UEnumeration *asciiEnum =
+    ucnv_openStandardNames("ibm-367", "IANA", &myError);
+    uenum_next(asciiEnum, &myError); /* skip preferred IANA alias */
+    /* get one of the non-preferred IANA aliases */
+    const char *ascii2 = uenum_next(asciiEnum, &myError);
+    uenum_close(asciiEnum);
+    ```
+
+4.  **By using the default converter**: The default converter can be opened by
+    passing a NULL as the name of the converter.
+
+    ```c
+    ucnv_open(NULL, &myErr);
+    ```
+
+> :point_right: **Note**: ICU chooses this converter based on the best information available to it.
+> The purpose of this converter is to interface with the OS using a codepage (i.e. `char *`).
+> Do not use it as a way of determining the best overall converter to use.
+> Usually any Unicode encoding form is the best way to store and send text data,
+> so that important data does not get lost in the conversion.
+> Also, if the OS supports Unicode-based API's (such as Win32),
+> it is better to use only those Unicode API's.
+> As an example, the new Windows 2000 locales (such as Hindi) do not
+> define the default codepage to something that supports Hindi.
+> The default converter is used in expressions such as: `UnicodeString text("abc");`
+> to convert 'abc', and in the `u_uastrcpy()` C functions.
+> Code operating at the [OS level](../design.md) MAY choose to
+> change the default converter with `ucnv_setDefaultName()`.
+> However, be aware that this change has inconsistent results if it is done after
+> ICU components are initialized.
+
+### Closing a Converter
+
+Closing a converter frees memory occupied by that instance of the converter.
+However it does not release the larger shared data tables the converter might
+use. OS-level code may call `ucnv_flushCache()` to explicitly free memory occupied
+by [unused tables](../design.md).
+
+```c
+ucnv_close(conv)
+```
+
+### Converter Life Cycle
+
+Note that a Converter is created with a certain type (for instance, ISO-8859-3)
+which does not change over the life of that [object](../design.md). Converters
+should be allocated one per thread. They are cheap to create, as the shared data
+doesn't need to be reallocated.
+
+This is the typical life cycle of a converter, as shown step-by-step:
+
+1.  First, open up the converter with a specified name (or alias name).
+    ```c
+    UConverter *conv = ucnv_open("shift_jis", &status);
+    ```
+
+2.  Target here is the `char s[]` to write into, and targetSize is how big the
+    target buffer is. Source is the UChars that are being converted.
+    ```c
+    int32_t len = ucnv_fromUChars(conv, target, targetSize, source, u_strlen(source), &status);
+    ```
+
+3.  Clean up the converter.
+    ```c
+    ucnv_close(conv);
+    ```
+
+### Sharing Converters Between Threads
+
+A converter cannot be shared between threads at the same time. However, if it is
+reset it can be used for unrelated chunks of data. For example, use the same
+converter for converting data from Unicode to ISO-8859-3, and then reset it. Use
+the same converter for converting data from ISO-8859-3 back into Unicode.
+
+### Converting Large Quantities of Data
+
+If it is necessary to convert a large quantity of data in smaller buffers, use
+the same converter to convert each buffer. This will make sure any state is
+preserved from one chunk to the next. Doing this conversion is known as
+streaming or buffering, and is mentioned [Buffered or Streamed](#3-buffered-or-streamed)
+section (§) later in this chapter.
+
+### Cloning a Converter
+
+Cloning a converter returns a clone of the converter object along with any
+internal state that the converter might be storing. Cloning routines must be
+used with extreme care when using converters for stateful or multibyte
+encodings. If the converter object is carrying an internal state, and the
+newly-created clone is used to convert a new chunk of text, the converter
+produces incorrect results. Also note that the caller owns the cloned object and
+has to call `ucnv_close()` to dispose of the object. Calling `ucnv_reset()` before
+cloning will reset the converter to its original state.
+
+```c
+UConverter* newCnv = ucnv_safeClone(oldCnv, 0, &bufferSize, &err)
+```
+
+## Converter Behavior
+
+### Conversion
+
+1.  The converters always consume the source buffer as far as possible, and
+    advance the source pointer.
+
+2.  The converters write to the target all converted output as far as possible,
+    and then write any remaining output to the internal services buffer. When
+    the conversion routines are called again, the internal buffer is flushed out
+    and written to the target buffer before proceeding with any further
+    conversion.
+
+3.  In conversions to Unicode from Multi-byte encodings or conversions from
+    Unicode involving surrogates, if (a) only a partial byte sequence is
+    retrieved from the source buffer, (b) the "flush" parameter is set to "TRUE"
+    and (c) the end of source is reached, then the callback is called with
+    `U_TRUNCATED_CHAR_FOUND`.
+
+### Reset
+
+Converters can be reset explicitly or implicitly. Explicit reset is done by
+calling:
+
+1.  `ucnv_reset()`: Resets the converter to initial state in both directions.
+
+2.  `ucnv_resetToUnicode()`: Resets the converter to initial state to Unicode
+    direction.
+
+3.  `ucnv_resetFromUnicode()`: Resets the converter to initial state from Unicode
+    direction.
+
+The converters are reset implicitly when the conversion functions are called
+with the "flush" parameter set to "TRUE" and the source is consumed.
+
+### Error
+
+#### Conversion from Unicode
+
+Not all characters can be converted from Unicode to other codepages. In most
+cases, Unicode is a superset of the characters supported by any given codepage.
+
+The default behavior of ICU in this case is to substitute the illegal or
+unmappable sequence, with the appropriate substitution sequence for that
+codepage. For example, ISO-8859-1, along with most ASCII-based codepages, has
+the character 0x1A (Control-Z) as the substitution sequence. When converting
+from Unicode to ISO-8859-1, any characters which cannot be converted would be
+replaced by 0x1A's.
+
+SubChar1 is sometimes used as substitution character in MBCS conversions. For
+more information on SubChar1 please see the [Conversion Data](data.md) chapter.
+
+In stateful converters like ISO-2022-JP, if a substitution character has to be
+written to the target, then an escape/shift sequence to change the state to
+single byte mode followed by a substitution character is written to the target.
+
+The substitution character can be changed by calling the `ucnv_setSubstChars()`
+function with the desired codepage byte sequence. However, this has some
+limitations: It only allows setting a single character (although the character
+can consist of multiple bytes), and it may not work properly for some stateful
+converters (like HZ or ISO 2022 variants) when setting a multi-byte substitution
+character. (It will work for EBCDIC_STATEFUL ones.) Moreover, for setting a
+particular character, the caller needs to know the correct byte sequence for
+that character in the converter's codepage. (For example, a space (U+0020) is
+encoded as 0x20 in ASCII-based codepages, 0x40 in EBCDIC-based ones, 0x00 0x20
+or 0x20 0x00 in UTF-16 depending on the stream's endianness, etc.)
+
+The `ucnv_setSubstString()` function (new in ICU 3.6) lifts these limitations. It
+takes a Unicode string and verifies that it can be converted to the codepage
+without error and that it is not too long (32 bytes as of ICU 3.6). The string
+can contain zero, one or more characters. An empty string has the effect of
+using the skip callback. See the Error Callbacks below. Stateful converters are
+fully supported. The same Unicode string will give equivalent results with all
+converters that support its conversion.
+
+Internally, `ucnv_setSubstString()` stores the byte sequence from the test
+conversion if the converter is stateless, or the Unicode string itself if the
+converter is stateful. If the Unicode string is stored, then it is converted on
+the fly during substitution, handling all state transitions.
+
+The function `ucnv_getSubstChars()` can be used to retrieve the substitution byte
+sequence if it is the default one, set by `ucnv_setSubstChars()`, or if
+`ucnv_setSubstString()` stored the byte sequence for a stateless converter. The
+Unicode string set for a stateful converter cannot be retrieved.
+
+#### Conversion to Unicode
+
+In conversion to Unicode, errors are normally due to ill-formed byte sequences:
+Unused byte values, or lead bytes not followed by trail bytes according to the
+encoding scheme. Well-formed but unmappable sequences are unusual but possible.
+
+The ICU default behavior is to emit an `U+FFFD REPLACEMENT CHARACTER` per
+offending sequence.
+
+If the conversion table .ucm file contains a `<subchar1>` entry (such as in the
+ibm-943 table), a U+001A C0 control ("SUB") is emitted for single-byte
+illegal/unmappable input rather than `U+FFFD REPLACEMENT CHARACTER`. For details
+on this behavior look for "001A" in the [Conversion Data](data.md) chapter.
+
+* This behavior originates from mainframes with dedicated single-byte-to-single-byte
+  and double-to-double conversions.
+* Emitting U+001A for single-byte errors can be avoided by (a) removing the
+  `<subchar1>` mapping or (b) using a similar conversion table that does not
+  have this mapping (e.g., windows-932 instead of ibm-943) or (c) writing a
+  custom callback function.
+
+### Error Codes
+
+Here are some of the `UErrorCode`s which have significant meaning for conversion:
+
+#### U_INDEX_OUTOFBOUNDS_ERROR
+
+In `getNextUChar()` - all source data
+has been consumed without producing a Unicode character
+
+#### U_INVALID_CHAR_FOUND
+No mapping was found from the source to the target encoding. For example, U+0398
+(Capital Theta) has no mapping into ISO-8859-1, and so U_INVALID_CHAR_FOUND
+will result.
+
+#### U_TRUNCATED_CHAR_FOUND
+
+All of the source data was read, and a
+character sequence was incomplete. For example, only half of a double-byte
+sequence may have been encountered. When converting FROM Unicode, this error
+would occur when a conversion ends with a low surrogate (U+D800) at the end of
+the source, with no corresponding high surrogate.
+
+#### U_ILLEGAL_CHAR_FOUND
+
+A character sequence was found in the source which is disallowed in the source
+encoding scheme. For example, many MBCS encodings have only certain byte
+sequences which are allowed as lead bytes. When converting from Unicode, if a
+low surrogate is NOT followed immediately by a high surrogate, or a high
+surrogate without its preceding low surrogate, an illegal sequence results.
+Note: Most, but not all, converters forbid surrogate code points or unpaired
+surrogate code units. (Lead surrogate without trail, or trail without lead.)
+Some converters permit surrogate code points/unpaired surrogates because their
+charset specification permits it. For example, LMBCS, SCSU and
+BOCU-1.
+
+#### U_INVALID_TABLE_FORMAT
+
+An error occurred trying to read the backing data
+for the converter. The data could be corrupt, or the wrong
+version.
+
+#### U_BUFFER_OVERFLOW_ERROR
+
+More output (target) characters were produced
+than fit in the target buffer. If in `to/fromUnicode()`, then process the target
+buffer and call the function again to retrieve the overflowed characters.
+
+### Error Callbacks
+
+What actually happens is that an "error callback function" is called at the
+point where the conversion failure occurred. The function can deal with the
+failed characters as it sees fit. Possible options at the callback's disposal
+include ignoring the bad sequence, converting it to a different sequence, and
+returning an error to the caller. The callback can also consume any data past
+where the error occurred, whether or not that data would have caused an error.
+Only one callback is installed at a time, per direction (to or from unicode).
+
+A number of canned functions are provided by ICU, and an application can write
+new ones. The "callbacks" are either From Unicode (to codepage), or To Unicode
+(from codepage). Here is a list of the canned callbacks in ICU:
+
+1.  UCNV_**FROM_U**_CALLBACK_SUBSTITUTE: This callback is installed by default.
+    It will write the codepage's substitute sequence or a user-set substitute
+    sequence, or convert a user-set substitute UnicodeString to the codepage.
+    See "Error / Conversion from Unicode" above.
+
+2.  UCNV_**TO_U**_CALLBACK_SUBSTITUTE: This callback is installed by default. It
+    will write U+FFFD or sometimes U+001A. See "Error / Conversion to Unicode"
+    above.
+
+3.  UCNV_FROM_U_CALLBACK_SKIP, UCNV_TO_U_CALLBACK_SKIP: Simply ignores any
+    invalid characters in the input, no error is returned.
+
+4.  UCNV_FROM_U_CALLBACK_STOP, UCNV_TO_U_CALLBACK_STOP: Stop at the error.
+    Return the error to the caller. (When using the 'BUFFER' mode of conversion,
+    the source and target pointers returned can be examined to determine where
+    the error occurred. `ucnv_getInvalidUChars()` and `ucnv_getInvalidChars()`
+    return the actual text which failed).
+
+5.  UCNV_FROM_U_CALLBACK_ESCAPE, UCNV_TO_U_CALLBACK_ESCAPE: This callback is
+    especially useful for debugging. Missing codepage characters are replaced by
+    strings such as '%U094D' with the Unicode value, and missing Unicode chars
+    are replaced with text of the form '%X0A' where the codepage had the
+    unconvertible byte hex 0A.
+
+    When a callback is set, a "context" pointer is also provided. How this
+    pointer is created depends on the specific callback. There is usually a
+    `createContext()` function for that specific callback, where the caller can
+    set certain options for the callback. Consult the documentation for the
+    specific callback you are using. For ICU's canned callbacks, this pointer
+    may be set to NULL. The functions for setting a different callback also
+    return the old callback, and the old context pointer. These may be stored so
+    that the old callback is re-installed when an operation is finished.
+    
+    Additionally the following options can be passed as the context parameter to
+    UCNV_FROM_U_CALLBACK_ESCAPE callback function to produce different outputs.
+
+    | UCNV_ESCAPE_ICU     | %U12345 |
+    | ------------------- | ------- |
+    | UCNV_ESCAPE_JAVA    | \\u1234 |
+    | UCNV_ESCAPE_C       | \\udbc9\\udd36 for Plane 1 and \\u1234 for Plane 0 codepoints |
+    | UCNV_ESCAPE_XML_DEC | \&#4460; number expressed in Decimal |
+    | UCNV_ESCAPE_XML_HEX | \&#x1234; number expressed in Hexadecimal |
+
+Here are some examples of how to use callbacks.
+
+```c
+UConverter              *u;
+void                    *oldContext, *newContext;
+UConverterFromUCallback oldAction, newAction;
+u = ucnv_open("shift_jis", &myError);
+
+... /* do some conversion with u from unicode.. */
+
+ucnv_setFromUCallBack(
+    u, MY_FROMU_CALLBACK, newContext, &oldAction, &oldContext, &myError);
+
+... /* do some other conversion from unicode */
+
+/* Now, set the callback back */
+ucnv_setFromUCallBack(
+    u, oldAction, oldContext, &newAction, &newContext, &myError);
+
+```
+
+### Custom Callbacks
+
+Writing a callback is somewhat involved, and will be covered more completely in
+a future version of this document. One might look at the source to the provided
+callbacks as a starting point, and address any further questions to the mailing
+list.
+
+Basically, callback, unlike other ICU functions which expect to be called with
+`U_ZERO_ERROR` as the input, is called in an exceptional error condition. The
+callback is a kind of 'last ditch effort' to rectify the error which occurred,
+before it is returned back to the caller. This is why the implementation of STOP
+is very simple:
+
+```c
+void UCNV_FROM_U_CALLBACK_STOP(...) { }
+```
+
+The error code such as `U_INVALID_CHAR_FOUND` is returned to the user. If the
+callback determines that no error should be returned to the user, then the
+callback must set the error code to `U_ZERO_ERROR`. Note that this is a departure
+from most ICU functions, which are supposed to check the error code and return
+immediately if it is set.
+
+> :point_right: **Note**: See the functions `ucnv_cb_write...()` for
+> functions which a callback may use to perform its task.
+
+#### Ignore Default_Ignorable_Code_Point
+
+Unicode has a number of characters that are not by themselves meaningful but
+assist with line breaking (e.g., U+00AD Soft Hyphen & U+200B Zero Width Space),
+bi-directional text layout (U+200E Left-To-Right Mark), collation and other
+algorithms (U+034F Combining Grapheme Joiner), or indicate a preference for a
+particular glyph variant (U+FE0F Variation Selector 16). These characters are
+"invisible" by default, that is, they should normally not be shown with a glyph
+of their own, except in special circumstances. Examples include showing a hyphen
+for when a Soft Hyphen was used for a line break, or modifying the glyph of a
+character preceding a Variation Selector.
+
+Unicode has a character property to identify such characters, as well as
+currently-unassigned code points that are intended to be used for similar
+purposes: Default_Ignorable_Code_Point, or "DI" for short:
+http://www.unicode.org/cldr/utility/list-unicodeset.jsp?a=[:DI:]
+
+Most charsets do not have most or any of these characters.
+
+**ICU 54 and above by default skip default-ignorable code points if they are
+unmappable**. (Ticket #[10551](https://unicode-org.atlassian.net/browse/ICU-10551))
+
+**Older versions of ICU** replaced unmappable default-ignorable code points like
+any other unmappable code points, by a question mark or whatever substitution
+character is defined for the charset.
+
+For best results, a custom from-Unicode callback can be used to ignore
+Default_Ignorable_Code_Point characters that cannot be converted, so that they
+are removed from the charset output rather than replaced by a visible character.
+
+This is a code snippet for use in a custom from-Unicode callback:
+
+```c
+#include "unicode/uchar.h"
+// ...
+(from-Unicode callback)
+    switch(reason) {
+    case UCNV_UNASSIGNED:
+        if(u_hasBinaryProperty(codePoint, UCHAR_DEFAULT_IGNORABLE_CODE_POINT)) {
+            // Ignore/drop default ignorable code points that cannot be converted,
+            // rather than treating them like errors/writing a substitution character etc.
+            // For example, U+200B Zero Width Space,
+            // U+200E Left-To-Right Mark, U+FE0F Variation Selector 16.
+            *pErrorCode = U_ZERO_ERROR;
+            return;
+        } else {
+            // ...
+```
+
+## Modes of Conversion
+
+When a converter is instantiated, it can be used to convert both in the Unicode
+to Codepage direction, and also in the Codepage to Unicode direction. There are
+three ways to use the converters, as well as a convenience function which does
+not require the instantiation of a converter.
+
+1.  **Single-String**: Simplest type of conversion to or from Unicode. The data
+    is entirely contained within a single string.
+
+2.  **Character**: Converting from the codepage to a single Unicode codepoint,
+    one at a time.
+
+3.  **Buffer**: Convert data which may not fit entirely within a single buffer.
+    Usually the most efficient and flexible.
+
+4.  **Convenience**: Convert a single buffer from one codepage to another
+    through Unicode, without requiring the instantiation of a converter.
+
+### 1. Single-String
+
+Data must be contained entirely within a single string or buffer.
+
+```c
+conv = ucnv_open("shift_jis", &status);
+
+/* Convert from Unicode to Shift JIS */
+len = ucnv_fromUChars(conv, target, targetLen, source, sourceLen, &status);
+ucnv_close(conv);
+
+conv = ucnv_open("iso-8859-3", &status);
+/* Convert from ISO-8859-3 to Unicode */
+len = ucnv_toUChars(conv, target, targetSize, source, sourceLen, &status);
+ucnv_close(conv);
+```
+
+### 2. Character
+
+In this type, the input data is in the specified codepage. With each function
+call, only the next Unicode codepoint is converted at a time. This might be the
+most efficient way to scan for a certain character, or other processing of a
+single character at a time, because converters are stateful. This works even for
+multibyte charsets, and for stateful ones such as iso-2022-jp.
+
+```c
+conv = ucnv_open("Big-5", &status);
+UChar32 target;
+while(source < sourceLimit) {
+    target = ucnv_getNextUChar(conv, &source, sourceLimit, &status);
+    ASSERT(status);
+    processChar(target);
+}
+```
+
+### 3. Buffered or Streamed
+
+This is used in situations where a large document may be read in off of disk and
+processed. Also, many codepages take multiple bytes to encode a character, or
+have state. These factors make it impossible to convert arbitrary chunks of data
+without maintaining state across chunks. Even conversion from Unicode may
+encounter a leading surrogate at the end of one buffer, which needs to be paired
+with the trailing surrogate in the next buffer.
+
+A basic API principle of the ICU to/from Unicode functions is that they will
+ALWAYS attempt to consume all of the input (source) data, unless the output
+buffer is full or some other error occurs. In other words, there is no need to
+ever test whether all of the source data has been consumed.
+
+The basic loop that is used with the ICU buffer conversion routines is the same
+in the to and from Unicode directions. In the following pseudocode, either
+'source' (for fromUnicode) or 'target' (for toUnicode) are UTF-16 UChars.
+
+```c
+UErrorCode err = U_ZERO_ERROR;
+
+while (... /*input data available*/ ) {
+    ... /* read input data into buffer */
+    
+    source = ... /* beginning of read data */;
+    sourceLimit = source + readLength; // end + 1
+
+    UBool flush = (further input data still available) // (i.e. feof())
+
+    /* loop until all source has been processed */
+    do {
+        /* set up target pointers */
+        target = ... /* beginning of output buffer */;
+        targetLimit = target + sizeOfOutput;
+
+        err = U_ZERO_ERROR; /* so that the to/from does not fail */
+
+        ucnv_to/fromUnicode(converter, &target, targetLimit,
+                    &source, sourceLimit, NULL, flush, &err);
+
+        ... /* write (target-beginningOfOutputBuffer) items
+               starting at beginning of output buffer */
+    } while (err == U_BUFFER_OVERFLOW_ERROR);
+    if(U_FAILURE(error)) {
+        ... /* process error */
+        break; /* out of the 'while' loop that reads source data */
+    }
+}
+/* loop to read input data */
+if(U_FAILURE(error)) {
+    ... /* process error further */
+}
+```
+
+The above code optimizes for processing entire chunks of input data. An
+efficient size for the output buffer can be calculated as follows. (in bytes):
+
+```c
+ucnv_getMinCharSize() * inputBufferSize * sizeof(UChar)
+ucnv_getMaxCharSize() * inputBufferSize
+```
+
+There are two loops used, an outer and an inner. The outer loop fetches input
+data to keep the source buffer full, and the inner loop 'writes' out data to
+keep the output buffer empty.
+
+Note that while this efficiently handles data on the input side, there are some
+cases where the size of the output buffer is fixed. For instance, in network
+applications it is sometimes desirable to fill every output packet completely
+(not including the last packet in the sequence). The above loop does not ensure
+that every output buffer is completely full. For example, if a 4 UChar input
+buffer was used, and a 3 byte output buffer with `fromUnicode()`, the loop would
+typically write 3 bytes, then 1, then 3, and so on. If, instead of efficient use
+of the input data, the goal is filling output buffers, a slightly different loop
+can be used.
+
+In such a scenario, the inner write does not occur unless a buffer overflow
+occurs OR 'flush' is true. So, the 'write' and resetting of the target and
+targetLimit pointers would only happen
+`if (err == U_BUFFER_OVERFLOW_ERROR || flush == TRUE)`
+
+The flush parameter on each conversion call should be set to FALSE, until the
+conversion call is called for the last time for the buffer. This is because the
+conversion is stateful. On the last conversion call, the flush parameter should
+be set to TRUE. More details are mentioned in the API reference in
+[ucnv.h](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/ucnv_8h.html) .
+
+### 4. Pre-flighting
+
+Preflighting is the process of asking the conversion API for the size of target
+buffer required. (For a more general discussion, see the Preflighting section
+(§) in the [Strings](../strings/index.md) chapter.)
+
+This is accomplished by calling the `ucnv_fromUChars` and `ucnv_toUChars` functions.
+
+```c
+UChar uchar2;
+char input_char_buffer = "This is some text";
+
+targetsize = ucnv_toUChars(myConverter, NULL, targetcapacity,
+                           input_char_buffer, sizeof(input_char_buffer), &err);
+
+if(err==U_BUFFER_OVERFLOW_ERROR) {
+    err=U_ZERO_ERROR;
+    uchar2=(UChar*)malloc((targetsize) * sizeof(UChar));
+    targetsize = ucnv_toUChars(myConverter, uchar2, targetsize,
+                               input_char_buffer, sizeof(input_char_buffer), &err);
+    if(U_FAILURE(err)) {
+        printf("ucnv_toUChars() FAILED %s\n", myErrorName(err));
+    }
+    else {
+        printf("ucnv_toUChars() o.k.\n");
+    }
+}
+```
+
+> :point_right: **Note**: *This is inefficient since the conversion is performed
+> **twice**, once for finding the size of target and once for writing to the target*.
+
+### 5. Convenience
+
+ICU provides some convenience functions for conversions:
+
+```c
+ucnv_toUChars(myConverter, target_uchars, targetsize,
+              input_char_buffer, sizeof(input_char_buffer), &err);
+ucnv_fromUChars(cnv, cTarget, (cTargetLimit-cTarget),
+                uSource, (uSourceLimit-uSource), &errorCode);
+
+char target[100];
+UnicodeString str("ABCDEF", "iso-8859-1");
+int32_t targetsize = str.extract(0, str.length(), target, sizeof(target), "SJIS");
+target[targetsize] = 0; /* NULL termination */
+```
+
+## Conversion Examples
+
+See the [ICU Conversion Examples](https://github.com/unicode-org/icu/blob/main/icu4c/source/samples/ucnv/convsamp.cpp) for more information.

docs/userguide/conversion/data.md

@@ -0,0 +1,691 @@
+---
+layout: default
+title: Conversion Data
+nav_order: 2
+parent: Conversion
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Conversion Data
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Introduction
+
+### Algorithmic vs. Data-based
+
+In a comprehensive conversion library, there are three kinds of codepage
+converter implementations: converters that use algorithms, mapping data, or
+those converters that use both.
+
+1.  Most codepages have a simple and straightforward structure but have an
+    arbitrary relationship between input and output character codes. Mapping
+    tables are necessary to define the conversion. If the codepage characters
+    use more than one byte each, then the mapping table must also define the
+    structure of the codepage.
+
+2.  Algorithmic converters work by transforming the input stream with built-in
+    algorithms and possibly small, hard coded tables. The conversion can be
+    complex, but the actual mapping of a character code is done numerically if
+    the converter is purely algorithmic.
+
+3.  In some cases, a converter needs to be algorithmic for its basic operations
+    but also relies on mapping data.
+
+ICU provides converter implementations for all three groups of codepages. Since
+ICU always converts, to or from Unicode, the purely algorithmic converters are
+the ones for Unicode encodings (such as UTF-8, UTF-16BE, UTF-16LE, UTF-32BE,
+UTF-32LE, SCSU, BOCU-1 and UTF-7). Since Unicode is based on US-ASCII and
+ISO-8859-1 ("ISO Latin-1"), these encodings also use algorithmic converters for
+performance reasons.
+
+Most other codepages use simple byte sequences but are not encodings of Unicode.
+They are converted with generic code using mapping data tables. ICU also
+supports a few encodings, like ISO-2022 and its variants, that employ an
+algorithmic structure to switch between a set of codepages. The converters for
+these encodings are algorithmic but use mapping tables for the embedded
+codepages.
+
+### Stateful vs. Stateless
+
+Character encodings are either stateful or stateless:
+
+1.  Stateless encodings define a byte sequence for each character. Complete
+    character byte sequences can be used in any order, and the same complete
+    character byte sequences always encodes the same characters. It is
+    preferable to always encode one character using the same byte sequence.
+
+2.  Stateful encodings define byte sequences that change the state of the text
+    stream. Depending on the current state, the same byte sequence may encode a
+    different character and the same character may be encoded with different
+    byte sequences.
+
+This distinction between stateless and stateful encodings is important, because
+it determines if any available ICU converter implementation is used. The
+following are some more important considerations related to stateless versus
+stateful encodings:
+
+1.  A runtime converter object is always stateful, even for "stateless"
+    encodings. They are always stateful because an input buffer may end with a
+    partial byte sequence that is to be continued in the next input buffer in
+    the following conversion call. The information about this is stored in the
+    converter object. Similarly, if the input is Unicode text, then an input
+    buffer may end with the first of a pair of surrogates. The converter object
+    also stores overflow bytes or code units if the result of a character
+    mapping did not fit entirely into the output buffer.
+
+2.  Stateless encodings are stateful in our converter implementation to
+    interpret "complete byte sequences". They are "stateful" because many
+    encodings can have the same byte value used in different positions of byte
+    sequences for different characters; a specific byte value may be a lead byte
+    or a trail byte. For instance, the lead and trail byte values overlap in
+    codepages like Shift-JIS. If a program does not start reading at a character
+    boundary, it may instead interpret the byte sequences from two or more
+    separate characters as one character. Often, character boundaries can be
+    detected reliably only by reading the non-Unicode text linearly from the
+    beginning. This can be a problem for non-Unicode text processing, where text
+    insertion, deletion, and searching are common. The UTF-8/16/32 encodings do
+    not have this problem because the single, lead, or trail units have disjoint
+    values and character boundary can be easily found.
+
+3.  Some stateful encodings only switch between two states: one with one byte
+    per character and one with two bytes per character. This type of encoding is
+    very common in mainframe systems based on Extended Binary Coded Decimal
+    Interchange Code (EBCDIC) and is actually handled in ICU with almost the
+    same code and type of mapping tables as stateless codepages.
+
+4.  The classifications of algorithmic vs. data-based converters and of
+    stateless vs. stateful encodings are independent of each other: UTF-8,
+    UTF-16, and UTF-32 encodings are algorithmic but stateless; UTF-7 and SCSU
+    encodings are algorithmic and stateful; Windows-1252 and Shift-JIS encodings
+    are data-based and stateless; ISO-2022-JP encoding is algorithmic,
+    data-based, and stateful.
+
+### Scope of this chapter
+
+The following sections in this chapter discuss the mapping data tables that are
+used in ICU. For related material, please see:
+
+1.  [ICU character set collection](https://icu.unicode.org/charts/charset)
+
+2.  [Unicode Technical Report 22](http://www.unicode.org/reports/tr22/)
+
+3.  "Cross Mapping Tables" in [Unicode Online
+    Data](http://www.unicode.org/onlinedat/online.html)
+
+## ICU Mapping Table Data Files
+
+### Overview
+
+As stated above, most ICU converters rely on character mapping tables. ICU 1.8
+has one single data structure for all character mapping tables, which is used by
+a generic Multi-Byte Character Set (MBCS) converter implementation. The
+implementation is flexible enough to handle stateless encodings with the
+following parameters:
+
+1.  Support for variable-length, byte-based encodings with 1 to 4 bytes per
+    character.
+
+2.  Support for all Unicode characters (code points 0..0x10ffff). Since ICU 1.8
+    uses the UTF-16 encoding as its Unicode encoding form, surrogate pairs are
+    completely supported.
+
+3.  Efficient distinction between unassigned (unmappable) and illegal byte
+    sequences.
+
+4.  It is not possible to convert from Unicode to byte sequences with leading
+    zero bytes.
+
+5.  Simple stateful encodings are also handled using only Shift-In and Shift-Out
+    (SI/SO) codes and one single-byte and one double-byte state.
+
+> :point_right: **Note**: *In the context of conversion tables, "unassigned" code
+> points or codepage byte sequences are valid but do not have a **mapping**. This
+> is different from "unassigned" code points in a character set like Unicode or
+> Shift-JIS which are codes that do not have assigned **characters**.*
+
+Prior to version 1.8, ICU used more specific, more limited, converter
+implementations for Single Byte Character Set (SBCS), Double Byte Character Set
+(DBCS), and the stateful Extended Binary Coded Decimal Interchange Code (EBCDIC)
+codepages. Mapping table data is provided in text files. ICU comes with several
+dozen .ucm files (UniCode Mapping, in icu/source/data/mappings/) that are
+translated at build time by its makeconv tool (source code in
+icu/source/tools/makeconv). The makeconv tool writes one binary, memory-mappable
+.cnv file per .ucm file. The resulting .cnv files are included by default in the
+common data file for use at runtime.
+
+The format of the .ucm files is similar to the format of the UPMAP files as
+provided by IBM® in the codepage repository and as used in the uconvdef tool on
+AIX. UPMAP is a text file that specifies the mapping of a codepage character to
+and from Unicode.
+
+The format of the .cnv files is ICU-specific. The .cnv file format may change
+between ICU versions even for the same .ucm files. The .ucm file format may be
+extended to include more features.
+
+The following sections concentrate on the .ucm file format. The .cnv file format
+is described in the source code in the `icu/source/common/ucnvmbcs.c` directory
+and is updated using the MBCS converter implementation.
+
+These conversion tables can have more than one name. ICU allows multiple names
+("aliases") for the same encoding. It matches a requested encoding name against
+a list of names in `icu/source/data/mappings/convrtrs.txt` and when it finds a
+match, ICU opens a converter with the name in the leftmost position in the
+matching line. The name matching is not case-sensitive and ICU ignores spaces,
+dashes, and underscores. At build time, the gencnval tool located in the
+`icu/source/tools/gencnval` directory, generates a binary form of the convrtrs.txt
+file as a data file for runtime for the cnvalias.icu file ("Converter Aliases
+data file").
+
+### .ucm File Format
+
+.ucm files are line-oriented text files. Empty lines and comments starting with
+'`#`' are ignored.
+
+A .ucm file contains two sections:
+
+1.  a header with general specifications of the codepage
+
+2.  a mapping table section between the "CHARMAP" and "END CHARMAP" lines.
+
+For example:
+
+```
+<code_set_name>               "IBM-943"
+<char_name_mask>              "AXXXX"
+<mb_cur_min>                  1
+<mb_cur_max>                  2
+<uconv_class>                 "MBCS"
+<subchar>                     \xFC\xFC
+<subchar1>                    \x7F
+<icu:state>                   0-7f, 81-9f:1, a0-df, e0-fc:1
+<icu:state>                   40-7e, 80-fc
+#
+CHARMAP
+#
+#
+#ISO 10646      IBM-943
+#_________      _________
+<U0000> \x00 |0
+<U0001> \x01 |0
+<U0002> \x02 |0
+<U0003> \x03 |0
+...
+<UFFE4> \xFA\x55 |1
+<UFFE5> \x81\x8F |0
+<UFFFD> \xFC\xFC |2
+END CHARMAP
+
+```
+
+The header fields are:
+
+1.  code_set_name - The name of the codepage. The makeconv tool generates the
+    .cnv file name from the .ucm filename but uses this header field for the
+    converter name that it writes into the .cnv file for ucnv_getName. The
+    makeconv tool prints a warning message if this header field does not match
+    the file name. The file name is not case-sensitive.
+
+2.  char_name_mask - This is ignored by makeconv tool. "AXXXX" specifies that
+    the POSIX-style character "name" consists of one letter (Alpha) followed by
+    4 hexadecimal digits. Since ICU only uses Unicode character "names" (for
+    example, code points) the format is fixed (see below).
+
+3.  mb_cur_min - The minimum number of bytes per character.
+
+4.  mb_cur_max - The maximum number of bytes per character.
+
+5.  uconv_class - This can be either "SBCS", "DBCS", "MBCS", or
+    "EBCDIC_STATEFUL"
+    The most general converter class/type/category is MBCS, which requires that
+    the codepage structure has the following <icu:state> lines. The other types
+    of converters are subsets of MBCS. The makeconv tool uses predefined state
+    tables for these other converters when their structure is not explicitly
+    specified. The following describes how the converter types are interpreted:
+
+    a.  MBCS: Generic ICU converter type, requires a state table
+
+    b.  SBCS: Single-byte, 8-bit codepages
+
+    c.  DBCS: Double-byte EBCDIC codepages
+
+    d.  EBCDIC_STATEFUL: Mixed Single-Byte or Double-Byte EBCDIC codepages (stateful, using SI/SO)
+
+The following shows the exact implied state tables for non-MBCS types. A state
+table may need to be overwritten in order to allow supplementary characters
+(U+10000 and up).
+
+1.  subchar - The substitution character byte sequence for this codepage. This sequence must be a valid byte sequence according to the codepage structure.
+
+2.  subchar1 - This is the single byte substitution character when subchar is defined. Some IBM converter libraries use different substitution characters for "narrow" and "wide" characters (single-byte and double-byte). ICU uses only one substitution character per codepage because it is common industry  practice.
+
+3.  icu:state - See the "State Table Syntax in .ucm Files" section for a  detailed description of how to specify a codepage structure.
+
+4.  icu:charsetFamily - This specifies if the codepage is ASCII or EBCDIC based.
+
+The subchar and subchar1 fields have been known to cause some confusion. The
+following conditions outline when each are used:
+
+1.  Conversion from Unicode to a codepage occurs and an unassigned code point is
+    found
+
+    a.  If a subchar1 byte is defined and a subchar1 mapping is defined for the code point (with a |2 precision indicator),
+        output the subchar1
+
+    b.  Otherwise output the regular subchar
+
+2.  Conversion from a codepage to Unicode occurs and an unassigned codepoint is found
+
+    a.  If the input sequence is of length 1 and a subchar1 byte is specified for the codepage, output U+001A
+
+    b.  Otherwise output U+FFFD
+
+In the CHARMAP section of a .ucm file, each line contains a Unicode code point
+(like <U(*1-6 hexadecimal digits for the code point*)> ), a codepage character
+byte sequence (each byte like `\xhh` (2 hexadecimal digits) ), and an optional
+"precision" or "fallback" indicator.
+
+The precision indicator either must be present in all mappings or in none of
+them. The indicator is a pipe symbol `|` followed by a 0, 1, 2, 3, or 4 that has
+the following meaning:
+
+*   `|0` - A "normal", roundtrip mapping from a Unicode code point and back.
+*   `|1` - A "fallback" mapping only from Unicode to the codepage, but not back.
+*   `|2` - A subchar1 mapping. The code point is unmappable, and if a substitution
+    is performed, then the subchar1 should be used rather than the subchar.
+    Otherwise, such mappings are ignored.
+*   `|3` - A "reverse fallback" mapping only from the codepage to Unicode, but not
+    back to the codepage.
+*   `|4` - A "good one-way" mapping only from Unicode to the codepage, but not
+    back.
+
+Fallback mappings from Unicode typically do not map codes for the same
+character, but for "similar" ones. This mapping is sometimes done if a character
+exists in Unicode but not in the codepage. To replace it, ICU maps a codepage
+code to a similar-looking code for human-readable output. This mapping feature
+is not useful for text data transmission especially in markup languages where a
+Unicode code point can be escaped with its code point value. The ICU application
+programming interface (API) `ucnv_setFallback()` controls this fallback behavior.
+
+"Reverse fallbacks" are technically similar, but the same Unicode character can
+be encoded twice in the codepage. ICU always uses reverse fallbacks at runtime.
+
+A subset of the fallback mappings from Unicode is always used at runtime: Those
+that map private-use Unicode code points. Fallbacks from private-use code points
+are often introduced as replacements for previous roundtrip mappings for the
+same pair of codes. These replacements are used when a Unicode version assigns a
+new character that was previously mapped to that private-use code point. The
+mapping table is then changed to map the same codepage byte sequence to the new
+Unicode code point (as a new roundtrip) and the mapping from the old private-use
+code point to the same codepage code is preserved as a fallback.
+
+A "good one-way" mapping is like a fallback, but ICU always uses "good one-way"
+mappings at runtime, regardless of the fallback API flag.
+
+The idea is that fallbacks normally lose information, such as mapping from a
+compatibility variant of a letter to the ASCII version; however, fallbacks from
+PUA and reverse fallbacks are assumed to be for "the same character", just an
+older code for it.
+
+Something similar happens with from-Unicode Variation Selector sequences. It is
+possible to round-trip (`|0`) either the unadorned character or the sequence with
+a variation selector, and add a "good one-way" mapping (`|4`) from the other
+version. That "good one-way" mapping does not lose much information, and it is
+used even if the "use fallback" API flag is false. Alternatively, both mappings
+could be fallbacks (`|1`) that should be controlled by the "use fallback"
+attribute.
+
+### State table syntax in .ucm files
+
+The conversion to Unicode uses a state machine to achieve the above capabilities
+with reasonable data file sizes. The state machine information itself is loaded
+with the conversion data and defines the structure of the codepage, including
+which byte sequences are valid, unassigned, and illegal. This data cannot (or
+not easily) be computed from the pure mapping data. Instead, the .ucm files for
+MBCS encodings have additional entries that are specific to the ICU makeconv
+tool. The state tables for SBCS, DBCS, and EBCDIC_STATEFUL are implied, but they
+can be overridden (see the examples below). These state tables are specified in
+the header section of the .ucm file that contains the `<icu:state>` element. Each
+line defines one aspect of the state machine. The state machine uses a table of
+as many rows as there are states (= as many as there are `<icu:state>` lines).
+Each row has 256 entries; one for each possible byte value.
+
+The state table lines in the .ucm header conform to the following Extended
+Backus-Naur Form (EBNF)-like grammar (whitespace is allowed between all tokens):
+
+```
+row=[[firstentry ','] entry (',' entry)*]
+firstentry="initial" | "surrogates"
+           (initial state (default for state 0), output is all surrogate pairs)
+```
+
+Each state table row description (that follows the `<icu:state>`) begins with an
+optional initial or surrogates keyword and is followed by one or more column
+entries. For the purpose of codepage state tables, the states=rows in the table
+are numbered beginning at 0 for the first line in the .ucm file header. The
+numbers are assigned implicitly by the makeconv tool in order of the `<icu:state>`
+lines.
+
+A row may be empty (nothing following the `<icu:state>`) - that is equivalent to
+"all illegal" or 0-ff.i and is useful for trail byte states for all-illegal byte
+sequences.
+
+```
+entry=range [':' nextstate] ['.' [action]]
+range     = number ['-' number]
+nextstate = number (0..7f)
+action    = 'u' | 's' | 'p' | 'i'
+                (unassigned, state change only, surrogate pair, illegal)
+number    = (1- or 2-digit hexadecimal number)
+```
+
+Each column entry contains at least one hexadecimal byte value or value range
+and is separated by a comma. The column entry specifies how to interpret an
+input byte in the row's state. If neither a next state nor an action is
+explicitly specified (only the byte range is given) then the byte value
+terminates the byte sequence, results in a valid mapping to a Unicode BMP
+character, and resets the state number to 0. The first line with `<icu:state>` is
+called state 0.
+
+The next state can be explicitly specified with a separating colon ( : )
+followed by the number of the state (=number/index of the row, starting at 0).
+This specification is mostly used for intermediate byte values (such as bytes
+that are not the last ones in a sequence). The state machine needs to proceed to
+the next state and read another byte. In this case, no other action is
+specified.
+
+If the byte value(s) terminate(s) a byte sequence, then the byte sequence
+results in the following depending on the action that is announced with a period
+( . ) followed by a letter:
+
+| letter | meaning |
+|--|---------|
+| u | Unassigned. The byte sequence is valid but does not encode a character. |
+| none | (no letter) - Valid. If no action letter is specified, then the byte sequence is valid and encodes a Unicode character up to U+ffff |
+| p | Surrogate Pair. The byte sequence is valid and the result may map to a UTF-16 encoded surrogate pair |
+| i | Illegal. The byte sequence is illegal. This is the default for all byte values in a row that are not otherwise specified with column entries|
+| s | State change only. The byte sequence does not encode any character but may change the state number. This may be used with simple, stateful encodings (for example, SI/SO codes), but currently it is not used by ICU.|
+
+If an action is specified without a next state, then the next state number
+defaults to 0. In other words, a byte value (range) terminates a sequence if
+there is an action specified for it, or when there is neither an action nor a
+next state. In this case, the byte value defaults to "valid, next state is 0"
+(equivalent to :0.).
+
+If a byte value is not specified in any column entry row, then it is illegal in
+the current state. If a byte value is specified in more than one column entry of
+the same row, then ICU uses the last state. These specifications allow you to
+assign common properties for a wide byte value range followed by a few
+exceptions. This is easier than having to specify mutually exclusive ranges,
+especially if many of them have the same properties.
+
+The optional keyword at the beginning of a state line has the following effect:
+
+| keyword | effect |
+|---------|--------|
+| initial | The state machine can start reading byte sequences in this state. State 0 is always an initial state. Only initial states can be next states for final byte values. In an initial state, the Unicode mappings for all final bytes are also stored directly in the state table.
+| surrogates | All Unicode mappings for final bytes in non-initial states are stored in a separate table of 16-bit Unicode (UTF-16) code units. Since most legacy codepages map only to Unicode code points up to U+ffff (the Basic Multilingual Plane, BMP), the default allocation per mapping result is one 16-bit unit. Individual byte values can be specified to map to surrogate pairs (= two 16-bit units) with action letter p. The surrogates keyword specifies the values for the entire state (row). Surrogate pair mapping entries can still hold single units depending on the actual mapping data, but single-unit mapping entries cannot hold a pair of units. Mapping to single-unit entries is the default because the mapping is faster, uses half as much memory in the code units table, and is sufficient for most legacy codepages.|
+
+When converting to Unicode, the state machine starts in state number 0. In each
+iteration, the state machine reads one input (codepage) byte and either proceeds
+to the next state as specified, or treats it as a final byte with the specified
+action and an optional non-0 next (initial) state. This means that a state table
+needs to have at least as many state rows as the maximum number of bytes per
+character, which is the maximum length of any byte sequence.
+
+Exception: For EBCDIC_STATEFUL codepages, double-byte sequences start in state
+1, with the SI/SO bytes switching from state 0 to state 1 or from state 1 to
+state 0. See the default state table below.
+
+### Extension and delta tables
+
+ICU 2.8 adds an additional "extension" data structure to its conversion tables.
+The new data structure supports a number of new features. When any of the
+following features are used, then all mappings must use a precision indicator.
+
+#### Converting multiple characters as a unit
+
+Before ICU 2.8, only one Unicode code point could be converted to or from one
+complete codepage byte sequence. The new data structure supports the conversion
+between multiple Unicode code points and multiple complete codepage byte
+sequences. (A "complete codepage byte sequence" is a sequence of bytes which is
+valid according to the state table.)
+
+Syntax: Simply write more than one Unicode code point on a mapping line, and/or
+more than one complete codepage byte sequence. Plus signs (+) are optional
+between code points and between bytes. For example,
+ibm-1390_P110-2003.ucm contains
+
+    <U304B><U309A> \xEC\xB5 |0
+
+and test3.ucm contains
+
+    <U101234>+<U50005>+<U60006> \x07+\x00+\x01\x02\x0f+\x09 |0
+
+For more examples see the ICU conversion data and the
+`icu/source/test/testdata/test*.ucm` test data files.
+
+ICU 2.8 supports up to 19 UChars on the Unicode side of a mapping and up to 31
+bytes on the codepage side.
+
+The longest match possible is converted in order to properly handle tables where
+the source sides of some mappings are prefixes of the source sides of other
+mappings.
+
+As a side effect, if conversion offsets are written and a potential match
+crosses buffer boundaries, then some of the initial offsets for the following
+output may be unknown (-1) because their input was stored in the converter from
+a previous buffer while looking for a longer match.
+
+Conversion tables for SI/SO-stateful (usually EBCDIC_STATEFUL) codepages cannot
+include mappings with SI or SO bytes or where there are SBCS characters in a
+multi-character byte sequence. In other words, for these tables there must be
+exactly one byte in a mapping or else a sequence of one or more DBCS characters.
+
+#### Delta (extension-only) conversion table files
+
+Physically, a binary conversion table (.cnv) file automatically contains both a
+traditional "base table" data structure for the 1:1 mappings and a new
+"extension table" for the m:n mappings if any are encountered in the .ucm file.
+An extension table can also be requested manually by splitting the CHARMAP into
+two. The first CHARMAP section will be used for the base table, and the second
+only for the extension table. M:n mappings in the first CHARMAP will be moved to
+the extension table.
+
+In order to save space for very similar conversion tables, it is possible to
+create delta .cnv files that contain only an extension table and the name of
+another .cnv file with a base table. The base file must be split into two
+CHARMAPs such that the base file's base table does not contain any mappings that
+contradict any of the delta file's mappings.
+
+The delta (extension-only) file uses only a single CHARMAP section. In addition,
+it nees a line in the header that both causes building just a delta file and
+specifies the name of the base file. For example, windows-936-2000.ucm contains
+
+    <icu:base> “ibm-1386_P100-2002”
+
+makeconv ignores all mappings for the delta file that are also in the base
+file's base table. If the two conversion tables are sufficiently similar, then
+the delta file will contain only a relatively small set of mappings, which
+results in a small .cnv file. At runtime, both the delta file and its base file
+are loaded, and the base file's base table is used together with the extension
+file. The base file works as a standalone file, using its own extension table
+for its full set of mappings. The base file must be in the same ICU data package
+as the delta file.
+
+The hard part is to split the base file's mappings into base and extension
+CHARMAPs such that the base table does not overlap with any delta file, while
+all shared mappings should be in the base table. (The base table data structure
+is more compact than the extension table data structure.)
+
+ICU provides the ucmkbase tool in the
+[ucmtools](https://github.com/unicode-org/icu-data/tree/main/charset/source/ucmtools)
+collection to do this.
+
+For example, the following illustrates how to use ucmkbase to make a base .ucm
+file for three Shift-JIS conversion table variants. (ibm-943_P15A-2003.ucm
+becomes the base.)
+
+```
+C:\tmp\icu\ucm>ren ibm-943_P15A-2003.ucm ibm-943_P15A-2003.orig
+C:\tmp\icu\ucm>ucmkbase ibm-943_P15A-2003.orig ibm-943_P130-1999.ucm ibm-942_P12A-1999.ucm > ibm-943_P15A-2003.ucm
+```
+
+After this, the two delta .ucm files only need to get the following line added
+before the start of their CHARMAPs:
+
+```
+<icu:base> "ibm-943_P15A-2003"
+```
+
+The ICU tools and runtime code handle DBCS-only conversion tables specially,
+allowing them to be built into delta files with MBCS or EBCDIC_STATEFUL base
+files without using their single-byte mappings, and without ucmkbase moving the
+single-byte mappings of the base file into the base file's extension table. See
+for example ibm-16684_P110-2003.ucm and ibm-1390_P110-2003.ucm.
+
+#### Other enhancements
+
+ICU 2.8 adds support for the specification of which unassigned Unicode code
+points should be mapped to subchar1 rather than the default subchar. See the
+discussion of subchar1 above for more details.
+
+The extension table data structure also removes one minor limitation on ICU
+conversion tables: Fallback mappings to a single byte 00 are now allowed and
+handled properly. ICU versions before 2.8 could only handle roundtrips to/from
+00.
+
+### Examples for codepage state tables
+
+The following shows the exact implied state tables for non-MBCS types, A state
+table may need to be overwritten in order to allow supplementary characters
+(U+10000 and up).
+
+US-ASCII
+```
+0-7f
+```
+
+This single-row state table describes US-ASCII. Byte values from 0 to 0x7f are
+valid and map to Unicode characters up to U+ffff. Byte values from 0x80 to 0xff
+are illegal.
+
+Shift-JIS
+```
+0-7f, 81-9f:1, a0-df, e0-fc:1
+40-7e, 80-fc
+```
+
+This two-row state table describes the Shift-JIS structure which encodes some
+characters with one byte each and others with two bytes each. Bytes 0 to 0x7f
+and 0xa0 to 0xdf are valid single-byte encodings. Bytes 0x81 to 0x9f and 0xe0 to
+0xfc are lead bytes. (For example, they are followed by one of the bytes that is
+specified as valid in state 1). A byte sequence of 0x85 0x61 is valid while a
+single byte of 0x80 or 0xff is illegal. Similarly, a byte sequence of 0x85 0x31
+is illegal.
+
+EUC-JP
+```
+0-8d, 8e:2, 8f:3, 90-9f, a1-fe:1
+a1-fe
+a1-e4
+a1-fe:1, a1:4, a3-af:4, b6:4, d6:4, da-db:4, ed-f2:4
+a1-fe.u
+```
+
+This fairly complicated state table describes EUC-JP. Valid byte sequences are
+one, two, or three bytes long. Two-byte sequences have a lead byte of 0x8e and
+end in state 2, or have lead bytes 0xa1 to 0xfe and end in state 1. Three-byte
+sequences have a lead byte of 0x8f and continue in state 3. Some final byte
+value ranges are entirely unassigned, therefore they end in state 4 with an
+action letter of u for "unassigned" to save significant memory for the code
+units table. Assigned three-byte sequences end in state 1 like most two-byte
+sequences.
+
+SBCS default state table:
+```
+0-ff
+```
+SBCS by default implies the structure for single-byte, 8-bit codepages.
+
+DBCS default state table:
+```
+0-3f:3, 40:2, 41-fe:1, ff:3
+41-fe
+40
+
+```
+
+**Important**:
+These are four states — the fourth has an empty line (equivalent to 0-ff.i)!
+DBCS codepages, by default, are defined with the EBCDIC double-byte structure.
+Valid sequences are pairs of bytes from 0x41 to 0xfe and the one pair 0x40/0x40
+for the double-byte space. The structure is defined such that all illegal byte
+sequences are always two in length. Therefore, every byte in the initial state
+is a lead byte.
+
+EBCDIC_STATEFUL default state table:
+```
+0-ff, e:1.s, f:0.s
+initial, 0-3f:4, e:1.s, f:0.s, 40:3, 41-fe:2, ff:4
+0-40:1.i, 41-fe:1., ff:1.i
+0-ff:1.i, 40:1.
+0-ff:1.i
+```
+
+This is the structure of Mixed Single-byte and Double-byte EBCDIC codepages,
+which are stateful and use the Shift-In/Shift-Out (SI/SO) bytes 0x0f/0x0e. The
+initial state 0 is almost the same as for SBCS except for SI and SO. State 1 is
+also an initial state and is the basis for a state-shifted version of the DBCS
+structure above. All double-byte sequences return to state 1 and SI switches
+back to state 0. SI and SO are also allowed in their own states with no effect.
+
+> :point_right:  **Note**: *If a DBCS or EBCDIC_STATEFUL codepage maps supplementary (non-BMP) Unicode
+> characters, then a modified state table needs to be specified in the .ucm file.
+> The state table needs to use the surrogates designation for a table row or .p
+> for some entries.*
+> 
+> *The reuse of a final or intermediate state (shown for EUC-JP) is valid for as
+> long as there is no circle in the state chain. The mappings will be unique
+> because of the different path to the shared state (sharing a state saves some
+> memory; each state table row occupies 1kB in the .cnv file). This table also
+> shows the redefinition of byte value ranges within one state row (State number
+> 3) as shorthand. State 3 defines bytes a1-fe to go to state 1, but the following
+> entries redefine and override certain bytes to go to state 4.*
+
+An initial state never needs a surrogates designation or .p because Unicode
+mapping results in initial states that are stored directly in the state table,
+providing enough room in each cell. The size of a generated .cnv mapping table
+file depends primarily on the number and distribution of the mappings and on the
+number of valid, multi-byte sequences that the state table allows. Each state
+table row takes up one kilobyte.
+
+For single-byte codepages, the state table cells contain all two-Unicode
+mappings. Code point results for multi-byte sequences are stored in an array
+with enough room for all valid byte sequences. For all byte sequences that end
+in a surrogates or .p state, Unicode allocates two code units.
+
+If possible, valid state table entries may be changed to .u to reduce the number
+of valid, assignable sequences and to make the .cnv file smaller. If additional
+states are necessary, then each additional state itself adds 1kB to the file
+size, diminishing the file size savings. See the EUC-JP example above.
+
+For codepages with up to two bytes per character, the makeconv tool
+automatically compacts the bytes, if possible, by introducing one more trail
+byte state. This state replaces valid entries in the original trail state with
+unassigned entries and changes each lead byte entry to work with the new state
+if there are no mappings with that lead byte.
+
+For codepages with up to three or four bytes per character, compaction must be
+done manually. However, if the verbose option is set on the command line, the
+makeconv tool will print useful information about unassigned byte sequences.

docs/userguide/conversion/detection.md

@@ -0,0 +1,359 @@
+---
+layout: default
+title: Charset Detection
+nav_order: 3
+parent: Conversion
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Character Set Detection
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+Character set detection is the process of determining the character set, or
+encoding, of character data in an unknown format. This is, at best, an imprecise
+operation using statistics and heuristics. Because of this, detection works best
+if you supply at least a few hundred bytes of character data that's mostly in a
+single language. In some cases, the language can be determined along with the
+encoding.
+
+Several different techniques are used for character set detection. For
+multi-byte encodings, the sequence of bytes is checked for legal patterns. The
+detected characters are also check against a list of frequently used characters
+in that encoding. For single byte encodings, the data is checked against a list
+of the most commonly occurring three letter groups for each language that can be
+written using that encoding. The detection process can be configured to
+optionally ignore html or xml style markup, which can interfere with the
+detection process by changing the statistics.
+
+The input data can either be a Java input stream, or an array of bytes. The
+output of the detection process is a list of possible character sets, with the
+most likely one first. For simplicity, you can also ask for a Java Reader that
+will read the data in the detected encoding.
+
+There is another character set detection C++ library, the [Compact Encoding
+Detector](https://github.com/google/compact_enc_det), that may have a lower
+error rate, particularly when working with short samples of text.
+
+## CharsetMatch
+
+The `CharsetMatch` class holds the result of comparing the input data to a
+particular encoding. You can use an instance of this class to get the name of
+the character set, the language, and how good the match is. You can also use
+this class to decode the input data.
+
+To find out how good the match is, you use the `getConfidence()` method to get a
+*confidence value*. This is an integer from 0 to 100. The higher the value, the
+more confidence there is in the match For example:
+
+```java
+CharsetMatch match = ...;
+int confidence;
+confidence = match.getConfidence();
+if (confidence < 50 ) {
+// handle a poor match...
+} else {
+// handle a good match...
+}
+```
+
+In C, you can use the `ucsdet_getConfidence(const UCharsetMatch *ucsm, UErrorCode *status)`
+method to get a confidence value.
+
+```c
+const UCharsetMatch *ucm;
+UErrorCode status = U_ZERO_ERROR;
+int32_t confidence = ucsdet_getConfidence(ucm, &status);
+if (confidence <50) {
+    // handle a poor match...
+} else {
+    // handle a good match...
+}
+```
+
+To get the name of the character set, which can be used as an encoding name in
+Java, you use the `getName()` method:
+
+```java
+CharsetMatch match = ...;
+byte characterData[] = ...;
+String charsetName;
+String unicodeData;
+charsetName = match.getName();
+unicodeData = new String(characterData, charsetName);
+```
+
+To get the name of the character set in C:
+
+```c
+const UCharsetMatch *ucm;
+UErrorCode status = U_ZERO_ERROR;
+const char *name = ucsdet_getName(ucm, &status);
+```
+
+To get the three letter ISO code for the detected language, you use the
+`getLanguage()` method. If the language could not be determined, `getLanguage()`
+will return `null`. Note that language detection does not work with all charsets,
+and includes only a very small set of possible languages. It should not used if
+robust, reliable language detection is required.
+
+```java
+CharsetMatch match = ...;
+String languageCode;
+languageCode = match.getLanguage();
+if (languageCode != null) {
+    // handle the language code...
+}
+```
+
+The `ucsdet_getLanguage(const UCharsetMatch *ucsm, UErrorCode *status)` method
+can be used in C to get the language code. If the language could not be
+determined, the method will return an empty string.
+
+```c
+const UCharsetMatch *ucm;
+UErrorCode status = U_ZERO_ERROR;
+const char *language = ucsdet_getLanguage(ucm, &status);
+```
+
+If you want to get a Java String containing the converted data you can use the
+`getString()` method:
+
+```java
+CharsetMatch match = ...;
+String unicodeData;
+unicodeData = match.getString();
+```
+
+If you want to limit the number of characters in the string, pass the maximum
+number of characters you want to the `getString()` method:
+
+```java
+CharsetMatch match = ...;
+String unicodeData;
+unicodeData = match.getString(1024);
+```
+
+To get a `java.io.Reader` to read the converted data, use the `getReader()` method:
+
+```java
+CharsetMatch match = ...;
+Reader reader;
+StringBuffer sb = new StringBuffer();
+char[] buffer = new char[1024];
+int bytesRead = 0;
+reader = match.getReader();
+while ((bytesRead = reader.read(buffer, 0, 1024)) >= 0) {
+    sb.append(buffer, 0, bytesRead);
+}
+reader.close();
+```
+
+## CharsetDetector
+
+The `CharsetDetector` class does the actual detection. It matches the input data
+against all character sets, and computes a list of `CharsetMatch` objects to hold
+the results. The input data can be supplied as an array of bytes, or as a
+`java.io.InputStream`.
+
+To use a `CharsetDetector` object, first you construct it, and then you set the
+input data, using the `setText()` method. Because setting the input data is
+separate from the construction, it is easy to reuse a `CharsetDetector` object:
+
+```java
+CharsetDetector detector;
+byte[] byteData = ...;
+InputStream streamData = ...;
+detector = new CharsetDetector();
+detector.setText(byteData);
+// use detector with byte data...
+detector.setText(streamData);
+// use detector with stream data...
+```
+
+If you want to know which character set matches your input data with the highest
+confidence, you can use the `detect()` method, which will return a `CharsetMatch`
+object for the match with the highest confidence:
+
+```java
+CharsetDetector detector;
+CharsetMatch match;
+byte[] byteData = ...;
+detector = new CharsetDetector();
+detector.setText(byteData);
+match = detector.detect();
+```
+
+If you want to know which character set matches your input data in C, you can
+use the `ucsdet_detect(UCharsetDetector *csd , UErrorCode *status)` method.
+
+```c
+UCharsetDetector *csd;
+const UCharsetMatch *ucm;
+static char buffer[BUFFER_SIZE] = {....};
+int32_t inputLength = ... // length of the input text
+UErrorCode status = U_ZERO_ERROR;
+ucsdet_setText(csd, buffer, inputLength, &status);
+ucm = ucsdet_detect(csd, &status);
+```
+
+If you want to know all of the character sets that could match your input data
+with a non-zero confidence, you can use the `detectAll()` method, which will
+return an array of `CharsetMatch` objects sorted by confidence, from highest to
+lowest.:
+
+```java
+CharsetDetector detector;
+CharsetMatch matches[];
+byte[] byteData = ...;
+detector = new CharsetDetector();
+detector.setText(byteData);
+matches = detector.detectAll();
+for (int m = 0; m < matches.length; m += 1) {
+    // process this match...
+}
+```
+
+> :point_right: **Note**: The `ucsdet_detectALL(UCharsetDetector *csd , int32_t *matchesFound, UErrorCode *status)` 
+> method can be used in C in order to detect all of the character sets where `matchesFound` is a pointer
+> to a variable that will be set to the number of charsets identified that are consistent with the input data.
+
+The `CharsetDetector` class also implements a crude *input filter* that can strip
+out html and xml style tags. If you want to enable the input filter, which is
+disabled when you construct a `CharsetDetector`, you use the `enableInputFilter()`
+method, which takes a boolean. Pass in true if you want to enable the input
+filter, and false if you want to disable it:
+
+```java
+CharsetDetector detector;
+CharsetMatch match;
+byte[] byteDataWithTags = ...;
+detector = new CharsetDetector();
+detector.setText(byteDataWithTags);
+detector.enableInputFilter(true);
+match = detector.detect();
+```
+
+To enable an input filter in C, you can use
+`ucsdet_enableInputFilter(UCharsetDetector *csd, UBool filter)` function.
+
+```c
+UCharsetDetector *csd;
+const UCharsetMatch *ucm;
+static char buffer[BUFFER_SIZE] = {....};
+int32_t inputLength = ... // length of the input text
+UErrorCode status = U_ZERO_ERROR;
+ucsdet_setText(csd, buffer, inputLength, &status);
+ucsdet_enableInputFilter(csd, TRUE);
+ucm = ucsdet_detect(csd, &status);
+```
+
+If you have more detailed knowledge about the structure of the input data, it is
+better to filter the data yourself before you pass it to CharsetDetector. For
+example, you might know that the data is from an html page that contains CSS
+styles, which will not be stripped by the input filter.
+
+You can use the `inputFilterEnabled()` method to see if the input filter is
+enabled:
+
+```java
+CharsetDetector detector;
+detector = new CharsetDetector();
+// do a bunch of stuff with detector
+// which may or may not enable the input filter...
+if (detector.inputFilterEnabled()) {
+    // handle enabled input filter
+} else {
+    // handle disabled input filter
+}
+```
+
+> :point_right: **Note**: The ICU4C API provide `uscdet_isInputFilterEnabled(const UCharsetDetector* csd)` function
+> to check whether the input filter is enabled.
+
+The `CharsetDetector` class also has two convenience methods that let you detect
+and convert the input data in one step: the `getReader()` and `getString()` methods:
+
+```java
+CharsetDetector detector;
+byte[] byteData = ...;
+InputStream streamData = ...;
+String unicodeData;
+Reader unicodeReader;
+detector = new CharsetDetector();
+unicodeData = detector.getString(byteData, null);
+unicodeReader = detector.getReader(streamData, null);
+```
+
+> :point_right: **Note**: The second argument to the `getReader()` and `getString()` methods
+> is a String called `declaredEncoding`, which is not currently used. There is also a
+> `setDeclaredEncoding()` method, which is also not currently used.
+
+The following code is equivalent to using the convenience methods:
+
+```java
+CharsetDetector detector;
+CharsetMatch match;
+byte[] byteData = ...;
+InputStream streamData = ...;
+String unicodeData;
+Reader unicodeReader;
+detector = new CharsetDetector();
+detector.setText(byteData);
+match = detector.detect();
+unicodeData = match.getString();
+detector.setText(streamData);
+match = detector.detect();
+unicodeReader = match.getReader();CharsetDetector
+```
+
+## Detected Encodings
+
+The following table shows all the encodings that can be detected. You can get
+this list (without the languages) by calling the `getAllDetectableCharsets()`
+method:
+
+| **Character Set** | **Languages** |
+| ----------------- | ------------- |
+| UTF-8             | &nbsp;        |
+| UTF-16BE          | &nbsp;        |
+| UTF-16LE          | &nbsp;        |
+| UTF-32BE          | &nbsp;        |
+| UTF-32LE          | &nbsp;        |
+| Shift_JIS         | Japanese      |
+| ISO-2022-JP       | Japanese      |
+| ISO-2022-CN       | Simplified Chinese |
+| ISO-2022-KR       | Korean        |
+| GB18030           | Chinese       |
+| Big5              | Traditional Chinese |
+| EUC-JP            | Japanese      |
+| EUC-KR            | Korean        |
+| ISO-8859-1        | Danish, Dutch, English, French, German, Italian, Norwegian, Portuguese, Swedish |
+| ISO-8859-2        | Czech, Hungarian, Polish, Romanian |
+| ISO-8859-5        | Russian       |
+| ISO-8859-6        | Arabic        |
+| ISO-8859-7        | Greek         |
+| ISO-8859-8        | Hebrew        |
+| ISO-8859-9        | Turkish       |
+| windows-1250      | Czech, Hungarian, Polish, Romanian |
+| windows-1251      | Russian       |
+| windows-1252      | Danish, Dutch, English, French, German, Italian, Norwegian, Portuguese, Swedish |
+| windows-1253      | Greek         |
+| windows-1254      | Turkish       |
+| windows-1255      | Hebrew        |
+| windows-1256      | Arabic        |
+| KOI8-R            | Russian       |
+| IBM420            | Arabic        |
+| IBM424            | Hebrew        |

docs/userguide/conversion/index.md

@@ -0,0 +1,156 @@
+---
+layout: default
+title: Conversion
+nav_order: 700
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Conversion
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Conversion Overview
+
+A converter is used to convert from one character encoding to another. In the
+case of ICU, the conversion is always between Unicode and another encoding, or
+vice-versa. A text encoding is a particular mapping from a given character set
+definition to the actual bits used to represent the data.
+
+Unicode provides a single character set that covers the major languages of the
+world, and a small number of machine-friendly encoding forms and schemes to fit
+the needs of existing applications and protocols. It is designed for best
+interoperability with both ASCII and ISO-8859-1 (the most widely used character
+sets) to make it easier for Unicode to be used in almost all applications and
+protocols.
+
+Hundreds of encodings have been developed over the years, each for small groups
+of languages and for special purposes. As a result, the interpretation of text,
+input, sorting, display, and storage depends on the knowledge of all the
+different types of character sets and their encodings. Programs have been
+written to handle either one single encoding at a time and switch between them,
+or to convert between external and internal encodings.
+
+There is no single, authoritative source of precise definitions of many of the
+encodings and their names. However,
+[IANA](http://www.iana.org/assignments/character-sets) is the best source for
+names, and our Character Set repository is a good source of encoding definitions
+for each platform.
+
+The transferring of text from one machine to another one often causes some loss
+of information. Some platforms have a different interpretation of the text than
+the other platforms. For example, Shift-JIS can be interpreted differently on
+Windows™ compared to UNIX®. Windows maps byte value 0x5C to the backslash
+symbol, while some UNIX machines map that byte value to the Yen symbol. Another
+problem arises when a character in the codepage looks like the Unicode Greek
+letter Mu or the Unicode micro symbol. Some platforms map this codepage byte
+sequence to one Unicode character, while another platform maps it to the other
+Unicode character. Fallbacks can partially fix this problem by mapping both
+Unicode characters to the same codepage byte sequence. Even though some
+character information is lost, the text is still readable.
+
+ICU's converter API has the following main features:
+
+1.  Unicode surrogate support
+
+2.  Support for all major encodings
+
+3.  Consistent text conversion across all computer platforms
+
+4.  Text data can be streamed (buffered) through the API
+
+5.  Fast text conversion
+
+6.  Supports fallbacks to the codepage
+
+7.  Supports reverse fallbacks to Unicode
+
+8.  Allows callbacks for handling and substituting invalid or unmapped byte
+    sequences
+
+9.  Allows a user to add support for unsupported encodings
+
+This section deals with the processes of converting encodings to and from
+Unicode.
+
+## Recommendations
+
+1.  **Use Unicode encodings whenever possible.** Together with Unicode for
+    internal processing, it makes completely globalized systems possible and
+    avoids the many problems with non-algorithmic conversions. (For a discussion
+    of such problems, see for example ["Character Conversions and Mapping
+    Tables"](http://icu-project.org/docs/papers/conversions_and_mappings_iuc19.ppt)
+    on <http://icu-project.org/docs/> and the [XML Japanese
+    Profile](http://www.w3.org/TR/japanese-xml/)).
+
+    1.  Use UTF-8 and UTF-16.
+
+    2.  Use UTF-16BE, SCSU and BOCU-1 as appropriate.
+
+    3.  In special environments, other Unicode encodings may be used as well,
+        such as UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, UTF-EBCDIC, and
+        CESU-8. (For turning Unicode filenames into ASCII-only filename strings,
+        the IMAP-mailbox-name encoding can be used.)
+
+    4.  Do not exchange text with single/unpaired surrogates.
+
+2.  **Use legacy charsets only when absolutely necessary**. For best data
+    fidelity:
+
+    1.  ISO-8859-1 is relatively unproblematic — if its limited character
+        repertoire is sufficient — because it is converted trivially (1:1) to
+        Unicode, avoiding conversion table problems for its small set of
+        characters. (By contrast, proper conversion from US-ASCII requires a
+        check for illegal byte values 0x80..0xff, which is an unnecessary
+        complication for modern systems with 8-bit bytes. ISO-8859-1 is nearly
+        as ubiquitous for modern systems as US-ASCII was for 7-bit systems.)
+
+    2.  If you need to communicate with a certain platform, then use the same
+        conversion tables as that platform itself, or at least ones that are
+        very, very close.
+
+    3.  ICU's conversion table repository contains hundreds of Unicode
+        conversion tables from a number of common vendors and platforms as well
+        as comparisons between these conversion tables:
+        <https://icu.unicode.org/charts/charset> .
+
+    4.  Do not trust codepage documentation that is not machine-readable, for
+        example nice-looking charts: They are usually incomplete and out of
+        date.
+
+    5.  ICU's default build includes about 200 conversion tables. See the [ICU
+        Data](../icudata.md) chapter for how to add or remove conversion tables
+        and other data.
+
+    6.  In ICU, you can (and should) also use APIs that map a charset name
+        together with a standard/platform name. This allows you to get different
+        converters for the same ambiguous charset name (like "Shift-JIS"),
+        depending on the standard or platform specified. See the
+        [convrtrs.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/mappings/convrtrs.txt)
+        alias table, the [Using Converters](converters.md) chapter and [API
+        references](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/ucnv_8h.html) .
+
+    7.  For data exchange (rather than pure display), turn off fallback
+        mappings: `ucnv_setFallback(cnv, FALSE)`;
+
+    8.  For some text formats, especially XML and HTML, it is possible to set an
+        "escape callback" function that turns unmappable Unicode code points
+        into corresponding escape sequences, preventing data loss. See the API
+        references and the [ucnv sample
+        code](https://github.com/unicode-org/icu/tree/main/icu4c/source/samples/ucnv/)
+        .
+
+    9.  **Never modify a conversion table.** Instead, use existing ones that
+        match precisely those in systems with which you communicate. "Modifying"
+        a conversion table in reality just creates a new one, which makes the
+        whole situation even less manageable.

docs/userguide/datetime/calendar/examples.md

@@ -0,0 +1,275 @@
+---
+layout: default
+title: Calendar Examples
+nav_order: 2
+parent: Date/Time
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Calendar Examples
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Calendar for Default Time Zone
+
+These C++, C , and Java examples get a Calendar based on the default time zone
+and add days to a date.
+
+**C++**
+
+```c++
+UErrorCode status = U_ZERO_ERROR;
+GregorianCalendar* gc = new GregorianCalendar(status);
+if (U_FAILURE(status)) {
+    puts("Couldn't create GregorianCalendar");
+    return;
+}
+// set up the date
+gc->set(2000, Calendar::FEBRUARY, 26);
+gc->set(Calendar::HOUR_OF_DAY, 23);
+gc->set(Calendar::MINUTE, 0);
+gc->set(Calendar::SECOND, 0);
+gc->set(Calendar::MILLISECOND, 0);
+// Iterate through the days and print it out.
+for (int32_t i = 0; i < 30; i++) {
+    // print out the date.  
+    // You should use the DateFormat to properly format it
+    printf("year: %d, month: %d (%d in the implementation), day: %d\n",
+    gc->get(Calendar::YEAR, status),
+    gc->get(Calendar::MONTH, status) + 1,
+    gc->get(Calendar::MONTH, status),
+    gc->get(Calendar::DATE, status));
+    if (U_FAILURE(status)) {
+        puts("Calendar::get failed");
+        return;
+    }
+    // Add a day to the date
+    gc->add(Calendar::DATE, 1, status);
+    if (U_FAILURE(status)) {
+        puts("Calendar::add failed");
+        return;
+    }
+}
+delete gc;
+```
+
+**C**
+
+```c
+UErrorCode status = U_ZERO_ERROR;
+int32_t i;
+UCalendar* cal = ucal_open(NULL, -1, NULL, UCAL_GREGORIAN, &status);
+if (U_FAILURE(status)) {
+    puts("Couldn't create GregorianCalendar");
+    return;
+}
+// set up the date
+ucal_set(cal, UCAL_YEAR, 2000);
+ucal_set(cal, UCAL_MONTH, UCAL_FEBRUARY); /* FEBRUARY */
+ucal_set(cal, UCAL_DATE, 26);
+ucal_set(cal, UCAL_HOUR_OF_DAY, 23);
+ucal_set(cal, UCAL_MINUTE, 0);
+ucal_set(cal, UCAL_SECOND, 0);
+ucal_set(cal, UCAL_MILLISECOND, 0);
+// Iterate through the days and print it out.
+for (i = 0; i < 30; i++) {
+    // print out the date.
+    // You should use the udat_* API to properly format it
+    printf("year: %d, month: %d (%d in the implementation), day: %d\n",
+           ucal_get(cal, UCAL_YEAR, &status),
+           ucal_get(cal, UCAL_MONTH, &status) + 1,
+           ucal_get(cal, UCAL_MONTH, &status),
+           ucal_get(cal, UCAL_DATE, &status));
+    if (U_FAILURE(status)) {
+        puts("Calendar::get failed");
+        return;
+    }
+    // Add a day to the date
+    ucal_add(cal, UCAL_DATE, 1, &status);
+    if (U_FAILURE(status)) {
+        puts("Calendar::add failed");
+        return;
+    }
+}
+ucal_close(cal);
+```
+
+**Java**
+
+```java
+Calendar cal = new GregorianCalendar();
+if (cal == null) {
+    System.out.println("Couldn't create GregorianCalendar");
+    return;
+}
+// set up the date
+cal.set(Calendar.YEAR, 2000);
+cal.set(Calendar.MONTH, Calendar.FEBRUARY); /* FEBRUARY */
+cal.set(Calendar.DATE, 26);
+cal.set(Calendar.HOUR_OF_DAY, 23);
+cal.set(Calendar.MINUTE, 0);
+cal.set(Calendar.SECOND, 0);
+cal.set(Calendar.MILLISECOND, 0);
+// Iterate through the days and print it out.
+for (int i = 0; i < 30; i++) {
+    // print out the date.
+    System.out.println(" year: " + cal.get(Calendar.YEAR) + 
+                       " month: " + (cal.get(Calendar.MONTH) + 1) +
+                       " day : " + cal.get(Calendar.DATE)
+    );
+    cal.add(Calendar.DATE, 1);
+}
+```
+
+## Converting dates between calendars
+
+These C++, C , and Java examples demonstrates converting dates from one calendar
+(Gregorian) to another calendar (Japanese).
+
+**C++**
+
+```c++
+UErrorCode status = U_ZERO_ERROR;
+UDate time;
+Calendar *cal1, *cal2;
+// Create a new Gregorian Calendar.
+cal1 = Calendar::createInstance("en_US@calendar=gregorian", status);
+if (U_FAILURE(status)) {
+    printf("Error creating Gregorian calendar.\n");
+    return;
+}
+// Set the Gregorian Calendar to a specific date for testing.
+cal1->set(1980, UCAL_SEPTEMBER, 3);
+// Display the date.
+printf("Gregorian Calendar:\t%d/%d/%d\n",
+        cal1->get(UCAL_MONTH, status) + 1,
+        cal1->get(UCAL_DATE, status),
+        cal1->get(UCAL_YEAR, status));
+if (U_FAILURE(status)) {
+    printf("Error getting Gregorian date.");
+    return;
+}
+// Create a Japanese Calendar.
+cal2 = Calendar::createInstance("ja_JP@calendar=japanese", status);
+if (U_FAILURE(status)) {
+    printf("Error creating Japnese calendar.\n");
+    return;
+}
+// Set the date.
+time = cal1->getTime(status);
+if (U_FAILURE(status)) {
+    printf("Error getting time.\n");
+    return;
+}
+cal2->setTime(time, status);
+if (U_FAILURE(status)) {
+    printf("Error setting the date for Japanese calendar.\n");
+    return;
+}
+// Set the timezone
+cal2->setTimeZone(cal1->getTimeZone());
+// Display the date.
+printf("Japanese Calendar:\t%d/%d/%d\n",
+        cal2->get(UCAL_MONTH, status) + 1,
+        cal2->get(UCAL_DATE, status),
+        cal2->get(UCAL_YEAR, status));
+if (U_FAILURE(status)) {
+    printf("Error getting Japanese date.");
+    return;
+}
+delete cal1;
+delete cal2;
+```
+
+**C**
+
+```c
+UErrorCode status = U_ZERO_ERROR;
+UDate time;
+UCalendar *cal1, *cal2;
+// Create a new Gregorian Calendar.
+cal1 = ucal_open(NULL, -1, "en_US@calendar=gregorian", UCAL_TRADITIONAL,
+                 &status);
+if (U_FAILURE(status)) {
+    printf("Couldn't create Gregorian Calendar.");
+    return;
+}
+// Set the Gregorian Calendar to a specific date for testing.
+ucal_setDate(cal1, 1980, UCAL_SEPTEMBER, 3, &status);
+if (U_FAILURE(status)) {
+    printf("Error setting date.");
+    return;
+}
+// Display the date.
+printf("Gregorian Calendar:\t%d/%d/%d\n",
+        ucal_get(cal1, UCAL_MONTH, &status) + 1,
+        ucal_get(cal1, UCAL_DATE, &status),
+        ucal_get(cal1, UCAL_YEAR, &status));
+if (U_FAILURE(status)) {
+    printf("Error getting Gregorian date.");
+    return 1;
+}
+// Create a Japanese Calendar.
+cal2 = ucal_open(NULL, -1, "ja_J@calendar=japanese", UCAL_TRADITIONAL, &status);
+if (U_FAILURE(status)) {
+    printf("Couldn't create Japanese Calendar.");
+    return 1;
+}
+// Set the date.
+time = ucal_getMillis(cal1, &status);
+if (U_FAILURE(status)) {
+    printf("Error getting time.\n");
+    return;
+}
+ucal_setMillis(cal2, time, &status);
+if (U_FAILURE(status)) {
+    printf("Error setting time.\n");
+    return;
+}
+// Display the date.
+printf("Japanese Calendar:\t%d/%d/%d\n",
+        ucal_get(cal2, UCAL_MONTH, &status) + 1,
+        ucal_get(cal2, UCAL_DATE, &status),
+        ucal_get(cal2, UCAL_YEAR, &status));
+if (U_FAILURE(status)) {
+    printf("Error getting Japanese date.");
+    return;
+}
+ucal_close(cal1);
+ucal_close(cal2);
+```
+
+**Java**
+
+```java
+Calendar cal1, cal2;
+// Create a new Gregorian Calendar.
+cal1 = new GregorianCalendar();
+// Set the Gregorian Calendar to a specific date for testing.
+cal1.set(1980, Calendar.SEPTEMBER, 3);
+// Display the date.
+System.out.println("Gregorian Calendar:\t" + (cal1.get(Calendar.MONTH) + 1) +
+                    "/" +
+                    cal1.get(Calendar.DATE) + "/" +
+                    cal1.get(Calendar.YEAR));
+// Create a Japanese Calendar.
+cal2 = new JapaneseCalendar();
+// Set the date and timezone
+cal2.setTime(cal1.getTime());
+cal2.setTimeZone(cal1.getTimeZone());
+// Display the date.
+System.out.println("Japanese Calendar:\t" + (cal2.get(Calendar.MONTH) + 1) +
+                    "/" +
+                    cal2.get(Calendar.DATE) + "/" +
+                    cal2.get(Calendar.YEAR));
+```

docs/userguide/datetime/calendar/index.md

@@ -0,0 +1,323 @@
+---
+layout: default
+title: Calendar Services
+nav_order: 1
+parent: Date/Time
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Calendar Classes
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+ICU has two main calendar classes used for parsing and formatting Calendar
+information correctly:
+
+1.  `Calendar`
+
+    An abstract base class that defines the calendar API. This API supports
+    UDate to fields conversion and field arithmetic.
+
+2.  `GregorianCalendar`
+
+    A concrete subclass of `Calendar` that implements the standard calendar used
+    today internationally.
+
+In addition to these, ICU has other `Calendar` subclasses to support
+non-gregorian calendars including:
+
+*   Buddhist
+
+*   Chinese
+
+*   Coptic
+
+*   Ethiopic
+
+*   Hebrew
+
+*   Indian
+
+*   Islamic
+
+*   Japanese
+
+*   Persian
+
+The `Calendar` class is designed to support additional calendar systems in the future.
+
+> :point_right: **Note**: *`Calendar` classes are related to `UDate`, the `TimeZone` classes, and the `DateFormat`
+classes.*
+
+### Calendar locale and keyword handling
+
+When a calendar object is created, via either `Calendar::create()`, or
+`ucal_open()`, or indirectly within a date formatter, ICU looks up the 'default'
+calendar type for that locale. At present, all locales default to a Gregorian
+calendar, except for the compatibility locales th_TH_TRADITIONAL and
+ja_JP_TRADITIONAL. If the "calendar" keyword is supplied, this value will
+override the default for that locale.
+
+For instance, `Calendar::createInstance("fr_FR", status)` will create a Gregorian calendar,
+but `Calendar::createInstance("fr_FR@calendar=buddhist")` will create a Buddhist calendar.
+
+It is an error to use an invalid calendar type. It will produce a missing resource error.
+
+> :point_right: **Note**: *As of ICU 2.8, the above description applies to ICU4J only. ICU4J will have
+this behavior in 3.0*
+
+## Usage
+
+This section discusses how to use the `Calendar` class and the `GregorianCalendar` subclass.
+
+### Calendar
+
+`Calendar` is an abstract base class. It defines common protocols for a hierarchy
+of classes. Concrete subclasses of `Calendar`, for example the `GregorianCalendar`
+class, define specific operations that correspond to a real-world calendar
+system. `Calendar` objects (instantiations of concrete subclasses of `Calendar`),
+embody state that represents a specific context. They correspond to a real-world
+locale. They also contain state that specifies a moment in time.
+
+The API defined by `Calendar` encompasses multiple functions:
+
+1.  Representation of a specific time as a `UDate`
+
+2.  Representation of a specific time as a set of integer fields, such as `YEAR`,
+    `MONTH`, `HOUR`, etc.
+
+3.  Conversion from `UDate` to fields
+
+4.  Conversion from fields to `UDate`
+
+5.  Field arithmetic, including adding, rolling, and field difference
+
+6.  Context management
+
+7.  Factory methods
+
+8.  Miscellaneous: field meta-information, time comparison
+
+#### Representation and Conversion
+
+The basic function of the `Calendar` class is to convert between a `UDate` value and
+a set of integer fields. A `UDate` value is stored as UTC time in milliseconds,
+which means it is calendar and time zone independent. `UDate` is the most compact
+and portable way to store and transmit a date and time. `Integer` field values, on
+the other hand, depend on the calendar system (that is, the concrete subclass of
+`Calendar`) and the calendar object's context state.
+
+> :point_right: **Note**: *`Integer` field values are needed when implementing a human interface that must
+display or input a date and/or time.*
+
+At any given time, a calendar object uses (when `DateFormat` is not sufficient)
+either its internal `UDate` or its integer fields (depending on which has been set
+most recently via `setTime()` or `set()`), to represent a specific date and time.
+Whatever the current internal representation, when the caller requests a `UDate`
+or an integer field it is computed if necessary. The caller need never trigger
+the conversion explicitly. The caller must perform a conversion to set either
+the `UDate` or the integer fields, and then retrieve the desired data. This also
+applies in situations where the caller has some integer fields and wants to
+obtain others.
+
+#### Field Arithmetic
+
+Arithmetic with `UDate` values is straightforward. Since the values are
+millisecond scalar values, direct addition and subtraction is all that is
+required. Arithmetic with integer fields is more complicated. For example, what
+is the date June 4, 1999 plus 300 days? `Calendar` defines three basic methods (in
+several variants) that perform field arithmetic: `add()`, `roll()`, and
+`fieldDifference()`.
+
+The `add()` method adds positive or negative values to a specified field. For
+example, calling `add(Calendar::MONTH, 2)` on a `GregorianCalendar` object set to
+March 15, 1999 sets the calendar to May 15, 1999. The `roll()` method is similar,
+but does not modify fields that are larger. For example, calling
+`roll(Calendar::HOUR, n)` changes the hour that a calendar is set to without
+changing the day. Calling `roll(Calendar::MONTH, n)` changes the month without
+changing the year.
+
+The `fieldDifference()` method is the inverse of the `add()` method. It computes the
+difference between a calendar's currently set time and a specified `UDate` in
+terms of a specified field. Repeated calls to `fieldDifference()` compute the
+difference between two `UDate` objects in terms of whatever fields the caller specifies
+(for example, years, months, days, and hours). If the `add()` method is called
+with the results of `fieldDifference(when, n)`, then the calendar is moved toward
+field by field.
+
+This is demonstrated in the following example:
+
+```c++
+Calendar cal = Calendar.getInstance();
+cal.set(2000, Calendar.MARCH, 15);
+Date date = new Date(2000-1900, Calendar.JULY, 4);
+int yearDiff = cal.fieldDifference(date, Calendar.YEAR); // yearDiff <= 0
+int monthDiff = cal.fieldDifference(date, Calendar.MONTH); // monthDiff ;<= 3
+// At this point cal has been advanced 3 months to June 15, 2000.
+int dayDiff = cal.fieldDifference(date, Calendar.DAY_OF_MONTH); // dayDiff ;<=19
+// At this point cal has been advanced 19 days to July 4, 2000.
+```
+
+#### Context Management
+
+A `Calendar` object performs its computations within a specific context. The
+context affects the results of conversions and arithmetic computations. When a
+`Calendar` object is created, it establishes its context using either default
+values or values specified by the caller:
+
+1.  Locale-specific week data, including the first day of the week and the
+    minimal days in the first week. Initially, this is retrieved from the locale
+    resource data for the specified locale, or if none is specified, for the
+    default locale.
+
+2.  A `TimeZone` object. Initially, this is set to the specified zone object, or
+    if none is specified, the default `TimeZone`.
+
+The context of a `Calendar` object can be queried after the calendar is created
+using calls such as `getMinimalDaysInFirstWeek()`, `getFirstDayOfWeek()`, and
+`getTimeZone()`. The context can be changed using calls such as
+`setMinimalDaysInFirstWeek()`, `setFirstDayOfWeek()`, and `setTimeZone()`.
+
+#### Factory Methods
+
+Like other format classes, the best way to create a calendar object is by using
+one of the factory methods. These are static methods on the `Calendar` class that
+create and return an instance of a concrete subclass. Factory methods should be
+used to enable the code to obtain the correct calendar for a locale without
+having to know specific details. The factory methods on `Calendar` are named
+`createInstance()`.
+
+***`MONTH` field***
+> :point_right: **Note**: *Calendar numbers months starting from zero, so calling `cal.set(1998, 3, 5)`
+sets cal to April 15, 1998, not March 15, 1998. This follows the Java
+convention. To avoid mistakes, use the constants defined in the `Calendar` class
+for the months and days of the week. For example, `cal.set(1998, Calendar::APRIL, 15)`.*
+
+#### Ambiguous Wall Clock Time Resolution
+
+When the time offset from UTC has changed, it produces an ambiguous time slot
+around the transition. For example, many US locations observe daylight saving
+time. On the date of transition to daylight saving time in US, wall clock time
+jumps from 12:59 AM (standard) to 2:00 AM (daylight). Therefore, wall clock
+times from 1:00 AM to 1:59 AM do not exist on the date. When the input wall time
+falls into this missing time slot, the ICU Calendar resolves the time using the
+UTC offset before the transition by default. In this example, 1:30 AM is
+interpreted as 1:30 AM standard time (non-exist), so the final result will be
+2:30 AM daylight time.
+On the date of transition back to standard time, wall clock time is moved back
+one hour at 2:00 AM. So wall clock times from 1:00 AM to 1:59 AM occur twice. In
+this case, the ICU Calendar resolves the time using the UTC offset after the
+transition by default. For example, 1:30 AM on the date is resolved as 1:30 AM
+standard time.
+Ambiguous wall clock time resolution behaviors can be customized by Calendar
+APIs `setRepeatedWallTimeOption()` and `setSkippedWallTimeOption()`. These APIs are
+available in ICU 49 or later versions.
+
+### `GregorianCalendar`
+
+The `GregorianCalendar` class implements two calendar systems, the Gregorian
+calendar and the Julian calendar. These calendar systems are closely related,
+differing mainly in their definition of the leap year. The Julian calendar has
+leap years every four years; the Gregorian calendar refines this by excluding
+century years that are not divisible by 400. `GregorianCalendar` defines two eras,
+BC (B.C.E.) and AD (C.E.).
+
+Historically, most western countries used the Julian calendar until the 16th to
+20th century, depending on the country. They then switched to the Gregorian
+calendar. The `GregorianCalendar` class mirrors this behavior by defining a
+cut-over date. Before this date, the Julian calendar algorithms are used. After
+it, the Gregorian calendar algorithms are used. By default, the cut-over date is
+set to October 4, 1582 C.E., which reflects the time when countries first began
+adopting the Gregorian calendar. The `GregorianCalendar` class does not attempt
+historical accuracy beyond this behavior, and does not vary its cut-over date by
+locale. However, users can modify the cut-over date by using the
+`setGregorianChange()` method.
+
+Code that is written correctly instantiates calendar objects using the Calendar
+factory methods, and therefore holds a `Calendar*` pointer. Such code cannot
+directly access the GregorianCalendar-specific methods not present in `Calendar`.
+The correct way to handle this is to perform a dynamic cast, after testing the
+type of the object using `getDynamicClassID()`. For example:
+
+```c++
+void setCutover(Calendar *cal, UDate myCutover) {
+    if (cal->getDynamicClassID() == GregorianCalendar::getStaticClassID()) {
+        GregorianCalendar *gc = (GregorianCalendar*)cal;
+        gc->setGregorianChange(myCutover, status);
+    }
+}
+```
+
+> :point_right: **Note**: *This is a general technique that should be used throughout ICU in conjunction
+with the factory methods.*
+
+### Disambiguation
+
+When computing a `UDate` from fields, some special circumstances can arise. There
+might be insufficient information to compute the `UDate` (such as only year and
+month but no day in the month), there might be inconsistent information (such as
+"Tuesday, July 15, 1996" -— July 15, 1996, is actually a Monday), or the input
+time might be ambiguous because of time zone transition.
+
+1.  **Insufficient Information**
+    ICU Calendar uses the default field values to specify missing fields. The
+    default for a field is the same as that of the start of the epoch (that is,
+    `YEAR = 1970`, `MONTH = JANUARY`, `DAY_OF_MONTH = 1`).
+
+2.  **Inconsistent Information**
+    If fields conflict, the calendar gives preference to fields set more
+    recently. For example, when determining the day, the calendar looks for one
+    of the following combinations of fields:
+    `MONTH + DAY_OF_MONTH`
+    `MONTH + WEEK_OF_MONTH + DAY_OF_WEEK`
+    `MONTH + DAY_OF_WEEK_IN_MONTH + DAY_OF_WEEK`
+    `DAY_OF_YEAR`
+    `DAY_OF_WEEK + WEEK_OF_YEAR`
+    For the time of day, the calendar looks for one of the following
+    combinations of fields:
+    `HOUR_OF_DAY`
+    `AM_PM + HOUR`
+
+3.  **Ambiguous Wall Clock Time**
+    When time offset from UTC has changed, it produces ambiguous time slot
+    around the transition. For example, many US locations observe daylight
+    saving time. On the date switching to daylight saving time in US, wall clock
+    time jumps from 1:00 AM (standard) to 2:00 AM (daylight). Therefore, wall
+    clock time from 1:00 AM to 1:59 AM do not exist on the date. When the input
+    wall time fall into this missing time slot, the ICU Calendar resolves the
+    time using the UTC offset before the transition by default. In this example,
+    1:30 AM is interpreted as 1:30 AM standard time (non-exist), so the final
+    result will be 2:30 AM daylight time.
+    On the date switching back to standard time, wall clock time is moved back
+    one hour at 2:00 AM. So wall clock time from 1:00 AM to 1:59 AM occur twice.
+    In this case, the ICU Calendar resolves the time using the UTC offset after
+    the transition by default. For example, 1:30 AM on the date is resolved as
+    1:30 AM standard time.
+
+***Options for Ambiguous Time Resolution***
+> :point_right: **Note**: *Ambiguous wall clock time resolution behaviors can be customized by Calendar APIs `setRepeatedTimeOption()` and `setSkippedTimeOption()`. These methods are available in ICU 49 or later versions.*
+
+***`WEEK_OF_YEAR` field***
+> :point_right: **Note**: *Values calculated for the `WEEK_OF_YEAR` field range from 1 to 53. Week 1 for a year is the first week that contains at least `getMinimalDaysInFirstWeek()` days from that year. It depends on the values of `getMinimalDaysInFirstWeek()`, `getFirstDayOfWeek()`, and the day of the week of January 1. Weeks between week 1 of one year and week 1 of the following year are numbered sequentially from 2 to 52 or 53 (if needed).
+For example, January 1, 1998 was a Thursday. If `getFirstDayOfWeek()` is `MONDAY`
+and `getMinimalDaysInFirstWeek()` is `4` (these are the values reflecting ISO 8601
+and many national standards), then week 1 of 1998 starts on December 29, 1997,
+and ends on January 4, 1998. However, if `getFirstDayOfWeek()` is `SUNDAY`, then
+week 1 of 1998 starts on January 4, 1998, and ends on January 10, 1998. The
+first three days of 1998 are then part of week 53 of 1997.*
+
+## Programming Examples
+
+Programming for calendar [examples in C++, C, and Java](examples.md) .

docs/userguide/datetime/index.md

@@ -0,0 +1,156 @@
+---
+layout: default
+title: Date/Time
+nav_order: 900
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Date/Time Services
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview of ICU System Time Zones
+
+A time zone represents an offset applied to Greenwich Mean Time (GMT) to obtain
+local time. The offset might vary throughout the year, if daylight savings time
+(DST) is used, or might be the same all year long. Typically, regions closer to
+the equator do not use DST. If DST is in use, then specific rules define the
+point at which the offset changes and the amount by which it changes. Thus, a
+time zone is described by the following information:
+
+*   An identifying string, or ID. This consists only of invariant characters
+    (see the file `utypes.h`). It typically has the format continent / city. The
+    city chosen is not the only city in which the zone applies, but rather a
+    representative city for the region. Some IDs consist of three or four
+    uppercase letters; these are legacy zone names that are aliases to standard
+    zone names.
+
+*   An offset from GMT, either positive or negative. Offsets range from
+    approximately minus half a day to plus half a day.
+
+If DST is observed, then three additional pieces of information are needed:
+
+1.  The precise date and time during the year when DST begins. In the first half
+    of the year it's in the northern hemisphere, and in the second half of the
+    year it's in the southern hemisphere.
+
+2.  The precise date and time during the year when DST ends. In the first half
+    of the year it's in the southern hemisphere, and in the second half of the
+    year it's in the northern hemisphere.
+
+3.  The amount by which the GMT offset changes when DST is in effect. This is
+    almost always one hour.
+
+### System and User Time Zones
+
+ICU supports local time zones through the classes `TimeZone` and `SimpleTimeZone` in
+the C++ API. In the C API, time zones are designated by their ID strings.
+
+Users can construct their own time zone objects by specifying the above
+information to the C++ API. However, it is more typical for users to use a
+pre-existing system time zone since these represent all current international
+time zones in use. This document lists the system time zones, both in order of
+GMT offset and in alphabetical order of ID.
+
+Since this list changes one or more times a year, *this document only represents
+a snapshot*. For the most current list of ICU system zones, use the method
+`TimeZone::getAvailableIDs()`.
+
+*The zones are listed in binary sort order (that is, 'A' through 'Z' come before
+'a' through 'z'). This is the same order in which the zones are stored
+internally, and the same order in which they are returned by
+`TimeZone::getAvailableIDs()`. The reason for this is that ICU locates zones using
+a binary search, and the binary search relies on this sort order.*
+*You might notice that zones such as Etc/GMT+1 appear to have the wrong sign for
+their GMT offset. In fact, their sign is inverted since the the Etc zones follow
+the POSIX sign conventions. This is the way the original Olson data is set up,
+and ICU reproduces the Olson data faithfully. See the Olson files for more
+details.*
+
+### References
+
+The ICU system time zones are derived from the tz database (also known as the
+“Olson” database) at [ftp://elsie.nci.nih.gov/pub](ftp://elsie.nci.nih.gov/pub).
+This is the data used across much of the industry, including by UNIX systems,
+and is usually updated several times each year. ICU (since version 2.8) and base
+Java (since Java 1.4) contain code and tz data supporting both current and
+historic time zone usage.
+
+## How ICU Represents Dates/Times
+
+ICU represents dates and times using `UDate`s. A `UDate` is a scalar value that
+indicates a specific point in time, independent of calendar system and local
+time zone. It is stored as the number of milliseconds from a reference point
+known as the epoch. The epoch is midnight Universal Time Coordinated (UTC)
+January 1, 1970 A.D. Negative `UDate` values indicate times before the epoch.
+
+*These classes have the same architecture as the Java classes.*
+
+Most people only need to use the `DateFormat` classes for parsing and formatting
+dates and times. However, for those who need to convert dates and times or
+perform numeric calculations, the services described in this section can be very
+useful.
+
+To translate a `UDate` to a useful form, a calendar system and local time zone
+must be specified. These are specified in the form of objects of the `Calendar`
+and `TimeZone` classes. Once these two objects are specified, they can be used to
+convert the `UDate` to and from its corresponding calendar fields. The different
+fields are defined in the `Calendar` class and include the year, month, day, hour,
+minute, second, and so on.
+
+Specific `Calendar` objects correspond to calendar systems (such as Gregorian) and
+conventions (such as the first day of the week) in use in different parts of the
+world. To obtain a `Calendar` object for France, for example, call
+`Calendar::createInstance(Locale::getFrance(), status)`.
+
+The `TimeZone` class defines the conversion between universal coordinated time
+(UTC), and local time, according to real-world rules. Different `TimeZone`
+objects correspond to different real-world time zones. For example, call
+`TimeZone::createTimeZone("America/Los_Angeles")` to obtain an object that
+implements the U.S. Pacific time zone, both Pacific Standard Time (PST) and
+Pacific Daylight Time (PDT).
+
+As previously mentioned, the `Calendar` and `TimeZone` objects must be specified
+correctly together. One way of doing so is to create each independently, then
+use the `Calendar::setTimeZone()` method to associate the time zone with the
+calendar. Another is to use the `Calendar::createInstance()` method that takes a
+`TimeZone` object. For example, call `Calendar::createInstance(
+TimeZone::createInstance( "America/Los_Angeles"), Locale:getUS(), status)` to
+obtain a `Calendar` appropriate for use in the U.S. Pacific time zone.
+
+ICU has four classes pertaining to calendars and timezones:
+
+*   [`Calendar`](calendar/index.md)
+    
+    `Calendar` is an abstract base class that represents a calendar system.
+    `Calendar` objects map `UDate` values to and from the individual fields used in
+    a particular calendar system. `Calendar` also performs field computations such
+    as advancing a date by two months.
+
+*   [`Gregorian Calendar`](calendar/index.md)
+    
+    `GregorianCalendar` is a concrete subclass of `Calendar` that implements the
+    rules of the Julian calendar and the Gregorian calendar, which is the common
+    calendar in use internationally today.
+
+*   [`TimeZone`](timezone/index.md)
+    
+    `TimeZone` is an abstract base class that represents a time zone. `TimeZone`
+    objects map between universal coordinated time (UTC) and local time.
+
+*   [`SimpleTimeZone`](timezone/index.md)
+    
+    `SimpleTimeZone` is a concrete subclass of `TimeZone` that implements standard
+    time and daylight savings time according to real-world rules. Individual
+    `SimpleTimeZone` objects correspond to real-world time zones.

docs/userguide/datetime/timezone/examples.md

@@ -0,0 +1,91 @@
+---
+layout: default
+title:  Date and Time Zone Examples
+nav_order: 4
+parent: Date/Time
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Date and Time Zone Examples
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## C++ TimeZone example code
+
+This example code illustrates some time zone operations.
+
+```c++
+ UErrorCode success = U_ZERO_ERROR;
+ UnicodeString dateReturned, curTZNameEn, curTZNameFr;
+ UDate curDate;
+ int32_t stdOffset,dstOffset;
+
+ // Create a Time Zone with America/Los_Angeles
+ TimeZone *tzWest = TimeZone::createTimeZone("America/Los_Angeles");
+
+
+// Print out the Time Zone Name, GMT offset etc.
+ curTZNameEn = tzWest->getDisplayName(Locale::getEnglish(),curTZNameEn);
+ u_printf("%s\n","Current Time Zone Name in English:");
+ u_printf("%S\n", curTZNameEn.getTerminatedBuffer());
+
+ curTZNameFr = tzWest->getDisplayName(Locale::getCanadaFrench(),curTZNameFr);
+ u_printf("%s\n","Current Time Zone Name in French:");
+ u_printf("%S\n", curTZNameFr.getTerminatedBuffer());
+
+
+ // Create a Calendar to get current date
+ Calendar* calendar = Calendar::createInstance(success);
+ curDate = calendar->getNow();
+
+
+ // Print out the Current Date/Time in the given time zone
+ DateFormat *dt = DateFormat::createDateInstance();
+ dateReturned = dt->format(curDate,dateReturned,success);
+ u_printf("%s\n", "Current Time:");
+ u_printf("%S\n", dateReturned.getTerminatedBuffer());
+
+
+ // Use getOffset to get the stdOffset and dstOffset for the given time
+ tzWest->getOffset(curDate,true,stdOffset,dstOffset,success);
+ u_printf("%s\n%d\n","Current Time Zone STD offset:",stdOffset/(1000*60*60));
+ u_printf("%s\n%d\n","Current Time Zone DST offset:",dstOffset/(1000*60*60));
+ u_printf("%s\n", "Current date/time is in daylight savings time?");
+ u_printf("%s\n", (calendar->inDaylightTime(success))?"Yes":"No");
+
+
+ // Use createTimeZoneIDEnumeration to get the specific Time Zone IDs
+ // in United States with -5 hour standard offset from GMT
+ stdOffset = (-5)*U_MILLIS_PER_HOUR; // U_MILLIS_PER_HOUR = 60*60*1000;
+ StringEnumeration *ids = TimeZone::createTimeZoneIDEnumeration(UCAL_ZONE_TYPE_CANONICAL_LOCATION,"US",&stdOffset,success);
+ for (int i=0; i<ids->count(success);i++) {
+   u_printf("%s\n",ids->next(NULL,success));
+ }
+
+
+ // Use Calendar to get the hour of the day for different time zones
+ int32_t hour1,hour2;
+ TimeZone *tzEast = TimeZone::createTimeZone("America/New_York");
+ Calendar * cal1 = Calendar::createInstance(tzWest,success);
+ Calendar * cal2 = Calendar::createInstance(tzEast,success);
+ hour1 = cal1->get(UCAL_HOUR_OF_DAY,success);
+ hour2 = cal2->get(UCAL_HOUR_OF_DAY,success);
+ u_printf("%s\n%d\n","Current hour of the day in North American West: ", hour1);
+ u_printf("%s\n%d\n","Current hour of the day in North American East: ", hour2);
+
+ delete cal1;
+ delete cal2;
+ delete ids;
+ delete calendar;
+ delete dt;
+ ```

docs/userguide/datetime/timezone/index.md

@@ -0,0 +1,257 @@
+---
+layout: default
+title: TimeZone Classes
+nav_order: 3
+parent: Date/Time
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# ICU TimeZone Classes
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+A time zone is a system that is used for relating local times in different
+geographical areas to one another. For example, in the United States, Pacific
+Time is three hours earlier than Eastern Time; when it's 6 P.M. in San
+Francisco, it's 9 P.M. in Brooklyn. To make things simple, instead of relating
+time zones to one another, all time zones are related to a common reference
+point.
+
+For historical reasons, the reference point is Greenwich, England. Local time in
+Greenwich is referred to as Greenwich Mean Time, or GMT. (This is similar, but
+not precisely identical, to Universal Coordinated Time, or UTC. We use the two
+terms interchangeably in ICU since ICU does not concern itself with either leap
+seconds or historical behavior.) Using this system, Pacific Time is expressed as
+GMT-8:00, or GMT-7:00 in the summer. The offset -8:00 indicates that Pacific
+Time is obtained from GMT by adding -8:00, that is, by subtracting 8 hours.
+
+The offset differs in the summer because of daylight savings time, or DST. At
+this point it is useful to define three different flavors of local time:
+
+* **Standard Time**:
+  Standard Time is local time without a daylight savings time offset. For
+  example, in California, standard time is GMT-8:00; that is, 8 hours before
+  GMT.
+* **Daylight Savings Time**:
+  Daylight savings time is local time with a daylight savings time offset.
+  This offset is typically one hour, but is sometimes less. In California,
+  daylight savings time is GMT-7:00. Daylight savings time is observed in most
+  non-equatorial areas.
+* **Wall Time**:
+  Wall time is what a local clock on the wall reads. In areas that observe
+  daylight savings time for part of the year, wall time is either standard
+  time or daylight savings time, depending on the date. In areas that do not
+  observe daylight savings time, wall time is equivalent to standard time.
+
+## Time Zones in ICU
+
+ICU supports time zones through two classes:
+
+* **TimeZone**:
+  `TimeZone` is an abstract base class that defines the time zone API. This API
+  supports conversion between GMT and local time.
+* **SimpleTimeZone**:
+  `SimpleTimeZone` is a concrete subclass of TimeZone that implements the
+  standard time zones used today internationally.
+
+Timezone classes are related to `UDate`, the `Calendar` classes, and the
+`DateFormat` classes.
+
+### Timezone Class in ICU
+
+`TimeZone` is an abstract base class. It defines common protocol for a hierarchy
+of classes. This protocol includes:
+
+* A programmatic ID, for example, "America/Los_Angeles". This ID is used to
+  call up a specific real-world time zone. It corresponds to the IDs defined
+  in the [IANA Time Zone datbase](https://www.iana.org/time-zones) used by UNIX
+  and other systems, and has the format continent/city or ocean/city.
+* A raw offset. This is the difference, in milliseconds, between a time zone's
+  standard time and GMT. Positive raw offsets are east of Greenwich.
+* Factory methods and methods for handling the default time zone.
+* Display name methods.
+* An API to compute the difference between local wall time and GMT.
+
+#### Factory Methods and the Default Timezone
+
+The TimeZone factory method `createTimeZone()` creates and returns a `TimeZone`
+object given a programmatic ID. The user does not know what the class of the
+returned object is, other than that it is a subclass of `TimeZone`.
+
+The `createAvailableIDs()` methods return lists of the programmatic IDs of all
+zones known to the system. These IDs may then be passed to `createTimeZone()` to
+create the actual time zone objects. ICU maintains a comprehensive list of
+current international time zones, as derived from the Olson data.
+
+`TimeZone` maintains a static time zone object known as the *default time zone*.
+This is the time zone that is used implicitly when the user does not specify
+one. ICU attempts to match this to the host OS time zone. The user may obtain a
+clone of the default time zone by calling `createDefault()` and may change the
+default time zone by calling `setDefault()` or `adoptDefault()`.
+
+#### Display Name
+
+When displaying the name of a time zone to the user, use the display name, not
+the programmatic ID. The display name is returned by the `getDisplayName()`
+method. A time zone may have three display names:
+
+* Generic name, such as "Pacific Time".
+* Standard name, such as "Pacific Standard Time".
+* Daylight savings name, such as "Pacific Daylight Time".
+
+Furthermore, each of these names may be LONG or SHORT. The SHORT form is
+typically an abbreviation, e.g., "PST", "PDT".
+
+In addition to being available directly from the `TimeZone` API, the display name
+is used by the date format classes to format and parse time zones.
+
+#### getOffset() API
+
+`TimeZone` defines the API `getOffset()` by which the caller can determine the
+difference between local time and GMT. This is a pure virtual API, so it is
+implemented in the concrete subclasses of `TimeZone`.
+
+## Updating the Time Zone Data
+
+Time zone data changes often in response to governments around the world
+changing their local rules and the areas where they apply. ICU derives its tz
+data from the [IANA Time Zone Database](http://www.iana.org/time-zones).
+
+The ICU project publishes updated timezone resource data in response to IANA
+updates, and these can be used to patch existing ICU installations. Several
+update strategies are possible, depending on the ICU version and configuration.
+
+* ICU4J: Use the time zone update utility.
+* ICU4C 54 and newer: Drop in the binary update files.
+* ICU4C 36 and newer: the best update strategy will depend on how ICU data
+  loading is configured for the specific ICU installation.
+  * Data is loaded from a .dat package file: replace the time zone resources
+    in the .dat file using the icupkg tool.
+  * Data is loaded from a .dll or .so shared library: obtain the updated
+    sources for the tz resources and rebuild the data library.
+  * Data is loaded from individual files: drop in the updated binary .res
+    files.
+
+The [ICU Data](../../icudata.md) section of this user guide gives more
+information on how ICU loads resources.
+
+The ICU resource files required for time zone data updates are posted at
+<https://github.com/unicode-org/icu-data/tree/main/tzdata/icunew>. The
+required resource files for ICU version 44 and newer are
+
+* zoneinfo64.res
+* windowsZones.res
+* timezoneTypes.res
+* metaZones.res
+
+### ICU4C TZ update of a .dat Package File
+
+For ICU configurations that load data from a .dat package file, replace the time
+zone resources in that file.
+
+1. Download the new .res files from
+   `https://github.com/unicode-org/icu-data/tree/main/tzdata/icunew/<IANA tz version>/44/<platform directory>`.
+   * `<IANA tz version>` is a combination of year and letter, such as "2019c".
+   * *"44"* is the directory for updates to ICU version 4.4 and newer.
+   * `<platform directory>` is "le" for little endian processors, including
+     all Intel processors.
+   * `<platform directory>` is "be" for big endian processors, including IBM
+     Power and Sparc.
+   * `<platform directory>` is "ee" for IBM mainframes using EBCDIC character
+     sets.
+2. Check that the tool "icupkg" is available. If not already on your system,
+   you can get it by [downloading](https://github.com/unicode-org/icu/releases)
+   and building ICU, following the instructions in the ReadMe file included in
+   the download. Alternatively, on many Linux systems, "apt-get install
+   icu-devtools" will install the tool.
+3. Locate the .dat file to be updated, and do the update. The commands below
+   are for a .dat file named icudt55l.dat.
+
+```shell
+icupkg -a zoneinfo64.res icudt55l.dat
+icupkg -a windowsZones.res icudt55l.dat
+icupkg -a timezoneTypes.res icudt55l.dat
+icupkg -a metaZones.res icudt55l.dat
+```
+
+In ICU versions older than 4.4 some of the time zone resources have slightly
+different names. The update procedure is the same, but substitute the names
+found in the desired download directory - 42, 40, 38 or 36.
+
+### ICU4C TZ Update with Drop-in .res files (ICU 54 and newer)
+
+With this approach, the four individual .res files are dropped in any convenient
+location in the file system, and ICU is given an absolute path to the directory
+containing them. For the time zone resources only, ICU will check this directory
+first when loading data. This approach will work even when all other ICU data
+loading is from a shared library or .dat file.
+
+There are two ways to specify the directory:
+
+* At ICU build time, by defining the C pre-processor variable
+  `U_TIMEZONE_FILES_DIR` to the run time path to the directory containing the
+  .res files.
+* At run time, by setting the environment variable `ICU_TIMEZONE_FILES_DIR` to
+  the absolute path of the directory containing the .res files.
+
+If both are defined, the environment variable `ICU_TIMEZONE_FILES_DIR` take
+precedence. If either is defined, the time zone directory will be checked first,
+meaning that time zone resource files placed there will override time zone
+resources that may exist in other ICU data locations.
+
+To do the update, download the .res files appropriate for the platform, as
+described for the .dat file update above, and copy them into the time zone res
+file directory.
+
+### ICU4C TZ update when ICU is configured for individual files
+
+If the ICU-using application sets an ICU data path (or can be changed to set
+one), then the time zone .res file can be placed there. Download the files as
+described above and copy them to the specified directory. See the
+[ICU Data](../../icudata.md) page of the user guide for more information about
+the ICU data path.
+
+### ICU4C TZ update when ICU data is built into a shared library
+
+1. Set up the environment necessary to rebuild your specific configuration of
+   ICU.
+2. Download the .txt file sources for the updated resources from
+   `https://github.com/unicode-org/icu-data/tree/main/tzdata/icunew/<IANA tz version>/44`
+3. Copy the downloaded .txt files into the ICU sources for your installation,
+   in the subdirectory source/data/misc/
+4. Rebuid ICU.
+5. Copy the freshly built ICU data shared library to the desired destination.
+
+> :point_right: **Note**: The standard ICU download package contains pre-built
+> ICU data. To rebuild ICU data from .txt files, you will need to replace the
+> contents of `icu4c/source/data` with the contents of ICU4C data.zip. See
+> [ICU Data Build Tool](../../icu_data/buildtool.md) for more details.
+
+There are too many possible platform variations to be more specific about how to
+rebuild ICU4C in these instructions. See the ReadMe file included with the ICU
+sources for general information on building ICU.
+
+### Update the time zone data for ICU4J
+
+The [ICU4J Time Zone Update Update
+Utility](https://icu.unicode.org/download/icutzu) automates the process of
+updating ICU4J jar files with the latest time zone data. Instructions for use
+are [here](https://htmlpreview.github.io/?https://github.com/unicode-org/icu-data/blob/main/tzdata/tzu/readme.html).
+
+The updater will work with ICU version 3.4.2 and newer.
+
+## Sample Code
+
+See the [Date and Time Zone Examples](examples.md) subpage.

docs/userguide/datetime/universaltimescale.md

@@ -0,0 +1,271 @@
+---
+layout: default
+title: Universal Time Scale
+nav_order: 5
+parent: Date/Time
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Universal Time Scale
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+There are quite a few different conventions for binary datetime, depending on
+the platform or protocol. Some of these have severe drawbacks. For example,
+people using Unix time (seconds since Jan 1, 1970, usually in a 32-bit integer)
+think that they are safe until near the year 2038. But cases can and do arise
+where arithmetic manipulations causes serious problems. Consider the computation
+of the average of two datetimes, for example: if one calculates them with
+`averageTime = (time1 + time2)/2`, there will be overflow even with dates
+beginning in 2004. Moreover, even if these problems don't occur, there is the
+issue of conversion back and forth between different systems.
+
+Binary datetimes differ in a number of ways: the data type, the unit, and the
+epoch (origin). We'll refer to these as time scales. For example: (Sorted by
+epoch and unit, descending. In Java, `int64_t`=`long` and `int32_t`=`int`.)
+
+| Source                                         | Data Type                                                                          | Epoch       | Unit                                                    |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------- |
+| MacOS X (`CFDate/NSDate`)                      | `double` (1.0=1s but fractional seconds are used as well; imprecise for 0.1s etc.) | 2001-Jan-01 | seconds (and fractions thereof)                         |
+| Unix `time_t`                                  | `int32_t` or `int64_t` (`signed int32_t` limited to 1970..2038)                    | 1970-Jan-01 | seconds                                                 |
+| Java `Date`                                    | `int64_t`                                                                          | 1970-Jan-01 | milliseconds                                            |
+| Joda `DateTime`                                | `int64_t`                                                                          | 1970-Jan-01 | milliseconds                                            |
+| ICU4C `UDate`                                  | `double` (does not use fractional milliseconds)                                    | 1970-Jan-01 | milliseconds                                            |
+| JavaScript `Date`                              | `double` (does not use fractional milliseconds; JavaScript Number stores a double) | 1970-Jan-01 | milliseconds                                            |
+| Unix `struct timeval (as in gettimeofday)`     | `struct: time_t` (seconds); suseconds_t (microseconds)                             | 1970-Jan-01 | microseconds                                            |
+| Gnome `g_get_real_time()`                      | `gint64`                                                                           | 1970-Jan-01 | microseconds                                            |
+| Unix `struct timespec` (as in `clock_gettime`) | `struct: time_t` (seconds); long (nanoseconds)                                     | 1970-Jan-01 | nanoseconds                                             |
+| MacOS (old)                                    | `uint32_t` (1904..2040)                                                            | 1904-Jan-01 | seconds                                                 |
+| Excel                                          | ?                                                                                  | 1899-Dec-31 | days                                                    |
+| DB2                                            | ?                                                                                  | 1899-Dec-31 | days                                                    |
+| Windows `FILETIME`                             | `int64_t`                                                                          | 1601-Jan-01 | ticks (100 nanoseconds; finest granularity in industry) |
+| .NET `DateTime`                                | `uint62` (only 0001-9999; only 62 bits; also 2-bit field for UTC/local)            | 0001-Jan-01 | ticks (100 nanoseconds; finest granularity in industry) |
+| ICU Universal Time Scale                       | `int64_t`                                                                          | 0001-Jan-01 | same as .Net but allows 29000BC..29000AD                |
+
+All of the epochs start at 00:00 am (the earliest possible time on the day in
+question), and are usually assumed to be UTC.
+
+The ranges, in years, for different data types are given in the following table.
+The range for integer types includes the entire range expressible with positive
+and negative values of the data type. The range for double is the range that
+would be allowed without losing precision to the corresponding unit.
+
+| Units                  | 64-bit integer          | Double         | 32-bit integer |
+| ---------------------- | ----------------------- | -------------- | -------------- |
+| 1 second               | 5.84542x10<sup>11</sup> | 285,420,920.94 | 136.10         |
+| 1 millisecond          | 584,542,046.09          | 285,420.92     | 0.14           |
+| 1 microsecond          | 584,542.05              | 285.42         | 0.00           |
+| 100 nanoseconds (tick) | 58,454.20               | 28.54          | 0.00           |
+| 1 nanosecond           | 584.5420461             | 0.2854         | 0.00           |
+
+ICU implements a universal time scale that is similar to the 
+[.NET framework's System.DateTime](https://docs.microsoft.com/dotnet/api/system.datetime?view=netframework-4.8).
+The universal time scale is a 64-bit integer that holds ticks since midnight,
+January 1<sup>st</sup>, 0001. Negative values are supported. This has enough
+range to guarantee that calculations involving dates around the present are safe.
+
+The universal time scale always measures time according to the proleptic
+Gregorian calendar. That is, the Gregorian calendar's leap year rules are used
+for all times, even before 1582 when it was introduced. (This is different from
+the default ICU calendar which switches from the Julian to the Gregorian
+calendar in 1582. See `GregorianCalendar::setGregorianChange()` and
+`ucal_setGregorianChange()`).
+
+ICU provides conversion functions to and from all other major time scales,
+allowing datetimes in any time scale to be converted to the universal time
+scale, safely manipulated, and converted back to any other datetime time scale.
+
+## Background
+
+So how did we decide what to use for the universal time scale? Java time has
+plenty of range, but cannot represent a .NET `System.DateTime` value without
+severe loss of precision. ICU4C time addresses this by using a `double` that is
+otherwise equivalent to the Java time. However, there are disadvantages with
+doubles. They provide for much more graceful degradation in arithmetic
+operations. But they only have 53 bits of accuracy, which means that they will
+lose precision when converting back and forth to ticks. What would really be
+nice would be a `long double` (80 bits -- 64 bit mantissa), but that is not
+supported on most systems.
+
+The Unix extended time uses a structure with two components: time in seconds and
+a fractional field (microseconds). However, this is clumsy, slow, and prone to
+error (you always have to keep track of overflow and underflow in the fractional
+field). `BigDecimal` would allow for arbitrary precision and arbitrary range, but
+we did not want to use this as the normal type, because it is slow and does not
+have a fixed size.
+
+Because of these issues, we concluded that the .NET `System.DateTime` is the best
+timescale to use. However, we use the full range allowed by the data type,
+allowing for datetimes back to 29,000 BC and up to 29,000 AD. (`System.DateTime`
+uses only 62 bits and only supports dates from 0001 AD to 9999 AD). This time
+scale is very fine grained, does not lose precision, and covers a range that
+will meet almost all requirements. It will not handle the range that Java times
+do, but frankly, being able to handle dates before 29,000 BC or after 29,000 AD
+is of very limited interest.
+
+## Constants
+
+ICU provides routines to convert from other timescales to the universal time
+scale, to convert from the universal time scale to other timescales, and to get
+information about a particular timescale. In all of these routines, the
+timescales are referenced using an integer constant, according to the following
+table:
+
+| Source                 | ICU4C                         | ICU4J                    |
+| ---------------------- | ----------------------------- | ------------------------ |
+| Java                   | `UDTS_JAVA_TIME`              | `JAVA_TIME`              |
+| Unix                   | `UDTS_UNIX_TIME`              | `UNIX_TIME`              |
+| ICU4C                  | `UDTS_ICU4C_TIME`             | `ICU4C_TIME`             |
+| Windows FILETIME       | `UDTS_WINDOWS_FILE_TIME`      | `WINDOWS_FILE_TIME`      |
+| .NET DateTime          | `UDTS_DOTNET_DATE_TIME`       | `DOTNET_DATE_TIME`       |
+| Macintosh (old)        | `UDTS_MAC_OLD_TIME`           | `MAC_OLD_TIME`           |
+| Macintosh              | `UDTS_MAC_TIME`               | `MAC_TIME`               |
+| Excel                  | `UDTS_EXCEL_TIME`             | `EXCEL_TIME`             |
+| DB2                    | `UDTS_DB2_TIME`               | `DB2_TIME`               |
+| Unix with microseconds | `UDTS_UNIX_MICROSECONDS_TIME` | `UNIX_MICROSECONDS_TIME` |
+
+The routine that gets a particular piece of information about a timescale takes
+an integer constant that identifies the particular piece of information,
+according to the following table:
+
+| Value                | ICU4C                      | ICU4J                |
+| -------------------- | -------------------------- | -------------------- |
+| Precision            | `UTSV_UNITS_VALUE`         | `UNITS_VALUE`        |
+| Epoch offset         | `UTSV_EPOCH_OFFSET_VALUE`  | `EPOCH_OFFSET_VALUE` |
+| Minimum "from" value | `UTSV_FROM_MIN_VALUE`      | `FROM_MIN_VALUE`     |
+| Maximum "from" value | `UTSV_FROM_MAX_VALUE`      | `FROM_MAX_VALUE`     |
+| Minimum "to" value   | `UTSV_TO_MIN_VALUE`        | `TO_MIN_VALUE`       |
+| Maximum "to" value   | `UTSV_TO_MAX_VALUE`        | `TO_MAX_VALUE`       |
+
+Here is what the values mean:
+
+* Precision -- the precision of the timescale, in ticks.
+* Epoch offset -- the distance from the universal timescale's epoch to the timescale's epoch, in the timescale's precision.
+* Minimum "from" value -- the minimum timescale value that can safely be converted to the universal timescale.
+* Maximum "from" value -- the maximum timescale value that can safely be converted to the universal timescale.
+* Minimum "to" value -- the minimum universal timescale value that can safely be converted to the timescale.
+* Maximum "to" value -- the maximum universal timescale value that can safely be converted to the timescale.
+
+## Converting
+
+You can convert from other timescale values to the universal timescale using the
+"from" methods. In ICU4C, you use `utmscale_fromInt64`:
+
+```c
+UErrorCode err = U_ZERO_ERROR;
+int64_t unixTime = ...;
+int64_t universalTime;
+
+universalTime = utmscale_fromInt64(unixTime, UDTS_UNIX_TIME, &err);
+```
+
+In ICU4J, you use `UniversalTimeScale.from`:
+
+```java
+long javaTime = ...;
+long universalTime;
+
+universalTime = UniversalTimeScale.from(javaTime, UniversalTimeScale.JAVA_TIME);
+```
+
+You can convert values in the universal timescale to other timescales using the
+"to" methods. In ICU4C, you use `utmscale_toInt64`:
+
+```c
+UErrorCode err = U_ZERO_ERROR;
+int64_t universalTime = ...;
+int64_t unixTime;
+
+unixTime = utmscale_toInt64(universalTime, UDTS_UNIX_TIME, &err);
+```
+
+In ICU4J, you use `UniversalTimeScale.to`:
+
+```java
+long universalTime = ...;
+long javaTime;
+
+javaTime = UniversalTimeScale.to(universalTime, UniversalTimeScale.JAVA_TIME);
+```
+
+That's all there is to it!
+
+If the conversion is out of range, the ICU4C routines
+will set the error code to `U_ILLEGAL_ARGUMENT_ERROR`, and the ICU4J methods will
+throw `IllegalArgumentException`. In ICU4J, you can avoid out of range conversions
+by using the `BigDecimal` methods:
+
+```java
+long fileTime = ...;
+double icu4cTime = ...;
+BigDecimal utICU4C, utFile, utUnix, unixTime, macTime;
+
+utFile   = UniversalTimeScale.bigDecimalFrom(fileTime, UniversalTime.WINDOWS_FILE_TIME);
+
+utICU4C  = UniversalTimeScale.bigDecimalFrom(icu4cTime, UniversalTimeScale.ICU4C_TIME);
+
+unixTime = UniversalTimeScale.toBigDecimal(utFile, UniversalTime.UNIX_TIME);
+macTime  = UniversalTimeScale.toBigDecimal(utICU4C, UniversalTime.MAC_TIME);
+
+utUnix   = UniversalTimeScale.bigDecimalFrom(unixTime, UniversalTime.UNIX_TIME);
+```
+
+> :point_right: **Note**: Because the Universal Time Scale has a finer resolution
+> than some other time scales, time values that can be represented exactly in the 
+> Universal Time Scale will be rounded when converting to these time scales, and
+> resolution will be lost. If you convert these values back to the Universal Time
+> Scale, you will not get the same time value that you started with. If the time
+> scale to which you are converting uses a double to represent the time value, you
+> may loose precision even though the double supports a range that is larger than
+> the range supported by the Universal Time Scale.
+
+## Formatting and Parsing
+
+Currently, ICU does not support direct formatting or parsing of Universal Time
+Scale values. If you want to format a Universal Time Scale value, you will need
+to convert it to an ICU time scale value first. Use `UTDS_ICU4C_TIME` with ICU4C,
+and `UniversalTimeScale.JAVA_TIME` with ICU4J.
+
+When you parse a datetime string, the result will be an ICU time scale value.
+You can convert this value to a Universal Time Scale value using `UDTS_ICU4C_TIME`
+with ICU4C, and `UniversalTime.JAVA_TIME` for ICU4J.
+
+See the previous section, *Converting*, for details of how to do the conversion.
+
+## Getting Timescale Information
+
+To get information about a particular timescale in ICU4C, use
+`utmscale_getTimeScaleValue`:
+
+```c
+UErrorCode err = U_ZERO_ERROR;
+int64_t unixEpochOffset = utmscale_getTimeScaleValue(
+    UDTS_UNIX_TIME,
+    UTSV_EPOCH_OFFSET_VALUE,
+    &err);
+```
+
+In ICU4J, use `UniversalTimeScale.getTimeScaleValue`:
+
+```java
+long javaEpochOffset = UniversalTimeScale.getTimeScaleValue(
+    UniversalTimeScale.JAVA_TIME,
+    UniversalTimeScale.EPOCH_OFFSET_VALUE);
+```
+
+If the integer constants for selecting the timescale or the timescale value are
+out of range, the ICU4C routines will set the error code to
+`U_ILLEGAL_ARGUMENT_ERROR`, and the ICU4J methods will throw
+`IllegalArgumentException`.

docs/userguide/dev/contributions.md

@@ -0,0 +1,137 @@
+---
+layout: default
+title: Contributions
+nav_order: 4
+parent: Contributors
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Contributions to the ICU library
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Why Contribute?
+
+ICU is an open source library that is a de-facto industry standard for
+internationalization libraries. Our goal is to provide top of the line i18n
+support on all widely used platforms. By contributing your code to the ICU
+library, you will get the benefit of continuing improvement by the ICU team and
+the community, as well as testing and multi-platform portability. In addition,
+it saves you from having to re-merge your own additions into ICU each time you
+upgrade to a new ICU release.
+
+## Current Process
+
+See <https://icu.unicode.org/processes/contribute>.
+
+## Historical
+
+### Legal Issues ICU 1.8.1-57
+
+The following process was in place up to ICU 57, when the old ICU license was
+used.
+
+### Old Process
+
+In order for your code to be contributed, you need to assign to IBM joint
+copyright ownership in the contribution. You retain joint ownership in the
+contribution without restriction. (For the complete set of terms, please see the
+forms mentioned below.)
+
+The sections below describe two processes, for one-time and ongoing
+contributors. In either case, please complete the form(s) electronically and
+send it/them to IBM for review. After review by IBM, please print and sign the
+form(s), send it/them by mail, and send the code. The code will then be
+evaluated.
+
+Please consult a legal representative if you do not understand the implications
+of the copyright assignment.
+
+### One-Time Contributors
+
+If you would like to make a contribution only once or infrequently, please use
+the *Joint Copyright Assignment - One-time Contribution* form.
+(<https://github.com/unicode-org/icu-docs/blob/main/legal/contributions/Copyright_Assignment.rtf>).
+The contribution will be identified by a bug ID which is unique to the
+contribution and entered into the form. Therefore, please make sure that there
+is an appropriate bug (or Request For Enhancement) in the ICU bug database, or
+submit one.
+
+The code contribution will be checked into a special part of the ICU source code
+repository and evaluated. The ICU team may request updates, for example for
+better conformance with the ICU [design](../design.md) principles,
+[coding](codingguidelines.md) and testing guidelines, or performance. (See also
+the Requirements (§) above.) Such updates can be contributed without exchanging
+another form: An ICU team member commits related materials into the ICU source
+code repository using the same bug ID that was entered into the copyright
+assignment form.
+
+### Ongoing Contributors
+
+If you are interested in making frequent contributions to ICU, then the ICU
+Project Management Committee may agree to invite you as an ongoing contributor.
+Ongoing contributors may be individuals but are more typically expected to be
+companies with one or more people ("authors") writing different parts of one or
+more contributions.
+
+In this case, the relationship between the contributor and the ICU team is much
+closer: One or more authors belonging to the contributor will have commit access
+to the ICU source code repository. With this direct access come additional
+responsibilities including an understanding that the contributor will work to
+follow the technical Requirements (§) above for contributions, and agreement to
+adhere to the terms of the copyright assignment forms for all future
+contributions.
+
+The process for ongoing contributors involves two types of forms: Initially, and
+only once, an ongoing contributor submits a *Joint Copyright Assignment by
+Ongoing Contributor* form, agreeing to essentially the same terms as in the
+one-time contributor form, for all future contributions. (See the form at
+<https://github.com/unicode-org/icu-docs/blob/main/legal/contributions/Copyright_Assignment_ongoing.rtf>).
+
+The contributor must also send another form, *Addendum to Joint Copyright
+Assignment by Ongoing Contributor: Authors*, for the initial set and each
+addition of authors to ICU contributions, **before** any contributions from
+these authors are committed into the ICU source code repository. (Only new,
+additional authors need to be listed on each such form.) The contributor agrees
+to ensure that all of these authors agree to adhere to the terms of the
+associated *Joint Copyright Assignment by Ongoing Contributor Agreement*. (See
+the Authors Addendum form at
+<https://github.com/unicode-org/icu-docs/blob/main/legal/contributions/Copyright_Assignment_authors.rtf>).
+
+Some of an ongoing contributor's authors will have commit access to the ICU
+source code repository. Their committer IDs need to be established before
+completing the Authors Addendum form, so that these committer IDs can be entered
+there. (The committer IDs should be activated only after the form is received.)
+
+Committer authors commit materials directly into the appropriate parts of the
+ICU source code repository. Contributions from an ongoing contributor are
+identified by their association with the contributor's committer IDs.
+
+### Previous Contributions
+
+All previous "one-off" contributions from non-IBM sources to ICU are listed on
+the code contributions page in ICU's source code repository. The page contains
+links to the softcopies of the Joint Copyright Assignment forms. See
+<https://htmlpreview.github.io/?https://github.com/unicode-org/icu-docs/blob/main/legal/contributions/code_contributions.html>
+
+In addition, the following non-IBM companies are registered as Ongoing
+Contributors:
+
+*   Apple
+*   Google
+
+See the repository folder that contains the contributions page for the full set
+of softcopies of contributor agreements including one-off contributions,
+ongoing-contributor agreements and author-addendum documents to
+ongoing-contributor agreements:
+<https://github.com/unicode-org/icu-docs/tree/main/legal/contributions>

docs/userguide/dev/editing.md

@@ -0,0 +1,200 @@
+---
+layout: default
+title: User Guide Editing
+nav_order: 5
+parent: Contributors
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Editing the ICU User Guide
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+This version of the ICU User Guide is generated directly from the Markdown
+files in the `/docs` directory of the main repository. In particular, the
+Markdown files are customized to work with the Jekyll static site generator,
+which benefits from [GitHub's built-in support](https://docs.github.com/en/github/working-with-github-pages/setting-up-a-github-pages-site-with-jekyll)
+for Jekyll sites.
+
+## How to Contribute
+
+Because ICU User Guide source files are now contained within the main
+repository, changes can now be made through the same process for contributing 
+code patches. See [Contributions to the ICU Library](constributions.md) for the
+current process of filing an issue and submitting a pull request.
+
+In the case of a single file edit (ex: typo correction), a convenient way to
+create the pull request is to follow the "Edit this page on Github" link at
+the bottom of the page and [use GitHub to edit the file](https://docs.github.com/en/github/managing-files-in-a-repository/editing-files-in-your-repository)
+and create the new pull request.
+
+After the source branch for a potential pull request is made, the changes can 
+be previewed using the fork repository that contains the source branch.  The
+fork repository must be [configured to serve GitHub Pages](https://docs.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#choosing-a-publishing-source)
+from the branch and the Markdown pages root directory (`/docs`).
+> :point_right: **Note**:  there is a
+latency of several minutes before GitHub Pages renders new changes, and 
+[errors](https://docs.github.com/en/github/working-with-github-pages/about-jekyll-build-errors-for-github-pages-sites)
+prevent the changes from being rendered.
+
+## Jekyll Theme Configuration
+
+Jekyll site-wide configurations are stored
+in the `_config.yml` file. The current theme being used is
+[Just the Docs](https://pmarsceill.github.io/just-the-docs/).
+
+Due to incompatibilities between this theme and GitHub’s built-in implementation of the
+CommonMark Markdown parser, the default Jekyll Markdown parser, Kramdown, is
+used.
+
+## Document Structure
+
+Major chapters have Introduction pages, and further sections in a chapter are
+subpages of that main chapter page. The navigation bar is generated from the
+information provided in the header section of the Markdown file according to
+the theme's [navigation annotations](https://pmarsceill.github.io/just-the-docs/docs/navigation-structure/).
+
+## Syntax
+
+[Markdown](https://kramdown.gettalong.org/syntax.html) should be preferred over custom
+HTML to create content wherever possible.
+
+## Common Styles
+
+Styles are provided by the theme's settings, which can be modified in `_config.yml`.
+
+## Code
+
+Use the markdown notation of [single backtick](https://kramdown.gettalong.org/quickref.html#inline-code)
+code spans (inline) and [tilde line-demarcated](https://kramdown.gettalong.org/quickref.html#code-blocks)
+fenced code blocks (multi-line).
+
+Unlike Github-flavored Markdown, in multi-line fenced code
+blocks, the programming language in the [info string](https://spec.commonmark.org/0.29/#info-string)
+should be lowercased.
+
+## Notes
+
+> :point_right: **Note**: Notes should be made by starting the line with the
+following Markdown:
+
+~~~
+> :point_right: **Note**:
+~~~
+
+## TODOs
+
+"TODO" items should be marked by starting the line with the
+following Markdown:
+
+~~~
+> :construction: **TODO**:
+~~~
+
+This will result in a "TODO" item like this:
+
+> :construction: **TODO**: Adjust this page for use of GitHub Markdown (since 2020)
+
+## Emoji
+
+GitHub-flavored emoji are enabled using the
+[Jemoji](https://github.com/jekyll/jemoji) Ruby gem.
+
+## Bookmarks & Links
+
+For internal links, please used relative paths to the corresponding Markdown 
+file as the Markdown link path rather than specifying the full URL.
+
+Anchors are generated by Jekyll for sections using the section header text in
+lowercase with hyphens instead of spaces.
+
+> :construction: **TODO**: search our pages for "(§)" and fix the links.
+
+## Previewing Changes Locally
+
+Because of the latency in GitHub Pages rendering changes, it can be useful to 
+run a Jekyll instance locally to preview changes.
+
+### Setup
+
+GitHub Pages provides a list of
+[dependency versions](https://pages.github.com/versions/) used in order
+to allow local environments to match exactly. Since Jekyll is a Ruby project,
+setup details depend on gems (code packages), Bundler (dependency management for
+execution), and the version of Ruby.
+
+[rbenv](https://www.ruby-lang.org/en/documentation/installation/#rbenv) is one
+of the few different ways to install and control the version of Ruby.  To 
+install it and the required `ruby-build` plugin:
+```bash
+git clone https://github.com/rbenv/rbenv.git ~/.rbenv
+cd ~/.rbenv && src/configure && make -C src # Optional but greatly speeds up certain operations
+echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
+```
+```bash
+mkdir -p "$(rbenv root)"/plugins
+git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
+```
+
+To install specific Ruby version that GitHub Pages uses:
+```bash
+rbenv versions  # list all Ruby versions available
+rbenv install <version-num>  # install GH Pages Ruby version
+rbenv versions  # list all Ruby versions after installing
+```
+
+To activate the version of Ruby:
+```bash
+rbenv init  # OR:  eval "$(rbenv init -)"
+rbenv shell <version-num>
+rbenv versions  # verify the specified version is in use
+```
+
+To install [Bundler](https://bundler.io/):
+```bash
+gem install bundler
+```
+
+The simplest way to ensure that
+transitive dependency versions are included correctly is to just specify the
+`github-pages` gem. This is already configured in `Gemfile` in the root
+directory. Thus, to ensure that the Ruby shell has the correct versions of
+dependencies downloaded and cached, in the root directory (`/docs`), run:
+```bash
+cd <ICU>/docs  # change to User Guide docs root directory
+bundle update
+```
+
+### Running
+
+Ensure that the specific version of Ruby has been activated. Then use Bundler
+to ensure that the dependencies are downloaded in the current Ruby "shell"
+instance.  Then use Bundler to execute the Jekyll server.
+```bash
+rbenv init  # OR:  eval "$(rbenv init -)"
+rbenv shell <version-num>
+cd <ICU>/docs  # change to User Guide docs root directory
+bundle update
+bundle exec jekyll server
+```
+
+Jekyll will take several seconds to generate HTML from the Markdown, so the
+Jekyll server will wait for that before being ready. Then, the rendered pages
+will be available at <http://localhost:4000/icu/>.
+
+## Previous version
+
+The previous version of the ICU User Guide has been maintained via Google Sites. The Site
+address is <http://sites.google.com/site/icuprojectuserguide/>

docs/userguide/dev/index.md

@@ -0,0 +1,21 @@
+---
+layout: default
+title: Contributors
+nav_order: 1800
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Contributors
+
+Top-level page for topics for contributors to ICU. See the subpages listed below for
+details:
+
+[Coding Guidelines](codingguidelines.md)
+
+[Contributions to the ICU library](contributions.md)
+
+[Synchronization Issues](sync/index.md)

docs/userguide/dev/sync/custom.md

@@ -0,0 +1,245 @@
+---
+layout: default
+title: Custom ICU4C Synchronization
+nav_order: 3
+parent: Contributors
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Custom ICU4C Synchronization
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+> :warning: ***Support for including an alternate implementation of atomic and mutex
+> operations has been withdrawn and removed from ICU4C.***
+> See issue [ICU-20185](https://unicode-org.atlassian.net/browse/ICU-20185).
+
+### Build Time User Provided Synchronization
+
+Build time user synchronization provides a mechanism for platforms with special
+requirements to provide their own mutex and one-time initialization
+implementations to ICU. This facility was introduced in ICU 53. It may change
+over time.
+
+The alternative implementations are compiled directly into the ICU libraries.
+Alternative implementations cannot be plugged in at run time.
+
+The tables below show the items that must be defined by a custom ICU
+synchronization implementation. The list includes both functions that are used
+throughout ICU code and additional functions are for internal by other ICU
+synchronization primitives.
+
+**Low Level Atomics**, a set of platform or compiler dependent typedefs and
+inlines. Provided in the internal header file
+[`umutex.h`](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/umutex.h).
+
+| Type/Function                                           | Description                                                                   |
+|---------------------------------------------------------|-------------------------------------------------------------------------------|
+| `typedef u_atomic_int32_t`                              | A 32 bit integer that will work with low level atomic operations. (`typedef`) |
+| `umtx_loadAcquire(u_atomic_int32_t &var)`               |                                                                               |
+| `umtx_storeRelease(u_atomic_int32_t &var, int32_t val)` |                                                                               |
+| `umtx_atomic_inc(u_atomic_int32_t &var)`                |                                                                               |
+| `umtx_atomic_dec(u_atomic_int32_t &var)`                |                                                                               |
+
+**Mutexes**. Type declarations for ICU mutex wrappers. Provided in a header file.
+
+| Type                  | Description                                                                                       |
+|-----------------------|---------------------------------------------------------------------------------------------------|
+| `struct UMutex`       | An ICU mutex. All instances will be static. Typically just contains an underlying platform mutex. |
+| `U_MUTEX_INITIALIZER` | A C style initializer for a static instance of a `UMutex`.                                          |
+
+**Mutex and InitOnce implementations**. Out-of-line platform-specific code.
+Provided in a .cpp file.
+
+| Function                                | Description                                |
+|-----------------------------------------|--------------------------------------------|
+| `umtx_lock(UMutex *mutex)`              | Lock a mutex.                              |
+| `umtx_unlock(UMutex* mutex)`            | Unlock a mutex.                            |
+| `umtx_initImplPreInit(UInitOnce &uio)`  | `umtx_initOnce()` implementation function. |
+| `umtx_initImplPostInit(UInitOnce &uio)` | `umtx_initOnce()` implementation function. |
+
+`UInitOnce` and `umtx_initOnce()` are used internally by ICU for thread-safe
+one-time initialization. Their implementation is split into a
+platform-independent part (contained in
+[`umutex.h`](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/umutex.h)),
+and the pair of platform-dependent implementation functions listed above.
+
+**Build Setup**
+
+Compiler preprocessor variables are used to name the custom files to be included
+in the ICU build. If defined, the files are included at the top of the normal
+platform `#ifdef` chains in the ICU sources, and effectively define a new
+platform.
+
+| Macro              | Description                                             |
+|--------------------|---------------------------------------------------------|
+| `U_USER_ATOMICS_H` | Set to the name of the low level atomics header file.   |
+| `U_USER_MUTEX_H`   | Mutexes header file.                                    |
+| `U_USER_MUTEX_CPP` | Mutexes and `InitOnce` implementation file.             |
+
+It is possible (and reasonable) to supply only the two mutex files, while
+retaining the ICU default implementation for the low level atomics.
+
+Example ICU configure with user mutexes specified:
+
+    CPPFLAGS='-DU_USER_ATOMICS_H=atomic_c11.h -DU_USER_MUTEX_H=mutex_c11.h -DU_USER_MUTEX_CPP=mutex_c11.cpp' ./runConfigureICU --enable-debug Linux
+
+**Stability**
+
+This interface may change between ICU releases. The required set of functions
+may be extended, or details of the behavior required may be altered.
+
+The types and functions defined by this interface reach deeply into the ICU
+implementation, and we need to retain the ability to make changes should the
+need arise.
+
+**Examples**
+
+The code below shows a complete set of ICU user synchronization files.
+
+This implementation uses C++11 language mutexes and atomics. These make for a
+convenient reference implementation because the C++11 constructs are well
+defined and straight forward to use.
+
+Similar implementations for POSIX and Windows can be found in files
+`common/umutex.h` and `common/umutex.cpp`, in the platform `#ifdef` chains; these are
+part of the standard ICU distribution.
+
+**Mutex Header**
+```c++
+// Example of an ICU build time customized mutex header.
+//
+// Must define struct UMutex and an initializer that will work with static instances.
+// All UMutex instances in ICU code will be static.
+
+#ifndef ICU_MUTEX_C11_H
+#define ICU_MUTEX_C11_H
+#include <mutex>
+#include <condition_variable>
+struct UMutex {
+    std::mutex fMutex;
+};
+#define U_MUTEX_INITIALIZER {}
+#endif
+```
+
+**Atomics Header**
+```c++
+#include <atomic>
+
+typedef std::atomic<int32_t> u_atomic_int32_t;
+#define ATOMIC_INT32_T_INITIALIZER(val) ATOMIC_VAR_INIT(val)
+
+inline int32_t umtx_loadAcquire(u_atomic_int32_t &var) {
+    return var.load(std::memory_order_acquire);
+}
+
+inline void umtx_storeRelease(u_atomic_int32_t &var, int32_t val) {
+    var.store(val, std::memory_order_release);
+}
+
+inline int32_t umtx_atomic_inc(u_atomic_int32_t &var) {
+    return var.fetch_add(1) + 1;
+}
+
+inline int32_t umtx_atomic_dec(u_atomic_int32_t &var) {
+    return var.fetch_sub(1) - 1;
+}
+```
+
+**Mutex and InitOnce implementations**
+```c++
+//
+// Example ICU build time custom mutex cpp file.
+//
+// Must implement these functions:
+// umtx_lock(UMutex *mutex);
+// umtx_unlock(UMutex *mutex);
+// umtx_initImplPreInit(UInitOnce &uio);
+// umtx_initImplPostInit(UInitOnce &uio);
+
+U_CAPI void U_EXPORT2
+umtx_lock(UMutex *mutex) {
+    if (mutex == NULL) {
+        // Note: globalMutex is pre-defined in the platform-independent ICU code.
+        mutex = &globalMutex;
+    }
+    mutex->fMutex.lock();
+}
+
+U_CAPI void U_EXPORT2
+umtx_unlock(UMutex* mutex) `{
+    if (mutex == NULL) {
+        mutex = &globalMutex;
+    }
+    mutex->fMutex.unlock();
+}
+
+// A mutex and a condition variable are used by the implementation of umtx_initOnce()
+// The mutex is held only while the state of the InitOnce object is being changed or
+// tested. It is not held while initialization functions are running.
+// Threads needing to block, waiting for an initialization to complete, will wait
+// on the condition variable.
+// All InitOnce objects share a common mutex and condition variable. This means that
+// all blocked threads will wake if any (possibly unrelated) initialization completes.
+// Which does no harm, it should be statistically rare, and any spuriously woken
+// threads will check their state and promptly wait again.
+
+static std::mutex initMutex;
+static std::condition_variable initCondition;
+
+// This function is called from umtx_initOnce() when an initial test of a UInitOnce::fState flag
+// reveals that initialization has not completed, that we either need to call the
+// function on this thread, or wait for some other thread to complete the initialization.
+//
+// The actual call to the init function is made inline by template code
+// that knows the C++ types involved. This function returns TRUE if
+// the inline code needs to invoke the Init function, or FALSE if the initialization
+// has completed on another thread.
+//
+// UInitOnce::fState values:
+// 0: Initialization has not yet begun.
+// 1: Initialization is in progress, not yet complete.
+// 2: Initialization is complete.
+//
+UBool umtx_initImplPreInit(UInitOnce &uio) {
+    std::unique_lock<std::mutex> initLock(initMutex);
+    int32_t state = uio.fState;
+    if (state == 0) {
+        umtx_storeRelease(uio.fState, 1);
+        return TRUE; // Caller will next call the init function.
+    } else {
+        while (uio.fState == 1) {
+            // Another thread is currently running the initialization.
+            // Wait until it completes.
+            initCondition.wait(initLock);
+        }
+        U_ASSERT(uio.fState == 2);
+        return FALSE;
+    }
+}
+
+// This function is called from umtx_initOnce() just after an initializationfunction completes.
+// Its purpose is to set the state of the UInitOnce object to initialized, and to
+// unblock any threads that may be waiting on the initialization.
+//
+// Some threads may be waiting on the condition variable, requiring the notify_all().
+// Some threads may be racing to test the fState flag outside of the mutex, 
+// requiring the use of store-release when changing its value.
+
+void umtx_initImplPostInit(UInitOnce &uio) {
+    std::unique_lock<std::mutex> initLock(initMutex);
+    umtx_storeRelease(uio.fState, 2);
+    initCondition.notify_all();
+}
+```

docs/userguide/dev/sync/index.md

@@ -0,0 +1,86 @@
+---
+layout: default
+title: Synchronization
+nav_order: 2
+parent: Contributors
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Synchronization Issues
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+ICU is designed for use in multi-threaded environments. Guidelines for
+developers using ICU are in the [ICU Design](../../design.md) section of the
+user guide.
+
+Within the ICU implementation, access to shared or global data sometimes must be
+protected in order to provide the threading model promised by the ICU design.
+The information on this page is intended for developers of ICU library code
+itself.
+
+ICU4J uses normal JDK synchronization services.
+
+ICU4C faces a more difficult problem, as there is no standard, fully portable
+set of C or C++ synchronization primitives. Internally, ICU4C provides a small
+set of synchronization operations, and requires that all synchronization needed
+within the ICU library code be implemented using them.
+
+The ICU4C synchronization primitives are for internal use only; they are not
+exported as API to normal users of ICU.
+
+ICU provides implementations of its synchronization functions for Windows, POSIX
+and C++11 platforms, and provides a build-time interface to allow [custom
+implementations](custom.md) for other platforms.
+
+## ICU4C Synchronization Primitives
+
+The functions and types listed below are intended for use throughout the ICU
+library code, where ever synchronization is required. They are defined in the
+internal header
+[umutex.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/umutex.h).
+
+All synchronization within ICU4C implementation code must use these, and avoid
+direct use of functions provided by a particular operating system or compiler.
+
+For examples of use, search the ICU library code.
+
+**Low Level Atomics**
+
+| Type/Function                            | Description                                                     |
+|------------------------------------------|-----------------------------------------------------------------|
+| `typedef u_atomic_int32_t`               | A 32 bit integer type for use with low level atomic operations. |
+| `umtx_atomic_inc(u_atomic_int32_t &var)` |                                                                 |
+| `umtx_atomic_dec(u_atomic_int32_t &var)` |                                                                 |
+
+**Mutexes**
+
+| Type/Function                | Description                                                           |
+|------------------------------|-----------------------------------------------------------------------|
+| `struct UMutex`              | An ICU mutex. All instances must be `static`.                         |
+| `U_MUTEX_INITIALIZER`        | A C style initializer for a `UMutex`.                                 |
+| `umtx_lock(UMutex *mutex)`   | Lock a mutex.                                                         |
+| `umtx_unlock(UMutex* mutex)` | Unlock a mutex.                                                       |
+| `class Mutex`                | C++ Mutex wrapper with automatic lock & unlock. See header `mutex.h.` |
+
+**One Time Initialization**
+
+| Type/Function                   | Description                                                                             |
+|---------------------------------|-----------------------------------------------------------------------------------------|
+| `struct UInitOnce`              | Provides an efficient facility for one-time initialization of static or global objects. |
+| `umtx_initOnce(UInitOnce, ...)` | A family of initialization functions.                                                   |
+
+All of these functions are for internal ICU implementation use only. They are
+not exported, and not intended for external use.

docs/userguide/format_parse/datetime/examples.md

@@ -0,0 +1,293 @@
+---
+layout: default
+title: Date and Time Formatting Examples
+nav_order: 1
+grand_parent: Formatting
+parent: Formatting Dates and Times
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Date and Time Formatting Examples
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Format
+
+The ICU DateFormat interface enables you to format a date in milliseconds into a
+string representation of the date. Also, the interface enables you to parse the
+string back to the internal date representation in milliseconds.
+
+### C++
+
+```cpp
+DateFormat* df = DateFormat::createDateInstance();
+UnicodeString myString;
+UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; 
+for (int32_t i = 0; i < 3; ++i) {
+  myString.remove();
+  cout << df->format( myDateArr[i], myString ) << endl;
+}
+```
+
+### C
+
+```c
+/* 1st example: format the dates in millis 100000000 and 2000000000 */
+UErrorCode status=U_ZERO_ERROR;
+int32_t i, myStrlen=0;
+UChar* myString;
+UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
+UDateFormat* df = udat_open(UCAL_DEFAULT, UCAL_DEFAULT, NULL, "GMT", &status);
+for (i = 0; i < 3; ++i) {
+  myStrlen = udat_format(df, myDateArr[i], NULL, myStrlen, NULL, &status);
+  if(status==U_BUFFER_OVERFLOW_ERROR){
+    status=U_ZERO_ERROR;
+    myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
+    udat_format(df, myDateArr[i], myString, myStrlen+1, NULL, &status);
+    printf("%s\n", austrdup(myString) ); 
+    /* austrdup( a function used to convert UChar* to char*) */
+    free(myString);
+  }
+}
+```
+
+## Parse
+
+To parse a date for a different locale, specify it in the locale call. This call
+creates a formatting object.
+
+### C++
+
+```cpp
+DateFormat* df = DateFormat::createDateInstance
+  ( DateFormat::SHORT, Locale::getFrance());
+```
+
+### C
+
+```c
+/* 2nd example: parse a date with short French date/time formatter */
+UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", "GMT", &status);
+UErrorCode status = U_ZERO_ERROR;
+int32_t parsepos=0;     
+UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos,
+&status);
+```
+
+### Java
+
+```java
+import java.text.FieldPosition;
+import java.text.ParseException;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.Locale;
+
+import com.ibm.icu.text.DateFormat;
+
+public class TestDateTimeFormat {
+    public void run() {
+
+        // Formatting Dates
+
+        DateFormat dfUS = DateFormat.getDateInstance(DateFormat.FULL, Locale.US);
+        DateFormat dfFrance = DateFormat.getDateInstance(DateFormat.FULL, Locale.FRANCE);
+        StringBuffer sb = new StringBuffer();
+        Calendar c = Calendar.getInstance();
+        Date d = c.getTime();
+        sb = dfUS.format(d, sb, new FieldPosition(0));
+        System.out.println(sb.toString());
+
+        StringBuffer sbf = new StringBuffer();
+        sbf = dfFrance.format(d, sbf, new FieldPosition(0));
+        System.out.println(sbf.toString());
+
+        StringBuffer sbg = new StringBuffer();
+        DateFormat dfg = DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.SHORT);
+        FieldPosition pos = new FieldPosition(DateFormat.MINUTE_FIELD);
+        sbg = dfg.format(d, sbg, pos);
+        System.out.println(sbg.toString());
+        System.out.println(sbg.toString().substring(pos.getBeginIndex(), pos.getEndIndex()));
+
+        // Parsing Dates
+
+        String dateString_US = "Thursday, February 7, 2008";
+        String dateString_FRANCE = "jeudi 7 février 2008";
+        try {
+            Date parsedDate_US = dfUS.parse(dateString_US);
+            Date parsedDate_FRANCE = dfFrance.parse(dateString_FRANCE);
+            System.out.println(parsedDate_US.toString());
+            System.out.println(parsedDate_FRANCE.toString());
+        } catch (ParseException pe) {
+            System.out.println("Exception while parsing :" + pe);
+        }
+    }
+
+    public static void main(String args[]) {
+        new TestDateTimeFormat().run();
+    }
+}
+```
+
+## Getting Specific Date Fields
+
+To get specific fields of a date, you can use the FieldPosition function for C++
+or UFieldPosition function for C.
+
+### C++
+
+```cpp
+UErrorCode status = U_ZERO_ERROR;
+FieldPosition pos(DateFormat::YEAR_FIELD)
+UDate myDate = Calendar::getNow();
+UnicodeString str;
+DateFormat* df = DateFormat::createDateInstance
+  ( DateFormat::LONG, Locale::getFrance());
+
+df->format(myDate, str, pos, status);
+cout << pos.getBeginIndex() << "," << pos. getEndIndex() << endl;
+```
+
+### C
+
+```c
+UErrorCode status = U_ZERO_ERROR;
+UFieldPosition pos;
+UChar *myString;
+int32_t myStrlen = 0;
+char buffer[1024];
+
+
+pos.field = 1; /* Same as the DateFormat::EField enum */
+UDateFormat* dfmt = udat_open(UCAL_DEFAULT, UCAL_DEFAULT, NULL, "PST",
+&status);
+myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status);
+if (status==U_BUFFER_OVERFLOW_ERROR){
+    status=U_ZERO_ERROR;
+    myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
+    udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status);
+}
+printf("date format: %s\n", u_austrcpy(buffer, myString));
+buffer[pos.endIndex] = 0;   // NULL terminate the string.
+printf("UFieldPosition position equals %s\n", &buffer[pos.beginIndex]);
+```
+
+## DateTimePatternGenerator
+
+This class lets you get a different variety of patterns, such as month+day. The
+following illustrates this in Java, C++ and C.
+
+### Java
+
+```java
+// set up the generator
+DateTimePatternGenerator generator
+    = DateTimePatternGenerator.getInstance(locale);
+
+// get a pattern for an abbreviated month and day
+final String pattern = generator.getBestPattern("MMMd");
+SimpleDateFormat formatter = new SimpleDateFormat(pattern, locale);
+
+// use it to format (or parse)
+String formatted = formatter.format(new Date());
+// for French, the result is "13 sept."
+```
+
+### C++
+
+```cpp
+// set up the generator
+status = U_ZERO_ERROR;
+DateTimePatternGenerator *generator = DateTimePatternGenerator::createInstance( locale, status);
+if (U_FAILURE(status)) {
+    return;
+}
+    
+// get a pattern for an abbreviated month and day
+UnicodeString pattern = generator->getBestPattern(UnicodeString("MMMd"), status); 
+SimpleDateFormat *formatter = new SimpleDateFormat(pattern, locale, status); 
+
+// use it to format (or parse)
+UnicodeString formatted;
+formatted = formatter->format(Calendar::getNow(), formatted, status); 
+// for French, the result is "13 sept."
+```
+
+### C
+
+```c
+const UChar skeleton[]= {'M', 'M', 'M', 'd', 0};
+
+status=U_ZERO_ERROR;    
+generator=udatpg_open(locale, &status);
+if(U_FAILURE(status)) {
+    return;
+
+}
+
+/* get a pattern for an abbreviated month and day */
+length = udatpg_getBestPattern(generator, skeleton, 4,
+                                pattern, patternCapacity, &status);
+formatter = udat_open(UDAT_IGNORE, UDAT_DEFAULT, locale, NULL, -1, 
+                        pattern, length, &status);
+
+/* use it to format (or parse) */
+formattedCapacity = (int32_t)(sizeof(formatted)/sizeof((formatted)[0]));
+resultLen=udat_format(formatter, ucal_getNow(), formatted, formattedCapacity,
+                        NULL, &status);
+/* for French, the result is "13 sept." */
+```
+
+## Changing the TimeZone Formatting Style
+
+It also contains some helper functions for parsing patterns. Here's an example
+of replacing the kind of timezone used in a pattern.
+
+### Java
+
+```cpp
+/**
+ * Replace the zone string with a different type, eg v's for z's, etc.
+ * <p>Called with a pattern, such as one gotten from 
+ * <pre>
+ * String pattern = ((SimpleDateFormat)
+ * DateFormat.getTimeInstance(style, locale)).toPattern();
+ * </pre>
+ * @param pattern original pattern to change, such as "HH:mm zzzz"
+ * @param newZone Must be: z, zzzz, Z, ZZZZ, v, vvvv, V, or VVVV
+ * @return
+ */
+public String replaceZoneString(String pattern, String newZone) {
+    DateTimePatternGenerator.FormatParser formatParser =
+        new DateTimePatternGenerator.FormatParser();
+    final List itemList = formatParser.set(pattern).getItems();
+    boolean found = false;
+    for (int i = 0; i < itemList.size(); ++i) {
+        Object item = itemList.get(i);
+        if (item instanceof VariableField) {
+            // the first character of the variable field determines the type,
+            // according to CLDR.
+            String variableField = item.toString();
+            switch (variableField.charAt(0)) {
+            case 'z': case 'Z': case 'v': case 'V':
+                if (!variableField.equals(newZone)) {
+                    found = true;
+                    itemList.set(i, new VariableField(newZone));
+                }
+                break;
+            }
+        }
+    }
+    return found ? formatParser.toString() : pattern;
+}
+```

docs/userguide/format_parse/datetime/index.md

@@ -0,0 +1,386 @@
+---
+layout: default
+title: Formatting Dates and Times
+nav_order: 2
+parent: Formatting
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Formatting Dates and Times
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Formatting Dates and Times Overview
+
+Date and time formatters are used to convert dates and times from their internal
+representations to textual form and back again in a language-independent manner.
+The date and time formatters use `UDate`, which is the internal representation.
+Converting from the internal representation (milliseconds since midnight,
+January 1, 1970) to text is known as "formatting," and converting from text to
+milliseconds is known as "parsing." These processes involve two mappings:
+
+*   A mapping between a point in time (`UDate`) and a set of calendar fields,
+    which in turn depends on:
+    *   The rules of a particular calendar system (e.g. Gregorian, Buddhist,
+        Chinese Lunar)
+    *   The time zone
+*   A mapping between a set of calendar fields and a formatted textual
+    representation, which depends on the fields selected for display, their
+    display style, and the conventions of a particular locale.
+
+## `DateFormat`
+
+`DateFormat` helps format and parse dates for any locale. Your code can be
+completely independent of the locale conventions for months, days of the week,
+or calendar format.
+
+### Formatting Dates
+
+The `DateFormat` interface in ICU enables you to format a `Date` in milliseconds
+into a string representation of the date. It also parses the string back to the
+internal `Date` representation in milliseconds.
+
+```cpp
+DateFormat* df = DateFormat::createDateInstance();
+UnicodeString myString;
+UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 };
+for (int32_t i = 0; i < 3; ++i) {
+  myString.remove();
+  cout << df->format( myDateArr[i], myString ) << endl;
+}
+```
+
+To format a date for a different `Locale`, specify it in the call to:
+
+```cpp
+DateFormat* df = DateFormat::createDateInstance
+   ( DateFormat::SHORT, Locale::getFrance());
+```
+
+### Parsing Dates
+
+Use a `DateFormat` to parse also:
+
+```cpp
+UErrorCode status = ZERO_ERROR;
+UDate myDate = df->parse(myString, status);
+```
+
+When numeric fields abut one another directly, with no intervening delimiter
+characters, they constitute a run of abutting numeric fields. Such runs are
+parsed specially. For example, the format `"HHmmss"` parses the input text
+"123456" to 12:34:56, parses the input text "12345" to 1:23:45, and fails to
+parse "1234". In other words, the leftmost field of the run is flexible, while
+the others keep a fixed width. If the parse fails anywhere in the run, then the
+leftmost field is shortened by one character, and the entire run is parsed
+again. This is repeated until either the parse succeeds or the leftmost field is
+one character in length. If the parse still fails at that point, the parse of
+the run fails.
+
+### Producing Normal Date Formats for a Locale
+
+Use `createDateInstance` to produce the normal date format for that country. There
+are other static factory methods available. Use `createTimeInstance` to produce
+the normal time format for that country. Use `createDateTimeInstance` to produce a
+`DateFormat` that formats both date and time. You can pass 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:
+
+1.  `SHORT` is numeric, such as 12/13/52 or 3:30pm
+
+2.  `MEDIUM` is longer, such as Jan. 12, 1952
+
+3.  `LONG` is longer, such as January 12, 1952 or 3:30:32pm
+
+4.  `FULL` is completely specified, such as Tuesday, April 12, 1952 AD or
+    3:30:42pm PST
+
+For more general flexibility, the [`DateTimePatternGenerator`](index#datetimepatterngenerator)
+can map a custom selection of time and date fields, along with various display styles for
+those fields, to a locale-appropriate format that can then be set as the format to use by the `DateFormat`.
+
+### Producing Relative Date Formats for a Locale
+
+ICU currently provides limited support for formatting dates using a “relative”
+style, specified using `RELATIVE_SHORT`, `RELATIVE_MEDIUM`, `RELATIVE_LONG` or
+`RELATIVE_FULL`. As currently implemented, relative date formatting only affects
+the formatting of dates within a limited range of calendar days before or after
+the current date, based on the CLDR `<field type="day">`/`<relative>` data: For
+example, in English, "Yesterday", "Today", and "Tomorrow". Within this range,
+the specific relative style currently makes no difference. Outside of this
+range, relative dates are formatted using the corresponding non-relative style
+(`SHORT`, `MEDIUM`, etc.). Relative time styles are not currently supported, and
+behave just like the corresponding non-relative style.
+
+### Setting Time Zones
+
+You can set the time zone on the format. If you want more control over the
+format or parsing, cast the `DateFormat` you get from the factory methods to a
+`SimpleDateFormat`. This works for the majority of countries.
+
+> :point_right: **Note**: *Remember to check `getDynamicClassID()` before carrying out the cast.*
+
+### Working with Positions
+
+You can also use forms of the parse and format methods with `ParsePosition` and
+`FieldPosition` to enable you to:
+
+1.  Progressively parse through pieces of a string.
+
+2.  Align any particular field, or find out where it is for selection on the
+    screen.
+
+## `SimpleDateFormat`
+
+`SimpleDateFormat` is a concrete class used for formatting and parsing dates in a
+language-independent manner. It allows for formatting, parsing, and
+normalization. It formats or parses a date or time, which is the standard
+milliseconds since 24:00 GMT, Jan. 1, 1970.
+
+`SimpleDateFormat` is the only built-in implementation of `DateFormat`. It provides
+a programmable interface that can be used to produce formatted dates and times
+in a wide variety of formats. The formats include almost all of the most common
+ones.
+
+Create a date-time formatter using the following methods rather than
+constructing an instance of `SimpleDateFormat`. In this way, the program is
+guaranteed to get an appropriate formatting pattern of the locale.
+
+1.  `DateFormat::getInstance()`
+
+2.  `getDateInstance()`
+
+3.  `getDateTimeInstance()`
+
+If you need a more unusual pattern, construct a `SimpleDateFormat` directly and
+give it an appropriate pattern.
+
+### Date/Time Format Syntax
+
+A date pattern is a string of characters, where specific strings of characters
+are replaced with date and time data from a calendar when formatting or used to
+generate data for a calendar when parsing.
+
+The Date Field Symbol Table below contains the characters used in patterns to
+show the appropriate formats for a given locale, such as `yyyy` for the year.
+Characters may be used multiple times. For example, if `y` is used for the year,
+`"yy"` might produce "99", whereas `"yyyy"` produces "1999". For most numerical
+fields, the number of characters specifies the field width. For example, if `h` is
+the hour, `"h"` might produce "5", but `"hh"` produces "05". For some characters,
+the count specifies whether an abbreviated or full form should be used, but may
+have other choices, as given below.
+
+Two single quotes represents a literal single quote, either inside or outside
+single quotes. Text within single quotes is not interpreted in any way (except
+for two adjacent single quotes). Otherwise all ASCII letter from **a** to **z** and **A** to
+**Z** are reserved as syntax characters, and require quoting if they are to
+represent literal characters. In addition, certain ASCII punctuation characters
+may become variable in the future (eg `':'` being interpreted as the time
+separator and `'/'` as a date separator, and replaced by respective
+locale-sensitive characters in display).
+
+"Stand-alone" values refer to those designed to stand on their own independently, as opposed
+to being with other formatted values. "2nd quarter" would use the wide stand-alone
+format `"qqqq"`, whereas "2nd quarter 2007" would use the regular format `"QQQQ
+yyyy"`. For more information about format and stand-alone forms, see [CLDR Calendar Elements](https://www.unicode.org/reports/tr35/tr35-dates.html#months_days_quarters_eras).
+
+The pattern characters used in the Date Field Symbol Table are defined by CLDR; for more information see [CLDR Date Field Symbol Table](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table).
+
+Note that the examples may not reflect current CLDR data.
+
+#### Date Field Symbol Table
+
+| Symbol | Meaning | Pattern | Example Output |
+| --- | --- | --- | --- |
+| `G` | era designator | `G`, `GG`, or `GGG`<br/>`GGGG`<br/>`GGGGG` | AD<br/>Anno Domini<br/>A |
+| `y` | year | `yy`<br/>`y` or `yyyy` | 96<br/>1996 |
+| `Y` | year of "Week of Year" | `Y` | 1997 |
+| `u` | extended year | `u` | 4601 |
+| `U` | cyclic year name, as in Chinese lunar calendar | `U` | 甲子 |
+| `r` | related Gregorian year | `r` | 1996 |
+| `Q` | quarter | `Q`<br/>`QQ`<br/>`QQQ`<br/>`QQQQ`<br/>`QQQQQ` | 2<br/>02<br/>Q2<br/>2nd quarter<br/>2 |
+| `q` | stand-alone quarter | `q`<br/>`qq`<br/>`qqq`<br/>`qqqq`<br/>`qqqqq` | 2<br/>02<br/>Q2<br/>2nd quarter<br/>2 |
+| `M` | month in year | `M`<br/>`MM`<br/>`MMM`<br/>`MMMM`<br/>`MMMMM` | 9<br/>09<br/>Sep<br/>September<br/>S |
+| `L` | stand-alone month in year | `L`<br/>`LL`<br/>`LLL`<br/>`LLLL`<br/>`LLLLL` | 9<br/>09<br/>Sep<br/>September<br/>S |
+| `w` | week of year | `w`<br/>`ww` | 27<br/>27 |
+| `W` | week of month | `W` | 2 |
+| `d` | day in month | `d`<br/>`dd` | 2<br/>02 |
+| `D` | day of year | `D` | 189 |
+| `F` | day of week in month | `F` | 2 (2nd Wed in July) |
+| `g` | modified julian day | `g` | 2451334 |
+| `E` | day of week | `E,` `EE`, or `EEE`<br/>`EEEE`<br/>`EEEEE`<br/>`EEEEEE` | Tue<br/>Tuesday<br/>T<br/>Tu |
+| `e` | local day of week<br/>example: if Monday is 1st day, Tuesday is 2nd ) | `e` or `ee`<br/>`eee`<br/>`eeee`<br/>`eeeee`<br/>`eeeeee` | 2<br/>Tue<br/>Tuesday<br/>T<br/>Tu |
+| `c` | stand-alone local day of week | `c` or `cc`<br/>`ccc`<br/>`cccc`<br/>`ccccc`<br/>`cccccc` | 2<br/>Tue<br/>Tuesday<br/>T<br/>Tu |
+| `a` | am/pm marker | `a` | pm |
+| `h` | hour in am/pm (1~12) | `h`<br/>`hh` | 7<br/>07 |
+| `H` | hour in day (0~23) | `H`<br/>`HH` | 0<br/>00 |
+| `k` | hour in day (1~24) | `k`<br/>`kk` | 24<br/>24 |
+| `K` | hour in am/pm (0~11) | `K`<br/>`KK` | 0<br/>00 |
+| `m` | minute in hour | `m`<br/>`mm` | 4<br/>04 |
+| `s` | second in minute | `s`<br/>`ss` | 5<br/>05 |
+| `S` | fractional second - truncates (like other time fields)<br/>to the count of letters when formatting. Appends<br/>zeros if more than 3 letters specified. Truncates at<br/>three significant digits when parsing. | `S`<br/>`SS`<br/>`SSS`<br/>`SSSS` | 2<br/>23<br/>235<br/>2350 |
+| `A` | milliseconds in day | `A` | 61201235 |
+| `z` | Time Zone: specific non-location | `z`, `zz`, or `zzz`<br/>`zzzz` | PDT<br/>Pacific Daylight Time |
+| `Z` | Time Zone: ISO8601 basic hms? / RFC 822<br/>Time Zone: long localized GMT (=OOOO)<br/>TIme Zone: ISO8601 extended hms? (=XXXXX) | `Z`, `ZZ`, or `ZZZ`<br/>`ZZZZ`<br/>`ZZZZZ` | -0800<br/>GMT-08:00<br/>-08:00, -07:52:58, Z |
+| `O` | Time Zone: short localized GMT<br/>Time Zone: long localized GMT (=ZZZZ) | `O`<br/>`OOOO` | GMT-8<br/>GMT-08:00 |
+| `v` | Time Zone: generic non-location<br/>(falls back first to VVVV) | `v`<br/>`vvvv` | PT<br/>Pacific Time or Los Angeles Time |
+| `V` | Time Zone: short time zone ID<br/>Time Zone: long time zone ID<br/>Time Zone: time zone exemplar city<br/>Time Zone: generic location (falls back to OOOO) | `V`<br/>`VV`<br/>`VVV`<br/>`VVVV` | uslax<br/>America/Los_Angeles<br/>Los Angeles<br/>Los Angeles Time |
+| `X` | Time Zone: ISO8601 basic hm?, with Z for 0<br/>Time Zone: ISO8601 basic hm, with Z<br/>Time Zone: ISO8601 extended hm, with Z<br/>Time Zone: ISO8601 basic hms?, with Z<br/>Time Zone: ISO8601 extended hms?, with Z | `X`<br/>`XX`<br/>`XXX`<br/>`XXXX`<br/>`XXXXX` | -08, +0530, Z<br/>-0800, Z<br/>-08:00, Z<br/>-0800, -075258, Z<br/>-08:00, -07:52:58, Z |
+| `x` | Time Zone: ISO8601 basic hm?, without Z for 0<br/>Time Zone: ISO8601 basic hm, without Z<br/>Time Zone: ISO8601 extended hm, without Z<br/>Time Zone: ISO8601 basic hms?, without Z<br/>Time Zone: ISO8601 extended hms?, without Z | `x`<br/>`xx`<br/>`xxx`<br/>`xxxx`<br/>`xxxxx` | -08, +0530<br/>-0800<br/>-08:00<br/>-0800, -075258<br/>-08:00, -07:52:58 |
+| `'` | escape for text | `'` | (nothing) |
+| `' '` | two single quotes produce one | `' '` | ' |
+
+> :point_right: **Note**: *Any characters in the pattern that are not in the ranges of
+['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance,
+characters like `':'`, `'.'`, `' '`, `'#'` and `'@'` will appear in the resulting time
+text even they are not enclosed within single quotes. The single quote is used to
+'escape' letters. Two single quotes in a row, whether inside or outside a quoted
+sequence, represent a 'real' single quote.*
+
+> :point_right: **Note**: *A pattern containing any invalid pattern letter results in a failing `UErrorCode`
+result during formatting or parsing.*
+
+| Format Pattern | Result |
+| --- | --- |
+| `"yyyy.MM.dd G 'at' HH:mm:ss zzz"` | "1996.07.10 AD at 15:08:56 PDT" |
+| `"EEE, MMM d, ''yy"` | "Wed, July 10, '96" |
+| `"h:mm a"` | "12:08 PM" |
+| `"hh 'o''clock' a, zzzz"` | "12 o'clock PM, Pacific Daylight Time" |
+| `"K:mm a, z"` | "0:00 PM, PST" |
+| `"yyyyy.MMMM.dd GGG hh:mm aaa"` | "01996.July.10 AD 12:08 PM" |
+
+### Time Zone Display Names
+
+ICU supports time zone display names defined by the LDML ([Unicode Locale Data
+Markup Language](http://www.unicode.org/reports/tr35/) ) specification. Since
+ICU 3.8, the vast majority of localized time zone names are no longer associated
+with individual time zones. Instead, a set of localized time zone names are
+associated with a *metazone* and one or more individual time zones are mapped to
+the same *metazone*. For example, *metazone* “America_Pacific” has its own
+display name data such as “PST” “PDT” “PT” “Pacific Standard Time” “Pacific
+Daylight Time” “Pacific Time” and these names are shared by multiple individual
+time zones “America/Los_Angeles”, “America/Vancouver”, “America/Tijuana” and so
+on. The mapping from individual time zone to *metazone* is not a simple 1-to-1
+mapping, but it changes time to time. For example, time zone
+“America/Indiana/Tell_City” uses name data from *metazone* “America_Eastern”
+until April 2, 2006, but it changes to *metazone* “America_Central” after the
+date. So the display name used for “America/Indiana/Tell_City” before the date
+(e.g. “Eastern Time”) differs from the one after the date (e.g. “Central Time).
+
+> :point_right: **Note**: *Prior to ICU 3.8, a localized time zone name (except GMT format) and a time
+zone ID was in 1-to-1 relationship always. Therefore, a time zone name produced
+by `DateFormat` can be parsed back to the original time zone. This assumption no
+longer applies to ICU 3.8 and later releases for all time zone format types. If
+you program requires to roundtrip specific time zone ID, you must use the
+generic location format `VVVV` explained below.*
+
+There are several different display name types available in the LDML
+specification.
+
+#### Time Zone Display Name Types
+
+| Type | Description | Examples |
+| --- | --- | --- |
+| Generic non-location | Reflects wall time, suited for displaying recurring events, meetings or anywhere people do not want to be overly specific. Available in two length options – long and short. | Pacific Time<br/>PT |
+| Generic partial location | Reflects wall time, used as a fallback format when the generic non-location format is not specific enough. A generic partial location name is constructed from a generic non-location name with a location name. For example, “PT” is shared by multiple time zones via metazone “America_Pacific”. When GMT offset in the time zone at the given time differs from the preferred time zone of the metazone for the locale, location name is appended to generic non-location name to distinguish the time zone from the preferred zone. Available in two length options – long and short. | Pacific Time (Canada)<br/>PT (Yellowknife) |
+| Generic location | Reflects wall time, suited for populating choice list for time zones. If the time zone is the single time zone available in the region (country), the generic location name is constructed with the region name. Otherwise, the name is constructed from the region name and the city name. Unlike other format types, this name is unique per time zone. | United States (Los Angeles) Time<br/>Italy Time |
+| Specific non-location | Reflects a specific standard or daylight time. Available in two length options – long and short. | Pacific Standard Time<br/>PDT |
+| Localized GMT | A constant, specific offset from GMT in a localized form. | GMT-08:00 |
+| RFC822 GMT | A constant, specific offset from GMT in a locale insensitive format. | -0800 |
+
+Each format type in the above table is used as a primary type or a fallback in
+`SimpleDateFormat`. The table below explains how ICU time zone format pattern work
+and its characteristics.
+
+#### Time Zone Pattern Usage
+
+| Pattern | Behavior | Round-trip time at daylight transitions(\*) | Round-trip Time Zone | Suggested Usage |
+| --- | --- | --- | --- | --- |
+| `z`, `zz`, `zzz` | Short specific non-location format (e.g. “PST”). If the localized data is not available or the short abbreviation is not commonly used for the locale, localized GMT format is used (e.g. "GMT-08:00"). | yes | no | For displaying a time with a user friendly time zone name. |
+| `zzzz` | Long specific non-location format (e.g. “Pacific Standard Time”). If the localized data is not available, localized GMT format is used (e.g. "GMT-08:00"). | yes | no | Same as `z`, but longer format. |
+| `v` | Short generic non-location format (e.g. “PT”). If the localized data is not available or the short abbreviation is not commonly used for the locale, generic location format (e.g. “United States(Los Angeles) Time”) is used. If the localized data comes from metazone and the GMT offset at the given time in the specified time zone differs from the preferred time zone of the metazone for the locale, generic partial location format (e.g. “PT (Canada)”) is used. | no | no | For displaying a recurring wall time (e.g. events, meetings) or anywhere people do not want to be overly specific. |
+| `vvvv` | Long generic non-location format (e.g. “Pacific Time”). If the localized data is not available, generic location format (e.g. “United States(Los Angeles) Time”) is used. | no | no | Same as `v`, but longer format. |
+| `V` | Same as `z`, except using the short abbreviation even it is not commonly used for the locale. | yes | no | Same as `z`. |
+| `VVVV` | Generic location format (e.g. “United States (Los Angeles) Time”). | no | yes | For populating a choice list for time zones, because it supports 1-to-1 name/zone ID mapping and is more uniform than other text formats. Also, this is only the pattern supporting time zone round-trip. If your program requires to preserve the original time zone information, use this pattern. |
+| `Z`, `ZZ`, `ZZZ` | Localized GMT format (e.g. “GMT-08:00”). | yes | no | For displaying a time in UI in a uniformed manner. |
+| `ZZZZ` | RFC822 GMT format (e.g. “-0800”). | yes | no | For formatting a time for non-user-facing data. |
+
+\* At a transition from daylight saving time to standard time, there is a wall
+time interval occurs twice.
+
+## `DateTimePatternGenerator`
+
+The `DateTimePatternGenerator` class provides a way to map a request for a set of
+date/time fields, along with their width, to a locale-appropriate format
+pattern. The request is in the form of a “skeleton” which just contains pattern
+letters for the desired fields using the representation for the desired width.
+In a skeleton, anything other than a pattern letter is ignored, field order is
+insignificant, and there are two special additional pattern letters that may be
+used: `j` requests the preferred hour-cycle type for the locale (it gets mapped
+to one of `H`, `h`, `k`, or `K`); `J` is similar but requests no AM/PM marker
+even if the locale’s preferred hour-cycle type is `h` or `K`.
+
+For example, a skeleton of `“MMMMdjmm”` might result in the following format
+patterns for different locales:
+
+| locale | format pattern for skeleton `“MMMMdjmm”` | example              |
+| ------ | ---------------------------------------- | -------------------- |
+| en_US  | `"MMMM d  'at'  h:mm a"`                 | "April 2 at 5:00 PM" |
+| es_ES  | `"d 'de' MMMM, H:mm"`                    | "2 de abril, 17:00"  |
+| ja_JP  | `"M月d日 H:mm"`                            | "4月2日 17:00"         |
+
+The most important DateTimePatternGenerator methods are the varieties of
+getBestPattern.
+
+Note that the fields in the format pattern may be adjusted as appropriate for
+the locale and may not exactly match those in the skeleton. For example:
+
+*   In Russian (locale "ru"), the skeleton `"yMMMM"` will produce the format
+    pattern `"LLLL y"` (or `"LLLL y 'г'."`) since a month name without a day number
+    must be in nominative form, as indicated by `LLLL`.
+*   When using the Japanese calendar in the Japanese locale (locale
+    "ja@calendar=japanese"), the skeleton `"yMMMd"` will produce the format
+    pattern `"Gy年M月d日"` since the era must always be shown with the year in the
+    Japanese calendar.
+
+## `DateFormatSymbols`
+
+`DateFormatSymbols` is a public class for encapsulating localizable date-time
+formatting data, including time zone data. `DateFormatSymbols` is used by
+`DateFormat` and `SimpleDateFormat`.
+
+`DateFormatSymbols` specifies the exact character strings to use for various parts
+of a date or time For example, the names of the months and days of the week, the
+strings for AM and PM and the day of the week considered to be the first day of
+the week (used in drawing calendar grids) are controlled by `DateFormatSymbols`.
+
+Create a date-time formatter using the `createTimeInstance`, `createDateInstance`,
+or `createDateTimeInstance` methods in `DateFormat`. Each of these methods can
+return a date/time formatter initialized with a default format pattern, along
+with the date-time formatting data for a given or default locale. After a
+formatter is created, modify the format pattern using `applyPattern`.
+
+If you want to create a date-time formatter with a particular format pattern and
+locale, use one of the `SimpleDateFormat` constructors:
+
+```cpp
+UnicodeString aPattern("GyyyyMMddHHmmssSSZ", "");
+new SimpleDateFormat(aPattern, new DateFormatSymbols(Locale::getUS())
+```
+
+This loads the appropriate date-time formatting data from the locale.
+
+## Programming Examples
+
+See [date and time formatting examples](examples.md).

docs/userguide/format_parse/formatted_value.md

@@ -0,0 +1,91 @@
+---
+layout: default
+title: FormattedValue
+nav_order: 4
+grand_parent: Formatting
+parent: Formatting Numbers
+---
+<!--
+© 2019 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# `FormattedValue`
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+`FormattedValue` is an abstraction for localized strings with attributes
+returned by a number of ICU formatters.  APIs for `FormattedValue` are available
+in Java, C++, and C.  For more details and a list of all implementing classes,
+refer to the API docs:
+
+- [C++ `FormattedValue`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1FormattedValue.html)
+- [C `UFormattedValue`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/globals_u.html) -- search for "resultAsValue"
+- [Java `FormattedValue`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/FormattedValue.html)
+
+## Nested Span Fields
+
+Certain ICU formatters, like `FormattedList` and `FormattedDateInterval`, use
+*span fields* to return information about which spans of a string correspond
+to different input parameters.  In C and C++, span fields are implemented
+using a field category, with the field being set to the input index; in Java,
+they are implemented by associating an `Integer` value with a `SpanField`
+subclass.
+
+For example, in C++, here is how you can determine which region in a formatted
+date interval corresponds to the 2nd argument (index 1) in the input date
+interval (the "to" date):
+
+```cpp
+// Let fmt be a DateIntervalFormat for locale en-US and skeleton dMMMMy
+// Let input1 be July 20, 2018 and input2 be August 3, 2018:
+FormattedDateInterval result = fmt->formatToValue(*input1, *input2, status);
+assertEquals("Expected output from format",
+    u"July 20 \u2013 August 3, 2018", result.toString(status));
+ConstrainedFieldPosition cfpos;
+cfpos.constrainField(UFIELD_CATEGORY_DATE_INTERVAL_SPAN, 0);
+if (result.nextPosition(cfpos, status)) {
+    assertEquals("Expect start index", 0, cfpos.getStart());
+    assertEquals("Expect end index", 7, cfpos.getLimit());
+} else {
+    // No such span: can happen if input dates are equal.
+}
+assertFalse("No more than one occurrence of the field",
+    result.nextPosition(cfpos, status));
+```
+
+In C, the code looks very similar, except you use the equivalent C types.
+
+In Java, use the `constrainFieldAndValue` method:
+
+```java
+// Let fmt be a DateIntervalFormat for locale en-US and skeleton dMMMMy
+// Let input1 be July 20, 2018 and input2 be August 3, 2018:
+FormattedDateInterval result = fmt.formatToValue(input1, input2);
+assertEquals("Expected output from format",
+    "July 20 \u2013 August 3, 2018", result.toString());
+ConstrainedFieldPosition cfpos = new ConstrainedFieldPosition();
+cfpos.constrainFieldAndValue(DateIntervalFormat.SpanField.DATE_INTERVAL_SPAN, 0);
+if (result.nextPosition(cfpos)) {
+    assertEquals("Expect start index", 0, cfpos.getStart());
+    assertEquals("Expect end index", 7, cfpos.getLimit());
+} else {
+    // No such span: can happen if input dates are equal.
+}
+assertFalse("No more than one occurrence of the field",
+    result.nextPosition(cfpos));
+```
+
+A span may cover multiple primitive fields; in the above example, the span
+contains both a month and a date. Using `FormattedValue`, those primitive
+fields will also be present, and you can check their start and end indices to
+see if they are contained within a desired span.

docs/userguide/format_parse/index.md

@@ -0,0 +1,236 @@
+---
+layout: default
+title: Formatting
+nav_order: 1000
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Formatting and Parsing
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+Formatters translate between binary data and human-readable textual
+representations of these values. For example, you cannot display the computer
+representation of the number 103. You can only display the numeral 103 as a
+textual representation (using three text characters). The result from a
+formatter is a string that contains text that the user will recognize as
+representing the internal value. A formatter can also parse a string by
+converting a textual representation of some value back into its internal
+representation. For example, it reads the characters 1, 0 and 3 followed by
+something other than a digit, and produces the value 103 as an internal binary
+representation.
+
+These classes encapsulate information about the display of localized times,
+days, numbers, currencies, and messages. Formatting classes do both formatting
+and parsing and allow the separation of the data that the end-user sees from the
+code. Separating the program code from the data allows a program to be more
+easily localized. Formatting is converting a date, time, number, message or
+other object from its internal representation into a string. Parsing is the
+reverse operation. It is the process of converting a string to an internal
+representation of the date, time, number, message or other object.
+
+Using the formatting classes is an important step in internationalizing your
+software because the `format()` and `parse()` methods in each of the classes make
+your software language neutral, by replacing implicit conversions with explicit
+formatting calls.
+
+## Internationalization Formatting Tips
+
+This section discusses some of the ways you can format and parse numbers,
+currencies, dates, times and text messages in your program so that the data is
+separate from the code and can be easily localized. This is the information your
+users see on their computer screens, so it needs to be in a language and format
+that conforms to their local conventions.
+
+Some things you need to keep in mind while you are creating your code are the
+following:
+
+*   Keep your code and your data separate
+
+*   Format the data in a locale-sensitive manner
+
+*   Keep your code locale-independent
+
+*   Avoid writing special routines to handle specific locales
+
+*   String objects formatted by `format()` are parseable by the `parse()` method\*
+
+> :point_right: **Note**: Although parsing is supported in several legacy ICU APIs,
+it is generally considered bad practice to parse localized strings.
+For more information, read [Why You Should Not Parse
+Localized Strings](https://blog.sffc.xyz/post/190943794505/why-you-should-not-parse-localized-strings).
+
+### Numbers and Currencies
+
+Programs store and operate on numbers using a locale-independent binary
+representation. When displaying or printing a number it is converted to a
+locale-specific string. For example, the number 12345.67 is "12,345.67" in the
+US, "12 345,67" in France and "12.345,67" in Germany.
+
+By invoking the methods provided by the `NumberFormat` class, you can format
+numbers, currencies, and percentages according to the specified or default
+locale. `NumberFormat` is locale-sensitive so you need to create a new
+`NumberFormat` for each locale. `NumberFormat` methods format primitive-type
+numbers, such as double and output the number as a locale-specific string.
+
+For currencies you call `getCurrencyInstance` to create a formatter that returns a
+string with the formatted number and the appropriate currency sign. Of course,
+the `NumberFormat` class is unaware of exchange rates so, the number output is the
+same regardless of the specified currency. This means that the same number has
+different monetary values depending on the currency locale. If the number is
+9988776.65 the results will be:
+
+*   9 988 776,65 € in France
+
+*   9.988.776,65 € in Germany
+
+*   $9,988,776.65 in the United States
+
+In order to format percentages, create a locale-specific formatter and call the
+`getPercentInstance` method. With this formatter, a decimal fraction such as 0.75
+is displayed as 75%.
+
+#### Customizing Number Formats
+
+If you need to customize a number format you can use the `DecimalFormat` and
+the `DecimalFormatSymbols` classes in the [Formatting
+Numbers](numbers/index#formatting-numbers) chapter. This not usually necessary and
+it makes your code much more complex, but it is available for those rare
+instances where you need it. In general, you would do this by explicitly
+specifying the number format pattern.
+
+If you need to format or parse spelled-out numbers, you can use the
+`RuleBasedNumberFormat` class (see the [Formatting Numbers](numbers/index#formatting-numbers) chapter).
+You can instantiate a default formatter for a locale, or by using the 
+`RuleBasedNumberFormat` rule syntax, specify your own.
+
+Using `NumberFormat` class methods (see the [Formatting Numbers](numbers/index#formatting-numbers) chapter)
+with a predefined locale is the easiest and the most accurate way to format numbers, and currencies.
+
+> :point_right: **Note**: *See [Properties and ICU Rule Syntax](../strings/properties) for
+information regarding syntax characters.*
+
+### Date and Times
+
+You display or print a Date by first converting it to a locale-specific string
+that conforms to the conventions of the end user's Locale. For example, Germans
+recognize 20.4.98 as a valid date, and Americans recognize 4/20/98.
+
+> :point_right: **Note**: *The appropriate Calendar support is required for different locales. For
+example, the Buddhist calendar is the official calendar in Thailand so the
+typical assumption of Gregorian Calendar usage should not be used. ICU will pick
+the appropriate Calendar based on the locale you supply when opening a `Calendar`
+or `DateFormat`.*
+
+### Messages
+
+Message format helps make the order of display elements localizable. It helps
+address problems of grammatical differences in languages. For example, consider
+the sentence, "I go to work by car everyday." In Japanese, the grammar
+equivalent can be "Everyday, I to work by car go." Another example will be the
+plurals in text, for example, "no space for rent, one room for rent and many
+rooms for rent," where "for rent" is the only constant text among the three.
+
+## Formatting and Parsing Classes
+
+ICU provides four major areas and twelve classes for formatting numbers, dates
+and messages:
+
+### General Formatting
+
+*   `Format`:
+    
+    The abstract superclass of all format classes. It provides the basic methods
+    for formatting and parsing numbers, dates, strings and other objects.
+
+*   `FieldPosition`:
+    
+    A concrete class for holding the field constant and the begin and end
+    indices for number and date fields.
+
+*   `ParsePosition`:
+    
+    A concrete class for holding the parse position in a string during parsing.
+
+*   `Formattable`:
+    
+    `Formattable` objects can be passed to the `Format` class or its subclasses for
+    formatting. It encapsulates a polymorphic piece of data to be formatted and
+    is used with `MessageFormat`. `Formattable` is used by some formatting
+    operations to provide a single "type" that encompasses all formattable
+    values (e.g., it can hold a number, a date, or a string, and so on).
+
+*   `UParseError`:
+    
+    `UParseError` is used to returned detailed information about parsing errors.
+    It is used by the ICU parsing engines that parse long rules, patterns, or
+    programs. This is helpful when the text being parsed is long enough that
+    more information than a `UErrorCode` is needed to localize the error.
+
+**Formatting Numbers**
+
+*   [`NumberFormat`](numbers/legacy-numberformat#numberformat)
+    
+    The abstract superclass that provides the basic fields and methods for
+    formatting `Number` objects and number primitives to localized strings and
+    parsing localized strings to `Number` objects.
+
+*   [`DecimalFormat`](numbers/legacy-numberformat#decimalformat)
+    
+    A concrete class for formatting `Number` objects and number primitives to
+    localized strings and parsing localized strings to `Number` objects, in base 10.
+
+*   [`RuleBasedNumberFormat`](numbers/rbnf)
+    
+    A concrete class for formatting `Number` objects and number primitives to
+    localized text, especially spelled-out format such as found in check writing
+    (e.g. "two hundred and thirty-four"), and parsing text into `Number` objects.
+
+*   [`DecimalFormatSymbols`](numbers/legacy-numberformat#decimalformatsymbols)
+    
+    A concrete class for accessing localized number strings, such as the
+    grouping separators, decimal separator, and percent sign. Used by
+    `DecimalFormat`.
+
+**Formatting Dates and Times**
+
+*   [`DateFormat`](datetime/index#dateformat)
+    
+    The abstract superclass that provides the basic fields and methods for
+    formatting `Date` objects to localized strings and parsing date and time
+    strings to `Date` objects.
+
+*   [`SimpleDateFormat`](datetime/index#simpledateformat)
+    
+    A concrete class for formatting `Date` objects to localized strings and
+    parsing date and time strings to `Date` objects, using a `GregorianCalendar`.
+
+*   [`DateFormatSymbols`](datetime/index#dateformatsymbols)
+    
+    A concrete class for accessing localized date-time formatting strings, such
+    as names of the months, days of the week and the time zone.
+
+**Formatting Messages**
+
+*   [`MessageFormat`](messages/index#messageformat)
+    
+    A concrete class for producing a language-specific user message that
+    contains numbers, currency, percentages, date, time and string variables.
+
+*   [`ChoiceFormat`](messages/examples#choiceformat-class)
+    
+    A concrete class for mapping strings to ranges of numbers and for handling
+    plurals and names series in user messages.

docs/userguide/format_parse/messages/examples.md

@@ -0,0 +1,399 @@
+---
+layout: default
+title: Message Formatting Examples
+nav_order: 1
+parent: Formatting Messages
+grand_parent: Formatting
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Message Formatting Examples
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## `MessageFormat` Class
+
+ICU's `MessageFormat` class can be used to format messages in a locale-independent
+manner to localize the user interface (UI) strings.
+
+### C++
+
+```cpp
+
+/* The strings below can be isolated into a resource bundle
+* and retrieved dynamically
+*/
+#define LANGUAGE_NAMES "{0}<{1}languages {2}>\n"
+#define LANG_ATTRIB   "{0}<language id=\"{1}\" >{2}</language>\n"
+#define MONTH_NAMES "{0}<monthNames>\n"
+#define END_MONTH_NAMES "{0}</monthNames>\n"
+#define MONTH   "{0}<month id=\"{1}\">{2}</month>\n"
+#define MONTH_ABBR "{0}<monthAbbr>\n"
+#define END_MONTH_ABBR "{0}</monthAbbr>\n"
+
+UnicodeString CXMLGenerator::formatString(UnicodeString& str,UnicodeString&
+argument){
+Formattable args[] ={ argument};
+UnicodeString result;
+MessageFormat format(str,mError);
+FieldPosition fpos=0;
+format.format(args,1, result,fpos,mError);
+if(U_FAILURE(mError)) {
+  return UnicodeString("Illegal argument");
+}
+
+return result;
+}
+
+void CXMLGenerator::writeLanguage(UnicodeString& xmlString){
+
+UnicodeString *itemTags, *items;
+char* key="Languages";
+int32_t numItems;
+
+if(U_FAILURE(mError)) {
+  return;
+}
+
+mRBundle.getTaggedArray(key,itemTags, items, numItems, mError);
+if(mError!=U_USING_DEFAULT_ERROR && U_SUCCESS(mError) &&
+mError!=U_ERROR_INFO_START){
+
+  Formattable args[]={indentOffset,"",""};
+  xmlString= formatString(UnicodeString(LANGUAGE_NAMES),args,3);
+  indentOffset.append("\t");
+  for(int32_t i=0;i<numItems;i++){
+
+    args[0] = indentOffset;
+    args[1] =itemTags[i] ;
+    args[2] = items[i] ;
+    xmlString.append(formatString(UnicodeString(LANG_ATTRIB),args,3));
+  }
+
+  chopIndent();
+  args[0]=indentOffset;
+  args[1] =(UnicodeString(XML_END_SLASH));
+  args[2] = "";
+  xmlString.append(formatString(UnicodeString(LANGUAGE_NAMES),args,3));
+
+  return;
+}
+mError=U_ZERO_ERROR;
+xmlString.remove();
+}
+
+
+void CXMLGenerator::writeMonthNames(UnicodeString& xmlString){
+
+int32_t lNum;
+const UnicodeString* longMonths=
+mRBundle.getStringArray("MonthNames",lNum,mError);
+if(mError!=U_USING_DEFAULT_ERROR && mError!=U_ERROR_INFO_START && mError !=
+U_MISSING_RESOURCE_ERROR){
+  xmlString.append(formatString(UnicodeString(MONTH_NAMES),indentOffset));
+  indentOffset.append("\t");
+  for(int i=0;i<lNum;i++){
+   char c;
+   itoa(i+1,&c,10);
+   Formattable args[]={indentOffset,UnicodeString(&c),longMonths[i]};
+   xmlString.append(formatString(UnicodeString(MONTH),args,3));
+  }
+  chopIndent();
+  xmlString.append(formatString(UnicodeString(END_MONTH_NAMES),indentOffset));
+  mError=U_ZERO_ERROR;
+  return;
+}
+xmlString.remove();
+mError= U_ZERO_ERROR;
+}
+```
+
+### C
+
+```c
+
+void msgSample1(){
+
+    UChar *result, *tzID, *str;
+    UChar pattern[100];
+    int32_t resultLengthOut, resultlength;
+    UCalendar *cal;
+    UDate d1;
+    UErrorCode status = U_ZERO_ERROR;
+    str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1));
+    u_uastrcpy(str, "disturbance in force");
+    tzID=(UChar*)malloc(sizeof(UChar) * 4);
+     u_uastrcpy(tzID, "PST");
+     cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status);
+     ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status);
+     d1=ucal_getMillis(cal, &status);
+     u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet
+{2,number,integer}");
+     resultlength=0;
+     resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern),
+NULL,
+resultlength, &status, d1, str, 7);
+     if(status==U_BUFFER_OVERFLOW_ERROR){
+         status=U_ZERO_ERROR;
+         resultlength=resultLengthOut+1;
+         result=(UChar*)realloc(result, sizeof(UChar) * resultlength);
+         u_formatMessage( "en_US", pattern, u_strlen(pattern), result,
+resultlength, &status, d1, str, 7);
+     }
+     printf("%s\n",austrdup(result) ); //austrdup( a function used to convert
+UChar* to char*)
+     free(tzID);
+     free(str);
+     free(result);
+}
+
+char *austrdup(const UChar* unichars)
+
+{
+    int   length;
+    char *newString;
+
+    length    = u_strlen ( unichars );
+    newString = (char*)malloc ( sizeof( char ) * 4 * ( length + 1 ) );
+    if ( newString == NULL )
+        return NULL;
+
+    u_austrcpy ( newString, unichars );
+
+    return newString;
+}
+
+This is a more practical sample which retrieves data from a resource bundle
+and
+feeds the data
+to u_formatMessage to produce a formatted string
+
+void msgSample3(){
+
+char* key="Languages";
+int32_t numItems;
+    /* This constant string can also be in the resouce bundle and retrieved at
+the time
+     * of formatting
+     * eg:
+     * UResouceBundle* myResB = ures_open("myResources",currentLocale,&err);
+     * UChar* Lang_Attrib = ures_getString(myResb,"LANG_ATTRIB",&err);
+     */
+    UChar* LANG_ATTRIB   =(UChar*) "{0}<language id=\"{1}\"
+>{2}</language>\n";
+    UChar *result;
+    UResourceBundle* pResB,*pDeltaResB=NULL;
+    UErrorCode err=U_ZERO_ERROR;
+    UChar* indentOffset = (UChar*)"\t\t\t";
+    pResB = ures_open("","en",&err);
+if(U_FAILURE(err)) {
+  return;
+}
+
+    ures_getByKey(pResB, key, pDeltaResB, &err);
+
+    if(U_SUCCESS(err)) {
+        const UChar *value = 0;
+        const char *key = 0;
+        int32_t len = 0;
+        int16_t indexR = -1;
+        int32_t resultLength=0,resultLengthOut=0;
+        numItems = ures_getSize(pDeltaResB);
+        for(;numItems-->0;){
+            key= ures_getKey(pDeltaResB);
+            value = ures_get(pDeltaResB,key,&err);
+            resultLength=0;
+            resultLengthOut=u_formatMessage( "en_US", LANG_ATTRIB,
+u_strlen(LANG_ATTRIB),
+                                                NULL, resultLength, &err,
+indentOffset, value, key);
+            if(err==U_BUFFER_OVERFLOW_ERROR){
+                 err=U_ZERO_ERROR;
+                 resultLength=resultLengthOut+1;
+                 result=(UChar*)realloc(result, sizeof(UChar) * resultLength);
+                 u_formatMessage("en_US",LANG_ATTRIB,u_strlen(LANG_ATTRIB),
+                                result,resultLength,&err,indentOffset,
+                                value,key);
+
+                 printf("%s\n", austrdup(result) );
+            }
+
+        }
+
+  return;
+
+}
+err=U_ZERO_ERROR;
+}
+```
+
+### Java
+
+```java
+import com.ibm.icu.text.*;
+import java.util.Date;
+import java.text.FieldPosition;
+
+public class TestMessageFormat{
+    public void runTest() {
+        String format = "At {1,time,::jmm} on {1,date,::dMMMM}, there was {2} on planet {3,number,integer}.";
+        MessageFormat mf = new MessageFormat(format);
+        Object objectsToFormat[] = { new Date(System.currentTimeMillis()), new Date(System.currentTimeMillis()), "a Disturbance in the Force", new Integer(5)};
+        FieldPosition fp = new FieldPosition(1);
+        StringBuffer sb = new StringBuffer();
+        try{
+            sb = mf.format(objectsToFormat, sb, fp);
+            System.out.println(sb.toString());
+        }catch(IllegalArgumentException e){
+            System.out.println("Exception during formatting of type :" +e);
+        }
+    }
+
+    public static void main(String args[]){
+        try{
+            new TestMessageFormat().runTest();
+        }catch(Exception e){
+            System.out.println("Exception of type: "+e);
+        }
+    }
+}
+```
+
+## `ChoiceFormat` Class
+
+**Important:** The following documentation is outdated. *`ChoiceFormat` is
+probably not what you need. Please use `MessageFormat` with plural arguments for
+proper plural selection, and select arguments for simple selection among a fixed
+set of choices!*
+
+ICU's `ChoiceFormat` class provides more flexibility than the `printf()` and `scanf()`
+style functions for formatting UI strings. This interface can be useful if you
+would like a message to change according to the number of items you are
+displaying. 
+
+Note: Some Asian languages do not have plural words or phrases.
+
+### C++
+
+```cpp
+void msgSample1(){
+
+    UChar *result, *tzID, *str;
+    UChar pattern[100];
+    int32_t resultLengthOut, resultlength;
+    UCalendar *cal;
+    UDate d1;
+    UErrorCode status = U_ZERO_ERROR;
+    str=(UChar*)malloc(sizeof(UChar) * (strlen("disturbance in force") +1));
+    u_uastrcpy(str, "disturbance in force");
+    tzID=(UChar*)malloc(sizeof(UChar) * 4);
+     u_uastrcpy(tzID, "PST");
+     cal=ucal_open(tzID, u_strlen(tzID), "en_US", UCAL_TRADITIONAL, &status);
+     ucal_setDateTime(cal, 1999, UCAL_MARCH, 18, 0, 0, 0, &status);
+     d1=ucal_getMillis(cal, &status);
+     u_uastrcpy(pattern, "On {0, date, long}, there was a {1} on planet
+
+{2,number,integer}");
+     resultlength=0;
+     resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern),
+NULL,
+resultlength, &status, d1, str, 7);
+     if(status==U_BUFFER_OVERFLOW_ERROR){
+         status=U_ZERO_ERROR;
+         resultlength=resultLengthOut+1;
+         result=(UChar*)realloc(result, sizeof(UChar) * resultlength);
+         u_formatMessage( "en_US", pattern, u_strlen(pattern), result,
+resultlength, &status, d1, str, 7);
+     }
+     printf("%s\n",austrdup(result) ); //austrdup( a function used to convert
+UChar* to char*)
+     free(tzID);
+     free(str);
+double filelimits[] = {0,1,2};
+UErrorCode err;
+UnicodeString filepart[] = {"are no files","is one file","are {2} files"};
+ChoiceFormat fileform(filelimits, filepart,err);
+Format testFormats[] = {fileform, null, NumberFormat.getInstance()};
+MessageFormat pattform("There {0} on {1}",err);
+pattform.setFormats(testFormats);
+Formattable testArgs[] = {null, "ADisk", null};
+for (int i = 0; i < 4; ++i) {
+     testArgs[0] = i;
+     testArgs[2] = testArgs[0];
+     FieldPosition fpos=0;
+     format.format(args,1, result,fpos,mError);
+     UnicodeString result = pattform.format(testArgs);
+}
+```
+
+### C
+
+```c
+void msgSample2(){
+     UChar* str;
+     UErrorCode status = U_ZERO_ERROR;
+     UChar *result;
+     UChar pattern[100];
+     int32_t resultlength,resultLengthOut, i;
+     double testArgs[3]= { 100.0, 1.0, 0.0};
+     str=(UChar*)malloc(sizeof(UChar) * 10);
+     u_uastrcpy(str, "MyDisk");
+     u_uastrcpy(pattern, "The disk {1} contains {0,choice,0#no files|1#one
+file|1<{0,number,integer} files}");
+     for(i=0; i<3; i++){
+         resultlength=0;
+         resultLengthOut=u_formatMessage( "en_US", pattern, u_strlen(pattern),
+NULL, resultlength, &status, testArgs[i], str);
+         if(status==U_BUFFER_OVERFLOW_ERROR){
+             status=U_ZERO_ERROR;
+             resultlength=resultLengthOut+1;
+             result=(UChar*)malloc(sizeof(UChar) * resultlength);
+             u_formatMessage( "en_US", pattern, u_strlen(pattern), result,
+resultlength, &status, testArgs[i], str);
+         }
+     }
+     printf("%s\n", austrdup(result) ); //austrdup( a function used to
+convert
+UChar* to char*)
+     free(result);
+
+}
+```
+
+### Java
+
+```java
+import java.text.ChoiceFormat;
+import com.ibm.icu.text.*;
+import java.text.Format;
+
+public class TestChoiceFormat{
+    public void run(){
+        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}");
+        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));
+        }
+    }
+
+    public static void main(String args[]){
+        new TestChoiceFormat().run();
+    }
+}
+```

docs/userguide/format_parse/messages/index.md

@@ -0,0 +1,238 @@
+---
+layout: default
+title: Formatting Messages
+nav_order: 3
+parent: Formatting
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Formatting Messages
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+Messages are user-visible strings, often with variable elements like names,
+numbers and dates. Message strings are typically translated into the different
+languages of a UI, and translators move around the variable elements according
+to the grammar of the target language.
+
+For this to work in many languages, a message has to be written and translated
+as a single unit, typically a string with placeholder syntax for the variable
+elements. If the user-visible string were concatenated directly from fragments
+and formatted elements, then translators would not be able to rearrange the
+pieces, and they would have a hard time translating each of the string
+fragments.
+
+## `MessageFormat`
+
+The ICU **`MessageFormat`** class uses message `"pattern"` strings with
+variable-element placeholders (called "arguments" in the API docs) enclosed in
+{curly braces}. The argument syntax can include formatting details, otherwise a
+default format is used. For details about the pattern syntax and the formatting
+behavior see the `MessageFormat` API docs
+([Java](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/MessageFormat.html),
+[C++](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classMessageFormat.html#_details),
+[C](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/umsg_8h.html#_details)).
+
+### Complex Argument Types
+
+Certain types of arguments select among several choices which are nested
+`MessageFormat` pattern strings. Keeping these choices together in one message
+pattern string facilitates translation in context, by one single translator.
+(Commercial translation systems often distribute different messages to different
+translators.)
+
+*   Use a `"plural"` argument to select sub-messages based on a numeric value,
+    together with the plural rules for the specified language.
+*   Use a `"select"` argument to select sub-messages via a fixed set of keywords.
+*   Use of the old `"choice"` argument type is discouraged. It cannot handle
+    plural rules for many languages, and is clumsy for simple selection.
+
+It is tempting to cover only a minimal part of a message string with a complex
+argument (e.g., plural). However, this is difficult for translators for two
+reasons: 1. They might have trouble understanding how the sentence fragments in
+the argument sub-messages interact with the rest of the sentence, and 2. They
+will not know whether and how they can shrink or grow the extent of the part of
+the sentence that is inside the argument to make the whole message work for
+their language.
+
+**Recommendation:** If possible, use complex arguments as the outermost
+structure of a message, and write **full sentences** in their sub-messages. If
+you have nested select and plural arguments, place the **select** arguments
+(with their fixed sets of choices) on the **outside** and nest the plural
+arguments (hopefully at most one) inside.
+
+For example:
+
+{% raw  %}
+
+```text
+"{gender_of_host, select, "
+  "female {"
+    "{num_guests, plural, offset:1 "
+      "=0 {{host} does not give a party.}"
+      "=1 {{host} invites {guest} to her party.}"
+      "=2 {{host} invites {guest} and one other person to her party.}"
+      "other {{host} invites {guest} and # other people to her party.}}}"
+  "male {"
+    "{num_guests, plural, offset:1 "
+      "=0 {{host} does not give a party.}"
+      "=1 {{host} invites {guest} to his party.}"
+      "=2 {{host} invites {guest} and one other person to his party.}"
+      "other {{host} invites {guest} and # other people to his party.}}}"
+  "other {"
+    "{num_guests, plural, offset:1 "
+      "=0 {{host} does not give a party.}"
+      "=1 {{host} invites {guest} to their party.}"
+      "=2 {{host} invites {guest} and one other person to their party.}"
+      "other {{host} invites {guest} and # other people to their party.}}}}"
+```
+
+{% endraw %}
+
+**Note:** In a plural argument like in the example above, if the English message
+has both `=0` and `=1` (up to `=offset`+1) then it does not need a "`one`"
+variant because that would never be selected. It does always need an "`other`"
+variant.
+
+**Note:** *The translation system and the translator together need to add
+["`one`", "`few`" etc. if and as necessary per target
+language](http://cldr.unicode.org/index/cldr-spec/plural-rules).*
+
+### Quoting/Escaping
+
+If syntax characters occur in the text portions, then they need to be quoted by
+enclosing the syntax in pairs of ASCII apostrophes. A pair of ASCII apostrophes
+always represents one ASCII apostrophe, similar to `%%` in `printf` representing one `%`,
+although this rule still applies inside quoted text. ("`This '{isn''t}' obvious`" → "`This {isn't} obvious`")
+
+*   Before ICU 4.8, ASCII apostrophes always started quoted text and had
+    inconsistent behavior in nested sub-messages, which was a source of problems
+    with authoring and translating message pattern strings.
+*   Starting with ICU 4.8, an ASCII apostrophe only starts quoted text if it
+    immediately precedes a character that requires quoting (that is, "only where
+    needed"), and works the same in nested messages as on the top level of the
+    pattern. The new behavior is otherwise compatible; for details see the
+    MessageFormat and MessagePattern (new in ICU 4.8) API docs.
+*   Recommendation: Use the real apostrophe (single quote) character `’` (U+2019)
+    for human-readable text, and use the ASCII apostrophe `'` (U+0027) only in
+    program syntax, like quoting in MessageFormat. See the annotations for
+    U+0027 Apostrophe in The Unicode Standard.
+
+### Argument formatting
+
+Arguments are formatted according to their type, using the default ICU
+formatters for those types, unless otherwise specified. For unknown types the
+Java `MessageFormat` will call `toString()`.
+
+There are also several ways to control the formatting.
+
+#### Predefined styles (recommended)
+
+You can specify the `argStyle` to be one of the predefined values `short`, `medium`,
+`long`, `full` (to get one of the standard forms for dates / times) and `integer`,
+`currency`, `percent` (for number formatting).
+
+#### Skeletons (recommended)
+
+Numbers, dates, and times can use a skeleton in `argStyle`, prefixed with `::` to
+distinguish them from patterns. These are locale-independent ways to specify the
+format, and this is the recommended mechanism if the predefined styles are not
+appropriate.
+
+##### Date skeletons:
+
+- **ICU4J:**
+<https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/SimpleDateFormat.html>
+
+- **ICU4C:** <https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classSimpleDateFormat.html>
+
+##### Number formatter skeletons:
+
+- **ICU4J:**
+<https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/number/NumberFormatter.html>
+
+- **ICU4C:** <https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1NumberFormat.html>
+
+#### Format the parameters separately (recommended)
+
+You can format the parameter as you need **before** calling `MessageFormat`, and
+then passing the resulting string as a parameter to `MessageFormat`.
+
+This offers maximum control, and is preferred to using custom format objects
+(see below).
+
+#### String patterns (discouraged)
+
+These can be used for numbers, dates, and times, but they are locale-sensitive,
+and they therefore would need to be localized by your translators, which adds
+complexity to the localization, and placeholder details are often not accessible
+by translators. If such a pattern is not localized, then users see confusing
+formatting. Consider using skeletons instead of patterns in your message
+strings.
+
+Allowing translators to localize date patterns is error-prone, as translators
+might make mistakes (resulting in invalid ICU date formatter syntax). Also, CLDR
+provides curated patterns for many locales, and using your own pattern means
+that you don't benefit from that CLDR data and the results will likely be
+inconsistent with the rest of the patterns that ICU uses.
+
+It is also a bad internationalization practice, because most companies only
+translate into "generic" versions of the languages (French, or Spanish, or
+Arabic). So the translated patterns get used in tens of countries. On the other
+hand, skeletons are localized according to the MessageFormat locale, which
+should include regional variants (e.g., “fr-CA”).
+
+#### Custom Format Objects (discouraged)
+
+The `MessageFormat` class allows setting custom Format objects to format
+arguments, overriding the arguments' pattern specification. This is discouraged:
+For custom formatting of some values it should normally suffice to format them
+externally and to provide the formatted strings to the `MessageFormat.format()`
+methods.
+
+Only the top-level arguments are accessible and settable via `setFormat()`,
+`getFormat()` etc. Arguments inside nested sub-messages, inside
+choice/plural/select arguments, are "invisible" via these API methods.
+
+Some of these methods (the ones corresponding to the original JDK `MessageFormat`
+API) address the top-level arguments in their order of appearance in the pattern
+string, which is usually not useful because it varies with translations. Newer
+methods address arguments by argument number ("index") or name.
+
+### Examples
+
+The following code fragment created this output: "At 4:34 PM on March 23, there
+was a disturbance in the Force on planet 7."
+
+```cpp
+    UErrorCode err = U_ZERO_ERROR;
+    Formattable arguments[] = {
+       (int32_t)7,
+       Formattable(Calendar.getNow(), Formattable::kIsDate),
+       "a disturbance in the Force"
+    };
+
+    UnicodeString result;
+    result = MessageFormat::format(
+       "At {1,time,::jmm} on {1,date,::dMMMM}, there was {2} on planet{0,number,integer}.",
+       arguments,
+       3,
+       result,
+       err);
+```
+
+There are several more usage examples for the `MessageFormat` and `ChoiceFormat`
+classes in [C , C++ and Java](examples.md).

docs/userguide/format_parse/numbers/index.md

@@ -0,0 +1,30 @@
+---
+layout: default
+title: Formatting Numbers
+nav_order: 1
+parent: Formatting
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Formatting Numbers
+
+Since ICU 60, the recommended mechanism for formatting numbers is 
+[`NumberFormatter`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/numberformatter_8h.html#details)
+([Java](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/number/NumberFormatter.html)).  `NumberFormatter` supports the formatting of:
+
+- Decimal Formatting
+- Currencies
+- Measurement Units
+- Percentages
+- Scientific Notation
+- Compact Notation
+
+For number ranges, including currency and measurement unit ranges, see [`NumberRangeFormatter`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/numberrangeformatter_8h.html) ([Java](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/number/NumberRangeFormatter.html)).
+
+For rule-based number formatting, including spellout rules and support for traditional numbering systems not covered by base-10 decimal digits, see [rbnf.md](rbnf.md).
+
+For the classic `NumberFormat` class, which also includes legacy parsing support for localized number strings, see [legacy-numberformat.md](legacy-numberformat.md).

docs/userguide/format_parse/numbers/legacy-numberformat.md

@@ -0,0 +1,215 @@
+---
+layout: default
+title: Legacy NumberFormat
+nav_order: 1
+grand_parent: Formatting
+parent: Formatting Numbers
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Legacy `NumberFormat`
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Note
+
+> :warning: Since ICU 60, the recommended way to format numbers is NumberFormatter; see [index.md](index.md).
+> 
+> This page is here for reference for the older NumberFormat hierarchy in ICU4C and ICU4J.
+
+## `NumberFormat`
+
+[`NumberFormat`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classNumberFormat.html) is
+the abstract base class for all number formats. It provides an interface for
+formatting and parsing numbers. It also provides methods to determine which
+locales have number formats, and what their names are. `NumberFormat` helps format
+and parse numbers for any locale. Your program can be written to be completely
+independent of the locale conventions for decimal points or
+thousands-separators. It can also be written to be independent of the particular
+decimal digits used or whether the number format is a decimal. A normal decimal
+number can also be displayed as a currency or as a percentage.
+
+```
+1234.5       //Decimal number
+$1234.50     //U.S. currency
+1.234,57€    //German currency
+123457%      //Percent
+```
+
+### Usage
+
+#### Formatting for a `Locale`
+
+To format a number for the current `Locale`, use one of the static factory methods
+to create a format, then call a format method to format it. To format a number
+for a different `Locale`, specify the `Locale` in the call to `createInstance()`. You
+can control the numbering system to be used for number formatting by creating a
+`Locale` that uses the `@numbers` keyword defined. For example, by default, the Thai
+locale "th" uses the western digits 0-9. To create a number format that uses the
+native Thai digits instead, first create a locale with `"@numbers=thai"` defined.
+See [the description on Locales](../../locale/index.md) for details.
+
+> :point_right: **Note**: If you are formatting multiple numbers, save processing time
+> by constructing the formatter once and then using it several times.
+
+#### Instantiating a `NumberFormat`
+
+The following methods are used for instantiating `NumberFormat` objects:
+
+1.  **`createInstance()`**
+    Returns the normal number format for the current locale or for a specified
+    locale.
+
+2.  **`createCurrencyInstance()`**
+    Returns the currency format for the current locale or for a specified
+    locale.
+
+3.  **`createPercentInstance()`**
+    Returns the percentage format for the current locale or for a specified
+    locale.
+
+4.  **`createScientificInstance()`**
+    Returns the scientific number format for the current locale or for a
+    specified locale.
+
+To create a format for spelled-out numbers, use a constructor on `RuleBasedNumberFormat`.
+
+#### Currency Formatting
+
+Currency formatting, i.e., the formatting of monetary values, combines a number
+with a suitable display symbol or name for a currency. By default, the currency
+is set from the locale data from when the currency format instance is created,
+based on the country code in the locale ID. However, for all but trivial uses,
+this is fragile because countries change currencies over time, and the locale
+data for a particular country may not be available.
+
+For proper currency formatting, both number and currency must be
+specified. Aside from achieving reliably correct results, this also allows to
+format monetary values in any currency with the format of any locale, like in
+exchange rate lists. If the locale data does not contain display symbols or
+names for a currency, then the 3-letter ISO code itself is displayed.
+
+The locale ID and the currency code are effectively independent: The locale ID
+defines the general format for the numbers, and whether the currency symbol or
+name is displayed before or after the number, while the currency code selects
+the actual currency with its symbol, name, number of digits, and [rounding
+mode](rounding-modes.md).
+
+In ICU and Java, the currency is specified in the form of a 3-letter ISO 4217
+code. For example, the code "USD" represents the US Dollar and "EUR" represents
+the Euro currency.
+
+In terms of APIs, the currency code is set as an attribute on a number format
+object (on a currency instance), while the number value is passed into each
+`format()` call or returned from `parse()` as usual.
+
+1.  ICU4C (C++) `NumberFormat.setCurrency()` takes a Unicode string (`const UChar*`) with the 3-letter code.
+
+2.  ICU4C (C API) allows to set the currency code via `unum_setTextAttribute()`
+    using the `UNUM_CURRENCY_CODE` selector.
+
+3.  ICU4J `NumberFormat.setCurrency()` takes an ICU Currency object which
+    encapsulates the 3-letter code.
+
+4.  The base JDK's `NumberFormat.setCurrency()` takes a JDK Currency object which
+    encapsulates the 3-letter code.
+
+The functionality of `Currency` and `setCurrency()` is more advanced in ICU than in
+the base JDK. When using ICU, setting the currency automatically adjusts the
+number format object appropriately, i.e., it sets not only the currency symbol
+and display name, but also the correct number of fraction digits and the correct
+[rounding mode](rounding-modes.md). This is not the case with the base JDK. See
+the API references for more details.
+
+There is ICU4C sample code at
+[icu4c/source/samples/numfmt/main.cpp](https://github.com/unicode-org/icu/blob/main/icu4c/source/samples/numfmt/main.cpp)
+which illustrates the use of `NumberFormat.setCurrency()`.
+
+#### Displaying Numbers
+
+You can also control the display of numbers with methods such as
+`getMinimumFractionDigits()`. If you want even more control over the format or
+parsing, or want to give your users more control, cast the `NumberFormat` returned
+from the factory methods to a `DecimalNumberFormat`. This works for the vast
+majority of countries.
+
+#### Working with Positions
+
+You can also use forms of the parse and format methods with `ParsePosition` and
+`UFieldPosition` to enable you to:
+
+1.  progressively parse through pieces of a string.
+
+2.  align the decimal point and other areas.
+
+For example, you can align numbers in two ways:
+
+1.  If you are using a mono-spaced font with spacing for alignment, pass the
+    `FieldPosition` in your format call with `field = INTEGER_FIELD`. On output,
+    `getEndIndex` is set to the offset between the last character of the integer
+    and the decimal. Add `(desiredSpaceCount - getEndIndex)` spaces at the front
+    of the string. You can also use the space padding feature available in
+    `DecimalFormat`.
+
+2.  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 additional characters at
+    the end (that is, with parentheses in negative numbers: "(12)" for -12).
+
+#### Emulating `printf`
+
+`NumberFormat` can produce many of the same formats as printf.
+
+| printf | ICU |
+|--------|-----|
+| Width specifier, e.g., `"%5d"` has a width of 5. | Use `DecimalFormat`. Either specify the padding, with can pad with any character, or specify a minimum integer count and a minimum fraction count, which will emit a specific number of digits, with zero padded to the left and right. |
+| Precision specifier for `%f` and `%e`, e.g. `"%.6f"` or `"%.6e"`. This defines the number of digits to the right of the decimal point. | Use `DecimalFormat`. Specify the maximum fraction digits. |
+| General scientific notation, `%g`. This format uses either `%f` or `%e`, depending on the magnitude of the number being displayed. | Use `ChoiceFormat` with `DecimalFormat`. For example, for a typical `%g`, which has 6 significant digits, use a `ChoiceFormat` with thresholds of 1e-4 and 1e6. For values between the two thresholds, use a fixed `DecimalFormat` with the pattern `"@#####"`. For values outside the thresholds, use a `DecimalFormat` with the pattern `"@#####E0"`. |
+
+## `DecimalFormat`
+
+`DecimalFormat` is a `NumberFormat` that converts numbers into strings using the
+decimal numbering system. This is the formatter that provides standard number
+formatting and parsing services for most usage scenarios in most locales. In
+order to access features of `DecimalFormat` not exposed in the `NumberFormat` API,
+you may need to cast your `NumberFormat` object to a `DecimalFormat`. You may also
+construct a `DecimalFormat` directly, but this is not recommended because it can
+hinder proper localization.
+
+For a complete description of `DecimalFormat`, including the pattern syntax,
+formatting and parsing behavior, and available API, see the [ICU4J `DecimalFormat`
+API](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/DecimalFormat.html) or
+[ICU4C `DecimalFormat`
+API](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classDecimalFormat.html) documentation.
+
+## `DecimalFormatSymbols`
+
+[`DecimalFormatSymbols`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classDecimalFormatSymbols.html)
+specifies the exact characters a `DecimalFormat` uses for various parts of a
+number (such as the characters to use for the digits, the character to use as
+the decimal point, or the character to use as the minus sign).
+
+This class represents the set of symbols needed by `DecimalFormat` to format
+numbers. `DecimalFormat` creates its own instance of `DecimalFormatSymbols` from its
+locale data. The `DecimalFormatSymbols` can be adopted by a `DecimalFormat`
+instance, or it can be specified when a `DecimalFormat` is created. If you need to
+change any of these symbols, can get the `DecimalFormatSymbols` object from your
+`DecimalFormat` and then modify it.
+
+## Additional Sample Code
+
+C/C++: See
+[icu4c/source/samples/numfmt/](https://github.com/unicode-org/icu/blob/main/icu4c/source/samples/numfmt/)
+in the ICU source distribution for code samples showing the use of ICU number
+formatting.

docs/userguide/format_parse/numbers/rbnf-examples.md

@@ -0,0 +1,109 @@
+---
+layout: default
+title: RuleBasedNumberFormat Examples
+nav_order: 6
+grand_parent: Formatting
+parent: Formatting Numbers
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# `RuleBasedNumberFormat` Examples
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Annotated `RuleBasedNumberFormat` Example
+
+The following example provides a quick idea of how the rules work. The
+[`RuleBasedNumberFormat` API
+documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classRuleBasedNumberFormat.html)
+describes the rule syntax in more detail.
+
+This ruleset formats a number using standard decimal place-value notation, but
+using words instead of digits, e.g. 123.4 formats as 'one two three point four':
+
+```
+"-x: minus >>;\n"
++ "x.x: << point >>;\n"
++ "zero; one; two; three; four; five; six;\n"
++ "    seven; eight; nine;\n"
++ "10: << >>;\n"
++ "100: << >>>;\n"
++ "1000: <<, >>>;\n"
++ "1,000,000: <<, >>>;\n"
++ "1,000,000,000: <<, >>>;\n"
++ "1,000,000,000,000: <<, >>>;\n"
++ "1,000,000,000,000,000: =#,##0=;\n";
+```
+
+In this example, the rules consist of one (unnamed) ruleset. It lists nineteen
+rules, each terminated by a semicolon. It starts with two special rules for
+handling negative numbers and non-integers. (This is true of most rulesets.)
+Following are rules for increasing integer ranges, up to 10e15. The portion of
+the rule before a colon, if any, provides information about the range and some
+additional information about how to apply the rule. Most rule bodies (following
+the colon) consist of recursion instructions and/or plain text substitutions.
+The rules in this example work as follows:
+
+1.  **-x: minus >>;**
+    If the number is negative, output the string 'minus ' and recurse using the
+    absolute value.
+
+2.  **x.x: << point >>;**
+    If the number is not an integer, recurse using the integral part, emit the
+    string ' point ', and process the ruleset in 'fractional mode' for the
+    fractional part. Generally, this emits single digits.
+
+3.  **zero; one; ... nine;**
+    Each of these ten rules applies to a range. By default, the first range
+    starts at zero, and succeeding ranges start at the previous start + 1. These
+    ranges all default, so each of these ten rules has a 'range' of a single
+    integer, 0 to 9. When the current value is in one of these ranges, the rules
+    emit the corresponding text (e.g. 'one', 'two', and so on).
+
+4.  **10: << >>;**
+    This starts a new range at 10 (not default) and sets the limit of the range
+    for the previous rule. Divide the number by the divisor (which defaults to
+    the highest power of 10 lower or equal to range start value, e.g. 10),
+    recurse using the integral part, emit the string ' ' (space), then recurse
+    using the remainder.
+
+5.  **100: << >>>;**
+    This starts a new range at 100 (again, limiting the previous rule's range).
+    It is similar to the previous rule, except for the use of '>>>'. '>>' means
+    to recurse by matching the value against all the ranges to find the rule,
+    '>>>' means to recurse using the previous rule. We must force the previous
+    rule in order to get the rule for 'ten' invoked in order to emit '0' when
+    processing numbers like 105.
+
+6.  **1000: <<, >>>; 1,000,000: ...**
+    These start new ranges at intervals of 1000. They are all similar to the
+    rule for 100 except they output ', ' (comma space) to delimit thousands.
+    Note that the range value can include commas for readability.
+
+7.  **1,000... =#,##0=;**
+    This last rule in the ruleset applies to all values at or over 10e15. The
+    pattern '==' means to use the current unmodified value, and text within in
+    the pattern (this works for '<<' and similar patterns as well) describes the
+    ruleset or decimal format to use. If this text starts with '0' or '#', it is
+    presumed to be a decimal format pattern. So this rule means to format the
+    unmodified number using a decimal format constructed with the pattern
+    '#,##0'.
+
+Rulesets are invoked by first applying negative and fractional rules, then by
+finding the rule whose range includes the current value and applying that rule,
+recursing as directed by the rule. Again, a complete description of the rule
+syntax can be found in the [API
+Documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classRuleBasedNumberFormat.html).
+
+More rule examples can be found in the `RuleBasedNumberFormat` [demo
+source](https://github.com/unicode-org/icu/blob/main/icu4j/demos/src/com/ibm/icu/dev/demo/rbnf/RbnfSampleRuleSets.java).

docs/userguide/format_parse/numbers/rbnf.md

@@ -0,0 +1,138 @@
+---
+layout: default
+title: RuleBasedNumberFormat
+nav_order: 5
+grand_parent: Formatting
+parent: Formatting Numbers
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# RuleBasedNumberFormat
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+# Overview
+
+[RuleBasedNumberFormat](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classRuleBasedNumberFormat.html)
+can format and parse numbers in spelled-out format, e.g. "one hundred and
+thirty-four". For example:
+
+```
+"one hundred and thirty-four" // 134 using en_US spellout
+"one hundred and thirty-fourth" // 134 using en_US ordinal
+"hundertvierunddreissig" // 134 using de_DE spellout
+"MCMLVIII" // custom, 1958 in roman numerals
+```
+
+RuleBasedNumberFormat is based on rules describing how to format a number. The
+rule syntax is designed primarily for formatting and parsing numbers as
+spelled-out text, though other kinds of formatting are possible. As a
+convenience, custom API is provided to allow selection from three predefined
+rule definitions, when available: SPELLOUT, ORDINAL, and DURATION. Users can
+request formatters either by providing a locale and one of these predefined rule
+selectors, or by specifying the rule definitions directly.
+
+> :point_right: **Note**: ICU provides number spellout rules for several locales, but not for all of the
+locales that ICU supports, and not all of the predefined rule types. Also, as of
+release 2.6, some of the provided rules are known to be incomplete.
+
+## Instantiation
+
+Unlike the other standard number formats, there is no corresponding factory
+method on NumberFormat. Instead, RuleBasedNumberFormat objects are instantiated
+via constructors. Constructors come in two flavors, ones that take rule text,
+and ones that take one of the predefined selectors. Constructors that do not
+take a Locale parameter use the current default locale.
+
+The following constructors are available:
+
+1.  **RuleBasedNumberFormat(int)**
+    Returns a format using predefined rules of the selected type from the
+    current locale.
+
+2.  **RuleBasedNumberFormat(Locale, int)**
+    As above, but specifies locale.
+
+3.  **RuleBasedNumberFormat(String)**
+    Returns a format using the provided rules, and symbols (if required) from
+    the current locale.
+
+4.  **RuleBasedNumberFormat(String, Locale)**
+    As above, but specifies locale.
+
+## Usage
+
+RuleBasedNumberFormat can be used like other NumberFormats. For example, in
+Java:
+
+```java
+double num = 2718.28;
+NumberFormat formatter = 
+    new RuleBasedNumberFormat(RuleBasedNumberFormat.SPELLOUT);
+String result = formatter.format(num);
+System.out.println(result);
+
+// output (in en_US locale):
+// two thousand seven hundred and eighteen point two eight
+```
+
+## Rule Sets
+
+Rule descriptions can provide multiple named rule sets, for example, the rules
+for en_US spellout provides a '%simplified' rule set that displays text without
+commas or the word 'and'. Rule sets can be queried and set on a
+RuleBasedNumberFormat. This lets you customize a RuleBasedNumberFormat for use
+through its inherited NumberFormat API. For example, in Java:
+
+You can also format a number specifying the ruleset directly, using an
+additional overload of format provided by RuleBasedNumberFormat. For example, in
+Java:
+
+> :point_right: **Note**: There is no standardization of rule set names, so you must either query the
+names, as in the first example above, or know the names that are defined in the
+rules for that formatter.
+
+## Rules
+
+The following example provides a quick look at the RuleBasedNumberFormat rule
+syntax.
+
+These rules format a number using standard decimal place-value notation, but
+using words instead of digits, e.g. 123.4 formats as 'one two three point four':
+
+```
+"-x: minus >>;\n"
++ "x.x: << point >>;\n"
++ "zero; one; two; three; four; five; six;\n"
++ "    seven; eight; nine;\n"
++ "10: << >>;\n"
++ "100: << >>>;\n"
++ "1000: <<, >>>;\n"
++ "1,000,000: <<, >>>;\n"
++ "1,000,000,000: <<, >>>;\n"
++ "1,000,000,000,000: <<, >>>;\n"
++ "1,000,000,000,000,000: =#,##0=;\n";
+```
+
+Rulesets are invoked by first applying negative and fractional rules, and then
+using a recursive process. It starts by finding the rule whose range includes
+the current value and applying that rule. If the rule so directs, it emits text,
+including text obtained by recursing on new values as directed by the rule. As
+you can see, the rules are designed to accommodate recursive processing of
+numbers, and so are best suited for formatting numbers in ways that are
+inherently recursive.
+
+A full explanation of this example can be found in the [RuleBasedNumberFormat
+examples](rbnf-examples.md). A complete description of the rule syntax can be
+found in the [RuleBasedNumberFormat API
+Documentation](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classRuleBasedNumberFormat.html).

docs/userguide/format_parse/numbers/rounding-modes.md

@@ -0,0 +1,153 @@
+---
+layout: default
+title: Rounding Modes
+nav_order: 2
+grand_parent: Formatting
+parent: Formatting Numbers
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Rounding Modes
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+The following rounding modes are used with ICU's Decimal Formatter. Note that
+ICU's use of the terms "Down" and "Up" here are somewhat at odds with other
+definitions, but are equivalent to the same modes used in Java's JDK.
+
+## Comparison of Rounding Modes
+
+This chart shows the values -2.0 through 2.0 in increments of 0.1, and shows the
+resulting ICU format when formatted with no decimal digits.
+
+*Note: Some of the options below are not available in ICU4J because we use the JDK RoundingMode.*
+
+| #    | CEILING | FLOOR | DOWN | UP | HALFEVEN | HALFODD | HALFCEILING | HALFFLOOR | HALFDOWN | HALFUP | #    |
+|------|---------|-------|------|----|----------|---------|-------------|-----------|----------|--------|------|
+| -2.0 | -2      | -2    | -2   | -2 | -2       | -2      | -2          | -2        | -2       | -2     | -2.0 |
+| -1.9 | -1      | -2    | -1   | -2 | -2       | -2      | -2          | -2        | -2       | -2     | -1.9 |
+| -1.8 | -1      | -2    | -1   | -2 | -2       | -2      | -2          | -2        | -2       | -2     | -1.8 |
+| -1.7 | -1      | -2    | -1   | -2 | -2       | -2      | -2          | -2        | -2       | -2     | -1.7 |
+| -1.6 | -1      | -2    | -1   | -2 | -2       | -2      | -2          | -2        | -2       | -2     | -1.6 |
+| -1.5 | -1      | -2    | -1   | -2 | -2       | -1      | -1          | -2        | -1       | -2     | -1.5 |
+| -1.4 | -1      | -2    | -1   | -2 | -1       | -1      | -1          | -1        | -1       | -1     | -1.4 |
+| -1.3 | -1      | -2    | -1   | -2 | -1       | -1      | -1          | -1        | -1       | -1     | -1.3 |
+| -1.2 | -1      | -2    | -1   | -2 | -1       | -1      | -1          | -1        | -1       | -1     | -1.2 |
+| -1.1 | -1      | -2    | -1   | -2 | -1       | -1      | -1          | -1        | -1       | -1     | -1.1 |
+| -1.0 | -1      | -1    | -1   | -1 | -1       | -1      | -1          | -1        | -1       | -1     | -1.0 |
+| -0.9 | -0      | -1    | -0   | -1 | -1       | -1      | -1          | -1        | -1       | -1     | -0.9 |
+| -0.8 | -0      | -1    | -0   | -1 | -1       | -1      | -1          | -1        | -1       | -1     | -0.8 |
+| -0.7 | -0      | -1    | -0   | -1 | -1       | -1      | -1          | -1        | -1       | -1     | -0.7 |
+| -0.6 | -0      | -1    | -0   | -1 | -1       | -1      | -1          | -1        | -1       | -1     | -0.6 |
+| -0.5 | -0      | -1    | -0   | -1 | -0       | -1      | -0          | -1        | -0       | -1     | -0.5 |
+| -0.4 | -0      | -1    | -0   | -1 | -0       | -0      | -0          | -0        | -0       | -0     | -0.4 |
+| -0.3 | -0      | -1    | -0   | -1 | -0       | -0      | -0          | -0        | -0       | -0     | -0.3 |
+| -0.2 | -0      | -1    | -0   | -1 | -0       | -0      | -0          | -0        | -0       | -0     | -0.2 |
+| -0.1 | -0      | -1    | -0   | -1 | -0       | -0      | -0          | -0        | -0       | -0     | -0.1 |
+| 0.0  | 0       | 0     | 0    | 0  | 0        | 0       | 0           | 0         | 0        | 0      | 0.0  |
+| 0.1  | 1       | 0     | 0    | 1  | 0        | 0       | 0           | 0         | 0        | 0      | 0.1  |
+| 0.2  | 1       | 0     | 0    | 1  | 0        | 0       | 0           | 0         | 0        | 0      | 0.2  |
+| 0.3  | 1       | 0     | 0    | 1  | 0        | 0       | 0           | 0         | 0        | 0      | 0.3  |
+| 0.4  | 1       | 0     | 0    | 1  | 0        | 0       | 0           | 0         | 0        | 0      | 0.4  |
+| 0.5  | 1       | 0     | 0    | 1  | 0        | 1       | 1           | 0         | 0        | 1      | 0.5  |
+| 0.6  | 1       | 0     | 0    | 1  | 1        | 1       | 1           | 1         | 1        | 1      | 0.6  |
+| 0.7  | 1       | 0     | 0    | 1  | 1        | 1       | 1           | 1         | 1        | 1      | 0.7  |
+| 0.8  | 1       | 0     | 0    | 1  | 1        | 1       | 1           | 1         | 1        | 1      | 0.8  |
+| 0.9  | 1       | 0     | 0    | 1  | 1        | 1       | 1           | 1         | 1        | 1      | 0.9  |
+| 1.0  | 1       | 1     | 1    | 1  | 1        | 1       | 1           | 1         | 1        | 1      | 1.0  |
+| 1.1  | 2       | 1     | 1    | 2  | 1        | 1       | 1           | 1         | 1        | 1      | 1.1  |
+| 1.2  | 2       | 1     | 1    | 2  | 1        | 1       | 1           | 1         | 1        | 1      | 1.2  |
+| 1.3  | 2       | 1     | 1    | 2  | 1        | 1       | 1           | 1         | 1        | 1      | 1.3  |
+| 1.4  | 2       | 1     | 1    | 2  | 1        | 1       | 1           | 1         | 1        | 1      | 1.4  |
+| 1.5  | 2       | 1     | 1    | 2  | 2        | 1       | 2           | 1         | 1        | 2      | 1.5  |
+| 1.6  | 2       | 1     | 1    | 2  | 2        | 2       | 2           | 2         | 2        | 2      | 1.6  |
+| 1.7  | 2       | 1     | 1    | 2  | 2        | 2       | 2           | 2         | 2        | 2      | 1.7  |
+| 1.8  | 2       | 1     | 1    | 2  | 2        | 2       | 2           | 2         | 2        | 2      | 1.8  |
+| 1.9  | 2       | 1     | 1    | 2  | 2        | 2       | 2           | 2         | 2        | 2      | 1.9  |
+| 2.0  | 2       | 2     | 2    | 2  | 2        | 2       | 2           | 2         | 2        | 2      | 2.0  |
+| #    | CEILING | FLOOR | DOWN | UP | HALFEVEN | HALFODD | HALFCEILING | HALFFLOOR | HALFDOWN | HALFUP | #    |
+
+### Half Even
+
+This is ICU's default rounding mode. Values exactly on the 0.5 (half) mark
+(shown dotted in the chart) are rounded to the nearest even digit. This is often
+called Banker's Rounding because it is, on average, free of bias. It is the
+default mode specified for IEEE 754 floating point operations.
+
+Also known as ties-to-even, round-to-nearest, RN or RNE.
+
+### Half Odd
+
+Similar to Half Even, but rounds ties to the nearest odd number instead of even number.
+
+### Half Down
+
+Values exactly on the 0.5 (half) mark are rounded down (next smaller absolute
+value, towards zero).
+
+### Half Up
+
+Values exactly on the 0.5 (half) mark are rounded up (next larger absolute
+value, away from zero).
+
+### Down
+
+All values are rounded towards the next smaller absolute value (rounded towards
+zero, or RZ).
+
+Also known as: truncation, because the insignificant decimal places are simply
+removed.
+
+### Up
+
+All values are rounded towards the next greater absolute value (away from zero).
+
+### Half Ceiling
+
+Values exactly on the 0.5 (half) mark are rounded toward positive infinity (+∞).
+
+This is the default rounding mode in ECMAScript. In CSS, it is known as "nearest".
+
+### Half Floor
+
+Values exactly on the 0.5 (half) mark are rounded towards negative infinity (-∞).
+
+### Ceiling
+
+All values are rounded towards positive infinity (+∞). Also known as RI for
+Rounds to Infinity.
+
+### Floor
+
+All values are rounded towards negative infinity (-∞). Also known as RMI for
+Rounds to Minus Infinity.
+
+### Unnecessary
+
+The mode "Unnecessary" doesn't perform any rounding, but instead returns an
+error if the value cannot be represented exactly without rounding.
+
+## **Other References/Comparison**
+
+*   Decimal Context docs (used by ICU4C to implement rounding):
+    <http://speleotrove.com/decimal/decifaq1.html#rounding>
+*   Java 7 docs:
+    <http://docs.oracle.com/javase/7/docs/api/java/math/RoundingMode.html>
+*   IEEE 754 rounding rules:
+    <http://en.wikipedia.org/wiki/IEEE_754-2008#Rounding_rules>
+*   Wikipedia article on Rounding:
+    <http://en.wikipedia.org/wiki/Rounding#Tie-breaking>
+*   Live rounding mode chart: [Rounding Mode
+    Chart](https://htmlpreview.github.io/?https://github.com/unicode-org/icu-demos/blob/main/roundmode/round.html)
+    and [Source
+    Code](https://github.com/unicode-org/icu-demos/tree/main/roundmode)

docs/userguide/format_parse/numbers/skeletons.md

@@ -0,0 +1,385 @@
+---
+layout: default
+title: Number Skeletons
+nav_order: 3
+grand_parent: Formatting
+parent: Formatting Numbers
+---
+<!--
+© 2019 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Number Skeletons
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+Number skeletons are a locale-agnostic way to configure a `NumberFormatter` in
+ICU. Number skeletons work in `MessageFormat`.
+
+Number skeletons consist of case-sensitive tokens that correspond to settings
+in ICU `NumberFormatter`. For example, to format a currency in compact notation
+with the sign always shown, you could use this skeleton:
+
+    sign-always compact-short currency/GBP
+
+***Since ICU 67***, you can also use more concise syntax:
+
+    +! K currency/GBP
+
+To use a skeleton in `MessageFormat`, use the "number" type and prefix the
+skeleton with `::`
+
+    {0, number, :: +! K currency/GBP}
+
+The ICU `toSkeleton()` API outputs the long-form skeletons, but all parts of
+ICU that read user-specified number skeletons accept both long-form and
+concise skeletons.
+
+## Syntax
+
+A token consists of a *stem* and zero or more *options*.  The stem is what
+occurs before the first `"/"` character in a token, and the options are each of
+the subsequent `"/"`-delimited strings.  For example, `"compact-short"` and
+"currency" are stems, and `"GBP"` is an option.
+
+Tokens are space-separated, with exceptions for concise skeletons listed at
+the end of this document.
+
+Stems might also be dynamic strings (not a fixed list); these are called
+*blueprint stems*.  For example, to format a number with 2-3 significant
+digits, you could use the following stem:
+
+    @@#
+
+A few examples of number skeletons are shown below. The list of available
+stems and options can be found below in [Skeleton Stems and
+Options](#skeleton-stems-and-options).
+
+## Examples
+
+| Long Skeleton | Concise Skeleton | Input | en-US Output | Comments |
+|---|---|---|---|---|
+| `percent` | `%` | 25 | 25% |
+| `.00` | `.00` | 25 | 25.00 | Equivalent to `Precision::fixedFraction(2)` |
+| `percent .00` | `% .00` | 25 | 25.00% |
+| `scale/100` | `scale/100` | 0.3 | 30 | Multiply by 100 before formatting |
+| `percent scale/100` | `%x100` | 0.3 | 30% |
+| `measure-unit/length-meter` | `unit/meter` | 5 | 5 m | `UnitWidth` defaults to `Short` |
+| `measure-unit/length-meter` <br/> `unit-width-full-name` | `unit/meter` <br/> `unit-width-full-name` | 5 | 5 meters |
+| `currency/CAD` | `currency/CAD` | 10 | CA$10.00 |
+| `currency/CAD` <br/> `unit-width-narrow` | `currency/CAD` <br/> `unit-width-narrow` | 10 | $10.00 | Use the narrow symbol variant |
+| `compact-short` | `K` | 5000 | 5K |
+| `compact-long` | `KK` | 5000 | 5 thousand |
+| `compact-short` <br/> `currency/CAD` | `K currency/CAD` | 5000 | CA$5K |
+| - | - | 5000 | 5,000 |
+| `group-min2` | `,?` | 5000 | 5000 | Require 2 digits in group for separator |
+| `group-min2` | `,?` | 15000 | 15,000 |
+| `sign-always` | `+!` | 60 | +60 | Show sign on all numbers |
+| `sign-always` | `+!` | 0 | +0 |
+| `sign-except-zero` | `+?` | 60 | +60 | Show sign on all numbers except 0 |
+| `sign-except-zero` | `+?` | 0 | 0 |
+| `sign-accounting` <br/> `currency/CAD` | `() currency/CAD` | -40 | (CA$40.00) |
+
+## Skeleton Stems and Options
+
+The full set of features supported by number skeletons is listed by category below.
+
+### Notation
+
+Use one of the following stems to select compact or simple notation:
+
+- `compact-short` or `K` (concise)
+- `compact-long` or `KK` (concise)
+- `notation-simple` (or omit since this is default)
+
+There are two ways to select scientific or engineering notation: using long-form syntax or concise syntax.
+
+#### Scientific and Engineering Notation: Long Form
+
+Start with the stem `scientific` or `engineering`.  Those stems take the following optional options:
+
+- `/sign-xxx` sets the sign display option for the exponent; see [Sign](#sign).
+- `/*ee` sets exponent digits to "at least 2"; use `/*eee` for at least 3 digits, etc.
+    - ***Prior to ICU 67***, use `/+ee` instead of `/*ee`.
+
+For example, all the following skeletons are valid:
+
+- `scientific`
+- `scientific/sign-always`
+- `scientific/*ee`
+- `scientific/*ee/sign-always`
+
+#### Scientific and Engineering Notation: Concise Form
+
+The following are examples of concise form:
+
+| Concise Skeleton | Equivalent Long-Form Skeleton |
+|---|---|
+| `E0` | `scientific` |
+| `E00` | `scientific/*ee` |
+| `EE+!0` | `engineering/sign-always` |
+| `E+?00` | `scientific/sign-except-zero/+ee` |
+
+More precisely:
+
+1. Start with `E` for scientific or `EE` for engineering.
+2. Allow either `+!` or `+?` as a concise sign display option.
+3. Expect one or more `0`s.  If more than one, set minimum integer digits.
+
+### Unit
+
+The supported types of units are percent, currency, and measurement units.
+The following skeleton tokens are accepted:
+
+- `percent` or `%` (concise)
+- Special: `%x100` to scale the number by 100 and then format with percent
+- `permille`
+- `base-unit`
+- `currency/XXX`
+- `measure-unit/aaaa-bbbb` or `unit/bbb` (concise)
+
+The `percent`, `permille`, and `base-unit` stems do not take any options.
+
+The `currency` stem takes one required option: the three-letter ISO code of
+the currency to be formatted.
+
+The `measure-unit` stem takes one required option: the unit identifier of the
+unit to be formatted.  The full unit identifier is required: both the type and
+the subtype (for example, `length-meter`).
+
+The `unit` stem is an alternative to `measure-unit` that accepts a core unit
+identifier with the subtype but not the type (for example, `meter` instead of
+`length-meter`).  It also supports variations allowed by UTS 35, including the per unit with the `-per-` infix (for example, `unit/furlong-per-second`).
+
+### Per Unit
+
+To specify a unit to put in the denominator, use the following skeleton token.
+As with the `measure-unit` stem, pass the unit identifier as the option:
+
+- `per-measure-unit/aaaa-bbbb`
+
+Note that if the `unit` stem is used, the denominator can be placed in the same
+token as the numerator.
+
+### Unit Width
+
+The unit width can be specified by the following stems:
+
+- `unit-width-narrow`
+- `unit-width-short`
+- `unit-width-full-name`
+- `unit-width-iso-code`
+- `unit-width-hidden`
+
+For more details, see
+[`UNumberUnitWidth`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/unumberformatter_8h.html).
+
+### Precision
+
+The precision category has more blueprint stems than most other categories;
+they are documented in detail below. The following non-blueprint stems are
+accepted:
+
+- `precision-integer` (round to the nearest integer) --- accepts fraction-precision options
+- `precision-unlimited` (do not perform rounding; display all digits)
+- `precision-increment/dddd` (round to *`dddd`*, a decimal number) --- see below
+- `precision-currency-standard`
+- `precision-currency-cash`
+
+To round to the nearest nickel, for example, use the skeleton
+`precision-increment/0.05`.  For more information on the decimal number
+syntax, see [Scale](#scale).
+
+#### Fraction Precision
+
+The following are examples of fraction-precision stems:
+
+| Stem | Explanation | Equivalent C++ Code |
+|---|---|---|
+| `.00` | Exactly 2 fraction digits | `Precision::fixedFraction(2) ` |
+| `.00*` | At least 2 fraction digits | `Precision::minFraction(2)` |
+| `.##` | At most 2 fraction digits | `Precision::maxFraction(2) ` |
+| `.0#` | Between 1 and 2 fraction digits | `Precision::minMaxFraction(1, 2)` |
+
+More precisely, the fraction precision stem starts with `.`, then contains
+zero or more `0` symbols, which implies the minimum fraction digits.  Then it
+contains either a `*`, for unlimited maximum fraction digits, or zero or more
+`#` symbols, which implies the minimum fraction digits when added to the `0`
+symbols.
+
+Note that the stem `.` is considered valid and is equivalent to `precision-integer`.
+
+Fraction-precision stems accept a single optional option: a number of significant digits.
+The options here correspond to the API functions on `FractionPrecision`. Some options
+require specifying `r` or `s` for relaxed mode or strict mode. For more information, see
+the API docs for UNumberRoundingPriority.
+
+| Skeleton | Explanation | Equivalent C++ Code |
+|---|---|---|
+| `.##/@@@*` | At most 2 fraction digits, but guarantee <br/> at least 3 significant digits | `Precision::maxFraction(2)` <br/> `.withMinDigits(3)` |
+| `.##/@##r` | Same as above | `Precision::maxFraction(2)` <br/> `.withSignificantDigits(1, 3, RELAXED)` |
+| `.##/@@@r` | Same as above, but pad trailing zeros <br/> to at least 3 significant digits | `Precision::maxFraction(2)` <br/> `.withSignificantDigits(3, 3, RELAXED)` |
+| `.00/@##` | Exactly 2 fraction digits, but do not <br/> display more than 3 significant digits | `Precision::fixedFraction(2)` <br/> `.withMaxDigits(3)` |
+| `.00/@##s` | Same as above | `Precision::fixedFraction(2)` <br/> `.withSignificantDigits(1, 3, STRICT)` |
+| `.00/@##s` | Same as above, but pad trailing zeros <br/> to at least 3 significant digits | `Precision::fixedFraction(2)` <br/> `.withSignificantDigits(3, 3, STRICT)` |
+
+Precisely, the option follows the syntax of the significant digits stem (see below),
+but one of the following must be true:
+
+- Option has one or more `@`s followed by the wildcard character (`withMinDigits`)
+- Option has exactly one `@` followed by zero or more `#`s (`withMaxDigits`)
+- Option has one or more `@`s followed by zero or more `#`s and ends in `s` or `r` (`withSignificantDigits`)
+
+#### Significant Digits Precision
+
+The following are examples of stems for significant figures:
+
+| Stem | Explanation | Equivalent C++ Code|
+|---|---|---|
+| `@@@` | Exactly 3 significant digits | `Precision::fixedSignificantDigits(3)` |
+| `@@@*` | At least 3 significant digits | `Precision::minSignificantDigits(3)` |
+| `@##` | At most 3 significant digits | `Precision::maxSignificantDigits(3)` |
+| `@@#` | Between 2 and 3 significant digits | `...::minMaxSignificantDigits(2, 3)` |
+
+The precise syntax is very similar to fraction precision.  The blueprint stem
+starts with one or more `@` symbols, which implies the minimum significant
+digits.  Then it contains either a `*`, for unlimited maximum significant
+digits, or zero or more `#` symbols, which implies the minimum significant
+digits when added to the `@` symbols.
+
+#### Trailing Zero Display
+
+***Starting with ICU 69***, a new option called `trailingZeroDisplay` was added.
+To enable this in an ICU number skeleton, append `/w` to any precision token:
+
+| Skeleton | Explanation | Equivalent C++ Code |
+|---|---|---|
+| `.00/w` | Exactly 2 fraction digits, but hide <br/> them if they are all 0 | `Precision::fixedFraction(2)` <br/> `.trailingZeroDisplay(` <br/> `UNUM_TRAILING_ZERO_HIDE_IF_WHOLE)` |
+| `precision-curren` <br/> `cy-standard/w` | Currency rounding, but hide <br/> fraction digits if they are all 0 | `Precision::currency(UCURR_USAGE_STANDARD)` <br/> `.trailingZeroDisplay(` <br/> `UNUM_TRAILING_ZERO_HIDE_IF_WHOLE)` |
+
+#### Wildcard Character
+
+***Prior to ICU 67***, the symbol `+` was used for unlimited precision, instead
+of `*` (for example, `.00+`). For backwards compatibility, either `+` or `*` is
+accepted. This applies for both fraction digits and significant digits.
+
+### Rounding Mode
+
+The rounding mode can be specified by the following stems:
+
+- `rounding-mode-ceiling`
+- `rounding-mode-floor`
+- `rounding-mode-down`
+- `rounding-mode-up`
+- `rounding-mode-half-even`
+- `rounding-mode-half-down`
+- `rounding-mode-half-up`
+- `rounding-mode-unnecessary`
+
+For more details, see [Rounding Modes](rounding-modes.md).
+
+### Integer Width
+
+The following examples show how to specify integer width (minimum or maximum
+integer digits):
+
+| Long Form | Concise Form | Explanation | Equivalent C++ Code |
+|---|---|---|---|
+| `integer-width/*000` | `000` | At least 3 <br/> integer digits | `IntegerWidth::zeroFillTo(3)` |
+| `integer-width/##0` | - | Between 1 and 3 <br/> integer digits | `IntegerWidth::zeroFillTo(1)` <br/> `.truncateAt(3)`
+| `integer-width/00` | - | Exactly 2 <br/> integer digits | `IntegerWidth::zeroFillTo(2)` <br/> `.truncateAt(2)` |
+| `integer-width/*` | - | Zero or more <br/> integer digits | `IntegerWidth::zeroFillTo(0) `
+| `integer-width-trunc` | - | Zero integer digits | `IntegerWidth::zeroFillTo(0)` <br/> `.truncateAt(0)`
+
+The long-form option starts with either a single `*` symbol, signaling no limit
+on the number of integer digits (no *`truncateAt`*), or zero or more `#` symbols.
+It should then be followed by zero or more `0` symbols, indicating the minimum
+integer digits (the argument to *`zeroFillTo`*).  If there is no `*` symbol, the
+maximum integer digits (the argument to *`truncateAt`*) is the number of `#`
+symbols plus the number of `0` symbols.
+
+The concise skeleton is simply one or more `0` characters. This supports
+minimum integer digits but not maximum integer digits.
+
+The special stem `integer-width-trunc` covers the case when both *`truncateAt`* and *`zeroFillTo`* are zero.
+
+***Prior to ICU 67***, use the symbol `+` instead of `*`.
+
+### Scale
+
+To specify the scale, use the following stem and option:
+
+- `scale/dddd`
+
+where *`dddd`* is a decimal number. For example, the following are valid skeletons:
+
+- `scale/100` (multiply by 100)
+- `scale/1E2` (same as above)
+- `scale/0.5` (multiply by 0.5)
+
+The decimal number should conform to a standard decimal number syntax. In
+C++, it is parsed using the decimal number library described in
+[LocalizedNumberFormatter::formatDecimal](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/classicu_1_1number_1_1LocalizedNumberFormatter.html).
+In Java, it is parsed using
+[BigDecimal](https://docs.oracle.com/javase/7/docs/api/java/math/BigDecimal.html#BigDecimal%28java.lang.String%29).
+For maximum compatibility, it is highly recommended that your decimal number
+is able to be parsed by both engines.
+
+### Grouping
+
+The grouping strategy can be specified by the following stems:
+
+- `group-off` or `,_` (concise)
+- `group-min2` or `,?` (concise)
+- `group-auto` (or omit since this is the default)
+- `group-on-aligned` or `,!` (concise)
+- `group-thousands` (no concise equivalent)
+
+For more details, see
+[`UNumberGroupingStrategy`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/unumberformatter_8h.html).
+
+### Symbols
+
+The following stems are allowed for specifying the number symbols:
+
+- `latin` (use Latin-script digits)
+- `numbering-system/nnnn` (use the `nnnn` numbering system)
+
+A custom `NDecimalFormatSymbols` instance is not supported at this time.
+
+### Sign Display
+
+The following stems specify sign display:
+
+- `sign-auto` (or omit since this is the default)
+- `sign-always` or `+!` (concise)
+- `sign-never` or `+_` (concise)
+- `sign-accounting` or `()` (concise)
+- `sign-accounting-always` or `()!` (concise)
+- `sign-except-zero` or `+?` (concise)
+- `sign-accounting-except-zero` or `()?` (concise)
+- `sign-negative` or `+-` (concise)
+- `sign-accounting-negative` or `()-` (concise)
+
+For more details, see
+[`UNumberSignDisplay`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/unumberformatter_8h.html).
+
+### Decimal Separator Display
+
+The following stems specify decimal separator display:
+
+- `decimal-auto`
+- `decimal-always`
+
+For more details, see
+[`UNumberDecimalSeparatorDisplay`](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/unumberformatter_8h.html).

docs/userguide/icu/design.md

@@ -0,0 +1,970 @@
+---
+layout: default
+title: ICU Design
+nav_order: 5
+parent: ICU
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# ICU Architectural Design
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+# Overview
+
+This chapter discusses the ICU design structure, the ICU versioning support, and
+the introduction of namespace in C++.
+
+## Java and ICU Basic Design Structure
+
+The JDK internationalization components and ICU components both share the same
+common basic architectures with regard to the following:
+
+1. [Locales](#locales)
+2. [Data-driven services](#data-driven-services)
+3. [ICU threading models and the open and close model](#icu-threading-model-and-open-and-close-model)
+4. [Cloning customization](#cloning-customization)
+5. [Error handling](#error-handling)
+6. [Extensibility](#extensibility)
+7. [Resource bundle inheritance model](#resource-bundle-inheritance-model)
+
+There are design features in ICU4C that are not in the Java Development Kit
+(JDK) due
+to programming language restrictions. These features include the following:
+
+### Locales
+
+Locale IDs are composed of language, country, and variant information. The
+following links provide additional useful information regarding ISO standards:
+[ISO-639](http://lcweb.loc.gov/standards/iso639-2/englangn.html), and an ISO
+Country Code,
+[ISO-3166](http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html).
+For example, Italian, Italy, and Euro are designated as: it_IT_EURO.
+
+### Data-driven Services
+
+Data-driven services often use resource bundles for locale data. These services
+map a key to data. The resources are designed not only to manage system locale
+information but also to manage application-specific or general services data.
+ICU supports string, numeric, and binary data types and can be structured into
+nested arrays and tables.
+
+This results in the following:
+
+1. Data used by the services can be built at compile time or run time.
+2. For efficient loading, system data is pre-compiled to .dll files or files
+   that can be mapped into memory.
+3. Data for services can be added and modified without source code changes.
+
+### ICU Threading Model and Open and Close Model
+
+The "open and close" model supports multi-threading. It enables ICU users to use
+the same kind of service for different locales, either in the same thread or in
+different threads.
+
+For example, a thread can open many collators for different languages, and
+different threads can use different collators for the same locale
+simultaneously. Constant data can be shared so that only the current state is
+allocated for each editor.
+
+The ICU threading model is designed to avoid contention for resources, and
+enable you to use the services for multiple locales simultaneously within the
+same thread. The ICU threading model, like the rest of the ICU architecture, is
+the same model used for the international services in Java™.
+
+When you use a service such as collation, the client opens the service using an
+ID, typically a locale. This service allocates a small chunk of memory used for
+the state of the service, with pointers to shared, read-only data in support of
+that service. (In Java, you call `getInstance()` to create an object; in C++,
+`createInstance()`. ICU uses the open and close metaphor in C because it is more
+familiar to C programmers.)
+
+If no locale is supplied when a service is opened, ICU uses the default locale.
+Once a service is open, changing the default locale has no effect. Thus, there
+can not be any thread synchronization between the default locales and open
+services.
+
+When you open a second service for the same locale, another small chunk of
+memory is used for the state of the service, with pointers to the same shared,
+read-only data. Thus, the majority of the memory usage is shared. When any
+service is closed, then the chunk of memory is deallocated. Other connections
+that point to the same shared data stay valid.
+
+Any number of services, for the same locale or different locales, can be open
+within the same thread or in different threads.
+
+#### Thread-safe const APIs
+
+In recent ICU releases, we have worked to make any service object *thread-safe*
+(usable concurrently) *as long as all of the threads are using only const APIs*:
+APIs that are declared const in C++, take a const this-like service pointer in
+C, or are "logically const" in Java. This is an enhancement over the original
+Java/ICU threading model. (Originally, concurrent use of even only const APIs
+was not thread-safe.)
+
+However, you cannot use a reference to an open service object in two threads at
+the same time *if either of them calls any non-const API*. An individual open
+service object is not thread-safe for concurrent "writes". Rather, for non-const
+use, you must use the clone function to create a copy of the service you want
+and then pass this copy to the second thread. This procedure allows you to use
+the same service in different threads, but avoids any thread synchronization or
+deadlock problems.
+
+#### Freezable
+
+Some classes also implement the `Freezable` interface (or similar pattern in
+C++), for example `UnicodeSet` or `Collator`: An object that typically starts
+out mutable can be set up and then "frozen", which makes it immutable and thus
+usable concurrently because all non-const APIs are disabled. A frozen object can
+never be "thawed". For example, a `Collator` can be created, various attributes
+set, then frozen and then used from many threads for comparing strings and
+getting sort keys.
+
+#### Clone vs. open
+
+Clone operations are designed to be much faster than reopening the service with
+initial parameters and copying the source's state. (With objects in C++ and
+Java, the clone function is also much safer than trying to recreate a service,
+since you get the proper subclass.) Once a service is cloned, changes will not
+affect the original source service, or vice-versa.
+
+Thus, the normal mode of operation is to:
+
+1. Open a service with a given locale.
+2. Use the service as long as needed. However, do not keep opening and closing
+   a service within a tight loop.
+3. Clone a service if it needs to be used in parallel in another thread.
+4. Close any clones that you open as well as any instances of the services that
+   are owned.
+
+> :point_right: **Note**: These service instances may be closed in any sequence.
+The preceding steps are given as an example.
+
+### Cloning Customization
+
+Typically, the services supplied with ICU cover the vast majority of usages.
+However, there are circumstances where the service needs to be customized for a
+new locale. ICU (and Java) enable you to create customized services. For
+example, you can create a `RuleBasedCollator` by merging the rules for French and
+Arabic to get a custom French-Arabic collation sequence. By merging these rules,
+the pointer does not point to a read-only table that is shared between threads.
+Instead, the pointer refers to a table that is specific to your particular open
+service. If you clone the open service, the table is copied. When you close the
+service, the table is destroyed.
+
+For some services, ICU supplies registration. You can register a customized open
+service under an ID; keeping a copy of that service even after you close the
+original. A client in that thread or in other threads can recreate a copy of the
+service by opening with that ID.
+
+ICU may cache service instances. Therefore, registration should be done during
+startup, before opening services by locale ID.
+
+These registrations are not persistent; once your program finishes, ICU flushes
+all the registrations. While you still might have multiple copies of data
+tables, it is faster to create a service from a registered ID than it is to
+create a service from rules.
+
+> :point_right: **Note**: To work around the lack of persistent registration,
+query the service for the parameters used to create it and then store those
+parameters in a file on a disk.
+
+For services whose IDs are locales, such as collation, the registered IDs must
+also be locales. For those services (like Transliteration or Timezones) that are
+cross-locale, the IDs can be any string.
+
+Prospective future enhancements for this model are:
+
+1. Having custom services share data tables, by making those tables reference
+   counted. This will reduce memory consumption and speed clone operations (a
+   performance enhancement chiefly useful for multiple threads using the same
+   customized service).
+2. Expanding registration for all the international services.
+3. Allowing persistent registration of services.
+
+#### Per-client Locale ID vs Per-thread Locale ID
+
+Some application environments operate by setting a per thread (or per process)
+locale ID, and then not passing the locale ID as a parameter during processing.
+If this usage model were used with ICU in a multi-threaded server, it might
+result in ICU being requested to constantly open, use, and then close service
+objects. Instead, it is recommended that locale IDs be associated with each
+client be stored with other per-client data, along with any service objects
+(such as collators or formatters) that client might use. If operations involving
+a single client are short-lived, it might be more efficient to keep a pool of
+service objects, organized according to locale. Then, if a particular locale's
+formatter is in high demand, that formatter can be used, and then returned to
+the pool.
+
+### ICU Memory Usage
+
+ICU4C APIs are designed to allow separate heaps for its libraries vs. the
+application. This is achieved by providing functions to allocate and release
+objects owned by ICU4C using only ICU4C library functions. For more details see
+the Memory Usage section in the [Coding Guidelines](dev/codingguidelines.md#memory-usage).
+
+### ICU4C Initialization and Termination
+
+The ICU library does not normally require any explicit initialization prior to
+use. An application begins use simply by calling any ICU API in the usual way.
+There are, however, a few functions affecting ICU's configuration, that, if used,
+must be called first, before other use of ICU in a process. These are outlined below.
+
+1. `u_setMemoryFunctions()`. This function replaces the standard library heap
+allocation functions used by ICU with alternate versions, provided by the
+application. If it is needed, `u_setMemoryFunctions()` must be called first, before
+any other use of ICU. This functionality is not commonly used.
+
+2. ICU Data Locating Functions, `u_setCommonData()`, `u_setDataDirectory()`, and
+`u_setAppData()`. One or more of these functions will be required when ICU is
+configured to load its data directly from files rather than taking it from the
+default data DLL, and the files are not in the default location. Again, this is
+not common. See [ICU Data](icudata#icu-data-directory).
+
+3. Sanity check that ICU is functioning and able to access data. This is
+important because configuration or installation problems that leave ICU unable
+to load its data do occur, and the resulting failures can be confusing.
+Since not all ICU APIs have UErrorCode parameters, in the absence of data they
+may sometimes silently return incorrect results.
+
+   The function `ulocdata_getCLDRVersion()` is suitable; it is small and light
+weight, requires data, and reports the error in the absence of data.
+
+
+When an application is terminating it should call the function `u_cleanup()`,
+which frees all heap storage and other system resources that are held internally
+by the ICU library. While the use of `u_cleanup()` is not strictly required,
+failure to call it will cause memory leak checking tools to report problems for
+resources being held by ICU library.
+
+Before calling `u_cleanup()`, all ICU objects that were created by the
+application must be deleted, and all ICU services (plain C APIs) must be closed.
+
+For some platforms the configure option `--enable-auto-cleanup`, or defining
+the option `UCLN_NO_AUTO_CLEANUP` to 0, will add code which automatically cleans
+up ICU when its shared library is unloaded. See comments in `ucln_imp.h`
+
+#### C++ Static Initialization and Destruction
+
+The ICU library itself does not rely on C++ static initializers, meaning that
+applications will not encounter order-of-initialization problems from the use of
+ICU.
+
+There are, however, some significant limitations for applications that make use
+of ICU at C++ static initialization time:
+
+1.  `u_setMemoryFunctions()` and the data locating functions, if needed, must
+still be called before any other use of ICU. Which includes any use during the
+construction of static objects.
+
+2.  `u_cleanup()` can only be called after all other ICU-using objects have been
+deleted. Finding a suitable time and place for the call to `u_cleanup()` may be
+difficult, however. Refer to the C++ literature on the order of static
+initialization and destruction.
+
+3.  Destruction of static objects that are scoped to a code block. These, by the
+conventions of C++, are lazily initialized when the code block is first entered,
+so there are no issues during static initialization. But object destruction
+happens when the program terminates, leaving the problem of where to call
+`u_cleanup()`, as discussed above.
+
+#### Dynamically Loading and Unloading ICU
+
+Applications may arrange to dynamically load the ICU library when it is needed,
+and unload it when through, repeating the process as required. The specific
+details for loading and unloading, and accessing such libraries, are operating
+system dependent.
+
+For ICU to be used in this way, before unloading, all ICU objects and services
+must be closed or deleted, and `u_cleanup()` must be called.
+
+On Windows, the loading and unloading of ICU should never be done inside
+[DllMain](https://docs.microsoft.com/en-us/windows/win32/dlls/dllmain). Loading
+one of the ICU libraries can cause other libraries or files to be loaded,
+leading to potential dead-lock.
+
+#### Initializing ICU in Multithreaded Environments
+
+There is one specialized case where extra care is needed to safely initialize
+ICU. This situation will arise only when ALL of the following conditions occur:
+
+1. The application main program is written in plain C, not C++.
+2. The application is multithreaded, with the first use of ICU within the
+   process possibly occurring simultaneously in more than one thread.
+3. The application will be run on a platform that does not handle C++ static
+   constructors from libraries when the main program is not in C++. Platforms
+   known to exhibit this behavior are Mac OS X and HP/UX. Platforms that handle
+   C++ libraries correctly include Windows, Linux and Solaris.
+
+To safely initialize the ICU library when all of the above conditions apply, the
+application must explicitly arrange for a first-use of ICU from a single thread
+before the multi-threaded use of ICU begins. A convenient ICU operation for this
+purpose is `uloc_getDefault()`, declared in the header file `unicode/uloc.h`.
+
+> :point_right: **Note**: The status of this situation needs further
+investigation. See issue
+[ICU-21380](https://unicode-org.atlassian.net/browse/ICU-21380)
+
+
+### Error Handling
+
+In order for ICU to maximize portability, this version includes only the subset
+of the C++ language that compile correctly on older C++ compilers and provide a
+usable C interface. Thus, there is no use of the C++ exception mechanism in the
+code or Application Programming Interface (API).
+
+To communicate errors reliably and support multi-threading, this version uses an
+error code parameter mechanism. Every function that can fail takes an error-code
+parameter by reference. This parameter is always the last parameter listed for
+the function.
+
+The `UErrorCode` parameter is defined as an enumerated type. Zero represents no
+error, positive values represent errors, and negative values represent non-error
+status codes. Macros (`U_SUCCESS` and `U_FAILURE`) are provided to check the
+error code.
+
+The `UErrorCode` parameter is an input-output function. Every function tests the
+error code before performing any other task and immediately exits if it produces
+a FAILURE error code. If the function fails later on, it sets the error code
+appropriately and exits without performing any other work, except for any
+cleanup it needs to do. If the function encounters a non-error condition that it
+wants to signal, such as "encountered an unmapped character" in conversion, the
+function sets the error code appropriately and continues. Otherwise, the
+function leaves the error code unchanged.
+
+Generally, only the functions that do not take a `UErrorCode` parameter, but
+call functions that do, must declare a variable. Almost all functions that take
+a `UErrorCode` parameter, and also call other functions that do, merely have to
+propagate the error code that they were passed to the functions they call.
+Functions that declare a new `UErrorCode` parameter must initialize it to
+`U_ZERO_ERROR` before calling any other functions.
+
+ICU enables you to call several functions (that take error codes) successively
+without having to check the error code after each function. Each function
+usually must check the error code before doing any other processing, since it is
+supposed to stop immediately after receiving an error code. Propagating the
+error-code parameter down the call chain saves the programmer from having to
+declare the parameter in every instance and also mimics the C++ exception
+protocol more closely.
+
+### Extensibility
+
+There are 3 major extensibility elements in ICU:
+
+1. **Data Extensibility**:
+   The user installs new locales or conversion data to enhance the existing ICU
+   support. For more details, refer to the package tool (:construction: **TODO**: need link)
+   chapter for more information.
+2. **Code Extensibility**:
+   The classes, data, and design are fully extensible. Examples of this
+   extensibility include the BreakIterator , RuleBasedBreakIterator and
+   DictionaryBasedBreakIterator classes.
+3. **Error Handling Extensibility**:
+   There are mechanisms available to enhance the built-in error handling when
+   it is necessary. For example, you can design and create your own conversion
+   callback functions when an error occurs. Refer to the
+   [Conversion](conversion/index.md) chapter callback section for more
+   information.
+
+### Resource Bundle Inheritance Model
+
+A resource bundle is a set of \<key,value> pairs that provide a mapping from key
+to value. A given program can have different sets of resource bundles; one set
+for error messages, one for menus, and so on. However, the program may be
+organized to combine all of its resource bundles into a single related set.
+
+The set is organized into a tree with "root" at the top, the language at the
+first level, the country at the second level, and additional variants below
+these levels. The set must contain a root that has all keys that can be used by
+the program accessing the resource bundles.
+
+Except for the root, each resource bundle has an immediate parent. For example,
+if there is a resource bundle `X_Y_Z`, then there must be the resource bundles:
+`X_Y`, and `X`. Each child resource bundle can omit any \<key,value> pair that is
+identical to its parent's pair. (Such omission is strongly encouraged as it
+reduces data size and maintenance effort). It must override any \<key,value> pair
+that is different from its parent's pair. If you have a resource bundle for the
+locale ID `language_country_variant`, you must also have
+a bundle for the ID `language_country` and one for the ID `language`.
+
+If a program doesn't find a key in a child resource bundle, it can be assumed
+that it has the same key as the parent. The default locale has no effect on
+this. The particular language used for the root is commonly English, but it
+depends on the developer's preference. Ideally, the language should contain
+values that minimize the need for its children to override it.
+
+The default locale is used only when there is not a resource bundle for a given
+language. For example, there may not be an Italian resource bundle. (This is
+very different than the case where there is an Italian resource bundle that is
+missing a particular key.) When a resource bundle is missing, ICU uses the
+parent unless that parent is the root. The root is an exception because the root
+language may be completely different than its children. In this case, ICU uses a
+modified lookup and the default locale. The following are different lookup
+methods available:
+
+**Lookup chain** : Searching for a resource bundle.
+
+    en_US_<some-variant>
+    en_US
+    en
+    <defaultLang>_<defaultCountry>
+    <defaultLang>
+    root
+
+**Lookup chain** : Searching for a \<key, value> pair after
+`en_US_<some-variant>` has ben loaded. ICU does not use the default locale in
+this case.
+
+    en_US_<some-variant>
+    en_US
+    en
+    root
+
+## Other ICU Design Principles
+
+ICU supports extensive version code and data changes and introduces namespace
+usage.
+
+### Version Numbers in ICU
+
+Version changes show clients when parts of ICU change. ICU; its components (such
+as `Collator`); each resource bundle, including all the locale data resource
+bundles; and individual tagged items within a resource bundle, have their own
+version numbers. Version numbers numerically and lexically increase as changes
+are made.
+
+All version numbers are used in Application Programming Interfaces (APIs) with a
+`UVersionInfo` structure. The `UVersionInfo` structure is an array of four
+unsigned bytes. These bytes are:
+
+1. Major version number
+2. Minor version number
+3. Milli version number
+4. Micro version number
+
+Two `UVersionInfo` structures may be compared using binary comparison (`memcmp`)
+to see which is larger or newer. Version numbers may be different for different
+services. For instance, do not compare the ICU library version number to the ICU
+collator version number.
+
+`UVersionInfo` structures can be converted to and from string representations as
+dotted integers (such as "1.4.5.0") using the `u_versionToString()` and
+`u_versionFromString()` functions. String representations may omit trailing zeros.
+
+The interpretation of version numbers depends on what is being described.
+
+#### ICU Release Version Number (ICU 49 and later)
+
+The first version number field contains the ICU release version number, for
+example 49. Each new version might contain new features, new locale data, and
+modified behavior. (See below for more information on
+[ICU Binary Compatibility](#icu-binary-compatibility)).
+
+The second field is 1 for the initial release (e.g., 49.1). The second and
+sometimes third fields are incremented for binary compatible maintenance
+releases.
+
+* For maintenance releases for only either C or J, the third field is
+  incremented (e.g., ICU4C 49.1.1).
+* For shared updates for C & J, the second field is incremented to 2 and
+  higher (e.g., ICU4C & ICU4J 49.2).
+
+(The second field is 0 during development, with milestone numbers in the third
+field during that time. For example, 49.0.1 for 49 milestone 1.)
+
+#### ICU Release Version Number (ICU 1.4 to ICU 4.8)
+
+In earlier releases, the first two version fields together indicated the ICU
+release, for example 4.8. The third field was 0 for the initial release, and 1
+and higher for binary compatible (bug fixes only) maintenance releases (e.g.,
+4.8.1). The fourth field was used for updates specific to only one of Java, C++,
+or ICU-in-Eclipse.
+
+The second version field was *even* for formal releases ("reference releases")
+(e.g., 1.6 or 4.8) and *odd* during their development (unreleased unstable
+snapshot versions; e.g., 4.7). During development, the third field contained the
+milestone number (e.g., 4.7.1 for 4.8 milestone 1). For very old ICU code, we
+published semi-formal “enhancement” releases with odd second-field numbers
+(e.g., 1.7).
+
+Library filenames and some other internal uses already used a concatenation of
+the first two fields ("48" for 4.8).
+
+#### Resource Bundles and Elements
+
+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. For example,
+
+```text
+en {
+    Version { "1.0.3.5" }
+    ...
+}
+```
+
+A resource bundle may omit the "version" element and thus, will inherit a
+version along the usual chain. For example, if the resource bundle **en_US**
+contained no "version" element, it would inherit "1.0.3.5" from the parent en
+element. If inheritance passes all the way to the root resource bundle and it
+contains no "version" resource, then the resource bundle receives the default
+version number 0.
+
+Elements within a resource bundle may also contain version numbers. For example:
+
+```text
+be {
+    CollationElements {
+        Version { "1.0.0.0" }
+        ...
+    }
+}
+```
+
+In this example, the CollationElements data is version 1.0.0.0. This element
+version is not related to the version of the bundle.
+
+#### Internal version numbers
+
+Internally, data files carry format and other version numbers. These version
+numbers ensure that ICU can use the data file. The interpretation depends
+entirely on the data file type. Often, the major number in the format version
+stays the same for backwards-compatible changes to a data file format. The minor
+format version number is incremented for additions that do not violate the
+backwards compatibility of the data file.
+
+#### Component Version Numbers
+
+ICU component version numbers may be found using:
+
+1. `u_getVersion()` returns the version number of ICU as a whole in C++. In C,
+   `ucol_getVersion()` returns the version number of ICU as a whole.
+2. `ures_getVersion()` and `ResourceBundle::getVersion()` return the version
+   number of a ResourceBundle. This is a data version number for the bundle as a
+   whole and subject to inheritance.
+3. `u_getUnicodeVersion()` and `Unicode::getUnicodeVersion()` return the version
+   number of the Unicode character data that underlies ICU. This version
+   reflects the numbering of the Unicode releases. See
+   <http://www.unicode.org/> for more information.
+4. `Collator::getVersion()` in C++ and `ucol_getVersion()` in C return the version
+   number of the Collator. This is a code version number for the collation code
+   and algorithm. It is a combination of version numbers for the collation
+   implementation, the Unicode Collation Algorithm data (which is the data that
+   is used for characters that are not mentioned in a locale's specific
+   collation elements), and the collation elements.
+
+#### Configuration and Management
+
+A major new feature in ICU 2.0 is the ability to link to different versions of
+ICU with the same program. Using this new feature, a program can keep using ICU
+1.8 collation, for example, while using ICU 2.0 for other services. ICU now can
+also be unloaded if needed, to free up resources, and then reloaded when it is
+needed.
+
+### Namespace in C++
+
+ICU 2.0 introduced the use of a C++ namespace to avoid naming collision between
+ICU exported symbols and other libraries. All the public ICU C++ classes are
+defined in the "icu_VersionNumber::" namespace, which is also aliased as
+namespace "icu". Starting with ICU 2.0, including any public ICU C++ header by
+default includes a "using namespace icu_VersionNumber" statement. This is for
+backward compatibility, and should be turned off in favor of explicitly using
+`icu::UnicodeString` etc. (see [How To Use ICU](howtouseicu.md)). (If entry point
+renaming is turned off, then only the unversioned "icu" namespace is used.)
+
+Starting with ICU 49, ICU4C requires namespace support.
+
+### Library Dependencies (C++)
+
+It is sometimes useful to see a dependency chart between the public ICU APIs and
+ICU libraries. This chart can be useful to people that are new to ICU or to
+people that want only certain ICU libraries.
+
+> :construction: **TODO**: The dependency chart is currently not available.
+
+Here are some things to realize about the chart.
+
+1. It gives a general overview of the ICU library dependencies.
+2. Internal dependencies, like the mutex API, are left out for clarity.
+3. Similar APIs were lumped together for clarity (e.g. Formatting). Some of
+   these dependency details can be viewed from the ICU API reference.
+4. The descriptions of each API can be found in our [ICU API
+   reference](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/)
+
+### Code Dependencies (C++)
+
+Starting with ICU 49, the dependencies of code files (.o files compiled from
+.c/.cpp) are documented in
+[source/test/depstest/dependencies.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/test/depstest/dependencies.txt).
+Adjacent Python code is used to parse this file and to
+[verify](https://icu.unicode.org/processes/release/tasks/healthy-code#TOC-Check-library-dependencies)
+that it matches the actual dependencies of the code files.
+
+The dependency list can be used to build subset libraries. In addition, by
+reducing intra-library dependencies, the code size of statically linked ICU code
+has been reduced.
+
+### ICU API categories
+
+ICU APIs, as defined in header and class files, are either "external" or
+"internal". External APIs are meant to be used by applications, while internal
+APIs should be used only within ICU. APIs are marked to indicate whether they
+are external or internal, as follows. Every external API has a lifecycle label,
+see below.
+
+#### External ICU4C APIs
+
+External ICU4C APIs are
+
+1. declared in header files in unicode folders and exported at build/install
+   time to an `include/unicode` folder
+2. when C++ class members, are `public` or `protected`
+3. do not have an `@internal` label
+
+Exception: Layout engine header files are not in a unicode folder, although the
+public ones are still copied to the `include/unicode` folder at build/install
+time. External layout engine APIs are the ones that have lifecycle labels and
+not an `@internal` label.
+
+#### External ICU4J APIs
+
+External ICU4J APIs are
+
+1. declared in one of the ICU4J core packages (`com.ibm.icu.lang`,
+   `com.ibm.icu.math`, `com.ibm.icu.text`, or `com.ibm.icu.util`).
+2. `public` or `protected` class members
+3. `public` or `protected` contained classes
+4. do not have an `@internal` label
+
+#### "System" APIs
+
+"System" APIs are external APIs that are intended only for special uses for
+system-level code, for example `u_cleanup()`. Normal users should not use them,
+although they are public and supported. System APIs have a `@system` label
+in addition to the lifecycle label that all external APIs have (see below).
+
+#### Internal APIs
+
+All APIs that do not fit any of the descriptions above are internal, which means
+that they are for ICU internal use only and may change at any time without
+notice. Some of them are member functions of public C++ or Java classes, and are
+"technically public but logistically internal" for implementation reasons;
+typically because programming languages don't provide sufficiently access
+control (without clumsy mechanisms). In this case, such APIs have an
+`@internal` label.
+
+### ICU API compatibility
+
+As ICU develops, it adds external APIs - functions, classes, constants, and so
+on. Occasionally it is also necessary to remove or change external APIs. In
+order to make this work, we use the following process:
+
+For all API changes (and for significant/controversial/difficult implementation
+changes), we use proposals to announce and discuss them. A proposal is simply an
+email to the icu-design mailing list that details what is proposed to be
+changed, with an expiration date of typically a week. This gives all mailing
+list members a chance to review upcoming changes, and to discuss them. A
+proposal often changes significantly as a result of discussion. Most proposals
+will eventually find consensus among list members; otherwise, the ICU-TC decides
+what to do. If the addition or change of APIs would affect you, please subscribe
+to the main [icu-design mailing list](https://icu.unicode.org/contacts).
+
+When a **new API** is added to ICU, it **is marked as draft with a `@draft ICU
+x.y` label in the API documentation, **where x.y is the ICU version when the
+API *signature* was introduced or last changed**. A draft API is not guaranteed
+to be stable! Although we will not make gratuitous changes, sometimes the draft
+APIs turns out to be unsatisfactory in actual practice and may need to be
+changed or even removed. Changes of "draft" API are subject to the proposal
+process described above.
+
+**When a `@draft ICU x.y` API is changed, it must remain `@draft` and its version
+number must be updated.**
+
+In ICU4J 3.4.2 and earlier, `@draft` APIs were also marked with Java's `@deprecated`
+tag, so that uses of draft APIs in client code would be flagged by the compiler.
+These uses of the `@deprecated` tag were indicated with the comment “This is a
+draft API and might change in a future release of ICU.” Many clients found this
+confusing and/or undesireable, so ICU4J 3.4.3 no longer marks draft APIs with
+the `@deprecated` tag by default. For clients who prefer the earlier behavior,
+ICU4J provides an ant build target, `restoreDeprecated`, which will update the
+source files to use the `@deprecated` tag. Then clients can just rebuild the ICU4J
+jar as usual.
+
+When an API is judged to be stable and has not been changed for at least one ICU
+release, it is relabeled as stable with a `@stable ICU x.y**` label in the API
+documentation. A stable API is expected to be available in this form for a long
+time. The ICU version **x.y** indicates the last time the API *signature* was
+introduced or changed. **The promotion from `@draft ICU x.y` to `@stable ICU x.y`
+must not change the x.y version number.**
+
+We occasionally make an exception and allow adding new APIs marked as
+`@stable ICU x.y` APIs in the x.y release itself if we believe that they have to
+be stable. We might do this for enum constants that reflect 1:1 Unicode property
+aliases and property value aliases, for a Unicode upgrade in the x.y release.
+
+We sometimes **"broaden" a `@stable`** API function by changing its signature
+in a compatible way. For example, in Java, we might change an input parameter
+from a `String` to a `CharSequence`. In this case we keep the `@stable` but
+update the ICU version number indicating the function signature change.
+
+Even a stable API may eventually need to become deprecated or obsolete. Such
+APIs are strongly discouraged from use. Typically, an improved API is introduced
+at the time of deprecation/obsolescence of the old one.
+
+1. Use of deprecated APIs is strongly discouraged, but they are retained for
+   backward compatibility. These are marked with labels like
+   `@deprecated ICU x.y Use u_abc() instead.`. **The ICU version x.y shows the
+   ICU release in which the API was first declared "deprecated".**
+2. In ICU4J, starting with release 57, a custom Javadoc tag `@discouraged`
+   was added. While similar to `@deprecated` it is used when either ICU wants
+   to discourage a particular API from use but the JDK hasn't deprecated it or
+   ICU needs to keep it for compatibility reasons. These are marked with labels
+   like `@discouraged ICU x.y. Use u_abc() instead.`.
+3. Obsolete APIs are are those whose continued retention will cause severe
+   conflicts or user error, or whose continued support would be a very
+   significant maintenance burden. We make every effort to keep these to a
+   minimum. Obsolete APIs are marked with labels like `@obsolete ICU x.y. Use
+   u_abc() instead since this API will be removed in that release.`.
+   **The x.y indicates that we plan to remove it in ICU version x.y.**
+
+Stable C or Java APIs will not be obsoleted because doing so would break
+forward binary compatibility of the ICU library. Stable APIs may be
+deprecated, but they will be retained in the library.
+
+An "obsolete" API will remain unchanged until it is removed in the indicated
+ICU release, which will be usually one year after the API was declared
+obsolete. Sometimes we still keep it available for some time via a
+compile-time switch but stop maintaining it. In rare occasions, an API must
+be replaced right away because of naming conflicts or severe defects; in
+such cases we provide compile-time switches (`#ifdef` or other mechanisms) to
+select the old API.
+
+For example, here is how an API might be tagged in various versions:
+
+* **In ICU 0.2**: The API is newly introduced as a draft in this release.
+
+  ```text
+  @draft ICU 0.2
+  f(x)
+  ```
+
+* **In ICU 0.4**: The draft version number is updated, because the signature
+  changed.
+
+  ```text
+  @draft ICU 0.4
+  f(x, y)
+  ```
+
+* **In ICU 0.6**: The API is promoted from draft to stable, but the version
+  number does not change, as the signature is the same.
+
+  ```text
+  @stable ICU 0.4
+  f(x, y)
+  ```
+
+* **In ICU 1.0**: The API is "broadened" in a compatible way. For example,
+  changing an input parameter from char to int or from some class to a base
+  class. The signature is changed (so we update the ICU version number), but old
+  calling code continues to work unchanged (so we retain @stable if that's what
+  it was.)
+
+  ```text
+  @stable ICU 1.0
+  f(xbase, y)
+  ```
+
+* **In ICU 1.2**: The API is demoted to deprecated (or obsolete) status.
+
+  ```text
+  @deprecated ICU 1.2 Use g(x,y,z) instead.
+  f(xbase, y)
+  ```
+
+  or, when this API is planned to be removed in ICU 1.4:
+
+  ```text
+  @obsolete ICU 1.4. Use g(x,y,z) instead.
+  f(xbase, y)
+  ```
+
+### ICU Binary Compatibility
+
+*Using ICU as an Operating System Level Library*
+
+ICU4C may be configured for use as a system library in an environment where
+applications that are built with one version of ICU must continue to run without
+change with later versions of the ICU shared library.
+
+Here are the requirements for enabling binary compatibility for ICU4C:
+
+1. Applications must use only APIs that are marked as stable.
+2. Applications must use only plain C APIs, never C++.
+3. ICU must be built with function renaming disabled.
+4. Applications must be built using an ICU that was configured for binary
+   compatibility.
+5. Use ICU version 3.0 or later.
+6. Provide both “common” and “i18n” libraries, or build a combined library.
+
+**Stable APIs Only.** APIs in the ICU library that are tagged as being stable
+will be maintained in future versions of the library. Stable functions will
+continue to exist with the same signature and the same meaning, allowing
+applications to continue to work without change.
+
+Stable APIs do not guarantee that the results from every function will always be
+completely identical between ICU versions (see the
+[Version Numbers in ICU](#version-numbers-in-icu) section above). Bugs may be
+fixed. The Unicode character data may change with new versions of the Unicode
+standard. Locale data may be updated or changed, yielding different results for
+operations like formatting or collation. Applications that require exact
+bit-for-bit, bug-for-bug compatibility of ICU results should not rely on ICU
+release-to-release binary compatibility, but should instead link against a
+specific version of ICU.
+
+To verify that an application uses only stable APIs, build it with the C
+preprocessor symbols `U_HIDE_DRAFT_API` and `U_HIDE_DEPRECATED_API` defined. This
+will produce build errors if any draft, deprecated or obsolete APIs are used. An
+operating system level installation of ICU may set this option permanently.
+
+**C APIs only.** Only plain C APIs remain compatible across ICU releases. The
+reason C++ binary compatibility is not supported is primarily because the design
+of C++ language and runtime environments present extreme technical difficulties
+to doing so. Stable C++ APIs are *source* compatible, but applications using
+them must be recompiled when moving between ICU releases.
+
+**Function renaming disabled.** Function renaming is an ICU feature that allows
+an application to explicitly link against a specific version of the ICU library,
+and to continue to use that version even when other ICU versions exist in the
+runtime environment. This is the exact opposite of release-to-release binary
+compatibility – instead of being able to transparently change ICU versions, an
+application is explicitly tied to one specific version.
+
+Function renaming is enabled by default, and must be disabled at ICU build time
+to enable release to release binary compatibility. To disable renaming, use the
+configure option
+
+```shell
+configure -–disable-renaming [other configure options]
+```
+
+(Configure options may also be passed to the runConfigureICU script.)
+
+To enable release-to-release binary compatibility, ICU must be built with
+`--disable-renaming`, *and* applications must be built using the headers and
+libraries that resulted from the `–-disable-renaming` ICU build
+
+**ICU Version 3.0 or Later.** Binary compatibility of ICU releases is supported
+beginning with ICU version 3.0. Older versions of ICU (2.8 and earlier) do not
+provide for binary compatibility between versions.
+
+**Provide both “common” and “i18n” libraries, or build a combined library.**
+It is rare but possible that services/APIs move from one library to another.
+For example, many years ago we moved the BreakIterator APIs from i18n to common,
+so that word titlecasing functions no longer needed separate code to find
+titlecasing or word break opportunities.
+
+More recently, the ListFormatter moved from the common library to i18n
+when its features grew beyond primitive patterns to also support
+FieldPosition and FormattedValue features.
+
+There is also a third, “io” library.
+It is possible that some of its functionality may be moved to the i18n or common
+libraries.
+(A likely candidate might be `operator<<(std::ostream& stream, const UnicodeString& s)`,
+although there are no actual plans to do so at the time of this writing.)
+
+One can build a combined library which provides the exports from
+both the “common” and “i18n” libraries,
+in order to provide a single library for linking against.
+
+This may be needed for some platforms where there is a strong relationship
+between an API and the library that implements it.
+For example, on Windows platforms, attempting to find an API that has been moved
+with a `LoadLibrary`/`GetProcAddress` approach will fail,
+unless you are using a combined library.
+
+#### Linking against multiple versions of ICU4C
+
+This section is intended to aid software developers who are implementing or
+integrating solutions based on ICU, that may need to consider having multiple
+versions of ICU running within the same executable (address space) at once.
+Typically, users of ICU are encouraged to update to the latest stable version.
+Under certain circumstances, however, behavior from earlier versions is desired,
+or else, an application is linking together code which is already built against
+a different version of ICU.
+
+The major and minor numbers are the first and second numbers in a version
+number, separated by a period. For example, in the version numbers 3.4.2.1,
+3.4.2, or 3.4, "3" is the major, and "4" is the minor. Normally, ICU employs
+"symbol renaming", such that the C function names and C++ object names are
+`#defined` to contain the major and minor numbers. So, for example, if your
+application calls the function `ucnv_open()`, it will link against
+`ucnv_open_3_4` if compiled against ICU 3.4, 3.4.2, or even 3.4.2.1. However, if
+compiled against ICU 3.8, the same code will link against `ucnv_open_3_8`.
+Similarly, `UnicodeString` is renamed to `UnicodeString_3_4`, etc. This is normally
+transparent to the user, however, if you inspect the symbols of the library or
+your code, you will see the modified symbols.
+
+If there are multiple versions of ICU being linked against in one application,
+it will need to link against all relevant libraries for each version, for
+example, common, i18n, and data. ICU uses standard library renaming, where, for
+example, `libicuuc.so` on one platform will actually be a symbolic link to
+`libicuuc.so.3.4`. When multiple ICU versions are used, the application may need
+to explicitly link against the exact versions of ICU being used.
+
+To disable renaming, build ICU with `--disable-renaming` passed to configure.
+Or, set the equivalent `#define U_DISABLE_RENAMING 1`. Renaming must be disabled
+both in the ICU build, and in the calling application.
+
+### ICU Data Compatibility
+
+Starting in ICU 3.8 and later, the data library that comes with ICU is binary
+compatible and structurally compatible with versions of ICU with the same major
+and minor version, or a maintenance release. This allows multiple maintenance
+releases of ICU to share the same data, but generally the latest maintenance
+release of the data should be used.
+
+The binary compatibility of the data refers to the resource bundle binary format
+that is contains the locale data, charset conversion tables and other file
+formats supported by ICU. These binary formats are readable by many versions of
+ICU. For example, resource bundles written with ICU 3.6 are readable by ICU 3.8.
+
+The structural compatibility of the data refers to the structural contents of
+the ICU data. The structure of the locale data may change between reference
+releases, but the keys to reference specific types of data will be the same
+between maintenance releases. This means that resource keys to access data
+within resource bundles will work between maintenance releases of a specific
+reference release. For example, an ICU 3.8 calendar will be able to use ICU
+3.8.1 data, and vis versa; however ICU 3.6 may not be able to read ICU 3.8
+locale data. Generally, these keys are not accessible by ICU users because only
+the ICU implementation uses these resource keys.
+
+The contents of the data library may change between ICU maintenance releases and
+give you different results due to important updates and bug fixes. An example of
+an important update would be a timezone rule update for when a country changes
+when daylight saving time occurs. So the results may be different between
+maintenance releases.
+
+### ICU4J Serialization Compatibility
+
+Starting in ICU4J 3.6, ICU4J stable API classes (marked as `@stable`) implementing
+`java.io.Serializable` support serialized objects to be deserialized by ICU4J 3.6
+or newer version of ICU4J. Some classes perform only shallow serialization,
+therefore, it is not guaranteed that a deserialized object behaves exactly same
+with the original object across ICU4J versions. Also, when it is difficult to
+maintain serialization compatibility in a certain class across different ICU4J
+versions for technical or other reasons, the ICU project committee may approve
+the breakage. In such event, a note explaining the compatibility issue will be
+posted in the ICU public mailing lists and also documented in the release note
+of the new ICU4J version introducing the incompatibility.

docs/userguide/icu/glossary.md

@@ -0,0 +1,143 @@
+---
+layout: default
+title: Glossary
+parent: ICU
+nav_order: 9000
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Glossary
+
+## ICU-specific Words and Acronyms
+
+For additional Unicode terms, please see the official 
+[Unicode Standard Glossary](https://www.unicode.org/glossary/).
+
+ Term       | Definition
+------------|------------
+**- A -**   | 
+**accent**  | A modifying mark on a character to indicate a change in vocal tone for pronunciation. For example, the accent marks in Latin script (acute, tilde, and ogonek) and the tone marks in Thai. Synonymous with diacritic.
+**accent character** | A character that has a diacritic attached to it.
+**alphabetic language** | A written language in which symbols represent vowels and consonants, and in which syllables and words are formed by a phonetic combination of symbols. Examples of alphabetic languages are English, Greek, and Russian. Contrast with ideographic language.
+**Arabic numerals** | Forms of decimal numerals used in most parts of the Arabic world (for instance, U+0660, U+0661, U+0662, U+0663). Although European digits (1, 2, 3...) derive historically from these forms, they are visually distinct and are coded separately. (Arabic digits are sometimes called Indic numerals; however, this nomenclature leads to confusion with the digits currently used with the scripts of India.) Arabic digits are referred to as Arabic-Indic digits in the Unicode Standard. Variant forms of Arabic digits used chiefly in Iran and Pakistan are referred to as Eastern Arabic-Indic digits.
+**Arabic script** | A cursive script used in Arabic countries. Other writing systems such as Latin and Japanese also have a cursive handwritten form, but usually are typeset or printed in discrete letter form. Arabic script has only the cursive form. Arabic script is also used for Urdu, (spoken in Pakistan, Bangladesh, and India), Farsi and Persian (spoken in Iran, Iraq, and Afghanistan).
+**ASCII** | "American Standard Code for Information Interchange." A standard 7-bit character set used for information interchange. ASCII encodes the basic Latin alphabet and punctuation used in American English, but does not encode the accented characters used in many European languages.
+**- B -** |  
+**base character** | A base character is a Unicode character that does not graphically combine with any preceding character. This does not include control or formatting characters. This is a characteristic of most Unicode characters.
+**baseline** | A conceptual line with respect to which successive characters are aligned.
+**Basic Multilingual Plane** | As defined by International Standard [ISO/IEC 10646](http://std.dkuug.dk/jtc1/sc2/wg2/), Unicode values `0000` through `FFFF`. This range covers all of the major living languages around the world.
+**bidi** | See bidirectional.
+**bidirectional** | Text which has a mixture of languages that read and write either left-to-right or right-to-left. Languages such as Arabic, Hebrew, and Yiddish have a general flow of text that proceeds horizontally from right to left, but numbers and Latin based languages like English are written from left to right.
+**big-endian** | A computer architecture that stores multiple-byte numerical values with the most significant byte (MSB or big end) values first in a computer's addressable memory. This is the opposite from little-endian.
+**BMP** | See Basic Multilingual Plane.
+**boundary** | A boundary is a location between user characters, words, or at the start or end of a string. Boundaries break the string into logical groups of characters.
+**boundary position** | Each boundary has a boundary position in a string. The boundary position is an integer that is the index of the character that follows it.
+**- C -** |  
+**canonical decomposition** | The decomposition of a character which results from recursively applying the canonical mappings until no characters can be further decomposed and then re-ordering non-spacing marks according to the canonical behavior rules. For instance, an acute accented A will decompose into an A character followed by an acute accent combining character. Canonical mappings do not remove formatting information, which is the opposite of what happens during a compatibility decomposition.
+**canonical equivalent** | Two character sequences are said to be canonical equivalents if their full canonical decomposition are identical.
+**CCSID** | Coded Character Set IDentifier. A number which IBM® uses to refer to the combination of particular code page(s), character set(s), and other information. This is defined formally in the CDRA (Coded Character Representation Architecture) documents from IBM.
+**character boundary** | A location between characters.
+**character properties** | The given properties of a character. These properties include, but are not limited to, case, numeric meaning, and direction to layout successive characters of the same type.
+**character set** | The set of characters represented with reference to the binary codes used for the characters. One character set can be encoded into more than one code page.
+**Chinese numerals** | Chinese characters that represent numbers. For example, the Chinese characters for 1, 2, and 3 are written with one, two, and three horizontal brush strokes, respectively. Contrast with Arabic numerals, Hindi numerals, and Roman numerals.
+**CJK** | Acronym for Chinese/Japanese/Korean characters.
+**code page** | An ordered set or characters in which a numeric index (code point value) is associated with each character. This term can also be called a "character set" or "charset."
+**code point value** | The encoding value for a character in the specified character set. For example the code point value of "A" in Unicode 3.0 is `0x0041`.
+**code set** | UNIX term equivalent to code page.
+**collation** | Text comparison using language-sensitive rules as opposed to bitwise comparison of numeric character codes. This is usually done to sort a list of strings.
+**collation element** | A collation element consists of the primary, secondary and tertiary weights of a user character.
+**combining character** | A combining character is a Unicode character that graphically combines with any preceding base character. A combining character does not stand alone unless it is being described. Accents are examples of combining characters.
+**combining character sequence** | A combining character sequence consists of a Unicode base character and zero or more Unicode combining characters. The base and combining characters are dynamically composed at printout time to a user character.
+**compatibility character** | A character that has a compatibility decomposition.
+**compatibility decomposition** | The decomposition of a character which results from recursively applying both compatibility mappings and canonical mappings until no characters can be further decomposed then re-ordering non-spacing marks according to the canonical behavior rules. Compatibility decomposition may remove formatting information, which is the opposite of what happens during a canonical decomposition.
+**compatibility equivalent** | Two characters sequences are said to be compatibility equivalent if their full compatibility decompositions are equivalent.
+**core product** | The language independent portion of a software product (as distinct from any particular localized version of that product - including the English language version). Sometimes, however, this term is used to refer to the English product as opposed to other localizations.
+**cursive script** | A script whose adjacent characters touch or are connected to each other. For example, Arabic script is cursive.
+**- D -** |  
+**DBCS (double-byte character set)** | A set of characters in which each character is represented by 2 bytes. Scripts such as Japanese, Chinese, and Korean contain more characters than can be represented by 256 code points, thus requiring two bytes to uniquely represent each character. The term DBCS is often used to mean MBCS (multi-byte character set). See multi-byte character set.
+**decomposable character** | A character that is comparable to a sequence of one or more other characters.
+**decomposition** | A sequence of one or more characters that is equivalent to a decomposable character.
+**diacritic** | A modifying mark on a character. For example, the accent marks in Latin script (acute, tilde, and ogonek) and the tone marks in Thai. Synonymous with accent.
+**digit** | A general term for a number character. A digit may or may not be base ten.
+**display string** | A display string is a string that may be shown to a user. Normally a display string is visible in GUI. These strings need to be translated for different countries.
+**- E -** |  
+**EBCDIC** | Extended Binary-Coded Decimal Interchange Code. A group of coded character sets that consists of eight-bit coded characters. EBCDIC-coded character sets map specified graphic and control characters onto code points, each consisting of 8 bits. EBCDIC is an extension of BCD (Binary-Coded Decimal), which uses only 7 bits for each character.
+**ECMA** | European Computer Manufacturers Association. A nonprofit organization formed by European computer vendors to announce standards applicable to the functional design and use of data processing equipment.
+**encoding scheme** | A set of specific definitions that describe the philosophy used to represent character data. Examples of specifications in such a definition are: the number of bits, the number of bytes, the allowable ranges of bytes, maximum number of characters, and meanings assigned to some generic and specific bit patterns.
+**European numerals** | A number comprised of the digits 0, 1, 2, 3, 4, 5, 6, 7, 8, and/or 9.
+**expansion** | The process of sorting a character as if it were expanded to two characters.
+**- F -** |  
+**font** | A set of graphic characters that have a characteristic design, or a font designer's concept of how the graphic characters should appear. The characteristic design specifies the characteristics of its graphic characters. Examples of characteristics are shape, graphic pattern, style, size, weight, and increment.
+**- G -** |  
+**globalization** | The process of developing, manufacturing, and marketing software products that are intended for worldwide distribution. This term combines two aspects of the work: internationalization (enabling the product to be used without language or culture barriers) and localization (translating and enabling the product for a specific locale).
+**glyph** | The actual shape (bit pattern, outline) of a character image. For example, an italic "A" and a roman "A" are two different glyphs representing the same underlying character. Strictly speaking, any two images that differ in shape constitute different glyphs. In this usage, glyph is a synonym for character image, or simply image.
+**graphic character** | A character, other than a control function, that has a visual representation normally handwritten, printed, or displayed.
+**Graphical User Interface** | Graphical User Interface is normally written as the acronym GUI. It is the display the end-user sees when running a program. Strings that are visible in the GUI need to localized to the end-user's language.
+**global application** | An application that can be completely translated for use in different locales. All text shown to the user is in the native language, and user expectations are met for dates, times, and other locale conventions.
+**GMT** | Greenwich mean time. In the 1840s the standard time kept by the Royal Greenwich Observatory located at Greenwich, England was established for all of England, Scotland, and Wales, replacing many local times in use in those days. Subsequently GMT became the official time reference for the world until 1972 when it was subsumed by the atomic clock-based coordinated universal time (UTC). GMT is also known as universal time.
+**GUI** | Acronym for "Graphical User Interface".
+**- H -** |  
+**Han Characters** | Ideographic characters of Chinese origin.
+**Hangul** | The Korean alphabet that consists of fourteen consonants and ten vowels. Hangul was created by a team of scholars in the 15th century at the behest of King Sejong. See jamo.
+**Hanja** | The Korean term for characters derived from Chinese.
+**Hiragana** | A Japanese phonetic syllabary. The symbols are cursive or curvilinear in style. See Kanji and Katakana.
+**- I -** |  
+**i18n** | Synonym for internationalization ("i" + 18 letters + "n"; lower case i is used to distinguish it from the numeral 1 (one)).
+**ideographic language** | A written language in which each character (ideogram) represents a thing or an idea (but not necessarily a particular word or phrase). An example of such a language is written Chinese (Zhongen). Contrast with alphabetic language.
+**Indic numerals** | A set of numerals used in India and many Arabic countries instead of, or in addition to, the Arabic numerals. Indic numeral shapes correspond to the Arabic numeral shapes. Contrast with Arabic numerals, Chinese numerals, and Roman numerals. See numbers.
+**internationalization** | Designing and developing a software product to function in multiple locales. This process involves identifying the locales that must be supported, designing features which support those locales, and writing code that functions equally well in any of the supported locales. Internationalized applications store their text in external resources, and use locale-sensitive utilities for formatting and collation.
+**ISO** | International Organization for Standardization. Contrary to popular belief, ISO does NOT stand for International Standards Organization because it is not an acronym. The ISO name is derived from the Greek word isos, which means "equal." ISO is a non-governmental international organization, and it promotes the development of standards on goods and services.
+**- J -** | 
+**jamo** | A set of consonants and vowels used in Korean Hangul. The word jamo is derived from ja, which means consonant, and mo, which means vowel.
+**- K -** | 
+**Kanji** | Chinese characters or ideograms used in Japanese writing. The characters may have different meanings from their Chinese counterparts. See Hiragana and Katakana.
+**Katakana** | A Japanese phonetic syllabary used primarily for foreign names and place names and words of foreign origin. The symbols are angular, while those of Hiragana are cursive. Katakana is written left to right, or top to bottom. See Kanji.
+**- L -** |  
+**L10n** | Synonym for "localization" ("L" + 10 letters + "n"; upper case L is used to distinguish it from the numeral 1 (one)).
+**L12y** | Acronym for "localizability" ("L" + 12 letters + "y"; upper case L is used to distinguish it from the numeral 1 (one)).
+**language** | A set of characters, phonemes, conventions, and rules used for conveying information. The aspects of a language are pragmatics, semantics, syntax, phonology, and morphology.
+**legacy** | An inherited obligation. For example, a legacy database might contain strategic data that must be maintained for a long time after the database has become technologically obsolete.
+**locale** | A set of conventions affected or determined by human language and customs, as defined within a particular geo-political region. These conventions include (but are not necessarily limited to) the written language, formats for dates, numbers and currency, sorting orders, etc.
+**locale-sensitive** | Exhibiting different behavior or returning different data, depending on the locale.
+**localizability** | The degree to which a software product can be localized. Localizable products separate data from code, correctly display the target language and function properly after being localized.
+**localization** | Modifying or adapting a software product to fit the requirements of a particular locale. This process includes (but may not be limited to) translating the user interface, documentation and packaging, changing dialog box geometries, customizing features (if necessary), and testing the translated product to ensure that it still works (at least as well as the original).
+**lowercase** | The small alphabetic characters, whether accented or not, as distinguished from the capital alphabetic characters. The concept of case applies to alphabets such as Latin, Cyrillic, and Greek, but not to Arabic, Hebrew, Thai, Japanese, Chinese, Korean, and many other scripts. Examples of lowercase letters are a, b, and c. Contrast with uppercase.
+**- M -** | 
+**MBCS** | Multi-byte Character Set. A set of characters in which each character is represented by 1 or more bytes. Contrast with DBCS and SBCS.
+**modifier characters** | '`@`' (French secondary collation rule)
+**multilingual** | An application that can simultaneously display and manipulate text in multiple languages. For example, a word processor that allows Japanese and English in the same document is multilingual.
+**- N -** | 
+**National Standard** | A linguistic rule, measurement, educational guideline, or technology-related convention as defined by a government or an industry standards organization. Examples include character sets, keyboard layouts, and some cultural conventions, such as punctuations.
+**NLS** | National Language Support. The features of a product that accommodate a specific region, its language, script, local conventions, and culture. See internationalization and localization.
+**non-display string** | A non-display string is a string such as a URL that is used programmatically and is not visible to an end-user. A non-display string does not need to be translated.
+**normalization** | The process of converting Unicode text into one of several standardized forms in which precomposed and combining characters are used consistently.
+**numbers** | Numbers express either quantity (cardinal) or order (ordinal). Many cultures have different forms for cardinal and ordinal numbers. For example, in French the cardinal number five is cinq, but the ordinal fifth is cinquième or 5eme or 5e. Numbers are written with symbols that are usually referred to as numerals. See Arabic numerals, Chinese numerals, Indic numerals, European numerals, and Roman numerals.
+**- P -** | 
+**pinyin** | A system to phonetically render Chinese ideograms in a Latin alphabet.
+**- R -** | 
+**relation characters** | '`<`' (primary difference collation rule) <br>'`;`' (secondary difference collation rule) <br>'`,`' (tertiary difference collation rule) <br>'`=`' (identical difference collation rule)
+**reset character** | '`&`' (reset the collation rules)
+**resource** | 1. Any part of a program which can appear to the user or be changed or configured by the user. <br>2. Any piece of the program's data, as opposed to its code.
+**resource bundle** | A set of culturally dependent data used by locale-sensitive classes in an internationalized software program to provide Locale specific responses to the end-user.
+**Roman numerals** | A system of writing numbers in which the characters I, V, X, L, C, D, and M have the value of 1, 5, 10, 50, 100, 500, and 1000, respectively. Lesser numbers in prefix positions indicate subtraction. For example MCMLXIV is 1964 in decimal because CM is 900, LX is 60, and IV is 4. Contrast with Arabic numerals, European numerals, Chinese numerals, and Indic numerals.
+**- S -** | 
+**SBCS (Single-byte character set)** | A set of characters in which each character is represented by 1 byte.
+**script** | A set of characters used to write a particular set of languages. For example, the Latin (or Roman) script is used to write English, French, Spanish, and most other European languages; the Cyrillic script is used to write Russian and Serbian.
+**separator** | The thousands separator (or digit grouping separator) is the local symbol used to separate every third digit in large numbers or lengthy decimal fractions. The decimal separator is the local symbol used to indicate the decimal position in a number. It may be a comma, period or some other language specific symbol.
+**string** | A set of consecutive characters treated by a computer as a single item.
+**- T -** | 
+**titlecase** | A set of words that usually have the first character of each word in uppercase characters. The rules for titlecase are specific to each locale. Titlecase words usually go on titles of literature and other publications.
+**transcoding** | Conversion of character data from one character set to another.
+**translation** | The conversion of text from one human language to another. This includes properly converting the grammar, spelling and meaning of the text into the target language.
+**transliteration** | Transformation of text from one script to another, usually based on phonetic equivalences and not word meanings. For example, Greek text might be transliterated into the Latin script so that it can be pronounced by English speakers.
+**- U -** | 
+**UCS** | Universal Multiple-Octet Coded Character Set. The Unicode standard is based upon this ISO/IEC 10646 standard. UCS characters look the same Unicode characters, but they do not have any character properties. Synonymous with UTF.
+**Unicode** | A character set that encompasses all of the world's living scripts. Unicode is the basis of most modern software internationalization.
+**Unicode character** | A Unicode character enables a computer to store, manipulate, and transfer to other computers multilingual text. A Unicode character has the binary range of 0..10FFFF.
+**uppercase** | The larger alphabetic characters, whether accented or not, as distinguished from the lowercase alphabetic characters. The concept of case applies to alphabets such as Latin, Cyrillic, and Greek, but not to Arabic, Hebrew, Thai, Japanese, Chinese, Korean, and many other scripts. Examples of uppercase letters are A, B, and C. Contrast with lowercase.
+**user character** | A character made up of two or more Unicode characters that are combined to form a more complex character that has its own semantic value. A user character is the smallest component of written language that has a semantic value to a native language user.
+**UTC time** | UTC stands for Coordinated Universal Time. This was formerly known as Greenwich Mean Time (GMT). It is used as a time constant that can be transformed to display an accurate date and time in any world calendar and time zone. This is a time scale based on a cesium atomic clocks.
+**UTF** | Unicode Transformation Format. A binary format of representing a Unicode character. There are several encoding forms for a Unicode character, which include UTF-8, UTF-16BE, UTF-16LE, UTF-32BE and UTF-32LE. The numbers in these encoding form names refer to the bit size of each number, and the BE and LE stands for big endian or little endian respectively. The UTF-8 and UTF-16 formats can take multiple units of binary numbers to represent a Unicode character.

docs/userguide/icu/howtouseicu.md

@@ -0,0 +1,224 @@
+---
+layout: default
+title: How To Use ICU
+nav_order: 2
+parent: ICU
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# How To Use ICU
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+# Overview
+
+ICU builds and installs as relatively standard libraries. For details about
+building, installing and porting see the [ICU4C
+readme](../icu4c/) and the
+[ICU4J readme](../icu4j/).
+In addition, ICU4C installs several scripts and makefile fragments that help
+build other code using ICU.
+
+For C++, note that there are [Recommended Build
+Options](icu4c/build#recommended-build-options)
+(both for normal use and for ICU as system-level libraries) which are not
+default simply for compatibility with older ICU-using code.
+
+Starting with ICU 49, the ICU4C Readme has a short section about
+[User-Configurable
+Settings](icu4c/build#user-configurable-settings).
+
+## C++ Makefiles
+
+The recommended way to use ICU in Makefiles is to use the
+[pkg-config](http://pkg-config.freedesktop.org/) files which are installed by
+ICU upon "`make install`". There are files for various libraries and components.
+This is preferred over the deprecated icu-config script.
+
+This table shows the package names used within pkg-config.
+
+|**Package**|**Contents**|
+|------|--------------------|
+|icu-uc|Common (uc) and Data (dt/data) libraries|
+|icu-i18n|Internationalization (in/i18n) library|icu-le [Layout Engine](../layoutengine/index.md)|
+|icu-lx|Paragraph Layout|
+|icu-io|[Ustdio](io/ustdio.md)/[iostream](io/ustream.md) library (icuio)
+
+For example, to compile a simple application, you could run the following
+command. See the [pkg-config](http://pkg-config.freedesktop.org/) manpage for
+more details.
+
+    c++ -o test test.c `pkg-config --libs --cflags icu-uc icu-io`
+
+ICU installs the pkg-config (.pc) files in `$(prefix)/lib/pkgconfig` (where
+`$(prefix)` is the installation prefix for ICU). Note that you may need to add
+`$(prefix)/lib/pkgconfig` to the `PKG_CONFIG_PATH` variable.
+
+### ICU in a small project
+
+For small projects, it may be convenient to take advantage of
+ICU's `autoconf`'ed files. ICU `make install` writes
+`$(prefix)/lib/icu/Makefile.inc` which defines most of the necessary *make*
+variables such as `$(CXX)`, `$(CXXFLAGS)`, `$(ICULIBS)`, `$(INVOKE)`, `$(ICUPKG)`,
+`$(datadir)`, etc.
+
+By itself, `Makefile.inc` is incomplete. It assumes that it will be included into another
+`Makefile` which will define `$(srcdir)`, `$(DYNAMICCXXFLAGS)` and similar values.
+
+In this case, it is probably best to copy ICU's
+`autoconf`'ed top-level `./Makefile` and/or library-target-style `i18n/Makefile` and/or
+binary-target-style `tools/icupkg/Makefile`. Then modify them as needed.
+
+### ICU in a medium-sized project
+
+If you use your own `autoconf`/`CMake`/... setup, consider cherry-picking only the
+definitions needed, for example paths to specific ICU data and tools.
+This is often preferable to taking the entire `Makefile.inc` and
+overriding (many) definitions that are different.
+
+For selective ICU definitions, use the installed
+`$(prefix)/bin/icu-config` script.
+Its contents are synchronized with `$(prefix)/lib/icu/Makefile.inc`.
+For example, use `icu-config --invoke=icupkg` to invoke the ICU .dat packaging tool.
+
+### ICU in a large project
+
+In this case, you probably have your own build system. Just use ICU's public header
+files, `.so` files, etc. See the next section, "C++ With Your Own Build System".
+
+## Notes on `icu-config`
+
+> :point_right: **Note**: **icu-config is deprecated, and no longer recommended for
+> production use. Please use pkg-config files or other options.**
+
+As of ICU 63.1, [icu-config has been deprecated
+(ICU-10464)](https://unicode-org.atlassian.net/browse/ICU-10464).
+`icu-config` may be disabled by default in the future.
+As of ICU 63.1, you may enable or disable 63.1 with a configure flag:
+`--enable-icu-config` or `--disable-icu-config`
+
+`icu-config` is installed (by ICU's `make install`) into `$(prefix)/bin/icu-config`.
+It can be convenient for **trivial, single-file programs** that use ICU. For
+example, you could compile and build a small program with this command line:
+
+    icu-config --cxx --cxxflags --cppflags --ldflags -o sample sample.cpp
+
+Detailed usage of `icu-config` script is described in its `man` page.
+
+## C++ With Your Own Build System
+
+If you are not using the standard build system, you will need to construct your
+own system. Here are a couple of starting points:
+
+*   At least for initial bring-up, use pre-built data files from the ICU
+    download or from a normally-built ICU. Copy the icudt***XXx*.dat file from
+    `icu/source/data/in/` or `icu/source/data/out/tmp/` in either of these two
+    locations, into `icu/source/data/in/`** on your target ICU system. That way,
+    you won't need to build ICU's data-generation tools.
+*   Don't compile all files. Look in the `Makefile.in` files for `OBJECTS=`
+    clauses which will indicate which source files should be compiled. (Some .c
+    files are #included into others and cannot be compiled by themselves.)
+*   ICU does not throw or handle exceptions. Consider turning them off via g++'s
+    `-fno-exceptions` or equivalent.
+*   Each ICU library needs to be compiled with -DU_COMMON_IMPLEMENTATION,
+    -DU_I18N_IMPLEMENTATION etc. as appropriate. See unicode/utypes.h for the
+    set of such macros. If you build one single DLL (shared library) for all of
+    ICU, also use -DU_COMBINED_IMPLEMENTATION. If you build ICU as
+    statically-linked libraries, use -DU_STATIC_IMPLEMENTATION.
+*   Use the [icu-support mailing list](https://icu.unicode.org/contacts).
+    Ask for help and guidance on your strategy.
+*   Up until ICU 4.8, there are one or two header files (platform.h, icucfg.h)
+    that are generated by autoconf/configure and thus differ by platform,
+    sometimes even by target settings on a single platform (e.g., AIX 32-bit vs.
+    64-bit, Mac OS X universal binaries PowerPC vs. x86). If you do not use
+    autoconf, you probably need to configure-generate these header files for
+    your target platforms and select among them, or merge the generated headers
+    if they are similar, or simulate their generation by other means.
+*   Starting with ICU 49, all source code files are fixed (not generated). In
+    particular, there is one single platform.h file which determines
+    platform-specific settings via `#if ...`
+
+## C++ Namespace
+
+ICU C++ APIs are normally defined in a versioned namespace, for example
+"icu_50". There is a stable "icu" alias which should be used instead. (Entry
+point versioning is only to allow for multiple ICU versions linked into one
+program. [It is optional and should be off for system
+libraries.](icu4c/build#recommended-build-options))
+
+By default, and only for backward compatibility, the ICU headers contain a line
+`using namespace icu_50;` which makes all ICU APIs visible in/with the global
+namespace (and potentially collide with non-ICU APIs there). One of the
+[Recommended Build
+Options](icu4c/build#recommended-build-options)
+is to turn this off.
+
+To write forward declarations, use
+
+    U_NAMESPACE_BEGIN
+    class UnicodeSet;
+    class UnicodeString;
+    U_NAMESPACE_END
+
+To qualify an ICU class name, use the "icu" alias:
+
+    static myFunction(const icu::UnicodeString &s) {...}
+
+Frequently used ICU classes can be made easier to use in .cpp files with
+
+    using icu::UnicodeSet;
+    using icu::UnicodeString;
+
+## Other Notes
+
+### Helper Install Utilities
+
+ICU installs `$(prefix)/share/icu/$(VERSION)/install-sh` and
+`$(prefix)/share/icu/$(VERSION)/mkinstalldirs`. These may be used by ICU tools and
+samples. Their paths are given in the installed `Makefile.inc` (see above).
+
+### Data Packaging Settings
+
+The `pkgdata` tool (see [Packaging ICU4C](packaging/index.md) ) makes use of the
+installed file `**$(prefix)/lib/icu/pkgdata.inc**` to set parameters for data
+packaging operations that require use of platform compilers and linkers ( in
+`static` or `dll` mode). `pkgdata` uses the icu-config script in order to locate
+**pkgdata.inc**. If you are not building ICU using the supplied tools, you may
+need to modify this file directly to allow `static` and `dll` modes to function.
+
+### Building and Running Trivial C/C++ Programs with `icurun`
+
+For building and running trivial (one-compilation-unit) programs with an
+installed ICU4C, the shell script
+[icurun](https://github.com/unicode-org/icu/blob/main/tools/scripts/icurun)
+may be used. For detailed help, see the top of that script.
+As an example, if ICU is installed to the prefix **/opt/local** and the current
+directory contains two sample programs "test1.cpp" and "test2.c", they may be
+compiled and run with any of the following commands. The "-i" option specifies
+either the installed icu-config script, or the directory containing that script,
+or the path to a 'bin' directory.
+
+*   `icurun **-i /opt/local** test1.cpp`
+*   `icurun **-i /opt/local/bin** test2.c`
+*   `icurun **-i /opt/local/bin/icu-config** test1.cpp`
+
+If "icu-config" is on the PATH, the -i option may be omitted:
+
+*   `icurun test1.cpp`
+
+Any additional arguments will be passed to the program.
+
+*   `icurun test1.cpp *args...*`
+
+*Please give feedback to the [icu-support mailing list](https://icu.unicode.org/contacts),
+and refer to [Ticket #8481](https://unicode-org.atlassian.net/browse/ICU-8481).*

docs/userguide/icu/i18n.md

@@ -0,0 +1,295 @@
+---
+layout: default
+title: Internationalization
+nav_order: 1
+parent: ICU
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Software Internationalization
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview of Software Internationalization
+
+Developing globalized software is a continuous balancing act as software
+developers and project managers inadvertently underestimate the level of effort
+and detail required to create foreign-language software releases.
+
+Software developers must understand the ICU services to design and deploy
+successful software releases. The services can save ICU users time in dealing
+with the kinds of problems that typically arise during critical stages of the
+software life cycle.
+
+In general, the standard process for creating globalized software includes
+"internationalization", which covers generic coding and design issues, and
+"localization", which involves translating and customizing a product for a
+specific market.
+
+Software developers must understand the intricacies of internationalization
+since they write the actual underlying code. How well they use established
+services to achieve mission objectives determines the overall success of the
+project. At a fundamental level, code and feature design affect how a product is
+translated and customized. Therefore, software developers need to understand key
+localization concepts.
+
+From a geographic perspective, a locale is a place. From a software perspective,
+a locale is an ID used to select information associated with a language and/or
+a place. ICU locale information includes the name and identifier of the spoken
+language, sorting and collating requirements, currency usage, numeric display
+preferences, and text direction (left-to-right or right-to-left, horizontal or
+vertical).
+
+General locale-sensitive standards include keyboard layouts, default paper and
+envelope sizes, common printers and monitor resolutions, character sets or
+encoding ranges, and input methods.
+
+## ICU Services Overview
+
+The ICU services support all major locales with language and sub-language pairs.
+The sub-language generally corresponds to a country. One way to think of this is
+in terms of the phrase "X language as spoken in Y country." The way people speak
+or write a particular language might not change dramatically from one country to
+the next (for example, German is spoken in Austria, Germany, and Switzerland).
+However, cultural conventions and national standards often differ a great deal.
+
+A key advantage to using the ICU services is the net result in reduced time to
+market. The translation of the display strings is bundled in separate text files
+for translation. A programmer team with translators no longer needs to search
+the source code in order to rewrite the software for each country and language.
+
+## Internationalization and Unicode
+
+Unicode enables a program to use a standard encoding scheme for all textual data
+within the program's environment. Conversion has to be done with incoming and
+outgoing data only. Operations on the text (while it is in the environment) are
+simplified since you do not have to keep track of the encoding of a particular
+text.
+
+Unicode supports multilingual data since it encodes characters for all world
+languages. You do not have to tag pieces of data with their encoding to enable
+the right characters, and you can mix languages within a single piece of text.
+
+Some of the advantages of using ICU to internationalize your program include the
+following:
+
+*   It can handle text in any language or combination of languages.
+
+*   The source code can be written so that the program can work for many
+    locales.
+
+*   Configurable, pluggable localization is enabled.
+
+*   Multiple locales are supported at the same time.
+
+*   Non-technical people can be given access to information and you don't have
+    to open the source code to them.
+
+*   Software can be developed so that the same code can be ported to various
+    platforms.
+
+## Project Management Tips for Internationalizing Software
+
+The following two processes are key when managing, developing and designing a
+successful internationalization software deliverable:
+
+1.  Separate the program's executable code from its UI elements.
+
+2.  Avoid making cultural assumptions.
+
+Keep static information (such as pictures, window layouts) separate from the
+program code. Also ensure that the text which the program generates on the fly
+(such as numbers and dates) comes out in the right language. The text must be
+formatted correctly for the targeted user community.
+
+Make sure the analysis and manipulation of both text and kinds of data
+(such as dates), is done in a manner that can be easily adapted for different
+languages and user communities. This includes tasks such as alphabetizing lists
+and looking for line-break positions.
+
+Characters must display on the screen correctly (the text's storage format must
+be translated to the proper visual images). They must also be accepted as input
+(translated from keystrokes, voice input or another kind of input into the
+text's storage format). These processes are relatively easy for English, but
+quite challenging for other languages.
+
+### Separating Executable Code from UI Elements
+
+Good software design requires that the programming code implementing the user
+interface (UI) be kept separate from code implementing the underlying
+functionality. The description of the UI must also be kept separate from the
+code implementing it.
+
+The description of the UI contains items that the user sees, including the
+various messages, buttons, and menu commands. It also contains information about
+how dialog boxes are to be laid out, and how icons, colors or other visual
+elements are to be used. For example, German words tend to be longer since they
+contains grammatical suffixes that English has lost in the last 800 years. The
+following table shows how word lengths can differ among languages.
+
+|English|German|Cyrillic-Serbian|
+|--------|--------|-------------|
+|cut|ausschneiden|исеци|
+|copy|kopieren|копирај|
+|paste|einfügen|залепи|
+
+The description of the UI, especially user-visible pieces of text, must be kept
+together and not embedded in the program's executable code. ICU provides the
+ResourceBundle services for this purpose.
+
+### Avoiding Cultural/Hidden Assumptions
+
+Another difficulty encountered when designing and implementing code is to make
+it flexible enough to handle different ways of doing things in other countries
+and cultures. Most programmers make unconscious assumptions about their user's
+language and customs when they design their programs. For example, in Thailand,
+the official calendar is the Buddhist calendar and not the Gregorian calendar.
+
+These assumptions make it difficult to translate the user interface portion of
+the code for some user communities without rewriting the underlying program. The
+ICU libraries provide flexible APIs that can be used to perform the most common
+and important tasks. They contain pre-built supporting data that enables them to
+work correctly in 75 languages and more than 200 locales. The key is
+understanding when, where, why, or how to use the APIs effectively.
+
+The remainder of this section provides an overview of some cultural and hidden
+assumptions components. See a list of topics below:
+*   [Numbers and Dates](#numbers-and-dates)
+*   [Messages](#messages)
+*   [Measuring Units](#measuring-units)
+*   [Alphabetical Order of Characters](#alphabetical-order-of-characters)
+*   [Characters](#characters)
+*   [Text Input and Layout](#text-input-and-layout)
+*   [Text Manipulation](#text-manipulation)
+*   [Date/Time Formatting](#datetime-formatting)
+*   [Distributed Locale Support](#distributed-locale-support)
+*   [LayoutEngine](#layoutengine)
+
+#### Numbers and Dates
+
+Numbers and dates are represented in different languages. Do not implement
+routines for converting numbers into strings, and do not call low-level system
+interfaces like `sprintf()` that do not produce language-sensitive results.
+Instead, see how ICU's [NumberFormat](format_parse/numbers/index.md) and
+[DateFormat](format_parse/datetime/index.md) services can be used more
+effectively.
+
+#### Messages
+
+Be careful when formulating assumptions about how individual pieces of text are
+used together to create a complete sentence (for example, when error messages
+are generated). The elements might go together in a different order if the
+message is translated into a new language. ICU provides
+[MessageFormat](format_parse/messages/index.md) (§) and
+[ChoiceFormat](format_parse/messages/index.md) (§) to help with these
+occurrences.
+
+> :point_right: **Note**: There also might be situations where parts of the sentence change when other
+parts of the sentence also change (selecting between singular and plural nouns
+that go after a number is the most common example).
+
+#### Measuring Units
+
+Numerical representations can change with regard to measurement units and
+currency values. Currency values can vary by country. A good example of this is
+the representation of $1,000 dollars. This amount can represent either U.S. or
+Canadian dollar values. US dollars can be displayed as USD while Canadian
+dollars can be displayed as CAD, depending on the locale. In this case, the
+displayed numerical quantity might change, and the number itself might also
+change. [NumberFormat](format_parse/numbers/index.md) provides some support for
+this.
+
+#### Alphabetical Order of Characters
+
+All languages (even those using the same alphabet) do not necessarily have the
+same concept of alphabetical order. Do not assume that alphabetical order is the
+same as the numerical order of the character's code-point values. In practice,
+'a' is distinct from 'A' and 'b' is distinct from 'B'. Each has a different code
+point . This means that you cannot use a bit-wise lexical comparison (such as
+what strcmp() provides), to sort user-visible lists.
+
+Not all languages interpret the same characters as equivalent. If a character's
+case is changed it is not always a one-to-one mapping. Accent differences, the
+presence or absence of certain characters, and even spelling differences might
+be insignificant when determining whether two strings are equal. The
+[Collator](collation/index.md) services provide significant help in this area.
+
+#### Characters
+
+A character does not necessarily correspond to a single code-point position in
+the backing store. All languages might not have the same definition of a word,
+and might not find that any group of characters separated by a white space is an
+acceptable approximation for the definition of a word. ICU provides the
+[BreakIterator](boundaryanalysis/index.md) services to help locate boundaries or
+when counting units of text.
+
+When checking characters for membership in a particular class, do not list the
+specific characters you are interested in, and do not assume they come in any
+particular order in the encoding scheme. For example, /A-Za-z/ does not mean all
+letters in most European languages, and /0-9/ does not mean all digits in many
+writing systems. This also holds true when using C interfaces such as `isupper()`
+and `islower()`. ICU provides a large group of utility functions for testing
+character properties, such as `u_isupper()` and `u_islower()`.
+
+#### Text Input and Layout
+
+Do not assume anything about how a piece of text might be drawn on the screen,
+including how much room it takes up, the direction it flows, or where on the
+screen it should start. All of these text elements vary according to language.
+As a result, there might not be a one-to-one relationship between characters and
+keystrokes. One-to-many, many-to-one, and many-to-many relationships between
+characters and keystrokes all occur in real text in some languages.
+
+#### Text Manipulation
+
+Do not assume that all textual data, which the program stores and manipulates,
+is in any particular language or writing system. ICU provides many methods that
+help with text storage. The `UnicodeString` class and `u_strxxx` functions are
+provided for Unicode-based character manipulation. For example, when appending
+an existing Unicode character buffer, characters can be removed or extracted out
+of the buffer.
+
+A good example of text manipulation is the Rosetta stone. The same text is
+written on it in Hieroglyphic, Greek and Demotic. ICU provides the services to
+correctly process multi-lingual text such as this correctly.
+
+#### Date/Time Formatting
+
+Time can be determined in many units, such as the lengths of months or years,
+which day is the first day of the week, or the allowable range of values like
+month and year (with `DateFormat`). It can also determine the time zone you are in
+(with `TimeZone`), or when daylight-savings time starts. ICU provides the Calendar
+services needed to handle these issues.
+
+#### Distributed Locale Support
+
+In most server applications, do not assume that all clients connected to the
+server interact with their users in the same language. Also do not assume that a
+session stops and restarts whenever a user speaking one language replaces
+another user speaking a different language. ICU provides sufficient flexibility
+for a program to handle multiple locales at the same time.
+
+For example, a Web server needs to serve pages to different users, languages,
+and date formats at the same time.
+
+#### LayoutEngine
+
+The ICU LayoutEngine is an Open Source library that provides a uniform, easy to
+use interface for preparing complex scripts or text for display. The Latin
+script, which is the most commonly used script among software developers, is
+also the least complex script to display especially when it is used to write
+English. Using the Latin script, characters can be displayed from left to right
+in the order that they are stored in memory. Some scripts require rendering
+behavior that is more complicated than the Latin script. We refer to these
+scripts as "complex scripts" and to text written in these scripts as "complex
+text."

docs/userguide/icu/index.md

@@ -0,0 +1,109 @@
+---
+layout: default
+title: ICU
+nav_order: 300
+has_children: true
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Introduction to ICU
+
+As companies integrate e-commerce on a global scale into their fundamental
+business processes, their prospective customers, established customers, and
+active partners can take advantage of increased revenue and decreased expenses
+through software internationalization. They also can improve customer
+communications and increase savings.
+
+## Meeting the Challenge of Globalization
+
+In today's business climate of globalization, companies must compete in a new
+Internet-enabled business climate of constant change and compressed time frames.
+Their customers expect reliable service and support.
+
+## Taking Advantage of Internationalized Software
+
+Companies need to establish a better linkage between their global business
+processes and the underlying supportive IT processes. If they want to deliver
+this new flexibility and agility, they must depend on the software
+internationalization process.
+
+The software internationalization development process uses libraries (such as
+the International Components for Unicode (ICU) libraries), to enable one single
+program to work with text in any language for any place in the world. For
+example, instead of having separate software versions for ten different
+countries, the ICU services can create one version that works seamlessly and
+transparently in all of them.
+
+The ICU components are an integral part of software development because they
+hide the cultural nuances and technical complexities of locale-specific software
+requirements. These complexities provide critical functionality for
+applications, but the application developer does not need to exert a huge effort
+or incur high costs to build them.
+
+## Justifying the Investment
+
+The business case needed to justify the investment in software
+internationalization is compelling when the investment is amortized over a
+number of projects. In the fast-paced and rapidly-evolving world of traditional
+and evolving e-businesses, these international components provide a firm ground
+on which companies, partners and suppliers can build their business
+transactions. They can share competitive information to help gain a significant
+economic advantage.
+
+The ICU services deliver proven value by lowering the cost required to integrate
+with disparate applications, systems and data sources on a regional and global
+scale. It provides value to a company's IT investment by lowering IT complexity,
+risk, maintenance costs and training costs. It also enhances organizational
+flexibility, leverages
+existing assets, and improves planning and decision-making. It enables
+organizational learning, process-driven synchronization, event-driven evaluation
+and decision-making.
+
+## Background and History of ICU
+
+ICU was originally developed by the Taligent company. The Taligent team later
+became the Unicode group at the IBM® Globalization Center of Competency in
+Cupertino. The team has received significant input from the open source
+community worldwide.
+
+Java™ classes developed at Taligent were incorporated into the Java Development
+Kit (JDK) 1.1 developed by Sun® Microsystems. The classes were then ported to
+C++ and later some classes were also ported to C. The classes provide
+internationalization utilities for writing global applications in C, C++, or
+Java programming languages.
+
+ICU for Java (ICU4J) includes enhanced versions of some of these classes, plus
+additional classes that complement the classes in the JDK. C and C++ versions of
+the same international functionality are available in ICU for C (ICU4C). The
+APIs differ slightly due to language differences and new functionality. For
+example, ICU4C includes a character converter API.
+
+ICU4J and ICU4C keep the same development goals. They both track additions to
+the Java internationalization APIs and implement the latest released Unicode
+standard. They also maintain a single, portable source code base.
+
+All of us in the ICU and open source group appreciate the time you are taking to
+understand our technology. We have put our best collective effort into these
+open components, and look forward to your questions, comments and suggestions.
+
+## Downloading ICU
+
+Download ICU in one of the following ways:
+
+1.  From the download page, <https://icu.unicode.org/download>, for
+    packaged stable releases of ICU.
+
+2.  From the source code repository, <https://github.com/unicode-org/icu/releases/>,
+    for the latest development versions.
+
+After downloading, see the included README file for information on what is
+included, building, installing, etc.
+
+## ICU License
+
+Current license: <https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE>
+
+See also FAQ section ["How is the ICU licensed"](icufaq/index#how-is-icu-licensed)

docs/userguide/icu/posix.md

@@ -0,0 +1,258 @@
+---
+layout: default
+title: C/POSIX Migration
+nav_order: 6
+parent: ICU
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# C/POSIX Migration
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Migration from Standard C and POSIX APIs
+
+The ISO C and POSIX standards define a number of APIs for string handling and
+internationalization in C. They do not support Unicode well because they were
+initially designed before Unicode/ISO 10646 were developed, and the POSIX APIs
+are also problematic for other internationalization aspects.
+
+This chapter discusses C/POSIX APIs with their problems, and shows which ICU
+APIs to use instead.
+
+> :point_right:  **Note**: *We use the term "POSIX" to mean the POSIX.1 standard (IEEE Std 1003.1) which
+defines system interfaces and headers with relevance for string handling and
+internationalization. The XPG3, XPG4, Single Unix Specification (SUS) and other
+standards include POSIX.1 as a subset, adding other specifications that are
+irrelevant for this topic.*
+
+> :construction: This chapter is not complete yet – more POSIX APIs are expected to be discussed
+in the future.
+
+## Strings and Characters
+
+### Character Sets and Encodings
+
+#### ISO C
+
+The ISO C standard provides two basic character types (`char` and `wchar_t`) and
+defines strings as arrays of units of these types. The standard allows nearly
+arbitrary character and string character sets and encodings, which was necessary
+when there was no single character set that worked everywhere.
+
+For portable C programs, characters and strings are opaque, i.e., a program
+cannot assume that any particular character is represented by any particular
+code or sequence of codes. Programs use standard library functions to handle
+characters and strings. Only a small set of characters — usually the set of
+graphic characters available in US-ASCII — can be reliably accessed via
+character and string literals.
+
+#### Problems
+
+1.  Many different encodings are used on each platform, making it difficult for
+    multiple programs and libraries to process the same text.
+
+2.  Programs often need to know the codes of special characters. For example,
+    code that parses a filename needs to know how the path and file separators
+    are encoded; this is commonly possible because filenames deliberately use
+    US-ASCII characters, but any software that uses non-ASCII characters becomes
+    platform-dependent. It is practically impossible to provide sophisticated
+    text processing without knowledge of the character set, its string encoding,
+    and other detailed features.
+
+3.  The C/POSIX standards only provide a very limited set of useful functions
+    for character and string handling; many functions that are provided do not
+    work for non-trivial cases.
+
+4.  While the size of the char type is in practice fixed to 8 bits in modern
+    compilers, and its common encodings are reasonably well documented, the size
+    of wchar_t varies between 8/16/32 bits depending on the compiler, and only
+    few of the string encodings used with it are documented.
+
+5.  See also [What size wchar_t do I need for
+    Unicode?](http://icu-project.org/docs/papers/unicode_wchar_t.html)
+
+6.  A program based on this model must be recompiled for each platform. Usually,
+    it must be recompiled for each supported language or family of languages.
+
+7.  The ISO C standard basically requires, by how its standard functions are
+    defined, that the data type for a single character code in a large character
+    set is the same as the string base unit type (wchar_t). This has led to C
+    standard library implementations using Unicode encodings which are either
+    limited for single-character functions to only part of Unicode, or suffer
+    from reduced interoperability with most Unicode-aware software.
+
+#### ICU
+
+ICU always processes Unicode text. Unicode covers all languages and allows safe
+hard coding of character codes, in addition to providing many standard or
+recommended algorithms and a lot of useful character property data. See the
+chapters about [Unicode Basics](unicode.md) and [Strings](strings/index.md) and others.
+
+ICU uses the 16-bit encoding form of Unicode (UTF-16) for processing, making it
+fully interoperable with most Unicode-aware software. See [UTF-16 for
+Processing](http://www.unicode.org/notes/tn12/). In the case of ICU4J, this is
+naturally the case because the Java language and the JDK use UTF-16.
+
+ICU uses and/or provides direct access to all of the [Unicode
+properties](strings/properties.md) which provide a much finer-grained
+classification of characters than [C/POSIX character
+classes](https://htmlpreview.github.io/?https://github.com/unicode-org/icu-docs/blob/main/design/posix_classes.html).
+
+In C/C++ source code character and string literals, ICU uses only "invariant"
+characters. They are the subset of graphic ASCII characters that are almost
+always encoded with the same byte values on all systems. (One set of byte values
+for ASCII-based systems, and another such set of byte values for EBCDIC
+systems.) See
+[`utypes.h`](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/unicode/utypes.h)
+for the set of "invariant" characters.
+
+With the use of Unicode, the implementation of many of the Unicode standard
+algorithms, and its cross-platform availability, ICU provides for consistent,
+portable, and reliable text processing.
+
+### Case Mappings
+
+#### ISO C
+
+The standard C functions `tolower()`, `toupper()`, etc. take and return one
+character code each.
+
+#### Problems
+
+1.  This does not work for German, where the character "ß" (sharp s) uppercases
+    to the two characters "SS". (It "expands".)
+
+2.  It does not work for Greek, where the character "Σ" (capital sigma)
+    lowercases to either "ς" (small final sigma) or "σ" (small sigma) depending
+    on whether the capital sigma is the last letter in a word. (It is
+    context-dependent.)
+
+3.  It does not work for Lithuanian and Turkic languages where a "combining dot
+    above" character may need to be removed in certain cases. (It "contracts"
+    and is language- and context-dependent.)
+
+4.  There are a number of other such cases.
+
+5.  There are no standard functions for title-casing strings.
+
+6.  There are no standard functions for case-folding strings. (Case-folding is
+    used for case-insensitive comparisons; there are C/POSIX functions for
+    direct, case-insensitive comparisons of pairs of strings. Case-folding is
+    useful when one string is compared to many others, or as part of a chain of
+    transformations of a string.)
+
+#### ICU
+
+Case mappings are operations taking and returning strings, to support length
+changes and context dependencies. Unicode provides algorithms and data for
+proper case mappings, and ICU provides APIs for them. (See the API references
+for various string functions and for Transforms/Transliteration.)
+
+### Character Classes
+
+#### ISO C
+
+The standard C functions isalpha(), isdigit(), etc. take a character code each
+and return boolean values for whether the character belongs to the current
+locale's respective character class.
+
+#### Problems
+
+1.  Character classes are bound to locales, instead of providing consistent
+    classifications for characters.
+
+2.  The same character may have different classifications depending on the
+    locale and the platform.
+
+3.  There are only very few POSIX character classes, and they are not well
+    defined. For example, there is a class for punctuation characters but not
+    one for symbols.
+
+4.  For example, the dollar symbol (“$”) may or may not belong to the punct
+    class depending on the locale, even on the same system.
+
+5.  The standard allows at most two sets of decimal digits: The digits of the
+    “portable character set” (i.e., those in the ASCII repertoire) and one more.
+    Some implementations only recognize ASCII digits in the isdigit() function.
+    However, there are many sets of decimal digits in a multilingual character
+    set like Unicode.
+
+6.  The POSIX standard assumes that each locale definition file carries the
+    character class data for all relevant characters. With many locales using
+    overlapping character repertoires, this can lead to a lot of duplication.
+    For efficiency, many UTF-8 locales define character classes only for very
+    few characters instead of for all of Unicode. For example, some de_DE.utf-8
+    locales only define character classes for characters used in German, or for
+    the repertoire of ISO 8859-1 – in other words, for only a tiny fraction of
+    the representable Unicode repertoire. Processing of text using more than
+    this repertoire is not possible with such an implementation.
+
+7.  For more about the problems with POSIX character classes in a Unicode
+    context see [Annex C: Compatibility Properties in Unicode
+    Technical Standard #18: Unicode Regular Expressions](http://www.unicode.org/reports/tr18/#Compatibility_Properties)
+    and see the mailing list archives for the unicode list (on unicode.org). See
+    also the ICU design document about [C/POSIX character
+    classes](https://htmlpreview.github.io/?https://github.com/unicode-org/icu-docs/blob/main/design/posix_classes.html).
+
+#### ICU
+
+ICU provides locale-independent access to all [Unicode
+properties](strings/properties.md) (except Unihan.txt properties), as well as to
+the POSIX character classes, via functions defined in `uchar.h` and in ICU4J's
+`UCharacter` class (see API references) as well as via `UnicodeSet`. The POSIX
+character classes are implemented according to the recommendations in UTS #18.
+
+The Unicode Character Database defines more than 70 character properties, their
+values are designed for the large character set as well as for real text
+processing, and they are updated with each version of Unicode. The UCD is
+available online, facilitating industry-wide consistency in the implementation
+of Unicode properties.
+
+## Formatting and Parsing
+
+### Currency Formatting
+
+#### POSIX
+
+The `strfmon()` function is used to format monetary values. The default format and
+the currency display symbol or display name are selected by the LC_MONETARY
+locale ID. The number formatting can also be controlled with a formatting string
+resembling what `printf()` uses.
+
+#### Problems
+
+1.  Selection of the currency via a locale ID is unreliable: Countries change
+    currencies over time, and the locale data for a particular country may not
+    be available. This results in using the wrong currency. For example, an
+    application may assume that a country has switched from a previous currency
+    to the Euro, but it may run on an OS that predates the switch.
+
+2.  Using a single locale ID for the whole format makes it very difficult to
+    format values for multiple currencies with the same number format (for
+    example, for an exchange rate list or for showing the price of an item
+    adjusted for several currencies). `strfmon()` allows to specify the number
+    format fully, but then the application cannot use a country's default number
+    format.
+
+3.  The set of formattable currencies is limited to those that are available via
+    locale IDs on a particular system.
+
+4.  There does not appear to be a function to parse currency values.
+
+#### ICU
+
+ICU number formatting APIs have separate, orthogonal settings for the number
+format, which can be selected with a locale ID, and the currency, which is
+specified with an ISO code. See the [Formatting
+Numbers](format_parse/numbers/index.md) chapter for details.

docs/userguide/icu/release.md

@@ -0,0 +1,33 @@
+---
+layout: default
+title: Release Info
+nav_order: 9
+parent: ICU
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Release Info
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## What Is New In The Current Release?
+
+See the [ICU download page](https://icu.unicode.org/download/) to find the subpage for the current release.
+
+The subpage for the current release will contain information on changes since the last release, bug fixes, known issues, changes to supported platforms and build environments, and migration issues for existing applications migrating from previous ICU releases. The page will also include an API Change Report, both for ICU4C and ICU4J, for a complete list of APIs added, removed, or changed in this release.
+
+Changes in previous releases can also be found the main [ICU download page](https://icu.unicode.org/download) in its version-specific subpages.
+
+## License Information
+
+The ICU projects (ICU4C and ICU4J) are hosted by the [Unicode Consortium](http://www.unicode.org/). The ICU binary and source files are distributed under the [UNICODE DATA FILES AND SOFTWARE LICENSE](http://www.unicode.org/copyright.html). The full copy of the license and third party software licenses are available in [LICENSE](https://github.com/unicode-org/icu/blob/main/icu4j/main/shared/licenses/LICENSE) file included in this package.

docs/userguide/icu/services.md

@@ -0,0 +1,379 @@
+---
+layout: default
+title: ICU Services
+nav_order: 4
+parent: ICU
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# ICU Services
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview of the ICU Services
+
+ICU enables you to write language-independent C/C++ and Java code that is used on
+separate, localized resources to get language-specific results. ICU supports
+many features, including language-sensitive text, dates, time, numbers,
+currency, message sorting, and searching. ICU provides language-specific results
+for a broad range of languages.
+
+### Strings, Properties and CharacterIterator
+
+ICU provides basic Unicode support for the following:
+
+*   [Unicode strings](strings/index.md)
+
+    ICU includes type definitions for UTF-16 strings and code points. It also
+    contains many C `u_string` functions and the C++ `UnicodeString` class with many
+    additional string functions.
+
+*   [Unicode properties](strings/properties.md)
+
+    ICU includes the C definitions and functions found in `uchar.h` as well as
+    some macros found in `utf.h`. It also includes the C++ Unicode class.
+
+*   [Unicode string iteration](strings/characteriterator.md)
+
+    In C, ICU uses the macros in `utf.h` for the iteration of strings. In C++, ICU
+    uses the characterIterator and its subclasses.
+
+### Conversion Basics
+
+A converter is used to transform text from one encoding type to another. In the
+case of Unicode, ICU transforms text from one encoding codepage to Unicode and
+back. An encoding is a mapping from a given character set definition to the
+actual bits used to represent the data.
+
+### Locale and Resources
+
+The ICU package contains the locale and resource bundles as well as the classes
+that implement them. Also, the ICU package contains the locale data (plain text
+resource bundles) and provides APIs to access and make use of that data in
+various services. Users need to understand these terms and the relationship
+between them.
+
+A locale identifies a group of users who have similar cultural and linguistic
+expectations for how their computers interact with them and process data. This
+is an abstract concept that is typically expressed by one of the following:
+
+A locale ID specifies a language and region enabling the software to support
+culturally and linguistically appropriate information for each user. A locale
+object represents a specific geographical, political, or cultural region. As a
+programmatic expression of locale IDs, ICU provides the C++ `Locale` class. In C,
+Application Programming Interfaces (APIs) use simple C `string` for locale IDs.
+
+ICU stores locale-specific data in resource bundles, which provide a general
+mechanism to access strings and other objects for ICU services to perform
+according to locale conventions. ICU contains data for its services to support
+many locales. Resource bundles contain the locale data of applications that use
+ICU. In C++, the `**ResourceBundle**` implements the locale data. In C, this
+feature is provided by the `**ures_**` interface.
+
+In addition to storing system-level data in ICU's resource bundles, applications
+typically also need to use resource bundles of their own to store
+locale-dependent application data. ICU provides the generic resource bundle APIs
+to access these bundles and also provides the tools to build them.
+
+> :point_right: **Note**: *Display strings, which are displayed to a user of a program, are bundled in a
+separate file instead of being embedded in the lines of the program.*
+
+### Locales and Services
+
+The interaction between locales and services is fundamental to ICU. Please refer
+to [Locales and Services](./locale/index#locales-and-services).
+
+### Transliteration
+
+Transliteration was originally designed to convert characters from one script to
+another (for example, from Greek to Latin, or Japanese Katakana to Latin). Now,
+transliteration is a more flexible mechanism that has pre-built transformations
+for case conversions, normalization conversions, the removal of given
+characters, and also for a variety of language and script transliterations.
+Transliterations can be chained together to perform a series of operations and
+each step of the process can use a UnicodeSet to restrict the characters that
+are affected. There are two basic types of transliterators:
+
+Most natural language transliterators (such as Greek-Latin) are written a
+rule-based transliterators.
+
+Transliterators can be written as text files using a
+simple language that is similar to regular expression syntax.
+
+### `Date` and `Time` Classes
+
+Date and time routines manage independent date and time functions in
+milliseconds since January 1, 1970 (0:00:00.000 UTC). Points in time before then
+are represented as negative numbers.
+
+ICU provides the following [classes](datetime/index.md) to support calendars and
+time zones:
+
+*   [`Calendar`](datetime/calendar/index#calendar)
+    
+    The abstract superclass for extracting calendar-related attributes from a `Date` value.
+
+*   [`GregorianCalendar`](datetime/calendar/index#gregoriancalendar)
+    
+    A concrete class for representing a Gregorian calendar.
+
+*   [`TimeZone`](datetime/timezone/index.md)
+    
+    An abstract superclass for representing a time zone.
+
+*   [`SimpleTimeZone`](datetime/timezone/index.md)
+    
+    A concrete class for representing a time zone for use with a Gregorian calendar.
+
+> :point_right: **Note**: *C classes provide the same functionality as the C++ classes with the exception
+of subclassing.*
+
+### Format and Parse
+
+Formatters translate between non-text data values and textual representations of
+those values. The result is a string of text that represents the internal value.
+A formatter can parse a string and convert a textual representation of some
+value (if it finds one it understands) back into its internal representation.
+For example, when the formatter reads the characters 1, 0, and 3 followed by
+something other than a digit, it produces the value 103 in its internal binary
+representation.
+
+A formatter takes a value and produces a user-readable string that represents
+that value or takes a string and parses it to produce a value.
+
+ICU provides the following areas and classes for general formatting, formatting
+numbers, formatting dates and times, and formatting messages:
+
+#### General Formatting
+
+See [Formatting and Parsing Classes](format_parse/index#formatting-and-parsing-classes) for an introduction to the following:
+
+* `Format`
+* `FieldPosition`
+* `ParsePosition`
+* `Formattable`
+
+#### Formatting Numbers
+
+*   [`NumberFormat`](format_parse/numbers/index#formatting-numbers)
+    NumberFormat provides the basic fields and methods to format number objects
+    and number primitives into localized strings and parse localized strings to
+    number objects.
+
+*   [`DecimalFormat`](format_parse/numbers/index#decimalformat)
+    DecimalFormat provides the methods used to format number objects and number
+    primitives into localized strings and parse localized strings into number
+    objects in base 10.
+
+*   [`DecimalFormatSymbols`](format_parse/numbers/index#decimalformatsymbols)
+    DecimalFormatSymbols is a concrete class used by DecimalFormat to access
+    localized number strings such as the grouping separators, the decimal
+    separator, and the percent sign.
+
+#### Formatting Dates and Times
+
+*   [`DateFormat`](format_parse/datetime/index.md)
+    
+    `DateFormat` provides the basic fields and methods for formatting date objects
+    to localized strings and parsing date and time strings to date objects.
+
+*   [`SimpleDateFormat`](format_parse/datetime/index.md)
+    
+    `SimpleDateFormat` is a concrete class used to format date objects to
+    localized strings and to parse date and time strings to date objects using a
+    `GregorianCalendar`.
+
+*   [`DateFormatSymbols`](format_parse/datetime/index.md)
+    
+    `DateFormatSymbols` is a concrete class used to access localized date and time
+    formatting strings, such as names of the months, days of the week, and the
+    time zone.
+
+#### Formatting Messages
+
+*   [`MessageFormat`](format_parse/messages/index.md)
+    
+    `MessageFormat` is a concrete class used to produce a language-specific user
+    message that contains numbers, currency, percentages, date, time, and string
+    variables.
+
+*   [`ChoiceFormat`](format_parse/messages/index.md)
+    
+    `ChoiceFormat` is a concrete class used to map strings to ranges of numbers
+    and to handle plural words and name series in user messages.
+
+> :point_right: **Note**: *C classes provide the same functionality as the C++ classes with the exception
+of subclassing.*
+
+### Searching and Sorting
+
+Sorting and searching non-English text presents a number of challenges that many
+English speakers are unaware of. The primary source of difficulty is accents,
+which have very different meanings in different languages, and sometimes even
+within the same language:
+
+*   Many accented letters, such as the é in café, are treated as minor variants
+    on the letter that is accented.
+
+*   Sometimes the accented form of a letter is treated as a distinct letter for
+    the purposes of comparison. For example, Å in Danish is treated as a
+    separate letter that sorts just after Z.
+
+*   In some cases, an accented letter is treated as if it were two letters. In
+    traditional German, for example, ä is compared as if it were ae.
+
+Searching and sorting is done through collation using the `Collator` class and its
+sub-classes `RuleBasedCollator` and `CollationElementIterator` as well as the
+`CollationKey` object. Collation determines the proper sort sequence for two or
+more natural language strings. It also can determine if two strings are
+equivalent for the purpose of searching.
+
+The `Collator` class and its sub-class `RuleBasedCollator` perform locale-sensitive
+string comparisons to create sorting and searching routines for natural language
+text. `Collator` and `RuleBasedCollator` can distinguish between characters
+associated with base characters (such as 'a' and 'b'), accent marks (such as
+'ò', 'ó'), and uppercase or lowercase properties (such as 'a' and 'A').
+
+ICU provides the following collation classes for sorting and searching natural
+language text according to locale-specific rules:
+
+*   [`Collator`](collation/architecture.md) is the abstract base class of all classes that compare strings.
+
+*   [`CollationElementIterator`](collation/architecture.md) is a concrete iterator class that provides an
+    iterator for stepping through each character of a locale-specific string
+    according to the rules of a specific collator object.
+
+*   [`RuleBasedCollator`](collation/architecture.md) is the only built-in 
+    implementation of the collator. It
+    provides a sophisticated mechanism for comparing strings in a
+    language-specific manner, and an interface that allows the user to
+    specifically customize the sorting order.
+
+*   [`CollationKey`](collation/architecture.md)  is an object that enables the fast sorting of strings by
+    representing a string as a sort key under the rules of a specific collator
+    object.
+
+> :point_right: **Note**: *C classes provide the same functionality as the C++ classes with the exception
+of subclassing.*
+
+### Text Analysis
+
+The BreakIterator services can be used for formatting and handling text;
+locating the beginning and ending points of a word; counting words, sentences,
+and paragraphs; and listing unique words. Specifically, text operations can be
+done to locate the following linguistic boundaries:
+
+*   Display text on the screen and locate places in the text where the
+    BreakIterator can perform word-wrapping to fit the text within the margins
+
+*   Locate the beginning and end of a word that the user has selected
+
+*   Count graphemes (or characters), words, sentences, or paragraphs
+
+*   Determine how far to move in the text store when the user hits an arrow key
+    to move forward or backward one grapheme
+
+*   Make a list of all the unique words in a document
+
+*   Figure out whether or not a range of text contains only whole words
+
+*   Capitalize the first letter of each word
+
+*   Extract a particular unit from the text such as "find me the third grapheme
+    in this document"
+
+The BreakIterator services were designed and developed around an "iterator" or
+"cursor" style of interface. The object points to a particular place in the
+text. You can move the pointer forward or backward to search the text for
+boundaries.
+
+The `BreakIterator` class makes it possible to iterate over user characters. A
+`BreakIterator` can find the location of a character, word, sentence or potential
+line-break boundary. This makes it possible for a software program to properly
+select characters for text operations such as highlighting a character, cutting
+a word, moving to the next sentence, or wrapping words at a line ending.
+`BreakIterator` performs these operations in a locale-sensitive manner, meaning
+that it recognizes text boundaries according to the particular locale ID.
+
+ICU provides the following classes for iterating over locale-specific text:
+
+*   [`BreakIterator`](boundaryanalysis/index.md)
+    
+    The abstract base class that defines the operations for finding and getting
+    the positions of logical breaks in a string of text: characters, words,
+    sentences, and potential line breaks.
+
+*   [`CharacterIterator`](strings/characteriterator.md)
+    
+    The abstract base class for forward and backward iteration over a string of
+    Unicode characters.
+
+*   [`StringCharacterIterator`](strings/index.md)
+    
+    A concrete class for forward and backward iteration over a string of Unicode
+    characters. `StringCharacterIterator` inherits from `CharacterIterator`.
+
+### Paragraph Layout
+
+See [Paragraph Layout](./layoutengine/paragraph.md) for more details.
+
+## Locale-Dependent Operations
+
+Many of the ICU classes are locale-sensitive, meaning that you have to create a
+different one for each locale.
+
+| C API | C++ Class | Description |
+|----------|--------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ubrk_` | `BreakIterator` | The `BreakIterator` class implements methods to find the location of boundaries in the text. |
+| `ucal_` | `Calendar` | The `Calendar` class is an abstract base class that converts between a `UDate` object and a set of integer fields such as `YEAR`, `MONTH`, `DAY`, `HOUR`, and so on. |
+| `umsg.h` | `ChoiceFormat` | A `ChoiceFormat` class enables you to attach a format to a range of numbers. |
+| `ucol_` | `CollationElementIterator` | The `CollationElementIterator` class is used as an iterator to walk through each character of an international string. |
+| `ucol_` | `CollationKey` | The `Collator` class generates the Collation keys. |
+| `ucol_` | `Collator` | The `Collator` class performs locale-sensitive string comparison. |
+| `udat_` | `DateFormat` | `DateFormat` is an abstract class for a family of classes. `DateFormat` converts dates and times from their internal representations to a textual form that is language-independent, and then back to their internal representations. |
+| `udat_` | `DateFormatSymbols` | `DateFormatSymbols` is a public class that encapsulates localized date and time formatting data. This information includes time zone information. |
+| `unum_` | `DecimalFormatSymbols` | This class represents the set of symbols needed by `DecimalFormat` to format numbers. |
+| `umsg.h` | `Format` | The `Format` class is the base class for all formats. |
+| `ucal_` | `GregorianCalendar` | `GregorianCalendar` is a concrete class that provides the standard calendar used in many locations. |
+| `uloc_` | `Locale` | A `Locale` object represents a specific geographical, political, or cultural region. |
+| `umsg.h` | `MessageFormat` | `MessageFormat` provides a means to produce concatenated messages in language-neutral way. |
+| `unum_` | `NumberFormat` | `NumberFormat` is an abstract base class for all number formats. |
+| `ures_` | `ResourceBundle` | `ResourceBundle` provides a means to access a collection of locale-specific information. |
+| `ucol_` | `RuleBasedCollator` | The `RuleBasedCollator` provides the implementation of the `Collator` class using data-driven tables. |
+| `udat_` | `SimpleDateFormat` | `SimpleDateFormat` is a concrete class used to format and parse dates in a language-independent way. |
+| `ucal_` | `SimpleTimeZone` | `SimpleTimeZone` is a concrete subclass of `TimeZone` that represents a time zone for use with a Gregorian calendar. |
+| `usearch_` | `StringSearch` | `StringSearch` provides a way to search text in a locale sensitive manner. |
+| `ucal_` | `TimeZone` | `TimeZone` represents a time zone offset, and also determines daylight savings time settings. |
+
+## Locale-Independent Operations
+
+The following ICU services can be used in all locales as they provide
+locale-independent services and users do not need to specify a locale ID:
+
+| C API | C++ Class | Description |
+|-----------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `ubidi_` |  | `UBiDi` is used for implementing the Unicode BiDi algorithm. |
+| `utf.h` | `CharacterIterator` | `CharacterIterator` is an abstract class that defines an API for iteration on text objects. It is an interface for forward and backward iteration and for the random access of a text object. Also, it provides backward compatibility to the Java and older ICU `CharacterIterator` classes. |
+| n/a | `Formattable` | `Formattable` is a thin wrapper class that converts between the primitive numeric types (`double`, `long`, and so on) and the `UDate` and `UnicodeString` classes. `Formattable` objects can be passed to the `Format` class or its subclasses for formatting. |
+| `unorm_` | `Normalizer` | `Normalizer` transforms Unicode text into an equivalent composed or decomposed form to allow for easier sorting and searching of text. |
+| n/a | `ParsePosition` | `ParsePosition` is a simple class used by the `Format` class and its subclasses to keep track of the current position during parsing. |
+| `uidna_` |  | An implementation of the IDNA protocol as defined in RFC 3490. |
+| `utf.h` | `StringCharacterIterator` | A concrete subclass of `CharacterIterator` that iterates over the characters (code units or code points) in a `UnicodeString`. |
+| `utf.h` | `UCharCharacterIterator` | A concrete subclass of `CharacterIterator` that iterates over the characters (code units or code points) in a `UChar` array. |
+| `uchar.h` |  | The Unicode character properties API allows you to query the properties associated with individual Unicode character values. |
+| `uregex_` | `RegexMatcher` | `RegexMatcher` is a regular expressions implementation. This allows you to perform string matching based upon a pattern. |
+| `utrans_` | `Transliterator` | `Transliterator` is an abstract class that transliterates text from one format to another. The most common type of transliterator is a script, or an alphabet. |
+| `uset_` | `UnicodeSet` | Objects of the `UnicodeSet` class represent character classes used in regular expressions. These classes specify a subset of the set of all Unicode characters. This is a mutable set of Unicode characters. |
+| `ustring.h` | `UnicodeString` | `UnicodeString` is a string class that stores Unicode characters directly. This class is a concrete implementation of the abstract class `Replaceable`. |
+| `ushape.h` |  | Provides operations to transform (shape) between Arabic characters and their presentation forms. |
+| `ucnv_` |  | The Unicode conversion API allows you to convert data written in one codepage/encoding to and from UTF-16. |

docs/userguide/icu/unicode.md

@@ -0,0 +1,545 @@
+---
+layout: default
+title: Unicode Basics
+nav_order: 3
+parent: ICU
+---
+<!--
+© 2020 and later: Unicode, Inc. and others.
+License & terms of use: http://www.unicode.org/copyright.html
+-->
+
+# Unicode Basics
+{: .no_toc }
+
+## Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Introduction to Unicode
+
+Unicode is a standard that precisely defines a character set as well as a small
+number of encodings for it. It enables you to handle text in any language
+efficiently. It allows a single application executable to work for a global
+audience. ICU, like Java™, Microsoft® Windows NT™, Windows™ 2000 and other
+modern systems, provides Internationalization solutions based on Unicode.
+
+This chapter is intended as an introduction to codepages in general and Unicode
+in particular. For further information, see:
+
+1.  [The Web site of the Unicode consortium](http://www.unicode.org/)
+
+2.  [What is
+    Unicode?](https://www.unicode.org/standard/WhatIsUnicode.html)
+
+3.  [IBM® Globalization](http://www.ibm.com/software/globalization/)
+
+Go to the [online ICU demos](https://icu4c-demos.unicode.org/icu-bin/icudemos) to
+see how a Unicode-based server application can handle text in many languages and
+many encodings.
+
+## Traditional Character Sets and Unicode
+
+Representing text-format data in computers is a matter of defining a set of
+characters and assigning each of them a number and a bit representation.
+Underlying this basic idea are three related concepts:
+
+1.  A character set or repertoire is an unordered collection of characters that
+    can be represented by numeric values.
+
+2.  A coded character set maps characters from a character set or repertoire to
+    numeric values.
+
+3.  A character encoding scheme defines the representation of numeric values
+    from one or more coded character sets in bits and bytes.
+
+For simple encodings such as ASCII, the last two concepts are basically the
+same: ASCII assigns 128 characters and control codes to consecutive numbers from
+0 to 127. These characters and control codes are encoded as simple, unsigned,
+binary integers. Therefore, ASCII is both a coded character set and a character
+encoding scheme.
+
+ASCII only encodes 128 characters, 33 of which are control codes rather than
+graphic, displayable characters. It was designed to represent English-language
+text for an American user base, and is therefore insufficient for representing
+text in almost any language other than American English. In fact, most
+traditional encodings were limited to one or few languages and scripts.
+
+ASCII offered a natural way to extend it: Designed in the 1960's to work in
+systems with 7-bit bytes while most computers and Internet protocols since the
+1970's use 8-bit bytes, the extra bit allowed another 128 byte values to
+represent more characters. Various encodings were developed that supported
+different languages. Some of these were based on ASCII, others were not.
+
+Languages such as Japanese need to encode considerably more than 256 characters.
+Various encoding schemes enable large character sets with thousands or tens of
+thousands of characters to be represented. Most of those encodings are still
+byte-based, which means that many characters require two or more bytes of
+storage space. A process must be developed to interpret some byte values.
+
+Various character sets and encoding schemes have been developed independently,
+cover only one or few languages each, and are incompatible. This makes it very
+difficult for a single system to handle text in more than one language at a
+time, and especially difficult to do so in a way that is interoperable across
+different systems.
+
+Generally, the minimum requirement for the interoperable exchange of text data
+is that the encoding (character set & encoding scheme) must be properly
+specified in the document and in the protocol. For example, email/SMTP and
+HTML/HTTP provide the means to specify the "charset", as it is called in
+Internet standards. However, very often the encoding is not specified, specified
+incorrectly, or the sender and receiver disagree on its implementation.
+
+The ISO 2022 encoding scheme was created to store text in many different
+languages. It allows other encodings to be embedded by first announcing them and
+then switching between them. Full support for all features and possible
+encodings with ISO 2022 requires complicated processing and the need to support
+many encodings. For East Asian languages, subsets were developed that cover only
+one language or a few at a time, but they are much more manageable. ISO 2022 is
+not well-suited for use in internal processing. It is designed for data
+exchange.
+
+## Glyphs versus Characters
+
+Programmers often need to distinguish between characters and glyphs. A character
+is the smallest semantic unit in a writing system. It is an abstract concept
+such as the letter A or the exclamation point. A glyph is the visual
+presentation of one or more characters, and is often dependent on adjacent
+characters.
+
+There is not always a one-to-one mapping between characters and glyphs. In many
+languages (Arabic is a prime example), the way a character looks depends heavily
+on the surrounding characters. Standard printed Arabic has as many as four
+different printed representations (glyphs) for every letter of the alphabet. In
+many languages, two or more letters may combine together into a single glyph
+(called a ligature), or a single character might be displayed with more than one
+glyph.
+
+Despite the different visual variants of a particular letter, it still retains
+its identity. For example, the Arabic letter heh has four different visual
+representations in common use. Whichever one is used, it still keeps its
+identity as the letter heh. It is this identity that Unicode encodes, not the
+visual representation. This also cuts down on the number of independent
+character values required.
+
+## Overview of Unicode
+
+Unicode was developed as a single-coded character set that contains support for
+all languages in the world. The first version of Unicode used 16-bit numbers,
+which allowed for encoding 65,536 characters without complicated multibyte
+schemes. With the inclusion of more characters, and following implementation
+needs of many different platforms, Unicode was extended to allow more than one
+million characters. Several other encoding schemes were added. This introduced
+more complexity into the Unicode standard, but far less than managing a large
+number of different encodings.
+
+Starting with Unicode 2.0 (published in 1996), the Unicode standard began
+assigning numbers from 0 to 10ffff<sub>16</sub>,which requires 21 bits but does not use
+them completely. This gives more than enough room for all written languages in
+the world. The original repertoire covered all major languages commonly used in
+computing. Unicode continues to grow, and it includes more scripts.
+
+The design of Unicode differs in several ways from traditional character sets
+and encoding schemes:
+
+1.  Its repertoire enables users to include text efficiently in almost all
+    languages within a single document.
+
+2.  It can be encoded in a byte-based way with one or more bytes per character,
+    but the default encoding scheme uses 16-bit units that allow much simpler
+    processing for all common characters.
+
+3.  Many characters, such as letters with accents and umlauts, can be combined
+    from the base character and accent or umlaut modifiers. This combining
+    reduces the number of different characters that need to be encoded
+    separately. "Precomposed" variants for characters that existed in common
+    character sets at the time were included for compatibility.
+
+4.  Characters and their usage are well-defined and described. While traditional
+    character sets typically only provide the name or a picture of a character
+    and its number and byte encoding, Unicode has a comprehensive database of
+    properties available for download. It also defines a number of processes and
+    algorithms for dealing with many aspects of text processing to make it more
+    interoperable.
+
+The early inclusion of all characters of commonly used character sets makes
+Unicode a useful "pivot" point for converting between traditional character
+sets, and makes it feasible to process non-Unicode text by first converting into
+Unicode, process the text, and convert it back to the original encoding without
+loss of data.
+
+> :point_right: *The first 128 Unicode code point values are assigned to the same characters as
+in US-ASCII. For example, the same number is assigned to the same character. The
+same is true for the first 256 code point values of Unicode compared to ISO
+8859-1 (Latin-1) which itself is a direct superset of US-ASCII. This makes it
+easy to adapt many applications to Unicode because the numbers for many
+syntactically important characters are the same.*
+
+## Character Encoding Forms and Schemes for Unicode
+
+Unicode assigns characters a number from 0 to 10FFFF<sub>16</sub>, giving enough elbow room
+to allow for unambiguous encoding of every character in common use. Such a
+character number is called a "code point".
+
+> :point_right: *Unicode code points are just non-negative integer numbers in a certain range.
+They do not have an implicit binary representation or a width of 21 or 32 bits.
+Binary representation and unit widths are defined for encoding forms.*
+
+For internal processing, the standard defines three encoding forms, and for file
+storage and protocols, some of these encoding forms have encoding schemes that
+differ in their byte ordering. The difference between an encoding form and an
+encoding scheme is that an encoding form maps the character set codes to values
+that fit into internal data types (like a short in C), while an encoding scheme
+maps to bits and bytes. For traditional encodings, they are the same since the
+encoding forms already map to bytes. 
+
+The different Unicode encoding forms are optimized for a variety of different
+uses:
+
+1.  UTF-16, the default encoding form, maps a character code point to either one
+    or two 16-bit integers.
+
+2.  UTF-8 is a byte-based encoding that offers backwards compatibility with
+    ASCII-based, byte-oriented APIs and protocols. A character is stored with 1,
+    2, 3, or 4 bytes.
+
+3.  UTF-32 is the simplest, but most memory-intensive encoding form: It uses one
+    32-bit integer per Unicode character.
+
+4.  SCSU is an encoding scheme that provides a simple compression of Unicode
+    text. It is designed only for input and output, not for internal use.
+
+ICU uses UTF-16 internally. ICU 2.0 fully supports supplementary characters
+(with code points 10000<sub>16</sub>..10FFFF<sub>16</sub>). Older versions of ICU provided only partial
+support for supplementary characters.
+
+For input/output, character encoding schemes define a byte serialization of
+text. UTF-8 is itself both an encoding form, and an encoding scheme because it is
+byte-based. For each of UTF-16 and UTF-32, there are two variants defined: one
+that serializes the code units in big-endian byte order (most significant byte
+first), and one that serializes the code units in little-endian byte order
+(least significant byte first). The corresponding encoding schemes are called
+UTF-16BE, UTF-16LE, UTF-32BE, and UTF-32LE.
+
+> :point_right: *The names "UTF-16" and "UTF-32" are ambiguous. Depending on context, they refer
+either to character encoding forms where 16/32-bit words are processed and are
+naturally stored in the platform endianness, or they refer to the
+IANA-registered charset names, i.e., to character encoding schemes or byte
+serializations. In addition to simple byte serialization, the charsets with
+these names also use optional Byte Order Marks (see [Serialized Formats](#serialized-formats) below).*
+
+## Overview of UTF-16
+
+The default encoding form of the Unicode Standard uses 16-bit code units. Code
+point values for the most common characters are in the range of 0 to FFFF<sub>16</sub> and
+are encoded with just one 16-bit unit of the same value. Code points from
+10000<sub>16</sub> to 10FFFF<sub>16</sub> are encoded with two code units that are often called
+"surrogates", and they are called a "surrogate pair" when, together, they
+correctly encode one Unicode character. The first surrogate in a pair must be in
+the range D800<sub>16</sub> to DBFF<sub>16</sub>, and the second one must be in the range DC00<sub>16</sub> to
+DFFF<sub>16</sub>. Every Unicode code point has only one possible UTF-16 encoding with
+either one code unit that is not a surrogate or with a correct pair of
+surrogates. The code point values D800<sub>16</sub> to DFFF<sub>16</sub> are set aside just for this
+mechanism and will never, by themselves, be assigned any characters.
+
+Most commonly used characters have code points below FFFF<sub>16</sub>, but Unicode 3.1
+assigns more than 40,000 supplementary characters that make use of surrogate
+pairs in UTF-16.
+
+Note that comparing UTF-16 strings lexically based on their 16-bit code units
+does not result in the same order as comparing the code points. This is not
+usually an issue since only rarely-used characters are affected. Most processes
+do not rely on the same results in such comparisons. Where necessary, a simple
+modification to a string comparison can be performed that still allows efficient
+code unit-based comparisons and makes them compatible with code point
+comparisons. ICU has C and C++ API functions for this.
+
+## Overview of UTF-8
+
+To meet the requirements of byte-oriented, ASCII-based systems, the Unicode
+Standard defines UTF-8. UTF-8 is a variable-length, byte-based encoding that
+preserves ASCII transparency.
+
+UTF-8 maintains transparency for all the ASCII code values (0..127). These
+values do not appear in any byte of a transformed result except as the direct
+representation of the ASCII values. Thus, ASCII text is also UTF-8 text.
+
+Characteristics of UTF-8 include:
+
+1.  Unicode code points 0 to 7F<sub>16</sub> are each encoded with a single byte of the
+    same value. Therefore, ASCII characters take up 50% less space with UTF-8
+    encoding than with UTF-16.
+
+2.  All other code points are encoded with multibyte sequences, with the first
+    byte (lead byte) indicating the number of bytes that follow (trail bytes).
+    This results in very efficient parsing. The lead bytes are in the range c0<sub>16</sub>
+    to fd<sub>16</sub>, the trail bytes are in the range 80<sub>16</sub> to bf<sub>16</sub>. The byte values fe<sub>16</sub>
+    and FF<sub>16</sub> are never used.
+
+3.  UTF-8 is relatively compact and resource conservative in its use of the
+    bytes required for encoding text in European scripts, but uses 50% more
+    space than UTF-16 for East Asian text. Code points up to 7FF<sub>16</sub> take up two
+    bytes, code points up to FFFF<sub>16</sub> take up three (50% more memory than UTF-16),
+    and all others four.
+
+4.  Binary comparisons of UTF-8 strings based on their bytes result in the same
+    order as comparing code point values.
+
+## Overview of UTF-32
+
+The UTF-32 encoding form always uses one single 32-bit integer per Unicode code
+point. This results in a very simple encoding.
+
+The drawback is its memory consumption: Since code point values use only 21
+bits, one-third of the memory is always unused, and since most commonly used
+characters have code point values of up to FFFF<sub>16</sub>, they take up only one 16-bit
+unit in UTF-16 (50% less) and up to three bytes in UTF-8 (25% less).
+
+UTF-32 is mainly used in APIs that are defined with the same data type for both
+code points and code units. Modern versions of the C standard library that
+support Unicode use a 32-bit `wchar_t` with UTF-32 semantics.
+
+## Overview of SCSU
+
+SCSU (Standard Compression Scheme for Unicode) is designed to reduce the size of
+Unicode text for both input and output. It is a simple compression that
+transforms the text into a byte stream. It typically uses one byte per character
+in small scripts, and two bytes per character in large, East Asian scripts.
+
+It is usually shorter than any of the UTFs. However, SCSU is stateful, which
+makes it unsuitable for internal processing. It also uses all possible byte
+values, which might require additional processing for protocols such as SMTP
+(email).
+
+See also <https://www.unicode.org/reports/tr6/> .
+
+## Other Unicode Encodings
+
+Other Unicode encodings have been developed over time for various purposes. Most
+of them are implemented in ICU, see
+[source/data/mappings/convrtrs.txt](https://github.com/unicode-org/icu/blob/main/icu4c/source/data/mappings/convrtrs.txt)
+
+1.  BOCU-1: Binary-Ordered Compression of Unicode
+    An encoding of Unicode that is about as compact as SCSU but has a much
+    smaller amount of state. Unlike SCSU, it preserves code point order and can
+    be used in 8bit emails without a transfer encoding. BOCU-1 does **not**
+    preserve ASCII characters in ASCII-readable form. See [Unicode Technical
+    Note #6](http://www.unicode.org/notes/tn6/) .
+
+2.  UTF-7: Designed for 7bit emails; simple and not very compact. Since email
+    systems have been 8-bit safe for several years, UTF-7 is not necessary any
+    more and not recommended. Most ASCII characters are readable, others are
+    base64-encoded. See [RFC 2152](http://www.ietf.org/rfc/rfc2152.txt) .
+
+3.  IMAP-mailbox-name: A variant of UTF-7 that is suitable for expressing
+    Unicode strings as ASCII characters for Unix filenames.
+    **The name "IMAP-mailbox-name" is specific to ICU!**
+    See [RFC 2060 INTERNET MESSAGE ACCESS PROTOCOL - VERSION
+    4rev1](http://www.ietf.org/rfc/rfc2060.txt) section 5.1.3. Mailbox
+    International Naming Convention.
+
+4.  UTF-EBCDIC: An EBCDIC-friendly encoding that is similar to UTF-8. See
+    [Unicode Technical Report #16](http://www.unicode.org/reports/tr16/) . **As
+    of ICU 2.6, UTF-EBCDIC is not implemented in ICU.**
+
+5.  CESU-8: Compatibility Encoding Scheme for UTF-16: 8-Bit
+    An incompatible variant of UTF-8 that preserves 16-bit-Unicode (UTF-16)
+    string order instead of code point order. Not for open interchange. See
+    [Unicode Technical Report #26](http://www.unicode.org/reports/tr26/) .
+
+## Programming using UTFs
+
+Programming using any of the UTFs is much more straightforward than with
+traditional multi-byte character encodings, even though UTF-8 and UTF-16 are
+also variable-width encodings.
+
+Within each Unicode encoding form, the code unit values for singletons (code
+units that alone encode characters), lead units, and for trailing units are all
+disjointed. This has crucial implications for implementations. The following
+lists these implications:
+
+1.  Determines the number of units for one code point using the lead unit. This
+    is especially important for UTF-8, where there can be up to 4 bytes per
+    character.
+
+2.  Determines boundaries. If ICU users randomly access text, you can always
+    determine the nearest code-point boundaries with a small number of machine
+    instructions.
+
+3.  Does not have any overlap. If ICU users search for string A in string B, you
+    never get a false match on code points. Users do not need to convert to code
+    points for string searching. False matches never occurs since the end of one
+    sequence is never the same as the start of another sequence. Overlap is one
+    of the biggest problems with common multi-byte encodings like Shift-JIS. All
+    the UTFs avoid this problem.
+
+4.  Uses simple iteration. Getting the next or previous code point is
+    straightforward, and only takes a small number of machine instructions.
+
+5.  Can use UTF-16 encoding, which is actually fully symmetric. ICU users can
+    determine from any single code unit whether it is the first, last, or only
+    one for a code point. Moving (iterating) in either direction through UTF-16
+    text is equally fast and efficient.
+
+6.  Uses slow indexing by code points. This indexing procedure is a disadvantage
+    of all variable-width encodings. Except in UTF-32, it is inefficient to find
+    code unit boundaries corresponding to the nth code point or to find the code
+    point offset containing the nth code unit. Both involve scanning from the
+    start of the text or from a last known boundary. ICU, like most common APIs,
+    always indexes by code units. It counts code units and not code points.
+
+Conversion between different UTFs is very fast. Unlike converting to and from
+legacy encodings like Latin-2, conversion between UTFs does not require table
+look-ups.
+
+ICU provides two basic data type definitions for Unicode. `UChar32` is a 32-bit
+type for code points, and used for single Unicode characters. It may be signed
+or unsigned. It is the same as `wchar_t` if it is 32 bits wide. `UChar` is an
+unsigned 16-bit integer for UTF-16 code units. It is the base type for strings
+(`UChar *`), and it is the same as `wchar_t` if it is 16 bits wide.
+
+Some higher-level APIs, used especially for formatting, use characters closer to
+a representation for a glyph. Such "user characters" are also called "graphemes"
+or "grapheme clusters" and require strings so that combining sequences can be
+included.
+
+## Serialized Formats
+
+In files, input, output, and network protocols, text must be accompanied by the
+specification of its character encoding scheme for a client to be able to
+interpret it correctly. (This is called a "charset" in Internet protocols.)
+However, an encoding scheme specification is not necessary if the text is only
+used within a single platform, protocol, or application where it is otherwise
+clear what the encoding is. (The language and text directionality should usually
+be specified to enable spell checking, text-to-speech transformation, etc.)
+
+*The discussion of encoding specifications in this section applies to standard
+Internet protocols where charset name strings are used. Other protocols may use
+numeric encoding identifiers and assign different semantics to those identifiers
+than Internet protocols.*
+
+Typically, the encoding specification is done in a protocol- and document
+format-dependent way. However, the Unicode standard offers a mechanism for
+tagging text files with a "signature" for cases where protocols do not identify
+character encoding schemes.
+
+The character ZERO WIDTH NO-BREAK SPACE (FEFF<sub>16</sub>) can be used as a signature by
+prepending it to a file or stream. The alternative function of U+FEFF as a
+format control character has been copied to U+2060 WORD JOINER, and U+FEFF
+should only be used for Unicode signatures.
+
+The different character encoding schemes generate different, distinct byte
+sequences for U+FEFF:
+
+1.  UTF-8: EF BB BF
+
+2.  UTF-16BE: FE FF
+
+3.  UTF-16LE: FF FE
+
+4.  UTF-32BE: 00 00 FE FF
+
+5.  UTF-32LE: FF FE 00 00
+
+6.  SCSU: 0E FE FF
+
+7.  BOCU-1: FB EE 28
+
+8.  UTF-7: 2B 2F 76 ( 38 | 39 | 2B | 2F )
+
+9.  UTF-EBCDIC: DD 73 66 73
+
+ICU provides the function `ucnv_detectUnicodeSignature()` for Unicode signature
+detection.
+
+*There is no signature for CESU-8 separate from the one for UTF-8. UTF-8 and
+CESU-8 encode U+FEFF and in fact all BMP code points with the same bytes. The
+opportunity for misidentification of one as the other is one of the reasons why
+CESU-8 should only be used in limited, closed, specific environments.*
+
+In UTF-16 and UTF-32, where the signature also distinguishes between big-endian
+and little-endian byte orders, it is also called a byte order mark (BOM). The
+signature works for UTF-16 since the code point that has the byte-swapped
+encoding, FFFE<sub>16</sub>, will never be a valid Unicode character. (It is a
+"non-character" code point.) In Internet protocols, if an encoding specification
+of "UTF-16" or "UTF-32" is used, it is expected that there is a signature byte
+sequence (BOM) that identifies the byte ordering, which is not the case for the
+encoding scheme/charset names with "BE" or "LE".
+
+*If text is specified to be encoded in the UTF-16 or UTF-32 charset and does not
+begin with a BOM, then it must be interpreted as UTF-16BE or UTF-32BE,
+respectively.*
+
+A signature is not part of the content, and must be stripped when processing.
+For example, blindly concatenating two files will give an incorrect result.
+
+If a signature was detected, then the signature "character" U+FEFF should be
+removed from the Unicode stream **after** conversion. Removing the signature
+bytes before conversion could cause the conversion to fail for stateful
+encodings like BOCU-1 and UTF-7.
+
+Whether a signature is to be recognized or not depends on the protocol or
+application.
+
+1.  If a protocol specifies a charset name, then the byte stream must be
+    interpreted according to how that name is defined. Only the "UTF-16" and
+    "UTF-32" names include recognition of the byte order marks that are specific
+    to them (and the ICU converters for these names do this automatically). None
+    of the other Unicode charsets are defined to include any signature/BOM
+    handling.
+
+2.  If no charset name is provided, for example for text files in most
+    filesystems, then applications must usually rely on heuristics to determine
+    the file encoding. Many document formats contain an embedded or implicit
+    encoding declaration, but for plain text files it is reasonable to use
+    Unicode signatures as simple and reliable heuristics. This is especially
+    common on Windows systems. However, some tools for plain text file handling
+    (e.g., many Unix command line tools) are not prepared for Unicode
+    signatures.
+
+## The Unicode Standard Is An Industry Standard
+
+The Unicode standard is an industry standard and parallels ISO 10646-1. Around
+1993, these two standards were effectively merged into the same character set
+standard. Both standards have the same character repertoire and the same
+encoding forms and schemes.
+
+One difference used to be that the ISO standard defined code point values to be
+from 0 to 7FFFFFFF<sub>16</sub>, not just up to 10FFFF<sub>16</sub>. The ISO work group decided to add
+an amendment to the standard. The amendment removes this difference by declaring
+that no characters will ever be assigned code points above 10FFFF<sub>16</sub>. The main
+reason for the ISO work group's decision is interoperability between the UTFs.
+UTF-16 can not encode any code points above this limit.
+
+This means that the code point space for both Unicode and ISO 10646 is now the
+same! **These changes to ISO 10646 have been made recently and should be
+complete in the edition ISO 10646:2003 which also combines all parts of the
+standard into one.**
+
+The former, larger code space is the reason why the ISO definition of UTF-8
+specifies sequences of five and six bytes to cover that whole range.
+
+Another difference is that the ISO standard defines encoding forms "UCS-4" and
+"UCS-2". UCS-4 is essentially UTF-32 with a theoretical upper limit of
+7FFFFFFF<sub>16</sub>, using 31 out of the 32 bits. However, in practice, the ISO committee
+has accepted that the characters above 10FFFF will not be encoded, so there is
+essentially no difference between the forms. The "4" stands for "four-byte
+form".
+
+UCS-2 is a subset of UTF-16 that is limited to code points from 0 to FFFF,
+excluding the surrogate code points. Thus, it cannot represent the characters
+with code points above FFFF (called supplementary characters).
+
+*There is no conversion necessary between UCS-2 and UTF-16. The difference is
+only in the interpretation of surrogates.*
+
+The standards differ in what kind of information they provide: The Unicode
+standard provides more character properties and describes algorithms etc., while
+the ISO standard defines collections, subsets and similar.
+
+The standards are synchronized, and the respective committees work together to
+add new characters and assign code point values.