### ICharacterReference

  The ICharacterReference class is a simple proxy class for accessing characters safely. This class is used in IText and ITextIterator's APIs wherever a non-constant UniChar& would otherwise be used. Changing a character through an ICharacterReference is safer and more efficient than changing a character through a UniChar& because:

  - Out-of-range character references are caught and throw an exception, rather than stomping on memory. (Although an ICharacterReference is not guaranteed to refer to the same character it did when created if the underlying IText is changed.)
  - ICharacterReference knows about the storage-sharing mechanism and can protect against inadvertent changes to ITexts that share storage with the IText the user intends to change.
  - ICharacterReference knows about the style mechanism and can protect against style- propagation problems that may result from things like the caller getting rid of a paragraph delimiter.

  ICharacterReference has no public constructors. The user must create an ICharacterReference using the [] operator or at() function on IText or the * or [] operator of one of the ITextIterator classes.

  Do not derive from this class.

### ICharacterReference - Member Functions and Data by Group

### Constructors & Destructor

Use the destructor in this group to destroy objects of class ICharacterReference.

~ICharacterReference

      public:
      ~ICharacterReference()

  Destroys the ICharacterReference object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Assignment Operators

Use the assignment operators in this group to replace the character referred to in the current ICharacterReference object with the given one specified by the that or newChar parameter.

operator =
  Changes the character referred to by the ICharacterReference.

  Overload 1

      public:
      ICharacterReference& operator =(UniChar newChar)

  Changes the character referred to by the ICharacterReference to newChar. This has the same effect as calling at_put() on the ICharacterReference's underlying IText.
  newChar
    The replacement character.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      ICharacterReference&
        operator =( const ICharacterReference& that )

  Changes the character the ICharacterReference refers to to be the same as the character referred to by the that parameter. It does not change *this to refer to the same character as that. This overload exists to make expressions like the following legal:

      someText[i] = someText[j]

  that
    A constant ICharacterReference to the replacement character.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Obtaining Its Offset or a Pointer to the Text

Use these functions to get a pointer to the text referred to or its offset.

offset

      public:
      size_t offset() const

  Returns the character offset within its IText of the character the ICharacterReference refers to.

  Note: ICharacterReference is implemented as a single pointer to a UniChar when possible, and as a pointer to an IText and a character offset the rest of the time. When an ICharacterReference holds a pointer to a character, this function returns (size_t)(-1) and the value returned by text() is not valid. (Consider this function to be obsolete.)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

text

      public:
      IText* text() const

  Returns a pointer to the IText the ICharacterReference refers to.

  Note: ICharacterReference is implemented as a single pointer to a UniChar when possible, and as a pointer to an IText and a character offset the rest of the time. Therefore, the value returned by this function may not be valid. To determine whether this value is valid, check the value returned by offset(). If it's (size_t)(-1), the value returned by text() is invalid. (Consider this function to be obsolete.)

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### ICharacterReference - Inherited Member Functions and Data

#### Inherited Public Functions

  ICharacterReference

  -     ICharacterReference(const ICharacterReference& that)

  -     operator UniChar() const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None