Double/float range annotation

[solonovamax]

It would be incredibly useful to have something similar to @Range for doubles/floats.

For example, to indicate that the return value is always in the range [0, 1] (0 to 1, inclusive)

something like

@Documented
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.TYPE_USE})
public @interface DoubleRange {
  double from();
  double to();
}

[amaembo]

Technically it's possible, but it looks like there are very few APIs which may benefit from this, like Math.random. Note that for Math.sin, it's less trivial, as it can also return NaN, and it should be possible to indicate this (add a boolean attribute like canBeNaN?). Also, for Math.random, 1.0 is not included, so it should be from=0.0, to=nextDown(1.0), which is somewhat difficult to write explicitly.

Please describe your use case. Which kinds of APIs do you want to annotate?

[solonovamax]

@amaembo

Also, for Math.random, 1.0 is not included, so it should be from=0.0, to=nextDown(1.0), which is somewhat difficult to write explicitly.

for this, you could have something like

public @interface DoubleRange {
    double from();
    double to();
    boolean fromInclusive() default true;
    boolean toInclusive() default true;
}

Note that for Math.sin, it's less trivial, as it can also return NaN, and it should be possible to indicate this (add a boolean attribute like canBeNaN?).

yeah, smth to indicate NaN would also probably be valuable:

public @interface DoubleRange {
    double from();
    double to();
    boolean fromInclusive() default true;
    boolean toInclusive() default true;
    boolean canBeNaN() default false;
}

Please describe your use case. Which kinds of APIs do you want to annotate?

most of the apis that I can think of which I'd annotate it with would be ones that return values either in the range [0, 1]/(0, 1]/etc., in the range [-1, 1]/(-1, 1), or in the range [0, 100]/etc.

although there are a few apis I can think of which would use different ranges to those, but not many.

here are a few examples off the top of my head:

• string metric functions (0 inclusive to infinity exclusive)
• normalized string metric functions (normalized levenshtein) (0-1 inclusive)
• ratios ("progress", "percent", etc.) (0-1 inclusive)
• percent (0-100 inclusive)
• minecraft health/food bars (0-20 inclusive)
• math functions. things similar to Math.sin(), Math.cos(), etc. for example,
  • fast inverse square root (0 inclusive to infinity exclusive)
  • logarithm (0 inclusive to infinity exclusive)
  • clamp to range -1 to 1
  • standard deviation (0 inclusive to infinity exclusive)
  • sigmoid functions (eg. logistic function, hyperbolic tangent, smoothstep, etc.) (0-1 exclusive)
  • normalized value (0-1 inclusive)
  • etc.
• values such as health, mana, experience, etc. in a game (0 inclusive to infinity exclusive)

---

the primary use cases I can think of for such an annotation would be

1. easily indicate to developers the range of the returned values
2. ide warnings when doing something like

   if (Math.random() > 2.0) { // <--- ide warning here
       // ...
   }

3. maybe someone might write something to test apis which have such an annotation, idk

I would find the first & second one most useful though, as I have noticed a few times in codebases I'm working on, comparisons like the above Math.random() one which logically make no sense written by other people

---

perhaps this is something that could be better expressed via @Contract? something like (read as "any input returns a number between 0 and 1 inclusive"):

@Contract("_ -> [0, 1]")

for exclusive ranges, for example Math.random(), you could do (read as "any input returns a number between 0 inclusive and 1 exclusive"):

@Contract("_ -> [0, 1)")

to include NaN, for example Math.sin(), perhaps something like (read as "any input returns a number between -1 and 1 inclusive or NaN"):

@Contract("_ -> [-1, 1] | NaN")

though, perhaps something like Math.sin() would be better annotated with something like (read as "returns NaN for NaN, NaN for Infinity, -0 for -0, 0 for 0, or a number between -1 and 1 inclusive"):

@Contract("NaN -> NaN; Infinity -> NaN; -0 -> -0; 0 -> 0; _ -> [-1, 1]")

however, this would require changing how @Contract is parsed, requiring any downstream consumers to adapt, so this might not be an option.