Add ascendNatural and descendNatural functions (#3442)

source/ascend.js

@@ -14,7 +14,7 @@ import _curry3 from './internal/_curry3.js';
  * @param {*} a The first item to be compared.
  * @param {*} b The second item to be compared.
  * @return {Number} `-1` if fn(a) < fn(b), `1` if fn(b) < fn(a), otherwise `0`
- * @see R.descend
+ * @see R.descend, R.ascendNatural, R.descendNatural
  * @example
  *
  *      const byAge = R.ascend(R.prop('age'));

source/ascendNatural.js

@@ -0,0 +1,37 @@
+import curry from './curry.js';
+
+
+/**
+ * Makes an ascending comparator function out of a function that returns a value
+ * that can be compared with natural sorting using localeCompare.
+ *
+ * @func
+ * @memberOf R
+ * @since v0.30.1
+ * @category Function
+ * @sig Ord b => s -> (a -> b) -> a -> a -> Number
+ * @param {String|Array} locales A string with a BCP 47 language tag, or an array of such strings. Corresponds to the locales parameter of the Intl.Collator() constructor.
+ * @param {Function} fn A function of arity one that returns a value that can be compared
+ * @param {*} a The first item to be compared.
+ * @param {*} b The second item to be compared.
+ * @return {Number} `-1` if a occurs before b, `1` if a occurs after b, otherwise `0`
+ * @see R.ascend
+ * @example
+ *
+ *      const unsorted = ['3', '1', '10', 'Ørjan', 'Bob', 'Älva'];
+ *
+ *      R.sort(R.ascendNatural('en', R.identity), unsorted);
+ *      // => ['1', '3', '10', 'Älva', 'Bob', 'Ørjan']
+ *
+ *      R.sort(R.ascendNatural('sv', R.identity), unsorted);
+ *      // => ['1', '3', '10', 'Bob', 'Älva', 'Ørjan']
+ *
+ *     R.sort(R.ascend(R.identity), unsorted);
+ *      // => ['1', '10', '3', 'Bob', 'Älva', 'Ørjan']
+ */
+var ascendNatural = curry(function ascendNatural(locales, fn, a, b) {
+  const aa = fn(a);
+  const bb = fn(b);
+  return aa.localeCompare(bb, locales, { numeric: true });
+});
+export default ascendNatural;

source/descend.js

@@ -14,7 +14,7 @@ import _curry3 from './internal/_curry3.js';
  * @param {*} a The first item to be compared.
  * @param {*} b The second item to be compared.
  * @return {Number} `-1` if fn(a) > fn(b), `1` if fn(b) > fn(a), otherwise `0`
- * @see R.ascend
+ * @see R.ascend, R.descendNatural, R.ascendNatural
  * @example
  *
  *      const byAge = R.descend(R.prop('age'));

source/descendNatural.js

@@ -0,0 +1,37 @@
+import curry from './curry.js';
+
+
+/**
+ * Makes a descending comparator function out of a function that returns a value
+ * that can be compared with natural sorting using localeCompare.
+ *
+ * @func
+ * @memberOf R
+ * @since v0.30.1
+ * @category Function
+ * @sig Ord b => s -> (a -> b) -> a -> a -> Number
+ * @param {String|Array} locales A string with a BCP 47 language tag, or an array of such strings. Corresponds to the locales parameter of the Intl.Collator() constructor.
+ * @param {Function} fn A function of arity one that returns a value that can be compared
+ * @param {*} a The first item to be compared.
+ * @param {*} b The second item to be compared.
+ * @return {Number} `-1` if a occurs after b, `1` if a occurs before b, otherwise `0`
+ * @see R.descend
+ * @example
+ *
+ *      const unsorted = ['3', '1', '10', 'Ørjan', 'Bob', 'Älva'];
+ *
+ *      R.sort(R.descendNatural('en', R.identity), unsorted);
+ *      // => ['Ørjan', 'Bob', 'Älva', '10', '3', '1']
+ *
+ *      R.sort(R.descendNatural('sv', R.identity), unsorted);
+ *      // => ['Ørjan', 'Älva', 'Bob', '10', '3', '1']
+ *
+ *     R.sort(R.descend(R.identity), unsorted);
+ *      // => ['Ørjan', 'Älva', 'Bob', '3', '10', '1']
+ */
+var descendNatural = curry(function descendNatural(locales, fn, a, b) {
+  const aa = fn(a);
+  const bb = fn(b);
+  return bb.localeCompare(aa, locales, { numeric: true });
+});
+export default descendNatural;

source/index.js

@@ -18,6 +18,7 @@ export { default as apply } from './apply.js';
 export { default as applySpec } from './applySpec.js';
 export { default as applyTo } from './applyTo.js';
 export { default as ascend } from './ascend.js';
+export { default as ascendNatural } from './ascendNatural.js';
 export { default as assoc } from './assoc.js';
 export { default as assocPath } from './assocPath.js';
 export { default as binary } from './binary.js';
@@ -44,6 +45,7 @@ export { default as curryN } from './curryN.js';
 export { default as dec } from './dec.js';
 export { default as defaultTo } from './defaultTo.js';
 export { default as descend } from './descend.js';
+export { default as descendNatural } from './descendNatural.js';
 export { default as difference } from './difference.js';
 export { default as differenceWith } from './differenceWith.js';
 export { default as dissoc } from './dissoc.js';

test/ascendNatural.js

@@ -0,0 +1,19 @@
+var R = require('../source/index.js');
+var eq = require('./shared/eq.js');
+
+describe('ascendNatural', function() {
+  it('builds an ascending natural comparator function out of the identity function', function() {
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.ascendNatural('en', R.identity)),
+      ['1', '3', '10', 'Älva', 'Bob', 'Ørjan']
+    );
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.ascendNatural('fr', R.identity)),
+      ['1', '3', '10', 'Älva', 'Bob', 'Ørjan']
+    );
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.ascendNatural('de', R.identity)),
+      ['1', '3', '10', 'Älva', 'Bob', 'Ørjan']
+    );
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.ascendNatural('sv', R.identity)),
+      ['1', '3', '10', 'Bob', 'Älva', 'Ørjan']
+    );
+  });
+});

test/descendNatural.js

@@ -0,0 +1,19 @@
+var R = require('../source/index.js');
+var eq = require('./shared/eq.js');
+
+describe('descendNatural', function() {
+  it('builds a descending natural comparator function out of the identity function', function() {
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.descendNatural('en', R.identity)),
+      ['Ørjan', 'Bob', 'Älva', '10', '3', '1']
+    );
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.descendNatural('fr', R.identity)),
+      ['Ørjan', 'Bob', 'Älva', '10', '3', '1']
+    );
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.descendNatural('de', R.identity)),
+      ['Ørjan', 'Bob', 'Älva', '10', '3', '1']
+    );
+    eq(['3', '1', '10', 'Ørjan', 'Bob', 'Älva'].sort(R.descendNatural('sv', R.identity)),
+      ['Ørjan', 'Älva', 'Bob', '10', '3', '1']
+    );
+  });
+});