You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xalan.apache.org by mk...@apache.org on 2002/10/30 17:41:11 UTC
cvs commit: xml-xalan/java/src/org/apache/xalan/lib ExsltDynamic.java ExsltMath.java ExsltStrings.java
mkwan 2002/10/30 08:41:11
Modified: java/src/org/apache/xalan/lib ExsltDynamic.java
ExsltMath.java ExsltStrings.java
Log:
Javadoc update for EXSLT functions.
Revision Changes Path
1.4 +105 -63 xml-xalan/java/src/org/apache/xalan/lib/ExsltDynamic.java
Index: ExsltDynamic.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/ExsltDynamic.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ExsltDynamic.java 23 Sep 2002 16:22:40 -0000 1.3
+++ ExsltDynamic.java 30 Oct 2002 16:41:11 -0000 1.4
@@ -85,7 +85,6 @@
* <pre>
* xmlns:math="http://exslt.org/dynamic"
* </pre>
- *
* The documentation for each function has been copied from the relevant
* EXSLT Implementer page.
*
@@ -101,26 +100,34 @@
* The dyn:max function calculates the maximum value for the nodes passed as
* the first argument, where the value of each node is calculated dynamically
* using an XPath expression passed as a string as the second argument.
- *
+ * <p>
* The expressions are evaluated relative to the nodes passed as the first argument.
* In other words, the value for each node is calculated by evaluating the XPath
* expression with all context information being the same as that for the call to
- * the dyn:max function itself, except for the following:
- *
- * - the context node is the node whose value is being calculated
- * - the context position is the position of the node within the node set passed as
- * the first argument to the dyn:max function, arranged in document order
- * - the context size is the number of nodes passed as the first argument to the
- * dyn:max function
- *
+ * the dyn:max function itself, except for the following:
+ * <p>
+ * <ul>
+ * <li>the context node is the node whose value is being calculated.</li>
+ * <li>the context position is the position of the node within the node set passed as
+ * the first argument to the dyn:max function, arranged in document order.</li>
+ * <li>the context size is the number of nodes passed as the first argument to the
+ * dyn:max function.</li>
+ * </ul>
+ * <p>
* The dyn:max function returns the maximum of these values, calculated in exactly
* the same way as for math:max.
- *
+ * <p>
* If the expression string passed as the second argument is an invalid XPath
* expression (including an empty string), this function returns NaN.
- *
+ * <p>
* This function must take a second argument. To calculate the maximum of a set of
* nodes based on their string values, you should use the math:max function.
+ *
+ * @param myContext The ExpressionContext passed by the extension processor
+ * @param nl The node set
+ * @param expr The expression string
+ *
+ * @return The maximum evaluation value
*/
public static double max(ExpressionContext myContext, NodeList nl, String expr)
throws SAXNotSupportedException
@@ -174,26 +181,34 @@
* The dyn:min function calculates the minimum value for the nodes passed as the
* first argument, where the value of each node is calculated dynamically using
* an XPath expression passed as a string as the second argument.
- *
+ * <p>
* The expressions are evaluated relative to the nodes passed as the first argument.
* In other words, the value for each node is calculated by evaluating the XPath
* expression with all context information being the same as that for the call to
* the dyn:min function itself, except for the following:
- *
- * - the context node is the node whose value is being calculated
- * - the context position is the position of the node within the node set passed
- * as the first argument to the dyn:min function, arranged in document order
- * - the context size is the number of nodes passed as the first argument to the
- * dyn:min function
- *
+ * <p>
+ * <ul>
+ * <li>the context node is the node whose value is being calculated.</li>
+ * <li>the context position is the position of the node within the node set passed
+ * as the first argument to the dyn:min function, arranged in document order.</li>
+ * <li>the context size is the number of nodes passed as the first argument to the
+ * dyn:min function.</li>
+ * </ul>
+ * <p>
* The dyn:min function returns the minimum of these values, calculated in exactly
* the same way as for math:min.
- *
+ * <p>
* If the expression string passed as the second argument is an invalid XPath expression
* (including an empty string), this function returns NaN.
- *
+ * <p>
* This function must take a second argument. To calculate the minimum of a set of
* nodes based on their string values, you should use the math:min function.
+ *
+ * @param myContext The ExpressionContext passed by the extension processor
+ * @param nl The node set
+ * @param expr The expression string
+ *
+ * @return The minimum evaluation value
*/
public static double min(ExpressionContext myContext, NodeList nl, String expr)
throws SAXNotSupportedException
@@ -247,26 +262,34 @@
* The dyn:sum function calculates the sum for the nodes passed as the first argument,
* where the value of each node is calculated dynamically using an XPath expression
* passed as a string as the second argument.
- *
+ * <p>
* The expressions are evaluated relative to the nodes passed as the first argument.
* In other words, the value for each node is calculated by evaluating the XPath
* expression with all context information being the same as that for the call to
* the dyn:sum function itself, except for the following:
- *
- * - the context node is the node whose value is being calculated
- * - the context position is the position of the node within the node set passed as
- * the first argument to the dyn:sum function, arranged in document order
- * - the context size is the number of nodes passed as the first argument to the
- * dyn:sum function
- *
+ * <p>
+ * <ul>
+ * <li>the context node is the node whose value is being calculated.</li>
+ * <li>the context position is the position of the node within the node set passed as
+ * the first argument to the dyn:sum function, arranged in document order.</li>
+ * <li>the context size is the number of nodes passed as the first argument to the
+ * dyn:sum function.</li>
+ * </ul>
+ * <p>
* The dyn:sum function returns the sumimum of these values, calculated in exactly
* the same way as for sum.
- *
+ * <p>
* If the expression string passed as the second argument is an invalid XPath
* expression (including an empty string), this function returns NaN.
- *
+ * <p>
* This function must take a second argument. To calculate the sumimum of a set of
* nodes based on their string values, you should use the sum function.
+ *
+ * @param myContext The ExpressionContext passed by the extension processor
+ * @param nl The node set
+ * @param expr The expression string
+ *
+ * @return The sum of the evaluation value on each node
*/
public static double sum(ExpressionContext myContext, NodeList nl, String expr)
throws SAXNotSupportedException
@@ -317,27 +340,29 @@
/**
* The dyn:map function evaluates the expression passed as the second argument for
* each of the nodes passed as the first argument, and returns a node set of those values.
- *
+ * <p>
* The expressions are evaluated relative to the nodes passed as the first argument.
* In other words, the value for each node is calculated by evaluating the XPath
* expression with all context information being the same as that for the call to
- * the dyn:map function itself, except for the following:
- *
- * - the context node is the node whose value is being calculated
- * - the context position is the position of the node within the node set passed
- * as the first argument to the dyn:map function, arranged in document order
- * - the context size is the number of nodes passed as the first argument to the
- * dyn:map function
- *
+ * the dyn:map function itself, except for the following:
+ * <p>
+ * <ul>
+ * <li>The context node is the node whose value is being calculated.</li>
+ * <li>the context position is the position of the node within the node set passed
+ * as the first argument to the dyn:map function, arranged in document order.</li>
+ * <li>the context size is the number of nodes passed as the first argument to the
+ * dyn:map function.</li>
+ * </ul>
+ * <p>
* If the expression string passed as the second argument is an invalid XPath
* expression (including an empty string), this function returns an empty node set.
- *
+ * <p>
* If the XPath expression evaluates as a node set, the dyn:map function returns
* the union of the node sets returned by evaluating the expression for each of the
* nodes in the first argument. Note that this may mean that the node set resulting
* from the call to the dyn:map function contains a different number of nodes from
* the number in the node set passed as the first argument to the function.
- *
+ * <p>
* If the XPath expression evaluates as a number, the dyn:map function returns a
* node set containing one exsl:number element (namespace http://exslt.org/common)
* for each node in the node set passed as the first argument to the dyn:map function,
@@ -347,20 +372,26 @@
* in an exsl:number holding the highest number the implementation can store, and
* -Infinity results in an exsl:number holding the lowest number the implementation
* can store.
- *
+ * <p>
* If the XPath expression evaluates as a boolean, the dyn:map function returns a
* node set containing one exsl:boolean element (namespace http://exslt.org/common)
* for each node in the node set passed as the first argument to the dyn:map function,
* in document order. The string value of each exsl:boolean element is 'true' if the
* expression evaluates as true for the node, and '' if the expression evaluates as
* false.
- *
+ * <p>
* Otherwise, the dyn:map function returns a node set containing one exsl:string
* element (namespace http://exslt.org/common) for each node in the node set passed
* as the first argument to the dyn:map function, in document order. The string
* value of each exsl:string element is the same as the result of converting the
* result of evaluating the expression for the relevant node to a string as with
- * the string function.
+ * the string function.
+ *
+ * @param myContext The ExpressionContext passed by the extension processor
+ * @param nl The node set
+ * @param expr The expression string
+ *
+ * @return The node set after evaluation
*/
public static NodeList map(ExpressionContext myContext, NodeList nl, String expr)
throws SAXNotSupportedException
@@ -446,12 +477,17 @@
* The dyn:evaluate function evaluates a string as an XPath expression and returns
* the resulting value, which might be a boolean, number, string, node set, result
* tree fragment or external object. The sole argument is the string to be evaluated.
- *
+ * <p>
* If the expression string passed as the second argument is an invalid XPath
* expression (including an empty string), this function returns an empty node set.
+ * <p>
+ * You should only use this function if the expression must be constructed dynamically,
+ * otherwise it is much more efficient to use the expression literally.
*
- * You should only use this function if the expression must be constructed dynamically
- * - otherwise it is much more efficient to use the expression literally.
+ * @param myContext The ExpressionContext passed by the extension processor
+ * @param xpathExpr The XPath expression string
+ *
+ * @return The evaluation result
*/
public static XObject evaluate(ExpressionContext myContext, String xpathExpr)
throws SAXNotSupportedException
@@ -483,37 +519,43 @@
* evaluating the expression passed as the second argument on each of the nodes passed
* as the first argument, then on the node set resulting from that and so on until no
* more nodes are found. For example:
- *
* <pre>
* dyn:closure(., '*')
* </pre>
- *
* returns all the descendant elements of the node (its element children, their
* children, their children's children and so on).
- *
+ * <p>
* The expression is thus evaluated several times, each with a different node set
* acting as the context of the expression. The first time the expression is
* evaluated, the context node set is the first argument passed to the dyn:closure
* function. In other words, the node set for each node is calculated by evaluating
* the XPath expression with all context information being the same as that for
- * the call to the dyn:closure function itself, except for the following:
- *
- * - the context node is the node whose value is being calculated
- * - the context position is the position of the node within the node set passed
- * as the first argument to the dyn:closure function, arranged in document order
- * - the context size is the number of nodes passed as the first argument to the
- * dyn:closure function
- * - the current node is the node whose value is being calculated
- *
+ * the call to the dyn:closure function itself, except for the following:
+ * <p>
+ * <ul>
+ * <li>the context node is the node whose value is being calculated.</li>
+ * <li>the context position is the position of the node within the node set passed
+ * as the first argument to the dyn:closure function, arranged in document order.</li>
+ * <li>the context size is the number of nodes passed as the first argument to the
+ * dyn:closure function.</li>
+ * <li>the current node is the node whose value is being calculated.</li>
+ * </ul>
+ * <p>
* The result for a particular iteration is the union of the node sets resulting
* from evaluting the expression for each of the nodes in the source node set for
* that iteration. This result is then used as the source node set for the next
* iteration, and so on. The result of the function as a whole is the union of
* the node sets generated by each iteration.
- *
+ * <p>
* If the expression string passed as the second argument is an invalid XPath
* expression (including an empty string) or an expression that does not return a
- * node set, this function returns an empty node set.
+ * node set, this function returns an empty node set.
+ *
+ * @param myContext The ExpressionContext passed by the extension processor
+ * @param nl The node set
+ * @param expr The expression string
+ *
+ * @return The node set after evaluation
*/
public static NodeList closure(ExpressionContext myContext, NodeList nl, String expr)
throws SAXNotSupportedException
1.8 +49 -6 xml-xalan/java/src/org/apache/xalan/lib/ExsltMath.java
Index: ExsltMath.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/ExsltMath.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- ExsltMath.java 4 Oct 2002 13:58:28 -0000 1.7
+++ ExsltMath.java 30 Oct 2002 16:41:11 -0000 1.8
@@ -91,7 +91,7 @@
* in descending order as it would be by xsl:sort with a data type of number. The maximum
* is the result of converting the string value of the first node in this sorted list to
* a number using the number function.
- *
+ * <p>
* If the node set is empty, or if the result of converting the string values of any of the
* nodes to a number is NaN, then NaN is returned.
*
@@ -126,7 +126,7 @@
* in ascending order as it would be by xsl:sort with a data type of number. The minimum
* is the result of converting the string value of the first node in this sorted list to
* a number using the number function.
- *
+ * <p>
* If the node set is empty, or if the result of converting the string values of any of
* the nodes to a number is NaN, then NaN is returned.
*
@@ -161,7 +161,7 @@
* calculated by math:max. A node has this maximum value if the result of converting its
* string value to a number as if by the number function is equal to the maximum value,
* where the equality comparison is defined as a numerical comparison using the = operator.
- *
+ * <p>
* If any of the nodes in the node set has a non-numeric value, the math:max function will
* return NaN. The definition numeric comparisons entails that NaN != NaN. Therefore if any
* of the nodes in the node set has a non-numeric value, math:highest will return an empty
@@ -198,7 +198,7 @@
* by math:min. A node has this minimum value if the result of converting its string value to
* a number as if by the number function is equal to the minimum value, where the equality
* comparison is defined as a numerical comparison using the = operator.
- *
+ * <p>
* If any of the nodes in the node set has a non-numeric value, the math:min function will return
* NaN. The definition numeric comparisons entails that NaN != NaN. Therefore if any of the nodes
* in the node set has a non-numeric value, math:lowest will return an empty node set.
@@ -230,7 +230,10 @@
}
/**
- * The math:abs function returns the absolute value of a number.
+ * The math:abs function returns the absolute value of a number.
+ *
+ * @param num A number
+ * @return The absolute value of the number
*/
public static double abs(double num)
{
@@ -238,7 +241,10 @@
}
/**
- * The math:acos function returns the arccosine value of a number.
+ * The math:acos function returns the arccosine value of a number.
+ *
+ * @param num A number
+ * @return The arccosine value of the number
*/
public static double acos(double num)
{
@@ -247,6 +253,9 @@
/**
* The math:asin function returns the arcsine value of a number.
+ *
+ * @param num A number
+ * @return The arcsine value of the number
*/
public static double asin(double num)
{
@@ -255,6 +264,9 @@
/**
* The math:atan function returns the arctangent value of a number.
+ *
+ * @param num A number
+ * @return The arctangent value of the number
*/
public static double atan(double num)
{
@@ -263,6 +275,10 @@
/**
* The math:atan2 function returns the angle ( in radians ) from the X axis to a point (y,x).
+ *
+ * @param num1 The X axis value
+ * @param num2 The Y axis value
+ * @return The angle (in radians) from the X axis to a point (y,x)
*/
public static double atan2(double num1, double num2)
{
@@ -271,6 +287,9 @@
/**
* The math:cos function returns cosine of the passed argument.
+ *
+ * @param num A number
+ * @return The cosine value of the number
*/
public static double cos(double num)
{
@@ -279,6 +298,9 @@
/**
* The math:exp function returns e (the base of natural logarithms) raised to a power.
+ *
+ * @param num A number
+ * @return The value of e raised to the given power
*/
public static double exp(double num)
{
@@ -287,6 +309,9 @@
/**
* The math:log function returns the natural logarithm of a number.
+ *
+ * @param num A number
+ * @return The natural logarithm of the number
*/
public static double log(double num)
{
@@ -295,6 +320,10 @@
/**
* The math:power function returns the value of a base expression taken to a specified power.
+ *
+ * @param num1 The base
+ * @param num2 The power
+ * @return The value of the base expression taken to the specified power
*/
public static double power(double num1, double num2)
{
@@ -303,6 +332,8 @@
/**
* The math:random function returns a random number from 0 to 1.
+ *
+ * @return A random double from 0 to 1
*/
public static double random()
{
@@ -311,6 +342,9 @@
/**
* The math:sin function returns the sine of the number.
+ *
+ * @param num A number
+ * @return The sine value of the number
*/
public static double sin(double num)
{
@@ -319,6 +353,9 @@
/**
* The math:sqrt function returns the square root of a number.
+ *
+ * @param num A number
+ * @return The square root of the number
*/
public static double sqrt(double num)
{
@@ -327,6 +364,9 @@
/**
* The math:tan function returns the tangent of the number passed as an argument.
+ *
+ * @param num A number
+ * @return The tangent value of the number
*/
public static double tan(double num)
{
@@ -345,6 +385,9 @@
* LOG2E
* SQRT1_2
* </pre>
+ * @param name The name of the constant
+ * @param precision The precision
+ * @return The value of the specified constant to the given precision
*/
public static double constant(String name, double precision)
{
1.6 +37 -20 xml-xalan/java/src/org/apache/xalan/lib/ExsltStrings.java
Index: ExsltStrings.java
===================================================================
RCS file: /home/cvs/xml-xalan/java/src/org/apache/xalan/lib/ExsltStrings.java,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- ExsltStrings.java 29 Oct 2002 16:17:35 -0000 1.5
+++ ExsltStrings.java 30 Oct 2002 16:41:11 -0000 1.6
@@ -69,7 +69,6 @@
* <pre>
* xmlns:math="http://exslt.org/strings"
* </pre>
- *
* The documentation for each function has been copied from the relevant
* EXSLT Implementer page.
*
@@ -83,16 +82,16 @@
/**
* The str:align function aligns a string within another string.
- *
+ * <p>
* The first argument gives the target string to be aligned. The second argument gives
* the padding string within which it is to be aligned.
- *
+ * <p>
* If the target string is shorter than the padding string then a range of characters
* in the padding string are repaced with those in the target string. Which characters
* are replaced depends on the value of the third argument, which gives the type of
* alignment. It can be one of 'left', 'right' or 'center'. If no third argument is
* given or if it is not one of these values, then it defaults to left alignment.
- *
+ * <p>
* With left alignment, the range of characters replaced by the target string begins
* with the first character in the padding string. With right alignment, the range of
* characters replaced by the target string ends with the last character in the padding
@@ -100,9 +99,15 @@
* is in the middle of the padding string, such that either the number of unreplaced
* characters on either side of the range is the same or there is one less on the left
* than there is on the right.
- *
+ * <p>
* If the target string is longer than the padding string, then it is truncated to be
- * the same length as the padding string and returned.
+ * the same length as the padding string and returned.
+ *
+ * @param targetStr The target string
+ * @param paddingStr The padding string
+ * @param type The type of alignment
+ *
+ * @return The string after alignment
*/
public static String align(String targetStr, String paddingStr, String type)
{
@@ -136,7 +141,10 @@
/**
* The str:concat function takes a node set and returns the concatenation of the
* string values of the nodes in that node set. If the node set is empty, it returns
- * an empty string.
+ * an empty string.
+ *
+ * @param nl A node set
+ * @return The concatenation of the string values of the nodes in that node set
*/
public static String concat(NodeList nl)
{
@@ -161,7 +169,12 @@
* length specified by the first argument; if the string is more than a character
* long, it may have to be truncated to produce the required length. If no second
* argument is specified, it defaults to a space (' '). If the second argument is
- * an empty string, str:padding returns an empty string.
+ * an empty string, str:padding returns an empty string.
+ *
+ * @param length The length of the padding string to be created
+ * @param pattern The string to be used as pattern
+ *
+ * @return A padding string of the given length
*/
public static String padding(double length, String pattern)
{
@@ -196,21 +209,23 @@
/**
* The str:split function splits up a string and returns a node set of token
* elements, each containing one token from the string.
- *
+ * <p>
* The first argument is the string to be split. The second argument is a pattern
* string. The string given by the first argument is split at any occurrence of
* this pattern. For example:
- *
* <pre>
- * str:split('a, simple, list', ', ')
- * Gives the node set consisting of:
+ * str:split('a, simple, list', ', ') gives the node set consisting of:
*
* <token>a</token>
* <token>simple</token>
* <token>list</token>
* </pre>
- *
* If the second argument is omitted, the default is the string ' ' (i.e. a space).
+ *
+ * @param str The string to be split
+ * @param pattern The pattern
+ *
+ * @return A node set of split tokens
*/
public static NodeList split(String str, String pattern)
{
@@ -266,15 +281,13 @@
/**
* The str:tokenize function splits up a string and returns a node set of token
* elements, each containing one token from the string.
- *
+ * <p>
* The first argument is the string to be tokenized. The second argument is a
* string consisting of a number of characters. Each character in this string is
* taken as a delimiting character. The string given by the first argument is split
* at any occurrence of any of these characters. For example:
- *
* <pre>
- * str:tokenize('2001-06-03T11:40:23', '-T:')
- * Gives the node set consisting of:
+ * str:tokenize('2001-06-03T11:40:23', '-T:') gives the node set consisting of:
*
* <token>2001</token>
* <token>06</token>
@@ -283,16 +296,20 @@
* <token>40</token>
* <token>23</token>
* </pre>
-
* If the second argument is omitted, the default is the string '	

 '
* (i.e. whitespace characters).
- *
+ * <p>
* If the second argument is an empty string, the function returns a set of token
* elements, each of which holds a single character.
- *
+ * <p>
* Note: This one is different from the tokenize extension function in the Xalan
* namespace. The one in Xalan returns a set of Text nodes, while this one wraps
* the Text nodes inside the token Element nodes.
+ *
+ * @param toTokenize The string to be tokenized
+ * @param delims The delimiter string
+ *
+ * @return A node set of split token elements
*/
public static NodeList tokenize(String toTokenize, String delims)
{
---------------------------------------------------------------------
To unsubscribe, e-mail: xalan-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xalan-cvs-help@xml.apache.org