vtkXMLUtilities.h 5.82 KB
Newer Older
1 2 3 4 5
/*=========================================================================

  Program:   Visualization Toolkit
  Module:    vtkXMLUtilities.h

6
  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
7 8 9
  All rights reserved.
  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.

10 11
     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
12 13 14
     PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
15 16 17 18 19 20 21 22
/**
 * @class   vtkXMLUtilities
 * @brief   XML utilities.
 *
 * vtkXMLUtilities provides XML-related convenience functions.
 * @sa
 * vtkXMLDataElement
*/
23

24 25
#ifndef vtkXMLUtilities_h
#define vtkXMLUtilities_h
26

27
#include "vtkIOXMLParserModule.h" // For export macro
28 29 30 31
#include "vtkObject.h"

class vtkXMLDataElement;

32
class VTKIOXMLPARSER_EXPORT vtkXMLUtilities : public vtkObject
33 34 35
{
public:
  static vtkXMLUtilities* New();
36
  vtkTypeMacro(vtkXMLUtilities, vtkObject);
37

38 39 40 41 42 43
  /**
   * Encode a string from one format to another
   * (see VTK_ENCODING_... constants).
   * If special_entites is true, convert some characters to their corresponding
   * character entities.
   */
44
  static void EncodeString(const char *input, int input_encoding,
45 46 47
                           ostream &output, int output_encoding,
                           int special_entities = 0);

48 49 50 51 52 53 54
  /**
   * Collate a vtkXMLDataElement's attributes to a stream as a series of
   * name="value" pairs (the separator between each pair can be specified,
   * if not, it defaults to a space).
   * Note that the resulting character-encoding will be UTF-8 (we assume
   * that this function is used to create XML files/streams).
   */
55 56
  static void CollateAttributes(vtkXMLDataElement*,
                                ostream&,
57 58
                                const char *sep = 0);

59 60 61 62 63 64 65 66 67 68
  /**
   * Flatten a vtkXMLDataElement to a stream, i.e. output a textual stream
   * corresponding to that XML element, its attributes and its
   * nested elements.
   * If 'indent' is not NULL, it is used to indent the whole tree.
   * If 'indent' is not NULL and 'indent_attributes' is true, attributes will
   * be indented as well.
   * Note that the resulting character-encoding will be UTF-8 (we assume
   * that this function is used to create XML files/streams).
   */
69 70
  static void FlattenElement(vtkXMLDataElement*,
                             ostream&,
71 72 73
                             vtkIndent *indent = 0,
                             int indent_attributes = 1);

74 75 76 77 78
  /**
   * Write a vtkXMLDataElement to a file (in a flattened textual form)
   * Note that the resulting character-encoding will be UTF-8.
   * Return 1 on success, 0 otherwise.
   */
79 80
  static int WriteElementToFile(vtkXMLDataElement*,
                                const char *filename,
81 82
                                vtkIndent *indent = 0);

83 84 85 86 87 88 89 90 91 92 93 94
  //@{
  /**
   * Read a vtkXMLDataElement from a stream, string or file.
   * The 'encoding' parameter will be used to set the internal encoding of the
   * attributes of the data elements created by those functions (conversion
   * from the XML stream encoding to that new encoding will be performed
   * automatically). If set to VTK_ENCODING_NONE, the encoding won't be
   * changed and will default to the default vtkXMLDataElement encoding.
   * Return the root element on success, NULL otherwise.
   * Note that you have to call Delete() on the element returned by that
   * function to ensure it is freed properly.
   */
95 96 97 98 99 100
  static vtkXMLDataElement* ReadElementFromStream(
    istream&, int encoding = VTK_ENCODING_NONE);
  static vtkXMLDataElement* ReadElementFromString(
    const char *str, int encoding = VTK_ENCODING_NONE);
  static vtkXMLDataElement* ReadElementFromFile(
    const char *filename, int encoding = VTK_ENCODING_NONE);
101 102 103 104 105 106 107 108 109 110
  //@}

  /**
   * Sets attributes of an element from an array of encoded attributes.
   * The 'encoding' parameter will be used to set the internal encoding of the
   * attributes of the data elements created by those functions (conversion
   * from the XML stream encoding to that new encoding will be performed
   * automatically). If set to VTK_ENCODING_NONE, the encoding won't be
   * changed and will default to the default vtkXMLDataElement encoding.
   */
111 112 113 114 115
  static void ReadElementFromAttributeArray(
        vtkXMLDataElement *element,
        const char** atts,
        int encoding);

116 117 118 119 120 121 122 123
  /**
   * Find all elements in 'tree' that are similar to 'elem' (using the
   * vtkXMLDataElement::IsEqualTo() predicate).
   * Return the number of elements found and store those elements in
   * 'results' (automatically allocated).
   * Warning: the results do not include 'elem' if it was found in the tree ;
   * do not forget to deallocate 'results' if something was found.
   */
124 125
  static int FindSimilarElements(vtkXMLDataElement *elem,
                                 vtkXMLDataElement *tree,
126 127
                                 vtkXMLDataElement ***results);

128 129 130 131 132 133
  //@{
  /**
   * Factor and unfactor a tree. This operation looks for duplicate elements
   * in the tree, and replace them with references to a pool of elements.
   * Unfactoring a non-factored element is harmless.
   */
134 135
  static void FactorElements(vtkXMLDataElement *tree);
  static void UnFactorElements(vtkXMLDataElement *tree);
136
  //@}
137

138
protected:
139 140
  vtkXMLUtilities() {}
  ~vtkXMLUtilities() {}
141 142 143

  static int FactorElementsInternal(vtkXMLDataElement *tree,
                                    vtkXMLDataElement *root,
144
                                    vtkXMLDataElement *pool);
145
  static int UnFactorElementsInternal(vtkXMLDataElement *tree,
146 147 148
                                      vtkXMLDataElement *pool);

private:
149
  vtkXMLUtilities(const vtkXMLUtilities&) VTK_DELETE_FUNCTION;
150
  void operator=(const vtkXMLUtilities&) VTK_DELETE_FUNCTION;
151 152 153 154 155
};

#endif


156
// VTK-HeaderTest-Exclude: vtkXMLUtilities.h