Lines Matching +full:all +full:- +full:apis
1 ---
6 ---
7 <!--
10 -->
16 {: .no_toc .text-delta }
21 ---
59 } else if(pBiDi==NULL || (length=pBiDi->length)<=0) {
72 Note: *Callers* (as opposed to implementers) of ICU APIs can simplify their code
94 return 0; // or calling UErrorCode-less
103 UnicodeString result = ((PluralRules*)uplrules)->select(number);
110 If the API function is non-const, then it should have a `UErrorCode` parameter.
130 set, but like exceptions it does not work well for non-failure information
136 * Use real APIs to get the same information if possible.
138 NUL-terminated, then `U_STRING_NOT_TERMINATED_WARNING` indicates this, but so
142 NUL-terminated strings but to use the length.)
148 real API replacements for all existing warning codes.
154 out-of-memory condition) but do not take a `UErrorCode` parameter and can
158 * A bogus object cannot be modified except with assignment-like functions.
176 "`@draft ICU 4.8`". For details of how we mark APIs see the "ICU API
178 Java, also see existing @draft APIs for complete examples.
198 #### Embedding Coding Examples in ICU4J - JCite
204 `{@.jcite com.ibm.icu.samples.util.timezone.BasicTimeZoneExample:---getNextTransitionExample}`
206 `// ---getNextTransisionExample` in `BasicTimeZoneExample.java` in package
214 * A sample code should use package name -
221 * A sample code should be self-contained as much as possible (use only JDK and
222 ICU public APIs if possible). This allows readers to cut & paste a code
225 lower camel case token - for example, "`// ---compareToExample`"
248 conv = ucnv_open("koi8-r", &status);
252 Notice the tag "`ucnv_open`" which must be the same in all three places (in
260 ### C/C++ Hiding Un-@stable APIs
262 In C/C++, we enclose `@draft` and such APIs with `#ifndef U_HIDE_DRAFT_API` or
288 We `#ifndef` `@draft`/`@deprecated`/... APIs as much as possible, including C
292 We do not `#ifndef` APIs where that would be problematic:
294 * struct/class members where that would modify the object layout (non-static
301 the compiler would auto-create public functions to replace `#ifndef`’ed ones
311 user-configurable settings (mostly in `uconfig.h`)
313 More handy copy-paste text:
334 define enum types in C++ style. Instead, define C-style enums with U... type
341 Use mixed-case letters that start with a lowercase letter for variables and
346 Use mixed-case that start with an uppercase letter for types. For example, use
365 string or array (the number of units are (limit-start))
374 as is common in C++ and Java APIs. This is the preferred order for new APIs.
386 application-specific ones. This assures that ICU headers can use existing
388 ICU files, all used headers should be explicitly included, even if some of them
395 All ICU headers should be included using ""-style includes (like
404 possible in platform-specific code where the behavior is known.
406 Please use C++-style casts, at least for pointers, for example `const_cast`.
415 [ICU-9434](https://unicode-org.atlassian.net/browse/ICU-9434) for details.
429 start to limit-1 such as an interval that is left-closed and right-open. Using
434 Set the default value to -1 for functions that take a buffer (pointer) and a
444 `UChar` (same as `char16_t`), `UChar32` (signed, 32-bit), and `UErrorCode`.
446 The language built-in type `bool` and constants `true` and `false` may be used
448 type `UBool` must be used in public APIs and in the definition of any persistent
475 Exception: The layout engine uses mixed-case file names.
483 used because they will not work on all C or C++ compilers.
484 In Microsoft Visual C++, go to Project Settings(alt-f7)->All Configurations->
485 C/C++->Customize and check Disable Language Extensions.
498 Use Java doc-style in-file documentation created with
520 Have one line that has the return type and place all the import declarations,
524 Function declarations need to be in the form `U_CAPI` return-type `U_EXPORT2` to
525 satisfy all the compilers' requirements.
543 > *Non-static C++ class member functions* do *not* get `U_CAPI`/`U_EXPORT2`
549 > was tedious and error-prone and added no value.
550 > Since ICU 68 (ICU-9961) we only use `U_CAPI` and `U_DEPRECATED`.
556 non-static symbols are not explicitly declared extern. These platforms will not
597 Not all functionality has or needs both kinds of API. More and more
598 functionality is available only via C APIs to avoid duplication of API,
599 documentation, and maintenance. C APIs are perfectly usable from C++ code,
600 especially with `UnicodeString` methods that alias or expose C-style string
616 Do not use function calls within a mutex block for mutual-exclusion (mutex)
620 Also, it is not guaranteed that mutex blocks are re-entrant; therefore, they
627 linkers do not distinguish between library exports and intra-library visible
633 Implicit constructors, assignments etc. can make simple-looking code
639 Background: We used to prefer C or C-style C++ for implementation code because
642 for much shorter, simpler, less error-prone and easier-to-maintain code, for
645 We still try to expose most functionality via *C APIs* because of the
646 difficulties of binary compatible C++ APIs exported from DLLs/shared libraries.
659 signedness. For example, do not cast a -1 to an enum type that only has
660 non-negative constants. Some compilers choose the internal representation very
662 `uint8_t` representation for an enum type with only small, non-negative constants.
663 Casting a -1 to such a type may result in an actual value of 255. (This has
671 In public APIs, assume `this!=0` and assume that references are not 0. In C code,
675 We do usually check all other (non-this) pointers for `NULL`, in those cases when
687 ICU4C APIs are designed to allow separate heaps for its libraries vs. the
689 destructors for all allocated objects. The C++ API uses a common base class with
705 All unmodifiable data should be declared `const`. This includes the pointers and
707 string as an array. This reduces the time to load the library and all its
743 compilers is almost never Unicode and may not be ASCII-compatible (especially on
753 1. It leads to intractable order-of-initialization dependencies.
754 2. It makes it difficult or impossible to release all of the libraries
783 not use features of C++ that are not implemented well in all compilers or are
796 exceptions, and ICU code is not exception-safe.
798 which create different types; they throw out-of-memory exceptions. ICU
800 * Non-polymorphic: For APIs, STL classes are also problematic because
806 We have started to use compiler-provided Run-Time Type Information (RTTI) in ICU
814 mechanism: All but one base classes must be interface/mixin classes, i.e., they
817 non-virtual members eliminates problems with the use and implementation of
835 support namespaces, users must rename all classes and global functions via
851 1. All classes with any virtual members or any bases with any virtual members
855 3. All virtual destructors should be defined out-of-line, and in a .cpp file
860 binaries smaller that use statically-linked ICU libraries, because the compiler
863 The Itanium C++ ABI (which is used on all x86 Linux) says: "The virtual table
865 function, i.e. the first non-pure virtual function that is not inline at the
869 (This was first done in ICU 49; see [ticket #8454](https://unicode-org.atlassian.net/browse/ICU-845…
876 release-specific one. (The actual namespace name is `icu` itself if renaming is
902 automatically done when `utypes.h` is included, so that all ICU classes are
904 `CXXFLAGS="-DU_USING_ICU_NAMESPACE=0"`.
906 #### Declare Class APIs
908 Class APIs need to be declared like either of the following:
910 #### Inline-Implemented Member Functions
912 Class member functions are usually declared but not inline-implemented in the
916 It is ok to inline-implement *trivial* functions in the class declaration.
919 single-statement-per-line rule slightly:
925 Most people also agree that very short multi-line implementations are ok inline
947 general, all instantiable classes (i.e., all classes except for interface/mixin
953 > :point_right: **Note**: Public ICU APIs must return or orphan only C++ objects
957 Simple types and pointers must be returned using fill-in parameters (instead of
980 man's RTTI" (Run-Time Type Information) mechanism (via
982 subclass as well (copy implementations from existing C++ APIs).
989 "poor man's RTTI" at all to subclasses of this class.
996 Interface/mixin classes must not inherit any non-interface/mixin class,
1016 and did not add any value because it was defined if-and-only-if `__cplusplus` was
1025 within ICU must be *adopt-on-call* (as opposed to, for example,
1026 adopt-on-success):
1029 in all cases, even if an error occurs and a `UErrorCode` is set. This means
1056 Example: (This is a best-practice example. It does not reflect current `Calendar`
1082 All ICU C++ class objects directly or indirectly inherit `UMemory` (see
1089 deleted, not from the context of where the statement is. Since non-class data
1096 such scoping is missing in non-ICU code, it may be simpler to compile ICU
1100 In ICU library code, allocation of non-class data types — simple integer types
1105 instead filling user-provided buffers or returning constant pointers without
1118 All memory allocations and object creations should be checked for success. In
1135 C++ memory management is error-prone, and memory leaks are hard to avoid, but
1138 First, if you can stack-allocate an object (for example, a `UnicodeString` or
1142 [LocalPointer](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/localpointer_8h.html)`<…
1145 idiom. The "smart pointer" auto-deletes the object when it goes out of scope,
1147 all auto-managed objects are deleted. You do not need to remember to write an
1152 * Except in a destructor where you delete all of the objects which the class
1164 (you got a non-NULL pointer for that) do you `.orphan()` your `LocalPointer`.
1169 Every object must always be deletable/destructable. That is, at a minimum, all
1174 [cmemory.h](https://github.com/unicode-org/icu/blob/master/icu4c/source/common/cmemory.h)
1178 [cmemory.h](https://github.com/unicode-org/icu/blob/master/icu4c/source/common/cmemory.h)
1183 ([charstr.h](https://github.com/unicode-org/icu/blob/master/icu4c/source/common/charstr.h))
1188 Global functions (non-class member functions) that are declared inline must be
1223 This section describes the C-specific guidelines or conventions to use.
1225 #### Declare and define C APIs with both `U_CAPI` and `U_EXPORT2`
1227 All C APIs need to be **both declared and defined** using the `U_CAPI` and
1241 Use prefixes to avoid name collisions. Some of those prefixes contain a 3- (or
1242 sometimes 4-) letter module identifier. Very general names like
1245 * For POSIX replacements, the (all lowercase) POSIX function names start with
1249 **mixed-case** function name. For example, use `u_charDirection()`,
1280 [LocalPointer](https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/localpointer_8h.html)
1315 Some, but not all, C compilers allow ICU users to declare functions inline
1323 We have changed all code that used `U_INLINE` to C++ (.cpp) using "inline", and
1328 All functions that are declared inline, or are small enough that an optimizing
1338 different 'open' APIs for each kind of instances, use an enum selector.
1344 #### Memory APIs Inside ICU
1351 All memory allocations in ICU should be checked for success. In the event of a
1370 | --- | --- | --- | --- |
1372 | `char *` | UTF-8 | `u8"¡Hola!"` | Only functions that are explicitly documented as expecting UTF…
1373 | `UChar *` | UTF-16 | `u"¡Hola!"` | All ICU functions with `UChar *` parameters |
1377 ICU source files are UTF-8 encoded, allowing any Unicode character to appear in
1383 "invariant characters" (a portable subset of the 7-bit ASCII repertoire) are
1404 The following are the ASCII and EBCDIC byte values for all of the invariant
1408 | --- | --- | --- |
1426 | - | 2D | 60 |
1441 strings for collation, etc. need to follow service-specific syntax, which means
1452 > :point_right: **Note**: All of these quoting mechanisms are supported by the
1458 been applied to all of the modules.
1467 The standard order for modifier keywords on APIs is:
1475 recommend ICU developers to use the Eclipse IDE feature \[Source\] - \[Organize
1478 All if/else/for/while/do loops use braces, even if the controlled statement is a
1488 use mixed-case identifiers for classes and methods and upper case for constants,
1492 file. It is recommended to run \[Source\] - \[Format\] (Ctrl+Shift+F) on Eclipse
1495 Use UTF-8 encoding (without BOM) for java source files.
1498 catch-up later during the throes of the release. Please javadoc all methods, not
1499 just external APIs, since this helps with maintenance.
1503 Avoid putting more than one top-level class in a single file. Either use
1507 automatically generates no-arg constructor when a class has no explicit
1522 modify later in a backwards-compatible way. Abstract classes, on the other hand,
1526 Current releases of ICU4J (since ICU 63) are restricted to use Java SE 7 APIs
1531 Public APIs should be placed in `com.ibm.icu.text`, `com.ibm.icu.util`, and
1533 classes, there are also APIs in `com.ibm.icu.math` but new APIs should not be
1536 APIs used only during development, testing, or tools work should be placed in
1539 A class or method which is used by public APIs (listed above) but which is not
1545 class that supports user-subclassing (rare).
1574 ICU4J uses the same binary data files as ICU4C, in the big-endian/ASCII form.
1578 several `InputStream` and related APIs:
1580 * Memory mapping is efficient, but not available for all data sources.
1612 * The common library provides mostly low-level utilities and basic APIs that
1613 often do not make use of Locales. Examples are APIs that deal with character
1614 properties, the Locale APIs themselves, and ResourceBundle APIs.
1615 * The i18n library provides Locale-dependent and -using APIs, such as for
1618 2. Put the source code files into the folder `icu/source/library-name`, then add
1621 `icu/source/library-name/Makefile.in`, to the OBJECTS variable. Add the
1623 * For Microsoft Visual C++ 6.0, add all the source code files to
1624 `icu/source/library-name/library-name.dsp`. If you don't have Visual C++, add
1626 3. Add test code to `icu/source/test/cintltest` for C APIs and to
1627 `icu/source/test/intltest` for C++ APIs.
1632 APIs from `cintltst.h` (which uses `ctest.h`) and check it into the appropriate
1645 The cintltst Test Suite contains all the tests for the International Components
1647 "cintltst -all" at the command line. This depends on the C Test Services:
1648 `cintltst` or `cintltst -all`.
1668 Output from the test is accomplished with three printf-like functions:
1678 on (or the `-v` option to the command line). This option is useful for
1740 Type `cintltst -h` to view its command line parameters.
1744 ### Usage: [ -l ] [ -v ] [ -verbose] [-a] [ -all] [-n]
1745 [-no_err_msg] [ -h] [ /path/to/test ]
1746 ### -l To get a list of test names
1747 ### -all To run all the test
1748 ### -a To run all the test(same as -all)
1749 ### -verbose To turn ON verbosity
1750 ### -v To turn ON verbosity(same as -verbose)
1751 ### -h To print this message
1752 ### -n To turn OFF printing error messages
1753 ### -no_err_msg (same as -n)
1754 ### -[/subtest] To run a subtest
1787 /* will only show if verbose is on (-v) */
1789 all.\n");
1816 add_tests(&root); /* address of root ptr- will be filled in */
1827 The IntlTest suite contains all of the tests for the C++ API of International
1831 `intltest -v > testOutput`.
1836 `alCPP` (All C++ interfaces) workspace. This builds the libraries as well as the
1842 `icu4c/source/test/intltest/Debug`, then type: `intltest -v >testOutput`. For the
1848 Type just `intltest -h` to see the usage:
1852 ### IntlTest [-option1 -option2 ...] [testname1 testname2 ...]
1853 ### where options are: verbose (v), all (a), noerrormsg (n),
1855 ### (Specify either -all (shortcut -a) or a test name).
1856 ### -all will run all of the tests.
1876 This facility affects all ICU 'current time' calculations, including date,
1885 CPPFLAGS+=-DU_DEBUG_FAKETIME
1895 5. You can test this by running the utility '`icuinfo -m`' which will print out
1902 $ make check ICUINFO_OPTS=-m U_FAKETIME_START=28800000 CINTLTST_OPTS=-v
1907 -1281957858861 ms from the current time 1281986658861
1933 pre-built into binary formats, i.e., they are parsed and processed once and then
1936 Most of the data items are pre-built into binary files that are then installed
1944 load-time or even runtime conversion.
1948 Binary data items are memory-mapped, i.e., they are used as readonly, constant
1962 * `UChar`: for 16-bit Unicode strings
1966 > :point_right: **Note**: ICU assumes that `char` is an 8-bit byte but makes no
1978 means that a field with a primitive type of size n bytes must be at an n-aligned
1979 offset from the start of the data block. `UChar` must be 2-aligned, `int32_t` must
1980 be 4-aligned, etc.
1987 // bad because i will be preceded by compiler-dependent padding
2004 widest member field. The struct `OKExample` must be 4-aligned because it contains
2009 compilers provide RTTI for all classes and structs, which inserts a `_vtable`
2026 and `uchar.c`/`uprops.c`) is set to indicate backward-incompatible changes with the
2027 major version number, backward-compatible additions with the minor version
2034 ### Makefile-based platforms
2038 change-controlled source files with debugging information.
2039 * Example: **`CPPFLAGS+=-DUDATA_DEBUG`** in common to enable data
2053 visible as strings in the debugger without expanding sub-items:
2056 ;; Copyright (C) 2010 IBM Corporation and Others. All Rights Reserved.