Skip to content

Add support for non-integer dimensions in Unit API #257

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Dustin4444 wants to merge 1 commit into
base: master
Choose a base branch
from
+27 −27
Open

Add support for non-integer dimensions in Unit API #257

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/apidocs/javax/measure/Dimension.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -189,7 +189,7 @@ <h3>divide</h3>
<li>
<section class="detail" id="pow(int)">
<h3>pow</h3>
<div class="member-signature"><span class="return-type"><a href="Dimension.html" title="interface in javax.measure">Dimension</a></span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Dimension.html#line-79">pow</a></span><wbr><span class="parameters">(int&nbsp;n)</span></div>
<div class="member-signature"><span class="return-type"><a href="Dimension.html" title="interface in javax.measure">Dimension</a></span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Dimension.html#line-79">pow</a></span><wbr><span class="parameters">(double&nbsp;n)</span></div>
<div class="block">Returns this dimension raised to an exponent. <code>(this<sup>n</sup>)</code></div>
<dl class="notes">
<dt>Parameters:</dt>
Expand All @@ -202,7 +202,7 @@ <h3>pow</h3>
<li>
<section class="detail" id="root(int)">
<h3>root</h3>
<div class="member-signature"><span class="return-type"><a href="Dimension.html" title="interface in javax.measure">Dimension</a></span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Dimension.html#line-90">root</a></span><wbr><span class="parameters">(int&nbsp;n)</span></div>
<div class="member-signature"><span class="return-type"><a href="Dimension.html" title="interface in javax.measure">Dimension</a></span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Dimension.html#line-90">root</a></span><wbr><span class="parameters">(double&nbsp;n)</span></div>
<div class="block">Returns the given root of this dimension.</div>
<dl class="notes">
<dt>Parameters:</dt>
Expand All @@ -217,7 +217,7 @@ <h3>root</h3>
<li>
<section class="detail" id="getBaseDimensions()">
<h3>getBaseDimensions</h3>
<div class="member-signature"><span class="return-type"><a href="https://docs.oracle.com/javase/8/docs/api/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;? extends <a href="Dimension.html" title="interface in javax.measure">Dimension</a>,<wbr><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html" title="class or interface in java.lang" class="external-link">Integer</a>&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Dimension.html#line-98">getBaseDimensions</a></span>()</div>
<div class="member-signature"><span class="return-type"><a href="https://docs.oracle.com/javase/8/docs/api/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;? extends <a href="Dimension.html" title="interface in javax.measure">Dimension</a>,<wbr><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html" title="class or interface in java.lang" class="external-link">Double</a>&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Dimension.html#line-98">getBaseDimensions</a></span>()</div>
<div class="block">Returns the (fundamental) base dimensions and their exponent whose product is this dimension, or <code>null</code> if this dimension is a base
dimension.</div>
<dl class="notes">
Expand Down
28 changes: 14 additions & 14 deletions docs/apidocs/javax/measure/Unit.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ <h2>Method Summary</h2>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Returns the quotient of this unit with the one specified.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;? extends <a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;,<wbr><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html" title="class or interface in java.lang" class="external-link">Integer</a>&gt;</code></div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="https://docs.oracle.com/javase/8/docs/api/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;? extends <a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;,<wbr><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html" title="class or interface in java.lang" class="external-link">Double</a>&gt;</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#getBaseUnits()" class="member-name-link">getBaseUnits</a>()</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Returns the base units and their exponent whose product is this unit, or <code>null</code> if this unit is a base unit (not a product of existing
Expand Down Expand Up @@ -243,19 +243,19 @@ <h2>Method Summary</h2>
<div class="block">Returns the product of this unit with the one specified.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#pow(int)" class="member-name-link">pow</a><wbr>(int&nbsp;n)</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#pow(double)" class="member-name-link">pow</a><wbr>(double&nbsp;n)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Returns an unit raised to the n-th (integer) power of this unit.</div>
<div class="block">Returns an unit raised to the n-th power of this unit.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;<a href="Unit.html" title="type parameter in Unit">Q</a>&gt;</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#prefix(javax.measure.Prefix)" class="member-name-link">prefix</a><wbr>(<a href="Prefix.html" title="interface in javax.measure">Prefix</a>&nbsp;prefix)</code></div>
<div class="col-last odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Returns a new unit equal to this unit prefixed by the specified <code>prefix</code>.</div>
</div>
<div class="col-first even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#root(int)" class="member-name-link">root</a><wbr>(int&nbsp;n)</code></div>
<div class="col-second even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#root(double)" class="member-name-link">root</a><wbr>(double&nbsp;n)</code></div>
<div class="col-last even-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3">
<div class="block">Returns an unit that is the n-th (integer) root of this unit.</div>
<div class="block">Returns an unit that is the n-th root of this unit.</div>
</div>
<div class="col-first odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;<a href="Unit.html" title="type parameter in Unit">Q</a>&gt;</code></div>
<div class="col-second odd-row-color method-summary-table method-summary-table-tab2 method-summary-table-tab3"><code><a href="#shift(double)" class="member-name-link">shift</a><wbr>(double&nbsp;offset)</code></div>
Expand Down Expand Up @@ -370,7 +370,7 @@ <h3>getSystemUnit</h3>
<li>
<section class="detail" id="getBaseUnits()">
<h3>getBaseUnits</h3>
<div class="member-signature"><span class="return-type"><a href="https://docs.oracle.com/javase/8/docs/api/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;? extends <a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;,<wbr><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html" title="class or interface in java.lang" class="external-link">Integer</a>&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Unit.html#line-135">getBaseUnits</a></span>()</div>
<div class="member-signature"><span class="return-type"><a href="https://docs.oracle.com/javase/8/docs/api/java/util/Map.html" title="class or interface in java.util" class="external-link">Map</a>&lt;? extends <a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;,<wbr><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/Double.html" title="class or interface in java.lang" class="external-link">Double</a>&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Unit.html#line-135">getBaseUnits</a></span>()</div>
<div class="block">Returns the base units and their exponent whose product is this unit, or <code>null</code> if this unit is a base unit (not a product of existing
units).</div>
<dl class="notes">
Expand Down Expand Up @@ -702,25 +702,25 @@ <h3>divide</h3>
</section>
</li>
<li>
<section class="detail" id="root(int)">
<section class="detail" id="root(double)">
<h3>root</h3>
<div class="member-signature"><span class="return-type"><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Unit.html#line-383">root</a></span><wbr><span class="parameters">(int&nbsp;n)</span></div>
<div class="block">Returns an unit that is the n-th (integer) root of this unit. Equivalent to the mathematical expression <code>unit^(1/n)</code>.</div>
<div class="member-signature"><span class="return-type"><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Unit.html#line-383">root</a></span><wbr><span class="parameters">(double&nbsp;n)</span></div>
<div class="block">Returns an unit that is the n-th root of this unit. Equivalent to the mathematical expression <code>unit^(1/n)</code>.</div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>n</code> - an integer giving the root's order as in 'n-th root'</dd>
<dd><code>n</code> - a double giving the root's order as in 'n-th root'</dd>
<dt>Returns:</dt>
<dd>the n-th root of this unit.</dd>
<dt>Throws:</dt>
<dd><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/ArithmeticException.html" title="class or interface in java.lang" class="external-link">ArithmeticException</a></code> - if <code>n == 0</code> or if this operation would result in an unit with a fractional exponent.</dd>
<dd><code><a href="https://docs.oracle.com/javase/8/docs/api/java/lang/ArithmeticException.html" title="class or interface in java.lang" class="external-link">ArithmeticException</a></code> - if <code>n == 0</code>.</dd>
</dl>
</section>
</li>
<li>
<section class="detail" id="pow(int)">
<section class="detail" id="pow(double)">
<h3>pow</h3>
<div class="member-signature"><span class="return-type"><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Unit.html#line-392">pow</a></span><wbr><span class="parameters">(int&nbsp;n)</span></div>
<div class="block">Returns an unit raised to the n-th (integer) power of this unit. Equivalent to the mathematical expression <code>unit^n</code>.</div>
<div class="member-signature"><span class="return-type"><a href="Unit.html" title="interface in javax.measure">Unit</a>&lt;?&gt;</span>&nbsp;<span class="element-name"><a href="../../src-html/javax/measure/Unit.html#line-392">pow</a></span><wbr><span class="parameters">(double&nbsp;n)</span></div>
<div class="block">Returns an unit raised to the n-th power of this unit. Equivalent to the mathematical expression <code>unit^n</code>.</div>
<dl class="notes">
<dt>Parameters:</dt>
<dd><code>n</code> - the exponent.</dd>
Expand Down
6 changes: 3 additions & 3 deletions src/main/java/javax/measure/Dimension.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ public interface Dimension {
* power to raise this {@code Dimension} to.
* @return <code>this<sup>n</sup></code>
*/
Dimension pow(int n);
Dimension pow(double n);
Copy link
Contributor

@desruisseaux desruisseaux Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pow(int) method cannot be removed (this comment applies also to all other similar changes in this pull-request). The pow(double) method could be added beside the existing pow(int) as method overloading, but see the comment below about whether the double type is really appropriate.

In the common case where the non-integer dimensions are fractions, we don't really need this new API. The same effect could be obtained by pow(numerator).root(denominator). Not all implementations may accept that, but not all implementations would accept the new pow(double) method neither.


/**
* Returns the given root of this dimension.
Expand All @@ -87,13 +87,13 @@ public interface Dimension {
* @throws ArithmeticException
* if {@code n == 0}.
*/
Dimension root(int n);
Dimension root(double n);

/**
* Returns the (fundamental) base dimensions and their exponent whose product is this dimension, or {@code null} if this dimension is a base
* dimension.
*
* @return the mapping between the fundamental dimensions and their exponent.
*/
Map<? extends Dimension, Integer> getBaseDimensions();
Map<? extends Dimension, Double> getBaseDimensions();
Copy link
Contributor

@desruisseaux desruisseaux Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current changes (as of January 20th) are incompatible with the current API. Furthermore, while non-integer dimensions may be needed in some domains, it is also a complication for the majority of users. I'm in favour of supporting advanced uses, but the challenge is to find a way to do that while preserving ease-of-use for the majority of users.

Unless we accept to break the API, this method cannot be changed. We could add a new method with a different name and declare that the old method throws FractionalDimensionException (or something like that) if the dimensions are not integers, but it is not clear to me what should be the name of the new method and, more important, what should be the number type. Is Double really the most appropriate type? For example, if the majority of non-integer dimensions are fractions, it is not easy to reconstitute the fraction from a double.

Before to introduce non-integer dimensions support in the API, I would like to see a list of use cases. Two of them have been mentioned in #256, but I would like to see more examples with more details.

Copy link
Member

@keilw keilw Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The JavaDoc says "...dimensions and their exponent". Is there even such thing as a non-integer exponent?

}
14 changes: 7 additions & 7 deletions src/main/java/javax/measure/Unit.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ public interface Unit<Q extends Quantity<Q>> {
*
* @return the base units and their exponent making up this unit.
*/
Map<? extends Unit<?>, Integer> getBaseUnits();
Map<? extends Unit<?>, Double> getBaseUnits();

/**
* Indicates if this unit is compatible with the unit specified. Units don't need to be equal to be compatible. For example (assuming {@code ONE}
Expand Down Expand Up @@ -372,24 +372,24 @@ public interface Unit<Q extends Quantity<Q>> {
Unit<?> divide(Unit<?> divisor);

/**
* Returns an unit that is the n-th (integer) root of this unit. Equivalent to the mathematical expression {@code unit^(1/n)}.
* Returns an unit that is the n-th root of this unit. Equivalent to the mathematical expression {@code unit^(1/n)}.
*
* @param n
* an integer giving the root's order as in 'n-th root'
* a double giving the root's order as in 'n-th root'
* @return the n-th root of this unit.
* @throws ArithmeticException
* if {@code n == 0} or if this operation would result in an unit with a fractional exponent.
* if {@code n == 0}.
*/
Unit<?> root(int n);
Unit<?> root(double n);

/**
* Returns an unit raised to the n-th (integer) power of this unit. Equivalent to the mathematical expression {@code unit^n}.
* Returns an unit raised to the n-th power of this unit. Equivalent to the mathematical expression {@code unit^n}.
*
* @param n
* the exponent.
* @return the result of raising this unit to the exponent.
*/
Unit<?> pow(int n);
Unit<?> pow(double n);

/**
* Returns the unit derived from this unit using the specified converter. The converter does not need to be linear. For example:<br>
Expand Down