From b30ef92e945fadd63ff5bed0bd531f5b3c548702 Mon Sep 17 00:00:00 2001 From: Andy Heninger Date: Fri, 24 Jun 2005 22:20:22 +0000 Subject: [PATCH] ICU-3944 API & Docs cleanup X-SVN-Rev: 18039 --- icu4c/source/common/unicode/utext.h | 65 +++++++++++++++---------- icu4c/source/common/utext.cpp | 62 +++++++++++------------ icu4c/source/test/cintltst/utexttst.c | 4 +- icu4c/source/test/intltest/utxttest.cpp | 4 +- 4 files changed, 74 insertions(+), 61 deletions(-) diff --git a/icu4c/source/common/unicode/utext.h b/icu4c/source/common/unicode/utext.h index cdbff1604bc..1588a18b5d7 100644 --- a/icu4c/source/common/unicode/utext.h +++ b/icu4c/source/common/unicode/utext.h @@ -87,9 +87,9 @@ * * When an index position is returned from a UText function, it will be * a native index to the underlying text. In the case of multi-unit characters, - * it will always refer to the first position, never to the interior. This - * is essentially the same thing as saying that a returned index will always - * point to a boundary between characters. + * it will always refer to the first position of the character, + * never to the interior. This is essentially the same thing as saying that + * a returned index will always point to a boundary between characters. * * When a native index is supplied to a UText function, all indices that * refer to any part of a multi-unit character representation are considered @@ -98,7 +98,7 @@ * * It is possible to test whether a native index is on a code point boundary * by doing a utext_setNativeIndex() followed by a utext_getNativeIndex(). - * If the index is returned unchanged, it is on a code point boundary. If + * If the index is returned unchanged, it was on a code point boundary. If * an adjusted index is returned, the original index referred to the * interior of a character. * @@ -178,7 +178,7 @@ utext_close(UText *ut); * @draft ICU 3.4 */ U_DRAFT UText * U_EXPORT2 -utext_openUTF8(UText *ut, const uint8_t *s, int32_t length, UErrorCode *status); +utext_openUTF8(UText *ut, const char *s, int32_t length, UErrorCode *status); /** @@ -203,38 +203,38 @@ utext_openUChars(UText *ut, const UChar *s, int32_t length, UErrorCode *status); /** * Open a writable UText for a non-const UnicodeString. * - * @param t Pointer to a UText struct. If NULL, a new UText will be created. - * If non-NULL, must refer to an initialized UText struct, which will then - * be reset to reference the specified input string. - * @param s A UnicodeString. + * @param ut Pointer to a UText struct. If NULL, a new UText will be created. + * If non-NULL, must refer to an initialized UText struct, which will then + * be reset to reference the specified input string. + * @param s A UnicodeString. * @param status Errors are returned here. - * @return Pointer to the UText. If a UText was supplied as input, this - * will always be used and returned. + * @return Pointer to the UText. If a UText was supplied as input, this + * will always be used and returned. * @draft ICU 3.4 */ U_DRAFT UText * U_EXPORT2 -utext_openUnicodeString(UText *t, UnicodeString *s, UErrorCode *status); +utext_openUnicodeString(UText *ut, UnicodeString *s, UErrorCode *status); /** * Open a UText for a const UnicodeString. The resulting UText will not be writable. * - * @param t Pointer to a UText struct. If NULL, a new UText will be created. + * @param ut Pointer to a UText struct. If NULL, a new UText will be created. * If non-NULL, must refer to an initialized UText struct, which will then * be reset to reference the specified input string. - * @param s A UnicodeString to be wrapped. + * @param s A const UnicodeString to be wrapped. * @param status Errors are returned here. * @return Pointer to the UText. If a UText was supplied as input, this * will always be used and returned. * @draft ICU 3.4 */ U_DRAFT UText * U_EXPORT2 -utext_openConstUnicodeString(UText *t, const UnicodeString *s, UErrorCode *status); +utext_openConstUnicodeString(UText *ut, const UnicodeString *s, UErrorCode *status); /** * Open a writable UText implementation for an ICU Replaceable object. - * @param t Pointer to a UText struct. If NULL, a new UText will be created. + * @param ut Pointer to a UText struct. If NULL, a new UText will be created. * If non-NULL, must refer to an already existing UText, which will then * be reset to reference the specified replaceable text. * @param rep A Replaceable text object. @@ -245,7 +245,7 @@ utext_openConstUnicodeString(UText *t, const UnicodeString *s, UErrorCode *statu * @draft ICU 3.4 */ U_DRAFT UText * U_EXPORT2 -utext_openReplaceable(UText *t, Replaceable *rep, UErrorCode *status); +utext_openReplaceable(UText *ut, Replaceable *rep, UErrorCode *status); #endif @@ -268,6 +268,11 @@ utext_openReplaceable(UText *t, Replaceable *rep, UErrorCode *status); * A shallow clone operation will not fail, barring truly exceptional conditions such * as memory allocation failures. * + * A UText and its clone may be safely concurrently accessed by separate threads. + * This is true for both shallow and deep clones. + * It is the responsibility of the Text Provider to ensure that this thread safety + * constraint is met. + * * @param dest A UText struct to be filled in with the result of the clone operation, * or NULL if the clone function should heap-allocate a new UText struct. * @param src The UText to be cloned. @@ -363,6 +368,7 @@ utext_current32(UText *ut); * advance the position to the first index following the character. * Returns U_SENTINEL (-1) if the position is at the end of the * text. + * This is a post-increment operation * * An inline macro version of this function, UTEXT_NEXT32(), * is available for performance critical use. @@ -381,6 +387,7 @@ utext_next32(UText *ut); * index precedes the current position, and return that character. * This is a pre-decrement operation. * Returns U_SENTINEL (-1) if the position is at the start of the text. + * This is a pre-decrement operation. * * An inline macro version of this function, UTEXT_PREVIOUS32(), * is available for performance critical use. @@ -672,7 +679,7 @@ utext_replace(UText *ut, * * @param ut The UText representing the text to be operated on. * @param nativeStart The native index of the start of the region to be copied or moved - * @param nativeLimit The native index of the character following the region to be replaced. + * @param nativeLimit The native index of the character position following the region to be copied. * @param destIndex The native destination index to which the source substring is copied or moved. * @param move If TRUE, then the substring is moved, not copied/duplicated. * @param status receives any error status. Possible errors include U_NO_WRITE_PERMISSION @@ -802,6 +809,12 @@ enum { * * A shallow clone operation must not fail except for truly exceptional conditions such * as memory allocation failures. + * + * A UText and its clone may be safely concurrently accessed by separate threads. + * This is true for both shallow and deep clones. + * It is the responsibility of the Text Provider to ensure that this thread safety + * constraint is met. + * * @param dest A UText struct to be filled in with the result of the clone operation, * or NULL if the clone function should heap-allocate a new UText struct. @@ -920,10 +933,10 @@ UTextExtract(UText *ut, * @draft ICU 3.4 */ typedef int32_t U_CALLCONV -UTextReplace(UText *t, +UTextReplace(UText *ut, int32_t nativeStart, int32_t nativeLimit, const UChar *replacementText, int32_t replacmentLength, - UErrorCode *pErrorCode); + UErrorCode *status); /** * Function type declaration for UText.copy(). @@ -954,11 +967,11 @@ UTextReplace(UText *t, * @draft ICU 3.4 */ typedef void U_CALLCONV -UTextCopy(UText *t, +UTextCopy(UText *ut, int32_t nativeStart, int32_t nativeLimit, int32_t nativeDest, UBool move, - UErrorCode *pErrorCode); + UErrorCode *status); /** * Function type declaration for UText.mapOffsetToNative(). @@ -1126,7 +1139,7 @@ struct UText { * @see UTextLength * @draft ICU 3.4 */ - UTextNativeLength *length; + UTextNativeLength *nativeLength; /** * (public) Function pointer for UTextAccess. @@ -1174,7 +1187,7 @@ struct UText { * @see UTextMapNativeIndexToUTF16 * @draft ICU 3.4 */ - UTextMapNativeIndexToUTF16 *mapIndexToUTF16; + UTextMapNativeIndexToUTF16 *mapNativeIndexToUTF16; /** * (public) Function pointer for UTextClose. @@ -1193,7 +1206,7 @@ struct UText { * If the supplied UText is already open, the provider's close function will be called * so that the struct can be reused by the open that is in progress. * - * @param utxt pointer to a UText struct to be re-used, or null if a new UText + * @param ut pointer to a UText struct to be re-used, or null if a new UText * should be allocated. * @param extraSpace The amount of additional space to be allocated as part * of this UText, for use by types of providers that require @@ -1203,7 +1216,7 @@ struct UText { * @draft ICU 3.4 */ U_DRAFT UText * U_EXPORT2 -utext_setup(UText *utxt, int32_t extraSpace, UErrorCode *status); +utext_setup(UText *ut, int32_t extraSpace, UErrorCode *status); /** * @internal diff --git a/icu4c/source/common/utext.cpp b/icu4c/source/common/utext.cpp index dc151af4418..e458ddbae5e 100644 --- a/icu4c/source/common/utext.cpp +++ b/icu4c/source/common/utext.cpp @@ -61,7 +61,7 @@ utext_moveIndex32(UText *ut, int32_t delta) { U_DRAFT int32_t U_EXPORT2 utext_nativeLength(UText *ut) { - return ut->length(ut); + return ut->nativeLength(ut); } @@ -92,7 +92,7 @@ utext_setNativeIndex(UText *ut, int32_t index) { // Reverse iterations may suffer slightly. ut->access(ut, index, TRUE, &ut->chunk); } else if(ut->chunk.nonUTF16Indexes) { - ut->chunk.offset=ut->mapIndexToUTF16(ut, index); + ut->chunk.offset=ut->mapNativeIndexToUTF16(ut, index); } else { ut->chunk.offset=index-ut->chunk.nativeStart; // Our convention is that the index must always be on a code point boundary. @@ -214,7 +214,7 @@ utext_next32From(UText *ut, int32_t index) { } offset = chunk->offset; } else if(chunk->nonUTF16Indexes) { - offset=ut->mapIndexToUTF16(ut, index); + offset=ut->mapNativeIndexToUTF16(ut, index); } else { offset = index - chunk->nativeStart; } @@ -248,7 +248,7 @@ utext_previous32From(UText *ut, int32_t index) { } offset = chunk->offset; } else if(chunk->nonUTF16Indexes) { - offset=ut->mapIndexToUTF16(ut, index); + offset=ut->mapNativeIndexToUTF16(ut, index); } else { offset = index - chunk->nativeStart; } @@ -857,7 +857,7 @@ utf8TextMapIndexToUTF16(UText *ut, int32_t index) { U_DRAFT UText * U_EXPORT2 -utext_openUTF8(UText *ut, const uint8_t *s, int32_t length, UErrorCode *status) { +utext_openUTF8(UText *ut, const char *s, int32_t length, UErrorCode *status) { if(U_FAILURE(*status)) { return NULL; } @@ -872,19 +872,19 @@ utext_openUTF8(UText *ut, const uint8_t *s, int32_t length, UErrorCode *status) } ut->providerProperties = I32_FLAG(UTEXT_PROVIDER_NON_UTF16_INDEXES); - ut->clone = noopTextClone; - ut->length = utf8TextLength; - ut->access = utf8TextAccess; - ut->extract = utf8TextExtract; - ut->mapOffsetToNative = utf8TextMapOffsetToNative; - ut->mapIndexToUTF16 = utf8TextMapIndexToUTF16; + ut->clone = noopTextClone; + ut->nativeLength = utf8TextLength; + ut->access = utf8TextAccess; + ut->extract = utf8TextExtract; + ut->mapOffsetToNative = utf8TextMapOffsetToNative; + ut->mapNativeIndexToUTF16 = utf8TextMapIndexToUTF16; ut->context=s; if(length>=0) { ut->b=length; } else { // TODO: really undesirable to do this scan upfront. - ut->b=(int32_t)uprv_strlen((const char *)s); + ut->b=(int32_t)uprv_strlen(s); } return ut; @@ -1167,12 +1167,12 @@ utext_openReplaceable(UText *ut, Replaceable *rep, UErrorCode *status) { ut->providerProperties |=I32_FLAG(UTEXT_PROVIDER_HAS_META_DATA); } - ut->clone = repTextClone; - ut->length = repTextLength; - ut->access = repTextAccess; - ut->extract = repTextExtract; - ut->replace = repTextReplace; - ut->copy = repTextCopy; + ut->clone = repTextClone; + ut->nativeLength = repTextLength; + ut->access = repTextAccess; + ut->extract = repTextExtract; + ut->replace = repTextReplace; + ut->copy = repTextCopy; ut->context=rep; return ut; @@ -1356,14 +1356,14 @@ U_DRAFT UText * U_EXPORT2 utext_openUnicodeString(UText *ut, UnicodeString *s, UErrorCode *status) { ut = utext_setup(ut, 0, status); if (U_SUCCESS(*status)) { - ut->clone = unistrTextClone; - ut->length = unistrTextLength; - ut->access = unistrTextAccess; - ut->extract = unistrTextExtract; - ut->replace = unistrTextReplace; - ut->copy = unistrTextCopy; + ut->clone = unistrTextClone; + ut->nativeLength = unistrTextLength; + ut->access = unistrTextAccess; + ut->extract = unistrTextExtract; + ut->replace = unistrTextReplace; + ut->copy = unistrTextCopy; - ut->context = s; + ut->context = s; ut->providerProperties = I32_FLAG(UTEXT_PROVIDER_STABLE_CHUNKS)| I32_FLAG(UTEXT_PROVIDER_WRITABLE); } @@ -1547,12 +1547,12 @@ utext_openUChars(UText *ut, const UChar *s, int32_t length, UErrorCode *status) } ut = utext_setup(ut, 0, status); if (U_SUCCESS(*status)) { - ut->clone = ucstrTextClone; - ut->length = ucstrTextLength; - ut->access = ucstrTextAccess; - ut->extract = ucstrTextExtract; - ut->replace = NULL; - ut->copy = NULL; + ut->clone = ucstrTextClone; + ut->nativeLength = ucstrTextLength; + ut->access = ucstrTextAccess; + ut->extract = ucstrTextExtract; + ut->replace = NULL; + ut->copy = NULL; ut->context = s; ut->providerProperties = I32_FLAG(UTEXT_PROVIDER_STABLE_CHUNKS); diff --git a/icu4c/source/test/cintltst/utexttst.c b/icu4c/source/test/cintltst/utexttst.c index 71bae6511c1..28c9422e96a 100644 --- a/icu4c/source/test/cintltst/utexttst.c +++ b/icu4c/source/test/cintltst/utexttst.c @@ -64,7 +64,7 @@ static void TestAPI(void) { UText utLoc = UTEXT_INITIALIZER; const char * cString = "Hello, World"; UChar uString[] = {0x41, 0x42, 0x43, 0}; - uint8_t *utf8String; + char *utf8String; UText *uta; UText *utb; UChar c; @@ -76,7 +76,7 @@ static void TestAPI(void) { utb = utext_close(uta); TEST_ASSERT(utb == NULL); - utf8String = (uint8_t *)cString; + utf8String = cString; uta = utext_openUTF8(&utLoc, utf8String, -1, &status); TEST_SUCCESS(status); TEST_ASSERT(uta == &utLoc); diff --git a/icu4c/source/test/intltest/utxttest.cpp b/icu4c/source/test/intltest/utxttest.cpp index 1468c3b04f5..2ffb30f0a41 100644 --- a/icu4c/source/test/intltest/utxttest.cpp +++ b/icu4c/source/test/intltest/utxttest.cpp @@ -120,7 +120,7 @@ void UTextTest::TestString(const UnicodeString &s) { // Do the test itself status = U_ZERO_ERROR; - ut = utext_openUTF8(NULL, (uint8_t *)u8String, -1, &status); + ut = utext_openUTF8(NULL, u8String, -1, &status); TEST_SUCCESS(status); TestAccess(sa, ut, cpCount, u8Map); utext_close(ut); @@ -144,7 +144,7 @@ void UTextTest::TestAccess(const UnicodeString &us, UText *ut, int cpCount, m *c // Check the length from the UText // int expectedLen = cpMap[cpCount].nativeIdx; - int utlen = ut->length(ut); + int utlen = ut->nativeLength(ut); TEST_ASSERT(expectedLen == utlen); //