Lines Matching +full:all +full:- +full:apis
1 ---
6 ---
7 <!--
10 -->
16 {: .no_toc .text-delta }
21 ---
53 See [Adoption of Objects](#adoption-of-objects) for further information.
63 } else if(pBiDi==nullptr || (length=pBiDi->length)<=0) {
76 Note: *Callers* (as opposed to implementers) of ICU APIs can simplify their code
98 return 0; // or calling UErrorCode-less
107 UnicodeString result = ((PluralRules*)uplrules)->select(number);
114 If the API function is non-const, then it should have a `UErrorCode` parameter.
134 set, but like exceptions it does not work well for non-failure information
140 * Use real APIs to get the same information if possible.
142 NUL-terminated, then `U_STRING_NOT_TERMINATED_WARNING` indicates this, but so
146 NUL-terminated strings but to use the length.)
152 real API replacements for all existing warning codes.
158 out-of-memory condition) but do not take a `UErrorCode` parameter and can
162 * A bogus object cannot be modified except with assignment-like functions.
180 "`@draft ICU 4.8`". For details of how we mark APIs see the "ICU API
182 Java, also see existing @draft APIs for complete examples.
202 #### Embedding Coding Examples in ICU4J - JCite
208 `{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getNextTransitionExample}`
210 `// ---getNextTransisionExample` in `BasicTimeZoneExample.java` in package
218 * A sample code should use package name -
225 * A sample code should be self-contained as much as possible (use only JDK and
226 ICU public APIs if possible). This allows readers to cut & paste a code
229 lower camel case token - for example, "`// ---compareToExample`"
252 conv = ucnv_open("koi8-r", &status);
256 Notice the tag "`ucnv_open`" which must be the same in all three places (in
264 ### C/C++ Hiding Un-@stable APIs
266 In C/C++, we enclose `@draft` and such APIs with `#ifndef U_HIDE_DRAFT_API` or
292 We `#ifndef` `@draft`/`@deprecated`/... APIs as much as possible, including C
296 We do not `#ifndef` APIs where that would be problematic:
298 * struct/class members where that would modify the object layout (non-static
305 the compiler would auto-create public functions to replace `#ifndef`’ed ones
315 user-configurable settings (mostly in `uconfig.h`)
317 More handy copy-paste text:
338 define enum types in C++ style. Instead, define C-style enums with U... type
345 Use mixed-case letters that start with a lowercase letter for variables and
350 Use mixed-case that start with an uppercase letter for types. For example, use
369 string or array (the number of units are (limit-start))
378 as is common in C++ and Java APIs. This is the preferred order for new APIs.
390 application-specific ones. This assures that ICU headers can use existing
392 ICU files, all used headers should be explicitly included, even if some of them
399 All ICU headers should be included using ""-style includes (like
408 possible in platform-specific code where the behavior is known.
410 Please use C++-style casts, at least for pointers, for example `const_cast`.
419 [ICU-9434](https://unicode-org.atlassian.net/browse/ICU-9434) for details.
433 start to limit-1 such as an interval that is left-closed and right-open. Using
438 Set the default value to -1 for functions that take a buffer (pointer) and a
448 `UChar` (same as `char16_t`), `UChar32` (signed, 32-bit), and `UErrorCode`.
450 The language built-in type `bool` and constants `true` and `false` may be used
452 type `UBool` must be used in public APIs and in the definition of any persistent
456 see [ICU-20973](https://unicode-org.atlassian.net/browse/ICU-20973).
483 Exception: The layout engine uses mixed-case file names.
491 used because they will not work on all C or C++ compilers.
492 In Microsoft Visual C++, go to Project Settings(alt-f7)->All Configurations->
493 C/C++->Customize and check Disable Language Extensions.
506 Use Java doc-style in-file documentation created with
528 Have one line that has the return type and place all the import declarations,
532 Function declarations need to be in the form `U_CAPI` return-type `U_EXPORT2` to
533 satisfy all the compilers' requirements.
551 > *Non-static C++ class member functions* do *not* get `U_CAPI`/`U_EXPORT2`
557 > was tedious and error-prone and added no value.
558 > Since ICU 68 (ICU-9961) we only use `U_CAPI` and `U_DEPRECATED`.
564 non-static symbols are not explicitly declared extern. These platforms will not
605 Not all functionality has or needs both kinds of API. More and more
606 functionality is available only via C APIs to avoid duplication of API,
607 documentation, and maintenance. C APIs are perfectly usable from C++ code,
608 especially with `UnicodeString` methods that alias or expose C-style string
624 Do not use function calls within a mutex block for mutual-exclusion (mutex)
628 Also, it is not guaranteed that mutex blocks are re-entrant; therefore, they
635 linkers do not distinguish between library exports and intra-library visible
641 Implicit constructors, assignments etc. can make simple-looking code
647 Background: We used to prefer C or C-style C++ for implementation code because
650 for much shorter, simpler, less error-prone and easier-to-maintain code, for
653 We still try to expose most functionality via *C APIs* because of the
654 difficulties of binary compatible C++ APIs exported from DLLs/shared libraries.
667 signedness. For example, do not cast a -1 to an enum type that only has
668 non-negative constants. Some compilers choose the internal representation very
670 `uint8_t` representation for an enum type with only small, non-negative constants.
671 Casting a -1 to such a type may result in an actual value of 255. (This has
679 In public APIs, assume `this!=0` and assume that references are not 0. In C code,
683 We do usually check all other (non-this) pointers for `NULL`, in those cases when
695 ICU4C APIs are designed to allow separate heaps for its libraries vs. the
697 destructors for all allocated objects. The C++ API uses a common base class with
713 All unmodifiable data should be declared `const`. This includes the pointers and
715 string as an array. This reduces the time to load the library and all its
751 compilers is almost never Unicode and may not be ASCII-compatible (especially on
761 1. It leads to intractable order-of-initialization dependencies.
762 2. It makes it difficult or impossible to release all of the libraries
791 not use features of C++ that are not implemented well in all compilers or are
804 exceptions, and ICU code is not exception-safe.
806 which create different types; they throw out-of-memory exceptions. ICU
808 * Non-polymorphic: For APIs, STL classes are also problematic because
814 We have started to use compiler-provided Run-Time Type Information (RTTI) in ICU
822 mechanism: All but one base classes must be interface/mixin classes, i.e., they
825 non-virtual members eliminates problems with the use and implementation of
843 support namespaces, users must rename all classes and global functions via
859 1. All classes with any virtual members or any bases with any virtual members
863 3. All virtual destructors should be defined out-of-line, and in a .cpp file
868 binaries smaller that use statically-linked ICU libraries, because the compiler
871 The Itanium C++ ABI (which is used on all x86 Linux) says: "The virtual table
873 function, i.e. the first non-pure virtual function that is not inline at the
877 (This was first done in ICU 49; see [ticket #8454](https://unicode-org.atlassian.net/browse/ICU-845…
884 release-specific one. (The actual namespace name is `icu` itself if renaming is
910 automatically done when `utypes.h` is included, so that all ICU classes are
912 `CXXFLAGS="-DU_USING_ICU_NAMESPACE=0"`.
914 #### Declare Class APIs
916 Class APIs need to be declared like either of the following:
918 #### Inline-Implemented Member Functions
920 Class member functions are usually declared but not inline-implemented in the
924 It is ok to inline-implement *trivial* functions in the class declaration.
927 single-statement-per-line rule slightly:
933 Most people also agree that very short multi-line implementations are ok inline
955 general, all instantiable classes (i.e., all classes except for interface/mixin
961 > :point_right: **Note**: Public ICU APIs must return or orphan only C++ objects
965 Simple types and pointers must be returned using fill-in parameters (instead of
988 man's RTTI" (Run-Time Type Information) mechanism (via
990 subclass as well (copy implementations from existing C++ APIs).
997 "poor man's RTTI" at all to subclasses of this class.
1004 Interface/mixin classes must not inherit any non-interface/mixin class,
1024 and did not add any value because it was defined if-and-only-if `__cplusplus` was
1033 the object. The semantics used within ICU are *adopt-on-call* (as opposed to,
1034 for example, adopt-on-success):
1037 in all cases, even if an error occurs and a `UErrorCode` is set. This means
1057 intended to be used with other-class constructors that may report a failure via
1070 Example: (This is a best-practice example. It does not reflect current `Calendar`
1100 All ICU C++ class objects directly or indirectly inherit `UMemory` (see
1107 deleted, not from the context of where the statement is. Since non-class data
1114 such scoping is missing in non-ICU code, it may be simpler to compile ICU
1118 In ICU library code, allocation of non-class data types — simple integer types
1123 instead filling user-provided buffers or returning constant pointers without
1136 All memory allocations and object creations should be checked for success. In
1153 C++ memory management is error-prone, and memory leaks are hard to avoid, but
1156 First, if you can stack-allocate an object (for example, a `UnicodeString` or
1160 [LocalPointer](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/localpointer_8h.html)`<…
1163 idiom. The "smart pointer" auto-deletes the object when it goes out of scope,
1165 all auto-managed objects are deleted. You do not need to remember to write an
1170 * Except in a destructor where you delete all of the objects which the class
1182 (you got a non-NULL pointer for that) do you `.orphan()` your `LocalPointer`.
1187 Every object must always be deletable/destructable. That is, at a minimum, all
1192 [cmemory.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/cmemory.h)
1196 [cmemory.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/cmemory.h)
1201 ([charstr.h](https://github.com/unicode-org/icu/blob/main/icu4c/source/common/charstr.h))
1206 Global functions (non-class member functions) that are declared inline must be
1241 This section describes the C-specific guidelines or conventions to use.
1243 #### Declare and define C APIs with both `U_CAPI` and `U_EXPORT2`
1245 All C APIs need to be **both declared and defined** using the `U_CAPI` and
1259 Use prefixes to avoid name collisions. Some of those prefixes contain a 3- (or
1260 sometimes 4-) letter module identifier. Very general names like
1263 * For POSIX replacements, the (all lowercase) POSIX function names start with
1267 **mixed-case** function name. For example, use `u_charDirection()`,
1298 [LocalPointer](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/localpointer_8h.html)
1333 Some, but not all, C compilers allow ICU users to declare functions inline
1341 We have changed all code that used `U_INLINE` to C++ (.cpp) using "inline", and
1346 All functions that are declared inline, or are small enough that an optimizing
1356 different 'open' APIs for each kind of instances, use an enum selector.
1362 #### Memory APIs Inside ICU
1369 All memory allocations in ICU should be checked for success. In the event of a
1388 | --- | --- | --- | --- |
1390 | `char *` | UTF-8 | `u8"¡Hola!"` | Only functions that are explicitly documented as expecting UTF…
1391 | `UChar *` | UTF-16 | `u"¡Hola!"` | All ICU functions with `UChar *` parameters |
1395 ICU source files are UTF-8 encoded, allowing any Unicode character to appear in
1401 "invariant characters" (a portable subset of the 7-bit ASCII repertoire) are
1422 The following are the ASCII and EBCDIC byte values for all of the invariant
1426 | --- | --- | --- |
1444 | - | 2D | 60 |
1459 strings for collation, etc. need to follow service-specific syntax, which means
1470 > :point_right: **Note**: All of these quoting mechanisms are supported by the
1476 been applied to all of the modules.
1485 The standard order for modifier keywords on APIs is:
1493 recommend ICU developers to use the Eclipse IDE feature \[Source\] - \[Organize
1496 All if/else/for/while/do loops use braces, even if the controlled statement is a
1506 use mixed-case identifiers for classes and methods and upper case for constants,
1510 file. It is recommended to run \[Source\] - \[Format\] (Ctrl+Shift+F) on Eclipse
1513 Use UTF-8 encoding (without BOM) for java source files.
1516 catch-up later during the throes of the release. Please javadoc all methods, not
1517 just external APIs, since this helps with maintenance.
1521 Avoid putting more than one top-level class in a single file. Either use
1525 automatically generates no-arg constructor when a class has no explicit
1540 modify later in a backwards-compatible way. Abstract classes, on the other hand,
1544 Current releases of ICU4J (since ICU 63) are restricted to use Java SE 7 APIs
1549 Public APIs should be placed in `com.ibm.icu.text`, `com.ibm.icu.util`, and
1551 classes, there are also APIs in `com.ibm.icu.math` but new APIs should not be
1554 APIs used only during development, testing, or tools work should be placed in
1557 A class or method which is used by public APIs (listed above) but which is not
1563 class that supports user-subclassing (rare).
1571 General discussion: See [ICU Design / ICU API compatibility](../icu/design.md#icu-api-compatibility…
1577 Such a change is source-compatible but not binary compatible.
1583 so that if someone has such compatibility overloads they all get exercised.
1608 ICU4J uses the same binary data files as ICU4C, in the big-endian/ASCII form.
1612 several `InputStream` and related APIs:
1614 * Memory mapping is efficient, but not available for all data sources.
1646 * The common library provides mostly low-level utilities and basic APIs that
1647 often do not make use of Locales. Examples are APIs that deal with character
1648 properties, the Locale APIs themselves, and ResourceBundle APIs.
1649 * The i18n library provides Locale-dependent and -using APIs, such as for
1652 2. Put the source code files into the folder `icu/source/library-name`, then add
1655 `icu/source/library-name/Makefile.in`, to the OBJECTS variable. Add the
1657 * For Microsoft Visual C++ 6.0, add all the source code files to
1658 `icu/source/library-name/library-name.dsp`. If you don't have Visual C++, add
1660 3. Add test code to `icu/source/test/cintltest` for C APIs and to
1661 `icu/source/test/intltest` for C++ APIs.
1666 APIs from `cintltst.h` (which uses `ctest.h`) and check it into the appropriate
1679 The cintltst Test Suite contains all the tests for the International Components
1681 "cintltst -all" at the command line. This depends on the C Test Services:
1682 `cintltst` or `cintltst -all`.
1702 Output from the test is accomplished with three printf-like functions:
1712 on (or the `-v` option to the command line). This option is useful for
1763 instructions in [How To Build And Install On Windows](../icu4c/build#how-to-build-and-install-on-wi…
1773 Type `cintltst -h` to view its command line parameters.
1777 ### Usage: [ -l ] [ -v ] [ -verbose] [-a] [ -all] [-n]
1778 [-no_err_msg] [ -h] [ /path/to/test ]
1779 ### -l To get a list of test names
1780 ### -all To run all the test
1781 ### -a To run all the test(same as -all)
1782 ### -verbose To turn ON verbosity
1783 ### -v To turn ON verbosity(same as -verbose)
1784 ### -h To print this message
1785 ### -n To turn OFF printing error messages
1786 ### -no_err_msg (same as -n)
1787 ### -[/subtest] To run a subtest
1820 /* will only show if verbose is on (-v) */
1822 all.\n");
1849 add_tests(&root); /* address of root ptr- will be filled in */
1860 The IntlTest suite contains all of the tests for the C++ API of International
1864 `intltest -v > testOutput`.
1869 `alCPP` (All C++ interfaces) workspace. This builds the libraries as well as the
1875 `icu4c/source/test/intltest/Debug`, then type: `intltest -v >testOutput`. For the
1881 Type just `intltest -h` to see the usage:
1885 ### IntlTest [-option1 -option2 ...] [testname1 testname2 ...]
1886 ### where options are: verbose (v), all (a), noerrormsg (n),
1888 ### (Specify either -all (shortcut -a) or a test name).
1889 ### -all will run all of the tests.
1909 This facility affects all ICU 'current time' calculations, including date,
1918 CPPFLAGS+=-DU_DEBUG_FAKETIME
1928 5. You can test this by running the utility '`icuinfo -m`' which will print out
1935 $ make check ICUINFO_OPTS=-m U_FAKETIME_START=28800000 CINTLTST_OPTS=-v
1940 -1281957858861 ms from the current time 1281986658861
1966 pre-built into binary formats, i.e., they are parsed and processed once and then
1969 Most of the data items are pre-built into binary files that are then installed
1977 load-time or even runtime conversion.
1981 Binary data items are memory-mapped, i.e., they are used as readonly, constant
1995 * `UChar`: for 16-bit Unicode strings
1999 > :point_right: **Note**: ICU assumes that `char` is an 8-bit byte but makes no
2011 means that a field with a primitive type of size n bytes must be at an n-aligned
2012 offset from the start of the data block. `UChar` must be 2-aligned, `int32_t` must
2013 be 4-aligned, etc.
2020 // bad because i will be preceded by compiler-dependent padding
2037 widest member field. The struct `OKExample` must be 4-aligned because it contains
2042 compilers provide RTTI for all classes and structs, which inserts a `_vtable`
2059 and `uchar.c`/`uprops.c`) is set to indicate backward-incompatible changes with the
2060 major version number, backward-compatible additions with the minor version
2067 ### Makefile-based platforms
2071 change-controlled source files with debugging information.
2072 * Example: **`CPPFLAGS+=-DUDATA_DEBUG`** in common to enable data
2086 visible as strings in the debugger without expanding sub-items:
2089 ;; Copyright (C) 2010 IBM Corporation and Others. All Rights Reserved.