/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/*

 * Licensed to the Apache Software Foundation (ASF) under one or more

 * contributor license agreements.  See the NOTICE file distributed with

 * this work for additional information regarding copyright ownership.

 * The ASF licenses this file to You under the Apache License, Version 2.0

 * (the "License"); you may not use this file except in compliance with

 * the License.  You may obtain a copy of the License at

 * 

 *      http://www.apache.org/licenses/LICENSE-2.0

 * 

 * Unless required by applicable law or agreed to in writing, software

 * distributed under the License is distributed on an "AS IS" BASIS,

 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

 * See the License for the specific language governing permissions and

 * limitations under the License.

 */

/*

 * $Id: DOM_CharacterData.hpp 568078 2007-08-21 11:43:25Z amassari $

 */

#ifndef DOM_CharacterData_HEADER_GUARD_

#define DOM_CharacterData_HEADER_GUARD_

#include <xercesc/util/XercesDefs.hpp>

#include "DOM_Node.hpp"

XERCES_CPP_NAMESPACE_BEGIN

class CharacterDataImpl;

/**

 * The <code>DOM_CharacterData</code> interface extends Node with a set  of

 * methods for accessing character data in the DOM.

 *

 * For clarity this set is defined here rather than on each class that uses

 * these methods. No DOM objects correspond directly to

 * <code>CharacterData</code>, though <code>Text</code> and others do inherit

 * the interface from it. All <code>offset</code>s in this interface start

 * from 0, and index in terms of Unicode 16 bit storage units.

 */

class DEPRECATED_DOM_EXPORT DOM_CharacterData: public DOM_Node {

private:

public:

  /** @name Constructors and assignment operator */

  //@{

  /**

    * Default constructor for DOM_CharacterData.  While there can be

    * no actual DOM nodes of type CharacterData, the C++ objects

    * function more like reference variables, and instances of

    * <code>DOM_CharacterData</code> can exist.  They will be null when created

    * by this constructor, and can then be assigned to refer to Text

    * or CDATASection nodes.

    */

    DOM_CharacterData();

  /**

    * Copy constructor

    *

    * @param other The object to be copied

    */

    DOM_CharacterData(const DOM_CharacterData &other);

  /**

    * Assignment operator

    *

    * @param other The object to be copied

    */

    DOM_CharacterData & operator = (const DOM_CharacterData &other);

    /**

      * Assignment operator.  This overloaded variant is provided for

      *   the sole purpose of setting a DOM_Node reference variable to

      *   zero.  Nulling out a reference variable in this way will decrement

      *   the reference count on the underlying Node object that the variable

      *   formerly referenced.  This effect is normally obtained when reference

      *   variable goes out of scope, but zeroing them can be useful for

      *   global instances, or for local instances that will remain in scope

      *   for an extended time,  when the storage belonging to the underlying

      *   node needs to be reclaimed.

      *

      * @param val   Only a value of 0, or null, is allowed.

      */

    DOM_CharacterData & operator = (const DOM_NullPtr *val);

    //@}

    /** @name Destructor. */

    //@{

	 /**

	  * Destructor for DOM_CharacterData.  The object being destroyed

      * is the reference to the Character Data node, not the character

      * data itself.

	  */

    ~DOM_CharacterData();

    //@}

    /** @name Getter functions. */

    //@{

  /**

   * Returns the character data of the node that implements this interface.

   *

   * The DOM implementation may not put arbitrary limits on the amount of data that

   * may be stored in a  <code>CharacterData</code> node. However,

   * implementation limits may  mean that the entirety of a node's data may

   * not fit into a single <code>DOMString</code>. In such cases, the user

   * may call <code>substringData</code> to retrieve the data in

   * appropriately sized pieces.

   * @exception DOMException

   *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

   * @exception DOMException

   *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than

   *   fit in a <code>DOMString</code> variable on the implementation

   *   platform.

   */

  DOMString          getData() const;

  /**

   * Returns the number of characters that are available through <code>data</code> and

   * the <code>substringData</code> method below.

   *

   * This may have the value

   * zero, i.e., <code>CharacterData</code> nodes may be empty.

   */

  unsigned int       getLength() const;

  /**

   * Extracts a range of data from the node.

   *

   * @param offset Start offset of substring to extract.

   * @param count The number of characters to extract.

   * @return The specified substring. If the sum of <code>offset</code> and

   *   <code>count</code> exceeds the <code>length</code>, then all

   *   characters to the end of the data are returned.

   * @exception DOMException

   *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater

   *   than the number of characters in <code>data</code>, or if the

   *   specified <code>count</code> is negative.

   *   <br>DOMSTRING_SIZE_ERR: Raised if the specified range of text does not

   *   fit into a <code>DOMString</code>.

   */

  DOMString          substringData(unsigned int offset,

                                   unsigned int count) const;

    //@}

    /** @name Functions that set or change data. */

    //@{

  /**

   * Append the string to the end of the character data of the node.

   *

   * Upon success, <code>data</code> provides access to the concatenation of

   * <code>data</code> and the <code>DOMString</code> specified.

   * @param arg The <code>DOMString</code> to append.

   * @exception DOMException

   *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

   */

  void               appendData(const DOMString &arg);

  /**

   * Insert a string at the specified character offset.

   *

   * @param offset The character offset at which to insert.

   * @param arg The <code>DOMString</code> to insert.

   * @exception DOMException

   *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater

   *   than the number of characters in <code>data</code>.

   *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

   */

  void               insertData(unsigned int offset, const  DOMString &arg);

  /**

   * Remove a range of characters from the node.

   *

   * Upon success,

   * <code>data</code> and <code>length</code> reflect the change.

   * @param offset The offset from which to remove characters.

   * @param count The number of characters to delete. If the sum of

   *   <code>offset</code> and <code>count</code> exceeds <code>length</code>

   *   then all characters from <code>offset</code> to the end of the data

   *   are deleted.

   * @exception DOMException

   *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater

   *   than the number of characters in <code>data</code>, or if the

   *   specified <code>count</code> is negative.

   *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

   */

  void               deleteData(unsigned int offset,

                                unsigned int count);

  /**

   * Replace the characters starting at the specified character offset with

   * the specified string.

   *

   * @param offset The offset from which to start replacing.

   * @param count The number of characters to replace. If the sum of

   *   <code>offset</code> and <code>count</code> exceeds <code>length</code>

   *   , then all characters to the end of the data are replaced (i.e., the

   *   effect is the same as a <code>remove</code> method call with the same

   *   range, followed by an <code>append</code> method invocation).

   * @param arg The <code>DOMString</code> with which the range must be

   *   replaced.

   * @exception DOMException

   *   INDEX_SIZE_ERR: Raised if the specified offset is negative or greater

   *   than the number of characters in <code>data</code>, or if the

   *   specified <code>count</code> is negative.

   *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.

   */

  void               replaceData(unsigned int offset,

                                 unsigned int count,

                                 const DOMString &arg);

  /**

   * Sets the character data of the node that implements this interface.

   *

   * @param data The <code>DOMString</code> to set.

   */

  void               setData(const DOMString &data);

  //@}

protected:

    DOM_CharacterData(CharacterDataImpl *impl);

};

XERCES_CPP_NAMESPACE_END

#endif