Records lengths of string edits but not replacement text. More...

#include <edits.h>

Inheritance diagram for icu::Edits:

Data Structures
struct	Iterator
	Access to the list of edits. More...

Public Member Functions
	Edits ()
	Constructs an empty object.

	Edits (const Edits &other)
	Copy constructor.

	Edits (Edits &&src) noexcept
	Move constructor, might leave src empty.

	~Edits ()
	Destructor.

Edits &	operator= (const Edits &other)
	Assignment operator.

Edits &	operator= (Edits &&src) noexcept
	Move assignment operator, might leave src empty.

void	reset () noexcept
	Resets the data but may not release memory.

void	addUnchanged (int32_t unchangedLength)
	Adds a no-change edit: a record for an unchanged segment of text.

void	addReplace (int32_t oldLength, int32_t newLength)
	Adds a change edit: a record for a text replacement/insertion/deletion.

UBool	copyErrorTo (UErrorCode &outErrorCode) const
	Sets the UErrorCode if an error occurred while recording edits.

int32_t	lengthDelta () const
	How much longer is the new text compared with the old text?

UBool	hasChanges () const

int32_t	numberOfChanges () const

Iterator	getCoarseChangesIterator () const
	Returns an Iterator for coarse-grained change edits (adjacent change edits are treated as one).

Iterator	getCoarseIterator () const
	Returns an Iterator for coarse-grained change and no-change edits (adjacent change edits are treated as one).

Iterator	getFineChangesIterator () const
	Returns an Iterator for fine-grained change edits (full granularity of change edits is retained).

Iterator	getFineIterator () const
	Returns an Iterator for fine-grained change and no-change edits (full granularity of change edits is retained).

Edits &	mergeAndAppend (const Edits &ab, const Edits &bc, UErrorCode &errorCode)
	Merges the two input Edits and appends the result to this object.

Detailed Description

Records lengths of string edits but not replacement text.

Supports replacements, insertions, deletions in linear progression. Does not support moving/reordering of text.

There are two types of edits: change edits and no-change edits. Add edits to instances of this class using addReplace(int32_t, int32_t) (for change edits) and addUnchanged(int32_t) (for no-change edits). Change edits are retained with full granularity, whereas adjacent no-change edits are always merged together. In no-change edits, there is a one-to-one mapping between code points in the source and destination strings.

After all edits have been added, instances of this class should be considered immutable, and an Edits::Iterator can be used for queries.

There are four flavors of Edits::Iterator:

getFineIterator() retains full granularity of change edits.
getFineChangesIterator() retains full granularity of change edits, and when calling next() on the iterator, skips over no-change edits (unchanged regions).
getCoarseIterator() treats adjacent change edits as a single edit. (Adjacent no-change edits are automatically merged during the construction phase.)
getCoarseChangesIterator() treats adjacent change edits as a single edit, and when calling next() on the iterator, skips over no-change edits (unchanged regions).

For example, consider the string "abcßDeF", which case-folds to "abcssdef". This string has the following fine edits:

abc ⇨ abc (no-change)
ß ⇨ ss (change)
D ⇨ d (change)
e ⇨ e (no-change)
F ⇨ f (change)

and the following coarse edits (note how adjacent change edits get merged together):

abc ⇨ abc (no-change)
ßD ⇨ ssd (change)
e ⇨ e (no-change)
F ⇨ f (change)

The "fine changes" and "coarse changes" iterators will step through only the change edits when their Edits::Iterator::next() methods are called. They are identical to the non-change iterators when their Edits::Iterator::findSourceIndex() or Edits::Iterator::findDestinationIndex() methods are used to walk through the string.

For examples of how to use this class, see the test TestCaseMapEditsIteratorDocs in UCharacterCaseTest.java.

An Edits object tracks a separate UErrorCode, but ICU string transformation functions (e.g., case mapping functions) merge any such errors into their API's UErrorCode.

Stable:: ICU 59

Definition at line 80 of file edits.h.

Constructor & Destructor Documentation

◆ Edits() [1/3]

icu::Edits::Edits ( )

inline

Constructs an empty object.

Stable:: ICU 59

Definition at line 86 of file edits.h.

◆ Edits() [2/3]

icu::Edits::Edits ( const Edits & other )

inline

Copy constructor.

Parameters

other source edits

Stable:: ICU 60

Definition at line 94 of file edits.h.

◆ Edits() [3/3]

icu::Edits::Edits ( Edits && src )

inlinenoexcept

Move constructor, might leave src empty.

This object will have the same contents that the source object had.

Parameters

src	source edits

Stable:: ICU 60

Definition at line 106 of file edits.h.

◆ ~Edits()

icu::Edits::~Edits ( )

Destructor.

Stable:: ICU 59

Member Function Documentation

◆ addReplace()

void icu::Edits::addReplace	(	int32_t	oldLength,
		int32_t	newLength
	)

Adds a change edit: a record for a text replacement/insertion/deletion.

Normally called from inside ICU string transformation functions, not user code.

Stable:: ICU 59

◆ addUnchanged()

void icu::Edits::addUnchanged ( int32_t unchangedLength )

Adds a no-change edit: a record for an unchanged segment of text.

Normally called from inside ICU string transformation functions, not user code.

Stable:: ICU 59

◆ copyErrorTo()

UBool icu::Edits::copyErrorTo ( UErrorCode & outErrorCode ) const

Sets the UErrorCode if an error occurred while recording edits.

Preserves older error codes in the outErrorCode. Normally called from inside ICU string transformation functions, not user code.

Parameters

outErrorCode Set to an error code if it does not contain one already and an error occurred while recording edits. Otherwise unchanged.

Returns: true if U_FAILURE(outErrorCode)

Stable:: ICU 59

◆ getCoarseChangesIterator()

Iterator icu::Edits::getCoarseChangesIterator ( ) const

inline

Returns an Iterator for coarse-grained change edits (adjacent change edits are treated as one).

Can be used to perform simple string updates. Skips no-change edits.

Returns: an Iterator that merges adjacent changes.

Stable:: ICU 59

Definition at line 438 of file edits.h.

◆ getCoarseIterator()

Iterator icu::Edits::getCoarseIterator ( ) const

inline

Returns an Iterator for coarse-grained change and no-change edits (adjacent change edits are treated as one).

Can be used to perform simple string updates. Adjacent change edits are treated as one edit.

Returns: an Iterator that merges adjacent changes.

Stable:: ICU 59

Definition at line 450 of file edits.h.

◆ getFineChangesIterator()

Iterator icu::Edits::getFineChangesIterator ( ) const

inline

Returns an Iterator for fine-grained change edits (full granularity of change edits is retained).

Can be used for modifying styled text. Skips no-change edits.

Returns: an Iterator that separates adjacent changes.

Stable:: ICU 59

Definition at line 462 of file edits.h.

◆ getFineIterator()

Iterator icu::Edits::getFineIterator ( ) const

inline

Returns an Iterator for fine-grained change and no-change edits (full granularity of change edits is retained).

Can be used for modifying styled text.

Returns: an Iterator that separates adjacent changes.

Stable:: ICU 59

Definition at line 473 of file edits.h.

◆ hasChanges()

UBool icu::Edits::hasChanges ( ) const

inline

Returns: true if there are any change edits

Stable:: ICU 59

Definition at line 177 of file edits.h.

◆ lengthDelta()

int32_t icu::Edits::lengthDelta ( ) const

inline

How much longer is the new text compared with the old text?

Returns: new length minus old length

Stable:: ICU 59

Definition at line 172 of file edits.h.

◆ mergeAndAppend()

Edits & icu::Edits::mergeAndAppend	(	const Edits &	ab,
		const Edits &	bc,
		UErrorCode &	errorCode
	)

Merges the two input Edits and appends the result to this object.

Consider two string transformations (for example, normalization and case mapping) where each records Edits in addition to writing an output string.
Edits ab reflect how substrings of input string a map to substrings of intermediate string b.
Edits bc reflect how substrings of intermediate string b map to substrings of output string c.
This function merges ab and bc such that the additional edits recorded in this object reflect how substrings of input string a map to substrings of output string c.

If unrelated Edits are passed in where the output string of the first has a different length than the input string of the second, then a U_ILLEGAL_ARGUMENT_ERROR is reported.

Parameters

ab	reflects how substrings of input string a map to substrings of intermediate string b.
bc	reflects how substrings of intermediate string b map to substrings of output string c.
errorCode	ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns: *this, with the merged edits appended

Stable:: ICU 60

◆ numberOfChanges()

int32_t icu::Edits::numberOfChanges ( ) const

inline

Returns: the number of change edits

Stable:: ICU 60

Definition at line 183 of file edits.h.

◆ operator=() [1/2]

Edits & icu::Edits::operator= ( const Edits & other )

Assignment operator.

Parameters

other source edits

Returns: *this

Stable:: ICU 60

◆ operator=() [2/2]

Edits & icu::Edits::operator= ( Edits && src )

noexcept

Move assignment operator, might leave src empty.

This object will have the same contents that the source object had. The behavior is undefined if *this and src are the same object.

Parameters

src	source edits

Returns: *this

Stable:: ICU 60

◆ reset()

void icu::Edits::reset ( )

noexcept

Resets the data but may not release memory.

Stable:: ICU 59

The documentation for this class was generated from the following file:

common/unicode/edits.h

Data Structures

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Edits() [1/3]

◆ Edits() [2/3]

◆ Edits() [3/3]

◆ ~Edits()

Member Function Documentation

◆ addReplace()

◆ addUnchanged()

◆ copyErrorTo()

◆ getCoarseChangesIterator()

◆ getCoarseIterator()

◆ getFineChangesIterator()

◆ getFineIterator()

◆ hasChanges()

◆ lengthDelta()

◆ mergeAndAppend()

◆ numberOfChanges()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ reset()