goog.provide('ol.TileUrlFunction');
goog.provide('ol.TileUrlFunctionType');

goog.require('goog.array');
goog.require('goog.asserts');
goog.require('goog.math');
goog.require('ol.TileCoord');
goog.require('ol.tilecoord');


/**
 * A function that takes an {@link ol.TileCoord} for the tile coordinate,
 * a `{number}` representing the pixel ratio and an {@link ol.proj.Projection}
 * for the projection  as arguments and returns a `{string}` or
 * undefined representing the tile URL.
 *
 * @typedef {function(ol.TileCoord, number,
 *           ol.proj.Projection): (string|undefined)}
 * @api
 */
ol.TileUrlFunctionType;


/**
 * @typedef {function(ol.TileCoord, ol.proj.Projection, ol.TileCoord=):
 *     ol.TileCoord}
 */
ol.TileCoordTransformType;


/**
 * @param {string} template Template.
 * @return {ol.TileUrlFunctionType} Tile URL function.
 */
ol.TileUrlFunction.createFromTemplate = function(template) {
  var zRegEx = /\{z\}/g;
  var xRegEx = /\{x\}/g;
  var yRegEx = /\{y\}/g;
  var dashYRegEx = /\{-y\}/g;
  return (
      /**
       * @param {ol.TileCoord} tileCoord Tile Coordinate.
       * @param {number} pixelRatio Pixel ratio.
       * @param {ol.proj.Projection} projection Projection.
       * @return {string|undefined} Tile URL.
       */
      function(tileCoord, pixelRatio, projection) {
        if (goog.isNull(tileCoord)) {
          return undefined;
        } else {
          return template.replace(zRegEx, tileCoord[0].toString())
                         .replace(xRegEx, tileCoord[1].toString())
                         .replace(yRegEx, tileCoord[2].toString())
                         .replace(dashYRegEx, function() {
                           var y = (1 << tileCoord[0]) - tileCoord[2] - 1;
                           return y.toString();
                         });
        }
      });
};


/**
 * @param {Array.<string>} templates Templates.
 * @return {ol.TileUrlFunctionType} Tile URL function.
 */
ol.TileUrlFunction.createFromTemplates = function(templates) {
  return ol.TileUrlFunction.createFromTileUrlFunctions(
      goog.array.map(templates, ol.TileUrlFunction.createFromTemplate));
};


/**
 * @param {Array.<ol.TileUrlFunctionType>} tileUrlFunctions Tile URL Functions.
 * @return {ol.TileUrlFunctionType} Tile URL function.
 */
ol.TileUrlFunction.createFromTileUrlFunctions = function(tileUrlFunctions) {
  goog.asserts.assert(tileUrlFunctions.length > 0,
      'Length of tile url functions should be greater than 0');
  if (tileUrlFunctions.length === 1) {
    return tileUrlFunctions[0];
  }
  return (
      /**
       * @param {ol.TileCoord} tileCoord Tile Coordinate.
       * @param {number} pixelRatio Pixel ratio.
       * @param {ol.proj.Projection} projection Projection.
       * @return {string|undefined} Tile URL.
       */
      function(tileCoord, pixelRatio, projection) {
        if (goog.isNull(tileCoord)) {
          return undefined;
        } else {
          var h = ol.tilecoord.hash(tileCoord);
          var index = goog.math.modulo(h, tileUrlFunctions.length);
          return tileUrlFunctions[index](tileCoord, pixelRatio, projection);
        }
      });
};


/**
 * @param {ol.TileCoord} tileCoord Tile coordinate.
 * @param {number} pixelRatio Pixel ratio.
 * @param {ol.proj.Projection} projection Projection.
 * @return {string|undefined} Tile URL.
 */
ol.TileUrlFunction.nullTileUrlFunction =
    function(tileCoord, pixelRatio, projection) {
  return undefined;
};


/**
 * @param {ol.TileCoordTransformType} transformFn Transform function.
 * @param {ol.TileUrlFunctionType} tileUrlFunction Tile URL function.
 * @return {ol.TileUrlFunctionType} Tile URL function.
 */
ol.TileUrlFunction.withTileCoordTransform =
    function(transformFn, tileUrlFunction) {
  var tmpTileCoord = [0, 0, 0];
  return (
      /**
       * @param {ol.TileCoord} tileCoord Tile Coordinate.
       * @param {number} pixelRatio Pixel ratio.
       * @param {ol.proj.Projection} projection Projection.
       * @return {string|undefined} Tile URL.
       */
      function(tileCoord, pixelRatio, projection) {
        if (goog.isNull(tileCoord)) {
          return undefined;
        } else {
          return tileUrlFunction(
              transformFn(tileCoord, projection, tmpTileCoord),
              pixelRatio,
              projection);
        }
      });
};


/**
 * @param {string} url URL.
 * @return {Array.<string>} Array of urls.
 */
ol.TileUrlFunction.expandUrl = function(url) {
  var urls = [];
  var match = /\{(\d)-(\d)\}/.exec(url) || /\{([a-z])-([a-z])\}/.exec(url);
  if (match) {
    var startCharCode = match[1].charCodeAt(0);
    var stopCharCode = match[2].charCodeAt(0);
    var charCode;
    for (charCode = startCharCode; charCode <= stopCharCode; ++charCode) {
      urls.push(url.replace(match[0], String.fromCharCode(charCode)));
    }
  } else {
    urls.push(url);
  }
  return urls;
};

@@ -481,16 +481,748 @@
 URL.%0A *%0A
+ * The %7B@link ol.TileCoord%7D's %60x%60 value%0A * increases from left to right, %60y%60 increases from bottom to top. At the%0A * bottom left corner, %60x%60 and %60y%60 are %600%60. To convert %60y%60 to increase from%0A * top to bottom, use the following code:%0A * %60%60%60js%0A * var tileGrid = new ol.tilegrid.TileGrid(%7B%0A *   extent: extent,%0A *   resolutions: resolutions,%0A *   tileSize: tileSize%0A * %7D);%0A *%0A * function calculateY(tileCoord) %7B%0A *   var z = tileCoord%5B0%5D;%0A *   var yFromBottom = tileCoord%5B2%5D;%0A *   var resolution = tileGrid.getResolution(z);%0A *   var tileHeight = ol.size.toSize(tileSize)%5B1%5D;%0A *   var matrixHeight =%0A *       Math.floor(ol.extent.getHeight(extent) / tileHeight / resolution);%0A *   return matrixHeight - yFromBottom - 1;%0A * %7D;%0A * %60%60%60%0A *%0A
  * @type

Improve doucmentation for ol.TileUrlFunctionType