Ramda.js R.mathMod() Method

Beginner
5 min read
Updated: Nov 2026
5 examples
Math

Definition

Ramda’s R.mathMod() is the modulo operator as mathematicians mean it, not JavaScript %. The official docs sample is R.mathMod(-17, 5) → 3 (while -17 % 5 is -2). Added in v0.3.0. See also R.modulo.

Both arguments must be integers, and the modulus must be a positive integer. Otherwise you get NaN. The docs also show a clock helper with R.__ and a curried seventeenMod that waits for the modulus.

Syntax

Call R.mathMod. Start with this line.

Ramda
R.mathMod(m, p)
CallWhat it does
R.mathMod(m, p)Primary signature.
R.mathMod(...)Call the math helper.

Prefer import { mathMod } from "ramda" when you want a named import.

Library declarations
Ramda
R.mathMod(m, p)

Parameters

ParameterDescription
mRequired. the dividend (the value you wrap). First argument. Must be an integer.
pRequired. the modulus (the wrap size). Second argument. Must be a positive integer.

Return Value

Return ValueDescription
*Returns a Number in 0 … p-1 when both arguments are valid integers and p > 0.

Ramda Examples

📚 Getting Started

The official -17 mod 5 sample, then the official integer-only NaN rules.

Example 1 — The Official Docs Example

From ramdajs.com/docs/#mathMod: R.mathMod(-17, 5) returns 3.

Ramda
R.mathMod(-17, 5);  //=> 3
R.mathMod(17, 5);   //=> 2
R.mathMod(17, -5);  //=> NaN
R.mathMod(17, 0);   //=> NaN
Try It Yourself

How It Works

True modulo answers “which residue class?” -17 is 3 below the next multiple of 5, so the official sample is 3. A negative or zero modulus is not a valid wrap size, so Ramda returns NaN.

Example 2 — Official Integer-Only Rules

The docs require integer arguments. A float on either side is NaN.

Ramda
R.mathMod(17.2, 5);  //=> NaN
R.mathMod(17, 5.3);  //=> NaN
R.mathMod(17, 5);    //=> 2
Try It Yourself

How It Works

Mathematical modulo is defined on integers. Ramda refuses floats instead of silently truncating them. Truncate or round first if your data is not already whole numbers.

📈 Practical Patterns

Official clock helper, seventeenMod curry, and a side-by-side with R.modulo.

Example 3 — Official clock with R.__

The docs fill the modulus and wait for the hour. Negative hours wrap the other way.

Ramda
var clock = R.mathMod(R.__, 12);

clock(15);  //=> 3
clock(24);  //=> 0
clock(-1);  //=> 11

// Without the placeholder, R.mathMod(12) waits for the modulus:
R.mathMod(12)(15);  //=> 12  (not wrapping hours)
Try It Yourself

How It Works

R.__ says “skip this slot.” R.mathMod(R.__, 12) stores the wrap size and waits for m. 15 is 3 o’clock on a 12-hour face; -1 wraps to 11. Plain R.mathMod(12) stores the dividend instead.

Example 4 — Official seventeenMod

Fix the first argument at 17 to try different moduli.

Ramda
var seventeenMod = R.mathMod(17);

seventeenMod(3);   //=> 2
seventeenMod(4);   //=> 1
seventeenMod(10);  //=> 7
Try It Yourself

How It Works

R.mathMod(17) is a function that still needs p. Calling it with 3 computes 17 mod 3, which is 2 — the official sample. This is the opposite of clock: here the dividend is fixed and the wrap size changes.

Example 5 — R.mathMod vs R.modulo

The docs pair these two. Map the clock helper to wrap a list of hours.

Ramda
R.modulo(-17, 5);   //=> -2
R.mathMod(-17, 5);  //=> 3

R.map(R.mathMod(R.__, 12), [11, 12, 13, 24, -1]);
//=> [11, 0, 1, 0, 11]
Try It Yourself

How It Works

R.modulo copies JavaScript %, so a negative dividend can stay negative. R.mathMod always lands in 0 … 11 for a 12-hour wrap — including -1 → 11.

Browser Support

R.mathMod() is plain JavaScript remainder math — it runs anywhere Ramda loads: every modern browser plus Node.js. Logos use the shared browser-image-sprite.png sprite from this project.

✓ Ramda 0.3.0+ · Any JS runtime

Ramda.js R.mathMod()

Load Ramda via CDN or npm, then call R.mathMod(m, p). Because it only uses integer remainder arithmetic, behavior is identical across engines.

100% With Ramda loaded
Google Chrome All versions · Desktop & Mobile
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Internet Explorer IE 6+ · Legacy environments
Full support
Opera All modern versions
Full support
R.mathMod() Universal

Bottom line: Safe in any project that includes Ramda. Use a CDN build such as ramda.min.js in the browser or install ramda from npm for Node.

Frequently Asked Questions

R.mathMod(m, p) returns the mathematical modulo of m by p. Unlike JavaScript's % operator and R.modulo, the result stays in 0 … p-1 when p is a positive integer — so R.mathMod(-17, 5) is 3, not -2.
R.mathMod(-17, 5) returns 3 and R.mathMod(17, 5) returns 2. Negative, zero, or non-integer moduli return NaN. The docs also show const clock = R.mathMod(R.__, 12) with clock(15) returning 3, and const seventeenMod = R.mathMod(17). Added in v0.3.0. See also R.modulo.
Yes. R.mathMod has arity 2 and is automatically curried, so R.mathMod(17, 5) and R.mathMod(17)(5) both return 2. Calling it with one argument returns a function that waits for the modulus.
When either argument is not an integer, or when the modulus p is zero or negative. Official samples: R.mathMod(17, -5), R.mathMod(17, 0), R.mathMod(17.2, 5), and R.mathMod(17, 5.3) all return NaN.
R.modulo follows JavaScript % and can return a negative remainder: R.modulo(-17, 5) is -2. R.mathMod is mathematical modulo and stays non-negative for a positive integer modulus: R.mathMod(-17, 5) is 3. Use mathMod for wrap-around indexes and clocks.
No. R.mathMod is a stable Ramda math helper from v0.3.0. It is not deprecated, experimental, or non-standard.

Review R.modulo()

True modulo and JavaScript remainder are a pair — learn both sign rules.

R.modulo() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

6 people found this page helpful