Vague documentation or incorrect behaviour in the breaks_* functions

[jttoivon]

The help pages of the scales::breaks_* say that

All breaks_() functions return a function for generating breaks. These functions takes, as their first argument a vector of values that represent the data range to provide breaks for.

It does not say what the length of the input vector should be. Some breaks_ functions seem to assume the length should be two, with the endpoints of the range provided. Other functions don't have this limitation.

Some examples:

library(scales)

good <- c(1, 20)
bad <- c(1, 10, 20)

scales::breaks_extended(n=5)(good)
#> [1]  0  5 10 15 20
scales::breaks_extended(n=5)(bad) # works
#> [1]  0  5 10 15 20

scales::breaks_width(width=5)(good)
#> [1]  0  5 10 15 20
scales::breaks_width(width=5)(bad) # clear error message
#> Error in `zero_range()`:
#> ! `x` must be length 1 or 2

scales::breaks_exp(n = 5)(good)
#> [1] 20 19 18 17  0
scales::breaks_exp(n = 5)(bad)   # cryptic error message
#> Error in top >= 3 && abs(diff(x)) >= 3: 'length = 2' in coercion to 'logical(1)'

scales::breaks_log(n = 5)(good)
#> [1]  1  3 10 30
scales::breaks_log(n = 5)(bad)   # works
#> [1]  1  3 10 30

scales::breaks_pretty(n=5)(good)
#> [1]  0  5 10 15 20
scales::breaks_pretty(n=5)(bad)  # works
#> [1]  0  5 10 15 20

scales::breaks_timespan(unit = "mins")(good)
#> Time differences in secs
#> [1]    0  240  480  720  960 1200
scales::breaks_timespan(unit = "mins")(bad)  # works
#> Time differences in secs
#> [1]    0  240  480  720  960 1200

^{Created on 2025-11-12 with reprex v2.1.1}

I would expect all the functions returned by the breaks_* functions to behave similarly.

I'm using scales version 1.4.0.

[teunbrand]

Would it be more clear if the phrase in the documentation went:

a vector of length 2 that represent the data range

[jttoivon]

That would be more clear, but then the implementations should be changed as well to enforce that requirement and to provide a clear error message if the length is not two.

[clauswilke]

I wouldn't be surprised if somebody somewhere is throwing all their data into a break function expecting the function to figure it out. So maybe the better strategy is to leave the documentation as is and make sure all functions work with the "bad" example input.

[teunbrand]

I mostly agree, there should be some normalisation of the x argument so that the functions always operate on a sorted vector of length 2 with no non-finite elements, like NA or Inf. Still, it can't hurt to document the intended input even if it accepts a wider range of inputs.

[jttoivon]

Looks great!