AuroraMiddleware/scuffed-code
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

ICU-4699 Freezable functions for UText

Browse Source 
X-SVN-Rev: 19042
This commit is contained in:
Andy Heninger 2006-01-30 05:56:06 +00:00
parent 76018d6c70
commit 107b13e9c4
1 changed files with 43 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
icu4c/source/common/unicode/utext.h
View File

@ -148,10 +148,6 @@ U_CDECL_BEGIN
struct UText; struct UText;
typedef struct UText UText; /**< C typedef for struct UText. @draft ICU 3.4 */ typedef struct UText UText; /**< C typedef for struct UText. @draft ICU 3.4 */
struct UTextChunk;
typedef struct UTextChunk UTextChunk; /**< C typedef for struct UTextChunk. @draft ICU 3.4 */
/*************************************************************************************** /***************************************************************************************
* *
@ -279,7 +275,7 @@ utext_openReplaceable(UText *ut, Replaceable *rep, UErrorCode *status);
/** /**
* Clone a UText. Much like opening a UText where the source text is itself * Clone a UText. This is much like opening a UText where the source text is itself
* another UText. * another UText.
* *
* A deep clone will copy both the UText data structures and the underlying text. * A deep clone will copy both the UText data structures and the underlying text.
@ -291,6 +287,10 @@ utext_openReplaceable(UText *ut, Replaceable *rep, UErrorCode *status);
* The standard UText implementations for UTF8, UChar *, UnicodeString and * The standard UText implementations for UTF8, UChar *, UnicodeString and
* Replaceable all support deep cloning. * Replaceable all support deep cloning.
* *
* The UText returned from a deep clone will be writable, assuming that the text
* provider is able to support writing, even if the source UText had been made
* non-writable by means of UText_freeze().
*
* A shallow clone replicates only the UText data structures; it does not make * A shallow clone replicates only the UText data structures; it does not make
* a copy of the underlying text. Shallow clones can be used as an efficient way to * a copy of the underlying text. Shallow clones can be used as an efficient way to
* have multiple iterators active in a single text string that is not being * have multiple iterators active in a single text string that is not being
@ -299,8 +299,15 @@ utext_openReplaceable(UText *ut, Replaceable *rep, UErrorCode *status);
* A shallow clone operation will not fail, barring truly exceptional conditions such * A shallow clone operation will not fail, barring truly exceptional conditions such
* as memory allocation failures. * as memory allocation failures.
* *
* A shallow clone will preserve the utext_isWritable() state of the source object.
* Note, however, that any writing (modification) to the text is while more than one
* UText is referring to the same underlying text storage is an error with unpredictable
* results, much like modifying the underlying text directly, bypassing a
* UText wrapper.
*
* A UText and its clone may be safely concurrently accessed by separate threads. * A UText and its clone may be safely concurrently accessed by separate threads.
* This is true for both shallow and deep clones. * This is true for read access only with shallow clones, and for both read and
* write access with deep clones.
* It is the responsibility of the Text Provider to ensure that this thread safety * It is the responsibility of the Text Provider to ensure that this thread safety
* constraint is met. * constraint is met.
* *
@ -644,12 +651,20 @@ utext_extract(UText *ut,
/** /**
* Return TRUE if the text can be written with utext_replace() or * Return TRUE if the text can be written (modified) with utext_replace() or
* utext_copy(). For the text to be writable, the text provider must * utext_copy(). For the text to be writable, the text provider must
* be of a type that supports writing. * be of a type that supports writing and the UText must not be frozen.
*
* Attempting to modify text when utext_isWriteable() is FALSE will fail -
* the text will not be modified, and an error will be returned from the function
* that attempted the modification.
* *
* @param ut the UText to be tested. * @param ut the UText to be tested.
* @return TRUE if the text is modifiable. * @return TRUE if the text is modifiable.
*
* @see utext_freeze()
* @see utext_replace()
* @see utext_copy()
* @draft ICU 3.4 * @draft ICU 3.4
* *
*/ */
@ -739,6 +754,26 @@ utext_copy(UText *ut,
UErrorCode *status); UErrorCode *status);
/**
* Freeze a UText. This prevents any modification to the underlying text itself
* by means of functions operating on this UText.
* <p/>
* Once frozen, a UText can not be unfrozen. The intent is to provide some
* assurance that a the text underlying a frozen UText wrapper will not
* be unexpectedly changing.
* <p/>
* Caution: freezing a UText will disable changes made via the specific
* frozen UText wrapper only; it will not have any effect on the ability to
* directly modify the text by bypassing the UText. Any such backdoor modifications
* are always an error while UText access is occuring because the underlying
* text can get out of sync with UText's buffering.
*
* @param ut The UText to be frozen.
* @see utext_isWritable()
*/
U_DRAFT void U_EXPORT2
utext_freeze(UText *ut);
/** /**
* UText provider properties (bit field indexes). * UText provider properties (bit field indexes).
* *