You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by jd...@locus.apache.org on 2000/03/06 21:23:17 UTC
cvs commit: xml-xalan/c/src/XercesPlatformSupport TextFileOutputStream.hpp XercesDOMPrintWriter.hpp XercesPlatformSupportException.hpp XercesStdTextOutputStream.hpp XercesTextOutputStream.hpp
jdonohue 00/03/06 12:23:16
Modified: c/src/Include DOMHelper.hpp
c/src/PlatformSupport NumberFormat.hpp STLHelper.hpp
c/src/TestXPath NodeNameTreeWalker.hpp
c/src/XercesPlatformSupport TextFileOutputStream.hpp
XercesDOMPrintWriter.hpp
XercesPlatformSupportException.hpp
XercesStdTextOutputStream.hpp
XercesTextOutputStream.hpp
Log:
Added javadoc comments
Revision Changes Path
1.4 +137 -2 xml-xalan/c/src/Include/DOMHelper.hpp
Index: DOMHelper.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/Include/DOMHelper.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DOMHelper.hpp 2000/02/17 20:24:35 1.3
+++ DOMHelper.hpp 2000/03/06 20:23:11 1.4
@@ -76,6 +76,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theAddress null pointer to compare
+ * @param theObject object to compare
+ * @return true if object represents a null instance
+ */
inline bool
operator==(
int /* theAddress */,
@@ -86,6 +94,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theAddress null pointer to compare
+ * @param theObject object to compare
+ * @return true if object represents a null instance
+ */
inline bool
operator==(
int /* theAddress */,
@@ -95,6 +111,14 @@
}
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theAddress null pointer to compare
+ * @param theObject object to compare
+ * @return true if object represents a null instance
+ */
inline bool
operator==(
int /* theAddress */,
@@ -105,6 +129,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theObject object to compare
+ * @param theAddress null pointer to compare
+ * @return true if object represents a null instance
+ */
inline bool
operator==(
const DOM_Node& theObject,
@@ -115,6 +147,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theObject object to compare
+ * @param theAddress null pointer to compare
+ * @return true if object represents a null instance
+ */
inline bool
operator==(
const DOM_NamedNodeMap& theObject,
@@ -125,6 +165,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theObject object to compare
+ * @param theAddress null pointer to compare
+ * @return true if object represents a null instance
+ */
inline bool
operator==(
const DOM_NodeList& theObject,
@@ -135,6 +183,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theAddress null pointer to compare
+ * @param theObject object to compare
+ * @return true if object does not represent a null instance
+ */
inline bool
operator!=(
int /* theAddress */,
@@ -145,6 +201,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theAddress null pointer to compare
+ * @param theObject object to compare
+ * @return true if object does not represent a null instance
+ */
inline bool
operator!=(
int /* theAddress */,
@@ -155,6 +219,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theAddress null pointer to compare
+ * @param theObject object to compare
+ * @return true if object does not represent a null instance
+ */
inline bool
operator!=(
int /* theAddress */,
@@ -165,6 +237,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theObject object to compare
+ * @param theAddress null pointer to compare
+ * @return true if object does not represent a null instance
+ */
inline bool
operator!=(
const DOM_Node& theObject,
@@ -175,6 +255,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theObject object to compare
+ * @param theAddress null pointer to compare
+ * @return true if object does not represent a null instance
+ */
inline bool
operator!=(
const DOM_NamedNodeMap& theObject,
@@ -185,6 +273,14 @@
+/**
+ * Compare with a pointer. Intended only to allow a convenient comparison
+ * with null.
+ *
+ * @param theObject object to compare
+ * @param theAddress null pointer to compare
+ * @return true if object does not represent a null instance
+ */
inline bool
operator!=(
const DOM_NodeList& theObject,
@@ -202,11 +298,22 @@
{
public:
+ /**
+ * Construct a XALAN_DOM_NodeHack instance from a DOM node.
+ *
+ * @param theOtherNode DOM node to use
+ */
XALAN_DOM_NodeHack(const DOM_Node& theOtherNode) :
DOM_Node(theOtherNode)
{
}
+ /**
+ * Construct a XALAN_DOM_NodeHack instance from an underlying DOM node
+ * implementation object.
+ *
+ * @param theOtherNode pointer to implementation object
+ */
XALAN_DOM_NodeHack(NodeImpl* theOtherNode) :
DOM_Node(theOtherNode)
{
@@ -216,6 +323,11 @@
{
}
+ /**
+ * Retrieve the underlying DOM node implementation object.
+ *
+ * @return pointer to implementation object
+ */
NodeImpl*
getImplementationObject() const
{
@@ -232,6 +344,13 @@
// according to the C++ standard, but it should work on 99.99% of
// architectures. We're only using it until STL hash containers are
// available.
+
+/**
+ * Less operator for two XALAN_DOM_NodeHack instances, needed for STL.
+ *
+ * @param theLHS first object to compare
+ * @param theRHS second object to compare
+ */
inline bool
operator<(
const XALAN_DOM_NodeHack& theLHS,
@@ -242,13 +361,21 @@
-// Functor for hashing DOM_Nodes.
+/**
+ * Functor for hashing DOM_Nodes.
+ */
#if defined(XALAN_NO_NAMESPACES)
struct DOM_NodeHashFunction : public unary_function<DOM_Node, size_t>
#else
struct DOM_NodeHashFunction : public std::unary_function<DOM_Node, size_t>
#endif
{
+ /**
+ * Determine a hash value for the given key.
+ *
+ * @param theKey key to hash
+ * @return hash value
+ */
result_type
operator() (const argument_type& theKey) const
{
@@ -258,13 +385,21 @@
-// Functor for hashing DOM_Elements.
+/**
+ * Functor for hashing DOM_Elements.
+ */
#if defined(XALAN_NO_NAMESPACES)
struct DOM_ElementHashFunction : public unary_function<DOM_Element, size_t>
#else
struct DOM_ElementHashFunction : public std::unary_function<DOM_Element, size_t>
#endif
{
+ /**
+ * Determine a hash value for the given key.
+ *
+ * @param theKey key to hash
+ * @return hash value
+ */
result_type
operator() (const argument_type& theKey) const
{
1.2 +54 -0 xml-xalan/c/src/PlatformSupport/NumberFormat.hpp
Index: NumberFormat.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/PlatformSupport/NumberFormat.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- NumberFormat.hpp 1999/12/18 19:47:50 1.1
+++ NumberFormat.hpp 2000/03/06 20:23:11 1.2
@@ -78,24 +78,78 @@
virtual
~NumberFormat();
+ /**
+ * Format a number into a string.
+ *
+ * @param theValue number to format
+ * @return string representation of number
+ */
virtual DOMString
format(double theValue);
+ /**
+ * Format a number into a string.
+ *
+ * @param theValue number to format
+ * @return string representation of number
+ */
virtual DOMString
format(int theValue);
+ /**
+ * Format a number into a string.
+ *
+ * @param theValue number to format
+ * @return string representation of number
+ */
virtual DOMString
format(unsigned int theValue);
+ /**
+ * Format a number into a string.
+ *
+ * @param theValue number to format
+ * @return string representation of number
+ */
virtual DOMString
format(long theValue);
+ /**
+ * Format a number into a string.
+ *
+ * @param theValue number to format
+ * @return string representation of number
+ */
virtual DOMString
format(unsigned long theValue);
+ /**
+ * Whether groupings are used for numbers, for example, "234,678"
+ *
+ * @return true if grouping used
+ */
virtual bool isGroupingUsed() const;
+
+ /**
+ * Change whether groupings are used for numbers, for example, "234,678"
+ *
+ * @param bUsed true to use grouping
+ */
virtual void setGroupingUsed(bool bUsed);
+
+ /**
+ * Change the size of groupings, for example, "234,678" uses a size of "3"
+ *
+ * @param s string representation of grouping size
+ */
virtual void setGroupingSize(const DOMString& s);
+
+ /**
+ * Change the separator string used for groupings, for example, "234,678"
+ * uses the separator ","
+ *
+ * @param s grouping separator string
+ */
virtual void setGroupingSeparator(const DOMString& s);
private:
1.4 +102 -9 xml-xalan/c/src/PlatformSupport/STLHelper.hpp
Index: STLHelper.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/PlatformSupport/STLHelper.hpp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- STLHelper.hpp 2000/02/17 20:27:26 1.3
+++ STLHelper.hpp 2000/03/06 20:23:11 1.4
@@ -67,7 +67,9 @@
#include <functional>
-
+/**
+ * Functor to delete objects, used in STL iteration algorithms.
+ */
template <class T>
#if defined(XALAN_NO_NAMESPACES)
struct DeleteFunctor : public unary_function<const T*, void>
@@ -75,6 +77,11 @@
struct DeleteFunctor : public std::unary_function<const T*, void>
#endif
{
+ /**
+ * Delete the object pointed to by argument.
+ *
+ * @param thePointer pointer to object to be deleted
+ */
result_type
operator()(argument_type thePointer) const
{
@@ -85,6 +92,10 @@
#if ! defined(__GNUC__)
+/**
+ * Functor to retrieve the key of a key-value pair in a map, used in STL
+ * iteration algorithms.
+ */
template <class PairType>
#if defined(XALAN_NO_NAMESPACES)
struct select1st : public unary_function<PairType, PairType::first_type>
@@ -94,6 +105,12 @@
{
typedef PairType value_type;
+ /**
+ * Retrieve the key of a key-value pair.
+ *
+ * @param thePair key-value pair
+ * @return key
+ */
result_type
operator()(const argument_type& thePair) const
{
@@ -103,6 +120,10 @@
+/**
+ * Functor to retrieve the value of a key-value pair in a map, used in STL
+ * iteration algorithms.
+ */
template <class PairType>
#if defined(XALAN_NO_NAMESPACES)
struct select2nd : public unary_function<PairType, PairType::second_type>
@@ -112,6 +133,12 @@
{
typedef PairType value_type;
+ /**
+ * Retrieve the value of a key-value pair.
+ *
+ * @param thePair key-value pair
+ * @return value
+ */
result_type
operator()(const argument_type& thePair)
{
@@ -120,22 +147,31 @@
};
#endif
-
+/*
+$$$ What's it all mean ???
+*/
template <class OutputIteratorType, class PairMemberSelectType>
struct PairIsolatorOutputIterator
{
+
+// $$$ This doesn't seem to be used anywhere ???
+/*
#if defined(XALAN_NO_NAMESPACES)
typedef output_iterator_tag iterator_category;
#else
typedef std::output_iterator_tag iterator_category;
#endif
+*/
typedef typename PairMemberSelectType::value_type value_type;
+// $$$ This doesn't seem to be used anywhere ???
+/*
typedef void difference_type;
typedef void pointer;
typedef void reference;
+*/
PairIsolatorOutputIterator(
OutputIteratorType theOutputIterator,
@@ -145,6 +181,12 @@
{
}
+ /**
+ * Changes the output iterator member based on a value.
+ *
+ * @param theValue value to use
+ * @return this object
+ */
PairIsolatorOutputIterator&
operator=(const value_type& theValue)
{
@@ -153,12 +195,22 @@
return *this;
}
+ /**
+ * Retrieve the object.
+ *
+ * @return this object
+ */
PairIsolatorOutputIterator&
operator*()
{
return *this;
}
+ /**
+ * Increments the output iterator member.
+ *
+ * @return this object
+ */
PairIsolatorOutputIterator&
operator++()
{
@@ -167,6 +219,11 @@
return *this;
}
+ /**
+ * Increments the output iterator member.
+ *
+ * @return this object
+ */
PairIsolatorOutputIterator& operator++(int)
{
m_OutputIterator++;
@@ -182,6 +239,9 @@
+/**
+ * Functor to delete value objects in maps, used in STL iteration algorithms.
+ */
template <class T>
#if defined(XALAN_NO_NAMESPACES)
struct MapValueDeleteFunctor : public unary_function<const T::value_type&, void>
@@ -189,6 +249,12 @@
struct MapValueDeleteFunctor : public std::unary_function<const typename T::value_type&, void>
#endif
{
+ /**
+ * Delete the value object in a map value pair. The value of the pair must
+ * be of pointer type.
+ *
+ * @param thePair key-value pair
+ */
result_type
operator()(argument_type thePair)
{
@@ -198,6 +264,11 @@
+/**
+ * Template allows nested execution of for_each algorithm by defining a unary
+ * functor that takes a container object as an argument, allowing iteration
+ * through the container.
+ */
template<class T, class Functor>
#if defined(XALAN_NO_NAMESPACES)
struct nested_for_each_functor : public unary_function<const T::value_type&, Functor>
@@ -205,11 +276,22 @@
struct nested_for_each_functor : public std::unary_function<const typename T::value_type&, Functor>
#endif
{
+ /**
+ * Construct a nested_for_each_functor instance.
+ *
+ * @param theFunctor functor to use as return type
+ */
nested_for_each_functor(Functor theFunctor) :
m_functor(theFunctor)
{
}
+ /**
+ * Execute the () operator, with the side effect of calling for_each on
+ * each element in the container argument with the functor member.
+ *
+ * @param theContainer container object
+ */
typename T::result_type
operator()(argument_type theContainer)
{
@@ -225,6 +307,7 @@
+// $$$ ???
/*
template <class InputIterator, class Function>
Function
@@ -239,13 +322,15 @@
*/
-// This functor is designed to compare 0-terminated arrays. It substitutes for
-// the default less<type*> so that pointers to arrays can be compared, rather than
-// copies of arrays. For example, you might want to use C-style strings as keys
-// in a map, rather than string objects. The default algorithm less<const char*>
-// would just compare the pointers, and not the vector of characters to which it
-// points. Using this algorithm instead of the default will allow the map to
-// work as expected.
+/**
+ * This functor is designed to compare 0-terminated arrays. It substitutes
+ * for the default less<type*> so that pointers to arrays can be compared,
+ * rather than copies of arrays. For example, you might want to use C-style
+ * strings as keys in a map, rather than string objects. The default
+ * algorithm less<const char*> would just compare the pointers, and not the
+ * vector of characters to which it points. Using this algorithm instead of
+ * the default will allow the map to work as expected.
+ */
template<class T>
#if defined(XALAN_NO_NAMESPACES)
struct less_null_terminated_arrays : public binary_function<const T*, const T*, bool>
@@ -253,6 +338,14 @@
struct less_null_terminated_arrays : public std::binary_function<const T*, const T*, bool>
#endif
{
+ /**
+ * Compare the values of two objects.
+ *
+ *
+ * @param theLHS first object to compare
+ * @param theRHS second object to compare
+ * @return true if objects are the same
+ */
result_type
operator()(first_argument_type theLHS,
second_argument_type theRHS) const
1.2 +21 -5 xml-xalan/c/src/TestXPath/NodeNameTreeWalker.hpp
Index: NodeNameTreeWalker.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/TestXPath/NodeNameTreeWalker.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- NodeNameTreeWalker.hpp 1999/12/18 19:47:52 1.1
+++ NodeNameTreeWalker.hpp 2000/03/06 20:23:13 1.2
@@ -75,20 +75,36 @@
{
public:
- /**
- * Constructor.
- */
+#if defined(XALAN_NO_NAMESPACES)
+# define XALAN_STD
+ typedef vector<DOM_Node> NodeVectorType;
+#else
+ typedef std::vector<DOM_Node> NodeVectorType;
+#endif
+
NodeNameTreeWalker();
virtual
~NodeNameTreeWalker();
+ /**
+ * Find all nodes matching a specified node in a specified node tree. The
+ * member m_matchingNodes is populated as a side effect.
+ *
+ * @param theNodeName name of node sought
+ * @param theStartNode start node for search
+ */
virtual void
findMatchingNodes(
const DOMString& theNodeName,
const DOM_Node& theStartNode);
- const std::vector<DOM_Node>&
+ /**
+ * Retrieve the matching nodes from the last search.
+ *
+ * @return vector of nodes
+ */
+ const NodeVectorType&
getMatchingNodes() const
{
return m_matchingNodes;
@@ -105,7 +121,7 @@
private:
DOMString m_nodeName;
- std::vector<DOM_Node> m_matchingNodes;
+ NodeVectorType m_matchingNodes;
};
1.3 +19 -0 xml-xalan/c/src/XercesPlatformSupport/TextFileOutputStream.hpp
Index: TextFileOutputStream.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/XercesPlatformSupport/TextFileOutputStream.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- TextFileOutputStream.hpp 2000/01/25 23:37:21 1.2
+++ TextFileOutputStream.hpp 2000/03/06 20:23:14 1.3
@@ -79,6 +79,11 @@
{
public :
+ /**
+ * Construct an TextFileOutputStream exception object.
+ *
+ * @param theFileName name of file causing the exception
+ */
TextFileOutputStream(const DOMString& theFileName);
virtual
@@ -131,6 +136,13 @@
{
public:
+ /**
+ * Construct an TextFileOutputStreamOpen exception object for an exception
+ * that occurred on opening a text file stream.
+ *
+ * @param theFileName name of file causing the exception
+ * @param theErrorCode number of error encountered
+ */
TextFileOutputStreamOpenException(
const DOMString& theFileName,
int theErrorCode);
@@ -146,6 +158,13 @@
{
public:
+ /**
+ * Construct an TextFileOutputStreamOpen exception object for an exception
+ * that occurred while writing to a text file stream.
+ *
+ * @param theFileName name of file causing the exception
+ * @param theErrorCode number of error encountered
+ */
TextFileOutputStreamWriteException(
const DOMString& theFileName,
int theErrorCode);
1.3 +8 -6 xml-xalan/c/src/XercesPlatformSupport/XercesDOMPrintWriter.hpp
Index: XercesDOMPrintWriter.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/XercesPlatformSupport/XercesDOMPrintWriter.hpp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- XercesDOMPrintWriter.hpp 2000/02/17 20:28:07 1.2
+++ XercesDOMPrintWriter.hpp 2000/03/06 20:23:14 1.3
@@ -76,8 +76,12 @@
{
public:
- // If fAutoFlush is true, the output will not
- // be buffered.
+ /**
+ * Construct a XercesDOMPrintWriter instance.
+ *
+ * @param theOutputStream output stream to write
+ * @param fAutoFlush if true, the output will not be buffered
+ */
XercesDOMPrintWriter(
TextOutputStream& theOutputStream,
bool fAutoFlush = false);
@@ -85,7 +89,8 @@
virtual
~XercesDOMPrintWriter();
- // Flush the stream, then check the error status.
+ // These methods are inherited from PrintWriter ...
+
virtual bool
checkError() const;
@@ -98,13 +103,11 @@
// Output functions...
- // If the length is UINT_MAX, then the array is assumed to be null-terminated.
virtual void
write(const char* s,
unsigned int theOffset = 0,
unsigned int theLength = UINT_MAX);
- // If the length is UINT_MAX, then the entire string is printed.
virtual void
write(const XMLCh* s,
unsigned int theOffset = 0,
@@ -113,7 +116,6 @@
virtual void
write(XMLCh c);
- // If the length is UINT_MAX, then the entire string is printed.
virtual void
write(const DOMString& s,
unsigned int theOffset = 0,
1.2 +6 -0 xml-xalan/c/src/XercesPlatformSupport/XercesPlatformSupportException.hpp
Index: XercesPlatformSupportException.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/XercesPlatformSupport/XercesPlatformSupportException.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XercesPlatformSupportException.hpp 1999/12/18 19:48:15 1.1
+++ XercesPlatformSupportException.hpp 2000/03/06 20:23:14 1.2
@@ -73,6 +73,12 @@
{
public:
+ /**
+ * Construct a Xerces Platform Support exception object
+ *
+ * @param theMessage message to print when exception thrown
+ * @param theType type of exception string
+ */
XercesPlatformSupportException(
const DOMString& theMessage,
const DOMString& theType);
1.2 +7 -1 xml-xalan/c/src/XercesPlatformSupport/XercesStdTextOutputStream.hpp
Index: XercesStdTextOutputStream.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/XercesPlatformSupport/XercesStdTextOutputStream.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XercesStdTextOutputStream.hpp 2000/01/25 22:18:18 1.1
+++ XercesStdTextOutputStream.hpp 2000/03/06 20:23:15 1.2
@@ -79,8 +79,14 @@
// A base class for all text output streams.
class XALAN_XERCESPLATFORMSUPPORT_EXPORT XercesStdTextOutputStream : public XercesTextOutputStream
{
-public :
+public:
+ /**
+ * Construct a XercesStdTextOutputStream instance for output to the
+ * standard output device.
+ *
+ * @param theOutputStream output stream to use
+ */
XercesStdTextOutputStream(std::ostream& theOutputStream);
virtual
1.2 +9 -0 xml-xalan/c/src/XercesPlatformSupport/XercesTextOutputStream.hpp
Index: XercesTextOutputStream.hpp
===================================================================
RCS file: /home/cvs/xml-xalan/c/src/XercesPlatformSupport/XercesTextOutputStream.hpp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XercesTextOutputStream.hpp 2000/01/25 22:18:18 1.1
+++ XercesTextOutputStream.hpp 2000/03/06 20:23:15 1.2
@@ -84,7 +84,9 @@
virtual
~XercesTextOutputStream();
+
// These are inherited from TextOutputStream...
+
virtual void
flush();
@@ -95,6 +97,13 @@
write(const char* const theBuffer);
// This is new...
+
+ /**
+ * Write a specified number of characters to the output stream.
+ *
+ * @param theBuffer character buffer to write from
+ * @param theBufferLength number of characters to write
+ */
virtual void
write(
const char* theBuffer,