feat($interpolate): use custom toString() function if present

Except on Numbers, Dates and Arrays.

Thanks to @danielkrainas for the initial implementation of this feature.

This behavior is consistent with implementations found in other languages such as Ruby, Python,
and CoffeeScript.
http://rubymonk.com/learning/books/1-ruby-primer/chapters/5-strings/lessons/31-string-basics
https://docs.python.org/2/library/stdtypes.html#string-formatting-operations
http://coffeescriptcookbook.com/chapters/strings/interpolation

The commit also exposes a private $$stringify method on the angular global, so that ngMessageFormat
can use the same logic without duplicating it.

Fixes #7317
Closes #8350
Fixes #11406

BREAKING CHANGE:

When converting values to strings, interpolation now uses a custom toString() function on objects
that are not Number, Array or Date (custom means that the `toString` function is not the same as
`Object.prototype.toString`). Otherwise, interpolation uses JSON.stringify() as usual.

Should you have a custom toString() function but still want the output of JSON.stringify(),
migrate as shown in the following examples:

Before:

```html
<span>{{myObject}}</span>
```

After - use the `json` filter to stringify the object:

```html
<span>{{myObject | json}}</span>
```

Author: Narretz

docs/content/guide/interpolation.ngdoc

@@ -26,6 +26,15 @@ normal {@link ng.$rootScope.Scope#$digest digest} cycle.
 
 Note that the interpolateDirective has a priority of 100 and sets up the watch in the preLink function.
 
+### How the string representation is computed
+
+If the interpolated value is not a `String`, it is computed as follows:
+- `undefined` and `null` are converted to `''`
+- if the value is an object that is not a `Number`, `Date` or `Array`, $interpolate looks for
+a custom `toString()` function on the object, and uses that. Custom means that
+`myObject.toString !== `Object.prototype.toString`.
+- if the above doesn't apply, `JSON.stringify` is used.
+
 ### Binding to boolean attributes
 
 Attributes such as `disabled` are called `boolean` attributes, because their presence means `true` and

src/.jshintrc

@@ -96,6 +96,7 @@
     "createMap": false,
     "VALIDITY_STATE_PROPERTY": false,
     "reloadWithDebugInfo": false,
+    "stringify": false,
 
     "NODE_TYPE_ELEMENT": false,
     "NODE_TYPE_ATTRIBUTE": false,

src/Angular.js

@@ -86,6 +86,7 @@
   getBlockNodes: true,
   hasOwnProperty: true,
   createMap: true,
+  stringify: true,
 
   NODE_TYPE_ELEMENT: true,
   NODE_TYPE_ATTRIBUTE: true,
@@ -1903,6 +1904,27 @@ function createMap() {
   return Object.create(null);
 }
 
+function stringify(value) {
+  if (value == null) { // null || undefined
+    return '';
+  }
+  switch (typeof value) {
+    case 'string':
+      break;
+    case 'number':
+      value = '' + value;
+      break;
+    default:
+      if (hasCustomToString(value) && !isArray(value) && !isDate(value)) {
+        value = value.toString();
+      } else {
+        value = toJson(value);
+      }
+  }
+
+  return value;
+}
+
 var NODE_TYPE_ELEMENT = 1;
 var NODE_TYPE_ATTRIBUTE = 2;
 var NODE_TYPE_TEXT = 3;

src/AngularPublic.js

@@ -156,7 +156,8 @@ function publishExternalAPI(angular) {
     '$$minErr': minErr,
     '$$csp': csp,
     '$$encodeUriSegment': encodeUriSegment,
-    '$$encodeUriQuery': encodeUriQuery
+    '$$encodeUriQuery': encodeUriQuery,
+    '$$stringify': stringify
   });
 
   angularModule = setupModuleLoader(window);

src/ng/interpolate.js

@@ -111,23 +111,6 @@ function $InterpolateProvider() {
         replace(escapedEndRegexp, endSymbol);
     }
 
-    function stringify(value) {
-      if (value == null) { // null || undefined
-        return '';
-      }
-      switch (typeof value) {
-        case 'string':
-          break;
-        case 'number':
-          value = '' + value;
-          break;
-        default:
-          value = toJson(value);
-      }
-
-      return value;
-    }
-
     //TODO: this is the same as the constantWatchDelegate in parse.js
     function constantWatchDelegate(scope, listener, objectEquality, constantInterp) {
       var unwatch;

src/ngMessageFormat/messageFormatCommon.js

@@ -8,15 +8,7 @@
 /* global isFunction: false */
 /* global noop: false */
 /* global toJson: false */
-
-function stringify(value) {
-  if (value == null /* null/undefined */) { return ''; }
-  switch (typeof value) {
-    case 'string':     return value;
-    case 'number':     return '' + value;
-    default:           return toJson(value);
-  }
-}
+/* global $$stringify: false */
 
 // Convert an index into the string into line/column for use in error messages
 // As such, this doesn't have to be efficient.

src/ngMessageFormat/messageFormatService.js

@@ -10,7 +10,6 @@
 /* global noop: true */
 /* global toJson: true */
 /* global MessageFormatParser: false */
-/* global stringify: false */
 
 /**
  * @ngdoc module
@@ -180,7 +179,7 @@ var $$MessageFormatFactory = ['$parse', '$locale', '$sce', '$exceptionHandler',
     return function stringifier(value) {
       try {
         value = trustedContext ? $sce['getTrusted'](trustedContext, value) : $sce['valueOf'](value);
-        return allOrNothing && (value === void 0) ? value : stringify(value);
+        return allOrNothing && (value === void 0) ? value : $$stringify(value);
       } catch (err) {
         $exceptionHandler($interpolateMinErr['interr'](text, err));
       }
@@ -214,6 +213,7 @@ var $interpolateMinErr;
 var isFunction;
 var noop;
 var toJson;
+var $$stringify;
 
 var module = window['angular']['module']('ngMessageFormat', ['ng']);
 module['factory']('$$messageFormat', $$MessageFormatFactory);
@@ -222,6 +222,7 @@ module['config'](['$provide', function($provide) {
   isFunction = window['angular']['isFunction'];
   noop = window['angular']['noop'];
   toJson = window['angular']['toJson'];
+  $$stringify = window['angular']['$$stringify'];
 
   $provide['decorator']('$interpolate', $$interpolateDecorator);
 }]);

test/ng/interpolateSpec.js

@@ -35,6 +35,29 @@ describe('$interpolate', function() {
     expect($interpolate('{{ false }}')({})).toEqual('false');
   }));
 
+  it('should use custom toString when present', inject(function($interpolate, $rootScope) {
+    var context = {
+      a: {
+        toString: function() {
+          return 'foo';
+        }
+      }
+    };
+
+    expect($interpolate('{{ a }}')(context)).toEqual('foo');
+  }));
+
+  it('should NOT use toString on array objects', inject(function($interpolate) {
+    expect($interpolate('{{a}}')({ a: [] })).toEqual('[]');
+  }));
+
+
+  it('should NOT use toString on Date objects', inject(function($interpolate) {
+    var date = new Date(2014, 10, 10);
+    expect($interpolate('{{a}}')({ a: date })).toBe(JSON.stringify(date));
+    expect($interpolate('{{a}}')({ a: date })).not.toEqual(date.toString());
+  }));
+
 
   it('should return interpolation function', inject(function($interpolate, $rootScope) {
     var interpolateFn = $interpolate('Hello {{name}}!');

test/ngMessageFormat/messageFormatSpec.js

@@ -311,6 +311,30 @@ describe('$$ngMessageFormat', function() {
     }));
 
 
+    it('should use custom toString when present', inject(function($interpolate, $rootScope) {
+       var context = {
+        a: {
+          toString: function() {
+            return 'foo';
+          }
+        }
+      };
+
+      expect($interpolate('{{ a }}')(context)).toEqual('foo');
+    }));
+
+    it('should NOT use toString on array objects', inject(function($interpolate) {
+      expect($interpolate('{{a}}')({ a: [] })).toEqual('[]');
+    }));
+
+
+    it('should NOT use toString on Date objects', inject(function($interpolate) {
+      var date = new Date(2014, 10, 10);
+      expect($interpolate('{{a}}')({ a: date })).toBe(JSON.stringify(date));
+      expect($interpolate('{{a}}')({ a: date })).not.toEqual(date.toString());
+    }));
+
+
     it('should return interpolation function', inject(function($interpolate, $rootScope) {
       var interpolateFn = $interpolate('Hello {{name}}!');