From a447385e32bed488f1cccd019ecbb80c8e405e2f Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Sun, 9 Oct 2011 13:06:24 +0000 Subject: [PATCH] [#670] Add more Javadoc to Field.xxx() functions --- jOOQ/src/main/java/org/jooq/Field.java | 276 +++++++++++++++++++++++-- 1 file changed, 258 insertions(+), 18 deletions(-) diff --git a/jOOQ/src/main/java/org/jooq/Field.java b/jOOQ/src/main/java/org/jooq/Field.java index 5373510a3f..91bb378fb7 100644 --- a/jOOQ/src/main/java/org/jooq/Field.java +++ b/jOOQ/src/main/java/org/jooq/Field.java @@ -257,6 +257,9 @@ public interface Field extends NamedTypeProviderQueryPart, AliasProvider + * This renders the same on all dialects: + * 
-[this]
 */ Field neg(); @@ -314,11 +317,21 @@ public interface Field extends NamedTypeProviderQueryPart, AliasProvider + * This renders the modulo operation where available: + * 
[this] % [value]
 + * ... or the modulo function elsewhere: + * 
mod([this], [value])
 */ Field mod(Number value); /** * An arithmetic expression getting the modulo of this divided by value + *

+ * This renders the modulo operation where available: + * 

[this] % [value]
+ * ... or the modulo function elsewhere: + * 
mod([this], [value])
 */ Field mod(Field value); @@ -328,131 +341,239 @@ public interface Field extends NamedTypeProviderQueryPart, AliasProvider + * This renders the sign function where available: + * 
sign([this])
 + * ... or simulates it elsewhere (without bind variables on values -1, 0, 1): + * 
+     * CASE WHEN [this] > 0 THEN 1
+     *      WHEN [this] < 0 THEN -1
+     *      ELSE 0
+     * END
      */
     Field sign();
 
     /**
      * Get the absolute value of a numeric field: abs(field)
+     * 

+     * This renders the same on all dialects:
+     * 
abs([this])

      */
     Field abs();
 
     /**
      * Get rounded value of a numeric field: round(field)
+     * 

+     * This renders the round function where available:
+     * 
round([this]) or
+     * round([this], 0)

+     * ... or simulates it elsewhere using floor and ceil
      */
     Field round();
 
     /**
      * Get rounded value of a numeric field: round(field, decimals)
+     * 

+     * This renders the round function where available:
+     * 
round([this], [decimals])

+     * ... or simulates it elsewhere using floor and ceil
      */
     Field round(int decimals);
 
     /**
      * Get the largest integer value not greater than [this]
+     * 

+     * This renders the floor function where available:
+     * 
floor([this])

+     * ... or simulates it elsewhere using round:
+     * 
round([this] - 0.499999999999999)

      */
     Field floor();
 
     /**
      * Get the smallest integer value not less than [this]
+     * 

+     * This renders the ceil or ceiling function where available:
+     * 
ceil([this]) or
+     * ceiling([this])

+     * ... or simulates it elsewhere using round:
+     * 
round([this] + 0.499999999999999)

      */
     Field ceil();
 
     /**
      * Get the sqrt(field) function
+     * 

+     * This renders the sqrt function where available:
+     * 
sqrt([this])
 ... or simulates it elsewhere using
+     * power (which in turn may also be simulated using ln and exp functions):
+     * 
power([this], 0.5)

      */
     Field sqrt();
 
     /**
-     * Get the exp(field) function
+     * Get the exp(field) function, taking this field as the power of e
+     * 

+     * This renders the same on all dialects:
+     * 
exp([this])

      */
     Field exp();
 
     /**
-     * Get the ln(field) function
+     * Get the ln(field) function, taking the natural logarithm of this field
+     * 

+     * This renders the ln or log function where available:
+     * 
ln([this]) or
+     * log([this])

      */
     Field ln();
 
     /**
      * Get the log(field, base) function
+     * 

+     * This renders the log function where available:
+     * 
log([this])
 ... or simulates it elsewhere (in
+     * most RDBMS) using the natural logarithm:
+     * 
ln([this]) / ln([base])

      */
     Field log(int base);
 
     /**
      * Get the power(field, exponent) function
+     * 

+     * This renders the power function where available:
+     * 
power([this], [exponent])
 ... or simulates it
+     * elsewhere using ln and exp:
+     * 
exp(ln([this]) * [exponent])

      */
     Field power(Number exponent);
 
     /**
      * Get the arc cosine(field) function
+     * 

+     * This renders the acos function where available:
+     * 
acos([this])

      */
     Field acos();
 
     /**
      * Get the arc sine(field) function
+     * 

+     * This renders the asin function where available:
+     * 
asin([this])

      */
     Field asin();
 
     /**
      * Get the arc tangent(field) function
+     * 

+     * This renders the atan function where available:
+     * 
atan([this])

      */
     Field atan();
 
     /**
      * Get the arc tangent 2(field, y) function
+     * 

+     * This renders the atan2 or atn2 function where available:
+     * 
atan2([this]) or
+     * atn2([this])

      */
     Field atan2(Number y);
 
     /**
      * Get the arc tangent 2(field, y) function
+     * 

+     * This renders the atan2 or atn2 function where available:
+     * 
atan2([this]) or
+     * atn2([this])

      */
     Field atan2(Field y);
 
     /**
      * Get the cosine(field) function
+     * 

+     * This renders the cos function where available:
+     * 
cos([this])

      */
     Field cos();
 
     /**
      * Get the sine(field) function
+     * 

+     * This renders the sin function where available:
+     * 
sin([this])

      */
     Field sin();
 
     /**
      * Get the tangent(field) function
+     * 

+     * This renders the tan function where available:
+     * 
tan([this])

      */
     Field tan();
 
     /**
      * Get the cotangent(field) function
+     * 

+     * This renders the cot function where available:
+     * 
cot([this])
 ... or simulates it elsewhere using
+     * sin and cos: 
cos([this]) / sin([this])

      */
     Field cot();
 
     /**
      * Get the hyperbolic sine function: sinh(field)
+     * 

+     * This renders the sinh function where available:
+     * 
sinh([this])
 ... or simulates it elsewhere using
+     * exp: 
(exp([this] * 2) - 1) / (exp([this] * 2))

      */
     Field sinh();
 
     /**
      * Get the hyperbolic cosine function: cosh(field)
+     * 

+     * This renders the cosh function where available:
+     * 
cosh([this])
 ... or simulates it elsewhere using
+     * exp: 
(exp([this] * 2) + 1) / (exp([this] * 2))

      */
     Field cosh();
 
     /**
      * Get the hyperbolic tangent function: tanh(field)
+     * 

+     * This renders the tanh function where available:
+     * 
tanh([this])
 ... or simulates it elsewhere using
+     * exp:
+     * 
(exp([this] * 2) - 1) / (exp([this] * 2) + 1)

      */
     Field tanh();
 
     /**
      * Get the hyperbolic cotangent function: coth(field)
+     * 

+     * This is not supported by any RDBMS, but simulated using exp exp:
+     * 
(exp([this] * 2) + 1) / (exp([this] * 2) - 1)

      */
     Field coth();
 
     /**
      * Calculate degrees from radians from this field
+     * 

+     * This renders the degrees function where available:
+     * 
degrees([this])
 ... or simulates it elsewhere:
+     * 
[this] * 180 / PI

      */
     Field deg();
 
     /**
      * Calculate radians from degrees from this field
+     * 

+     * This renders the degrees function where available:
+     * 
degrees([this])
 ... or simulates it elsewhere:
+     * 
[this] * PI / 180

      */
     Field rad();
 
@@ -632,115 +753,226 @@ public interface Field extends NamedTypeProviderQueryPart, AliasProvider
+     * This renders the upper function in all dialects:
+     * 
upper([this])

      */
     Field upper();
 
     /**
      * Get the lower(field) function
+     * 

+     * This renders the lower function in all dialects:
+     * 
lower([this])

      */
     Field lower();
 
     /**
      * Get the trim(field) function
+     * 

+     * This renders the trim function where available:
+     * 
trim([this])
 ... or simulates it elsewhere using
+     * rtrim and ltrim: 
ltrim(rtrim([this]))

      */
     Field trim();
 
     /**
      * Get the rtrim(field) function
+     * 

+     * This renders the rtrim function in all dialects:
+     * 
rtrim([this])

      */
     Field rtrim();
 
     /**
      * Get the ltrim(field) function
+     * 

+     * This renders the ltrim function in all dialects:
+     * 
ltrim([this])

      */
     Field ltrim();
 
     /**
      * Get the rpad(field, length) function
+     * 

+     * This renders the rpad function where available:
+     * 
rpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat([this], repeat(' ', [length] - length([this])))

      */
     Field rpad(Field length);
 
     /**
      * Get the rpad(field, length) function
+     * 

+     * This renders the rpad function where available:
+     * 
rpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat([this], repeat(' ', [length] - length([this])))

      */
     Field rpad(int length);
 
     /**
-     * Get the rpad(field, length, c) function
+     * Get the rpad(field, length, character) function
+     * 

+     * This renders the rpad function where available:
+     * 
rpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat([this], repeat([character], [length] - length([this])))

      */
-    Field rpad(Field length, Field c);
+    Field rpad(Field length, Field character);
 
     /**
-     * Get the rpad(field, length, c) function
+     * Get the rpad(field, length, character) function
+     * 

+     * This renders the rpad function where available:
+     * 
rpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat([this], repeat([character], [length] - length([this])))

      */
-    Field rpad(int length, char c);
+    Field rpad(int length, char character);
 
     /**
-     * Get the rpad(field, length) function
+     * Get the lpad(field, length) function
+     * 

+     * This renders the lpad function where available:
+     * 
lpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat(repeat(' ', [length] - length([this])), [this])

      */
     Field lpad(Field length);
 
     /**
-     * Get the rpad(field, length) function
+     * Get the lpad(field, length) function
+     * 

+     * This renders the lpad function where available:
+     * 
lpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat(repeat(' ', [length] - length([this])), [this])

      */
     Field lpad(int length);
 
     /**
-     * Get the rpad(field, length, c) function
+     * Get the lpad(field, length, character) function
+     * 

+     * This renders the lpad function where available:
+     * 
lpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat(repeat([character], [length] - length([this])), [this])

      */
-    Field lpad(Field length, Field c);
+    Field lpad(Field length, Field character);
 
     /**
-     * Get the rpad(field, length, c) function
+     * Get the lpad(field, length, character) function
+     * 

+     * This renders the lpad function where available:
+     * 
lpad([this], [length])
 ... or simulates it
+     * elsewhere using concat, repeat, and length, which may be simulated as
+     * well, depending on the RDBMS:
+     * 
concat(repeat([character], [length] - length([this])), [this])

      */
-    Field lpad(int length, char c);
+    Field lpad(int length, char character);
 
     /**
      * Get the repeat(count) function
+     * 

+     * This renders the repeat or replicate function where available:
+     * 
repeat([this], [count]) or
+     * replicate([this], [count])
 ... or simulates it elsewhere
+     * using rpad and length, which may be simulated as well, depending on the
+     * RDBMS:
+     * 
rpad([this], length([this]) * [count], [this])

      */
     Field repeat(Number count);
 
     /**
      * Get the repeat(field, count) function
+     * 

+     * This renders the repeat or replicate function where available:
+     * 
repeat([this], [count]) or
+     * replicate([this], [count])
 ... or simulates it elsewhere
+     * using rpad and length, which may be simulated as well, depending on the
+     * RDBMS:
+     * 
rpad([this], length([this]) * [count], [this])

      */
     Field repeat(Field count);
 
     /**
      * Get the replace(in, search) function
+     * 

+     * This renders the replace or str_replace function where available:
+     * 
replace([this], [search]) or
+     * str_replace([this], [search])
 ... or simulates it elsewhere
+     * using the three-argument replace function:
+     * 
replace([this], [search], '')

      */
     Field replace(Field search);
 
     /**
      * Get the replace(in, search) function
+     * 

+     * This renders the replace or str_replace function where available:
+     * 
replace([this], [search]) or
+     * str_replace([this], [search])
 ... or simulates it elsewhere
+     * using the three-argument replace function:
+     * 
replace([this], [search], '')

      */
     Field replace(String search);
 
     /**
      * Get the replace(in, search, replace) function
+     * 

+     * This renders the replace or str_replace function:
+     * 
replace([this], [search]) or
+     * str_replace([this], [search])

      */
     Field replace(Field search, Field replace);
 
     /**
      * Get the replace(in, search, replace) function
+     * 

+     * This renders the replace or str_replace function:
+     * 
replace([this], [search]) or
+     * str_replace([this], [search])

      */
     Field replace(String search, String replace);
 
     /**
      * Get the position(in, search) function
      * 

-     * This translates into any dialect
+     * This renders the position or any equivalent function:
+     * 
position([search] in [this]) or
+     * locate([this], [search]) or
+     * locate([search], [this]) or
+     * instr([this], [search]) or
+     * charindex([search], [this])

      */
     Field position(String search);
 
     /**
      * Get the position(in, search) function
      * 

-     * This translates into any dialect
+     * This renders the position or any equivalent function:
+     * 
position([search] in [this]) or
+     * locate([this], [search]) or
+     * locate([search], [this]) or
+     * instr([this], [search]) or
+     * charindex([search], [this])

      */
     Field position(Field search);
 
     /**
      * Get the ascii(field) function
+     * 

+     * This renders the replace or str_replace function:
+     * 
ascii([this])

      */
     Field ascii();
 
@@ -768,28 +1000,36 @@ public interface Field extends NamedTypeProviderQueryPart, AliasProvider
-     * This translates into any dialect
+     * This renders the substr or substring function:
+     * 
substr([this], [startingPosition]) or
+     * substring([this], [startingPosition])

      */
     Field substring(int startingPosition);
 
     /**
      * Get the substring(field, startingPosition) function
      * 

-     * This translates into any dialect
+     * This renders the substr or substring function:
+     * 
substr([this], [startingPosition]) or
+     * substring([this], [startingPosition])

      */
     Field substring(Field startingPosition);
 
     /**
      * Get the substring(field, startingPosition, length) function
      * 

-     * This translates into any dialect
+     * This renders the substr or substring function:
+     * 
substr([this], [startingPosition], [length]) or
+     * substring([this], [startingPosition], [length])

      */
     Field substring(int startingPosition, int length);
 
     /**
      * Get the substring(field, startingPosition, length) function
      * 

-     * This translates into any dialect
+     * This renders the substr or substring function:
+     * 
substr([this], [startingPosition], [length]) or
+     * substring([this], [startingPosition], [length])

      */
     Field substring(Field startingPosition, Field length);