Periodic wrap

周期回绕 · wrap-modulo

Fold positive and negative positions into one period so loops work in both directions.

JavaScript's % keeps the dividend's sign, so -0.2 % 1 stays negative. Used as a looping index, it can point outside the list. Double modulo yields a positive cycle; centered wrap gives the shortest displacement from the middle copy.

Formula

wrap(x,p) = ((x % p) + p) % p
centered(x,p) = wrap(x + p/2,p) − p/2

Parameters

	This page	Mature libraries
period p	1	GSAP `wrap(min,max,value)`The period must be positive.
centered	[−p/2, p/2)	our `centred()`Choose the nearest copy around the visual center.

Doing it well

Wrap negative values into valid indices too; GSAP's wrap() also uses double modulo.GSAP src/gsap-core.js:557–560
Keep the unwrapped position while scrolling, and wrap only when choosing an index or placing a copy.www-motion/rewrite/formation/geometry.js:44–49
Use centered wrap for the shortest centered displacement; our case runtime calls it centred.www-motion/rewrite/lib/case-runtime.js:4–5

In our cases

32 cases use periodic wrap. formation wraps browsing position for its ring and uses centered wrap for card displacement in a horizontal layout; the two ranges solve different placement problems.

Reference implementation · basics.js

/** x folded into [0, period) — also for negative x, unlike `%`. */
export const wrap = (x, period) => ((x % period) + period) % period;
/** x folded into [-period/2, period/2): "how far from the centre copy". */
export const wrapCentered = (x, period) => wrap(x + period / 2, period) - period / 2;