Monday, November 21, 2005

Prototype.js : String and Number

In a previous entry I kicked off this series of posts on the Prototype JavaScript library, with this being the second. In this entry I will cover the extensions that Prototype adds to the standard JavaScript String and Number objects.

API Summary

String  string.camelize()
String string.escapeHTML()
String string.inspect()
String string.parseQuery()
String string.stripTags()
String[] string.toArray()
Object string.toQueryParams()
String string.unescapeHTML()

Number number. succ()
Number number.times(iterator)
String number. toColorPart()

API Details

string.camelize()

Params:
None.

Returns:
String value in camel notation.

Takes the value of the String object and returns it in camel notation, meaning the first letter of each word is capitalized, except for the first. Words must be seperated by a dash ('-').

// newStr = "thisThatOther"
var str = 'this-that-other';
var newStr = str.camelize();

// same thing
var newStr = 'this-that-other'.camelize();

string.escapeHTML()

Params:
None.

Returns:
An HTML escaped string.

Returns the String value as an HTML escaped value.

var unescaped = 'escape <b>this</b>';
var escaped = unescaped.escapeHTML();

// same thing
var escaped = 'escape <b>this</b>'.escapeHTML();

string.inspect()

Params:
None.

Returns:
A quoted JavaScript value.

Returns the String value as a quoted and escaped JavaScript value. Note: I have seen some odd behavior where only the first single-quote in the string is escaped, but I am not sure if this behavior is limited to only certain browsers.

var unescaped = "escape 'this'";
var escaped = unescaped.inspect();

// same thing
var escaped = "escape 'this'".inspect();

string.parseQuery()

Params:
None.

Returns:
An Object that has a property for each query param.

Parses the target String value as a querystring, and creating an Object to hold the parsed values. Caution: If there are multiple values for a single key, only the last value in the unparsed string will be retained.

var query = "x=123&y=abc&z=456";
var queryObj = query.parseQuery();
// queryObj.x == '123'
// queryObj.y == 'abc'
// queryObj.z == '456'

string.stripTags()

Params:
None.

Returns:
String value with HTML tags removed.

Returns the value of the String object with any HTML tags removed.

// noTags == 'Hello World'
var tags = 'Hello <b>World</b>';
var noTags = tags.stripTags();

// same thing
var noTags = 'Hello <b>World</b>'.stripTags();

string.toArray()

Params:
None.

Returns:
Array of characters.

Returns the value of the String object as an Array object of single characters.

var str = 'Hello';
var strArray = str.toArray();
// strArray == new Array('H', 'e', 'l', 'l', 'o');

string.toQueryParams()

Params:
None.

Returns:
An Object that has a property for each query param.

Same as the parseQuery() method. See string.parseQuery() above.

string.unescapeHTML()

Params:
None.

Returns:
String value with HTML entities unescaped.

Takes a String value with HTML entities, decodes them, and returns the result as a new String value.
var htmlStr = '&lt;tag>';
var textStr = htmlStr.unescapeHTML();
// testStr == '<tag>'

number. succ()

Params:
None.

Returns:
The successor value.

Returns the successor value for the Number object. In other words, it returns the value plus 1.
var num = 5;
var next = num.succ();
// next == 6

number.times(iterator)

Params:
iterator - A function.

Returns:
The Number object.

Executes a specified function a number of times equal to the Number value. The iterator function will recieve the number of the current execution, starting at 0, and ending at the value of the number value minus 1.

// alert the values 0, 1, and 2.
new Number(3).times( function(val){alert(val)} );

// same thing
var x = 3;
function funcA(val) {alert(val)};
x.times(funcA);
number. toColorPart()

Params:
None.

Returns:
Hexidecimal representation of the number value.

Converts the Number value to it's hexidecimal representation.

// hex == '1e240'
var hex = new Number(123456).toColorPart();

// same thing
var num = 123456;
var hex = num.toColorPart();



1 comment:

sexy said...
This comment has been removed by a blog administrator.