Merge pull request #249 from rjmk/toEither

Adds `toEither :: a -> b? -> Either a b`

index.js

@@ -1265,7 +1265,7 @@
 
   //# toMaybe :: a? -> Maybe a
   //.
-  //. Takes a value and returns Nothing if the value is null or undefined;
+  //. Takes a value and returns Nothing if the value is `null` or `undefined`;
   //. Just the value otherwise.
   //.
   //. ```javascript
@@ -1883,6 +1883,31 @@
       [b, $Either(a, b), b],
       function(x, either) { return either.isRight ? either.value : x; });
 
+  //# toEither :: a -> b? -> Either a b
+  //.
+  //. Converts an arbitrary value to an Either: a Left if the value is `null`
+  //. or `undefined`; a Right otherwise. The first argument specifies the
+  //. value of the Left in the "failure" case.
+  //.
+  //. ```javascript
+  //. > S.toEither('XYZ', null)
+  //. Left('XYZ')
+  //.
+  //. > S.toEither('XYZ', 'ABC')
+  //. Right('ABC')
+  //.
+  //. > R.map(R.head, S.toEither('Invalid protocol', 'ftp://example.com/'.match(/^https?:/)))
+  //. Left('Invalid protocol')
+  //.
+  //. > R.map(R.head, S.toEither('Invalid protocol', 'https://example.com/'.match(/^https?:/)))
+  //. Right('https:')
+  //. ```
+  S.toEither =
+  def('toEither',
+      {},
+      [a, b, $Either(a, b)],
+      function(x, y) { return y == null ? Left(x) : Right(y); });
+
   //# either :: (a -> c) -> (b -> c) -> Either a b -> c
   //.
   //. Takes two functions and an Either, and returns the result of

test/toEither.js

@@ -0,0 +1,23 @@
+'use strict';
+
+var eq = require('./utils').eq;
+var S = require('..');
+
+
+describe('toEither', function() {
+
+  it('is a binary function', function() {
+    eq(typeof S.toEither, 'function');
+    eq(S.toEither.length, 2);
+  });
+
+  it('returns Left of the first argument when second argument is `null`-y', function() {
+    eq(S.toEither('a', null), S.Left('a'));
+    eq(S.toEither('a', undefined), S.Left('a'));
+  });
+
+  it('returns a Right of the second argument when it is not `null`-y', function() {
+    eq(S.toEither('a', 42), S.Right(42));
+  });
+
+});