It would be good to add a comparison between quantize and snap, showing how both can be useful.

I could also imagine a quantize function that, if passed a negative quantum, would result in the snap behavior. This would be a typical way to formulate such symmetric distinctions.

Well quantize will change any values bigger than (quantum+-tolerance) while snap will change any value smaller than (quantum+-tolerance). So I can certainly add that. There was talk of deprecating quantize just because it's horribly named (my proposed function 'snap' is what quantize should have been). Of course in an ideal world my new function would be 'quantize', and the current 'quantize' function would probably be called 'snap'. Backwards compatibility is annoying sometimes.

I'd also like to change the parameter name for quantize. I proposed 'grid' for snap, as it relates to the idea of a musical grid of beats (e.g. a sequencer/DAW). I really don't love that, but quantum is quite mathy and scary to non-math people (which is probably most users of SuperCollider, and certainly the ones most intimidated by it in the first place).

Quantize should be deprecated, for the reasons given in #2826:

• quantize does not do what most people will expect; in other words, its name is confusing
• what it does do is not a needed function for a vast majority of users
• it appears that quantize was incorrectly written, but needs to maintain backwards compatibility
• we should strongly encourage users to use a correctly behaving function rather than an incorrectly behaving function, and the best way to do that is through deprecation of the incorrect function

A possible alternative is to deprecate quantize and add a second function which does the same thing but is more appropriately named. However, I think you'll have a hard time coming up with a name for it, or even an example showing its utility. IMO there is none. I would rather just deprecate it.

I proposed 'grid' for snap

I think grid is fine, although it isn't immediately intuitive to me. Technically speaking the value isn't a grid, it's the resolution of the grid; EnvelopeView has the same naming problem. I offer 'resolution' for consideration. A longer name is OK here since it's very unlikely someone would type out the parameter name when calling it - in other words, write 3.snap(resolution: 4) instead of just 3.snap(4).

I'd also like to change the parameter name for quantize.

Since quantize will be deprecated, changing the parameter name doesn't do much. I think it should be left as-is.

If we can imagine another way for a number to snap, the name probably should be snapToGrid. But otherwise I'm fine with snap. I hope nobody complains that a float snapped at him.

I don't have a strong opinion on the name, but let's try to suggest concrete alternatives so the discussion doesn't derail.

we have roundUp and roundDown. Maybe something analog? Like roundToward?

On the other hand, snap isn't a bad name for what it does.

I can imagine many other rounding to grid functions, but they can almost always better be written directly as a function.

roundAbout ?

... sorry couldn't help myself

(I also needed to hold myself back!)

BTW, I never published this extension, but I use it all the time for FM modulator ratios:

SnapControlSpec : ControlSpec {
	var <>snap = 0.05;
	map { arg value;
		// maps a value from [0..1] to spec range
		var out = warp.map(value.clip(0.0, 1.0)),
		rounded = out.round(step);
		if((out absdif: rounded) <= snap) { ^rounded } { ^out }
	}
	unmap { arg value;
		// maps a value from spec range to [0..1]
		var rounded = value.round(step);
		if((value absdif: rounded) <= snap) { value = rounded };
		^warp.unmap(value.clip(clipLo, clipHi));
	}
	constrain { arg value;
		var rounded;
		value = value.asFloat.clip(clipLo, clipHi);
		rounded = value.round(step);
		if((value absdif: rounded) <= snap) { ^rounded } { ^value }
	}
}

SnapControlSpec(0.5, 20, \lin, 0.5).snap_(0.05), e.g.

Or a panner with an indent in the center: SnapControlSpec(-1, 1, \lin, 1).snap_(0.05)

I offer 'resolution' for consideration. A longer name is OK here since it's very unlikely someone would type out the parameter name when calling it - in other words, write 3.snap(resolution: 4) instead of just 3.snap(4).

This seems like a no-brainer. Resolution it is. Nice one.

roundToward isn't bad. roundWithTolerance would be perfect if it wasn't so long. gradualRound? There are two hard problems in Computer Science - naming things and cache invalidation.

I'd be inclined if we went down that route to replicate the old quantize function as snap (with better named parameters and help).

I won't hold my breath for graphics programs to start to roundToward grid lines instead of snapping to them...

my thought after seeing these suggestions is softRound

I like softRound.

How about I create a copy of quantize called 'snap' which has the behavior that James described (snap to grid lines). And my function is softRound. And I'll add better documentation for 'snap' than the current quantize function.

And quantize is deprecated.

roundSoftly would be found more easily in autocomplete.

naming shouldn't be justified by current autocomplete functionality imho. i'd rather have code that makes sense and fits with naming conventions.

Well there's currently a round and a roundUp (though not a roundDown - what's 'up' with that). So I guess it would fit into an already existing scheme if it was roundSoftly.

yes, that's what I actually wanted to say. But I'm fine with most variants.

So do we think we can achieve some kind of consensus on naming?

I'd like to call it roundSoft, or roundSoftly, just because it would fit into the already existing naming convention for round. And use snap for 'snap' in the sense that James referenced it above. But I'm open to persuasion.

And I'll start a new pull request to add roundDown... Seriously, why's that not in there?

if you're looking for a convention, the other things in SC that have "soft" in their names are:

• PV_SoftWipe
• softPut
• softSet
• softVol_
• softclip

similarly, there are

• hardFreeAll
• hardRun
• hardStop

So you had to bring facts to this discussion @brianlheim...

Okay I'll rename the function to softRound, move the help up so that it's in the round section. And I'll create a copy of quantize called snap. And I'll update help appropriately.

Is that cool?

Edited because I wrote the wrong function name (duh).

new function name softRound, not roundSoftly. Dammit.

I still need to rewrite the tests. Everything else should be done.

I think this should address all the issues.

The data now covers all the edge cases (plus a little extra for my OCD paranoia), including negative values. Also have tests for values that should never be entered.

Apparently I don't find user tests soothing :-/

as an aside, this has definitely given me some good ideas for what to include in a unit testing guide. i'm sorry that you didn't have anything to go off of for this PR, that shouldn't happen in the future.

That submodule keeps creeping back in. This should be fixed now.

NB - I realized at the last moment that this PR hadn't actually deprecated quantize yet, so I went ahead and pushed that change to your branch, @cianoc