1 // ==========================================================================
  2 // Project:   The M-Project - Mobile HTML5 Application Framework
  3 // Copyright: (c) 2011 M-Way Solutions GmbH. All rights reserved.
  4 //            (c) 2011 panacoda GmbH. All rights reserved.
  5 // Creator:   Frank
  6 // Date:      04.01.2011
  7 // License:   Dual licensed under the MIT or GPL Version 2 licenses.
  8 //            http://github.com/mwaylabs/The-M-Project/blob/master/MIT-LICENSE
  9 //            http://github.com/mwaylabs/The-M-Project/blob/master/GPL-LICENSE
 10 // ==========================================================================
 11 
 12 m_require('core/foundation/object.js');
 13 
 14 /**
 15  * @class
 16  *
 17  * The string builder is a utility object to join multiple strings to one single string.
 18  *
 19  * @extends M.Object
 20  */
 21 M.StringBuilder = M.Object.extend(
 22 /** @scope M.StringBuilder.prototype */ {
 23 
 24     /**
 25      * The type of this object.
 26      *
 27      * @type String
 28      */
 29     type: 'M.StringBuilder',
 30 
 31     /**
 32      * An array containing all strings used within this string builder.
 33      *
 34      * @type Array
 35      */
 36     strings: null,
 37 
 38     /**
 39      * This method appends the given string, 'value', to its internal list of strings. With
 40      * an additional parameter 'count', you can force this method to add the string multiple
 41      * times.
 42      *
 43      * @param {String} value The value of the string to be added.
 44      * @param {Number} count The number to specify how many times the string will be added.
 45      * @returns {Boolean} The result of this operation: success/YES, error/NO.
 46      */
 47     append: function (value, count) {
 48         count = typeof(count) === 'number' ? count : 1;
 49         if (value) {
 50             for(var i = 1; i <= count; i++) {
 51                 this.strings.push(value);
 52             }
 53             return YES;
 54         }
 55     },
 56 
 57     /**
 58      * This method clears the string builders internal string list.
 59      */
 60     clear: function () {
 61         this.strings.length = 0;
 62     },
 63 
 64     /**
 65      * This method returns a single string, consisting of all previously appended strings. They
 66      * are concatenated in the order they were appended to the string builder.
 67      *
 68      * @returns {String} The concatenated string of all appended strings.
 69      */
 70     toString: function () {
 71         return this.strings.join("");
 72     },
 73 
 74     /**
 75      * This method creates a new string builder instance.
 76      *
 77      * @param {String} str The initial string for this string builder.
 78      */
 79     create: function(str) {
 80         var stringBuilder = this.extend({
 81             strings: []
 82         });
 83         stringBuilder.append(str);
 84         
 85         return stringBuilder;
 86     }
 87     
 88 });