Module ringo/utils/strings

Adds useful methods to the JavaScript String type.

Functions

Sorter (field, order)

factory to create functions for sorting objects in an array

Parameters

String field name of the field each object is compared with
Number order (ascending or descending)

Returns

Function ready for use in Array.prototype.sort

b16decode (str, encoding)

Decodes a Base16 encoded string to a string or byte array.

Parameters

String str the Base16 encoded string
String encoding the encoding to use for the return value. Defaults to 'utf8'. Use 'raw' to get a ByteArray instead of a string.

Returns

the decoded string or ByteArray

b16encode (str, encoding)

Encode a string or binary to a Base16 encoded string

Parameters

String|Binary str a string or binary
String encoding optional encoding to use if first argument is a string. Defaults to 'utf8'.

Returns

the Base16 encoded string

b64decode (string, encoding)

Decodes a Base64 encoded string to a string or byte array.

Parameters

String string the Base64 encoded string
String encoding the encoding to use for the return value. Defaults to 'utf8'. Use 'raw' to get a ByteArray instead of a string.

Returns

the decoded string or ByteArray

b64encode (string, encoding)

Encode a string or binary to a Base64 encoded string

Parameters

String|Binary string a string or binary
String encoding optional encoding to use if first argument is a string. Defaults to 'utf8'.

Returns

the Base64 encoded string

capitalize (the, amount)

transforms the first n characters of a string to uppercase

Parameters

String the string to capitalize
Number amount of characters to transform

Returns

String the resulting string

compose (one)

create a string from a bunch of substrings

Parameters

String one or more strings as arguments

Returns

String the resulting string

contains (string, substring, fromIndex)

Returns true if string contains substring.

Parameters

String string the string to search in
String substring the string to search for
Number fromIndex optional index to start searching

Returns

Boolean true if str is contained in this string

count (string, pattern)

returns the amount of occurences of one string in another

Parameters

String string
String pattern

digest (string, algorithm)

function calculates a message digest of a string. If no argument is passed, the MD5 algorithm is used.

Parameters

String string the string to digest
String algorithm the name of the algorithm to use

Returns

String base16-encoded message digest of the string

endsWith (string, substring)

Returns true if string ends with the given substring

Parameters

String string the string to search in
String substring pattern to search for

Returns

Boolean true in case it matches the end of the string, false otherwise

entitize (string)

translates all characters of a string into HTML entitie

Parameters

String string the string

Returns

String translated result

escapeHtml (string)

Escape the string to make it safe for use within an HTML document.

Parameters

String string the string to escape

Returns

String the escaped string

escapeRegExp (str)

Accepts a string; returns the string with regex metacharacters escaped. the returned string can safely be used within a regex to match a literal string. escaped characters are [, ], {, }, (, ), -, *, +, ?, ., , ^, $, |, #, [comma], and whitespace.

Parameters

String str the string to escape

Returns

String the escaped string

format (format)

A simple string formatter. If the first argument is a format string containing a number of curly bracket pairs {} as placeholders, the same number of following arguments will be used to replace the curly bracket pairs in the format string. If the first argument is not a string or does not contain any curly brackets, the arguments are simply concatenated to a string and returned.

Parameters

String format string, followed by a variable number of values

Returns

String the formatted string

getCommonPrefix (str1, str2)

Get the longest common segment that two strings have in common, starting at the beginning of the string

Parameters

String str1 a string
String str2 another string

Returns

String the longest common segment

group (string, interval, string, ignoreWhiteSpace)

function inserts a string every number of characters

Parameters

String string
Number interval number of characters after which insertion should take place
String string to be inserted
Boolean ignoreWhiteSpace definitely insert at each interval position

Returns

String resulting string

isAlpha (string)

function returns true if the string contains only characters a-z

Parameters

string

Returns

Boolean true in case string is alpha, false otherwise

isAlphanumeric (string)

function returns true if the string contains only a-z and 0-9 (case insensitive!)

Parameters

string

Returns

Boolean true in case string is alpha, false otherwise

isDateFormat (string)

checks if a date format pattern is correct

Parameters

String string the string

Returns

Boolean true if the pattern is correct

isEmail (string)

returns true if the string looks like an e-mail

Parameters

String string

isFileName (string)

function checks if the string passed contains any characters that are forbidden in image- or filenames

Parameters

String string the string

Returns

Boolean

isHexColor (string)

function checks a string for a valid color value in hexadecimal format. it may also contain # as first character

Parameters

String string the string

Returns

Boolean false, if string length (without #) > 6 or < 6 or contains any character which is not a valid hex value

isNumeric (string)

function returns true if the string contains only 0-9

Parameters

string

Returns

Boolean true in case string is numeric, false otherwise

isUrl (string)

function checks if the string passed contains any characters that are forbidden in URLs and tries to create a java.net.URL from it FIXME: probably deprecated -> ringo.Url

Parameters

String string the string

Returns

Boolean

join (the, the, the)

append one string onto another and add some "glue" if none of the strings is empty or null.

Parameters

String the first string
String the string to be appended onto the first one
String the "glue" to be inserted between both strings

Returns

String the resulting string

pad (string, fill, length, mode)

fills a string with another string up to a desired length

Parameters

String string the string
String fill the filling string
Number length the desired length of the resulting string
Number mode the direction which the string will be padded in: a negative number means left, 0 means both, a positive number means right

Returns

String the resulting string

random (len, mode)

creates a random string (numbers and chars)

Parameters

Number len length of key
Number mode determines which letters to use. null or 0 = all letters; 1 = skip 0, 1, l and o which can easily be mixed with numbers; 2 = use numbers only

Returns

random string

repeat (string, num)

function repeats a string passed as argument

Parameters

String string the string
Number num amount of repetitions

Returns

String resulting string

startsWith (string, substring)

Returns true if string starts with the given substring

Parameters

String string the string to search in
String substring pattern to search for

Returns

Boolean true in case it matches the beginning of the string, false otherwise

stripTags (string)

Remove all potential HTML/XML tags from this string

Parameters

String string the string

Returns

String the processed string

titleize (string)

transforms the first n characters of each word in a string to uppercase

Parameters

String string the string

Returns

String the resulting string

toAlphanumeric (string)

function cleans a string by throwing away all non-alphanumeric characters

Parameters

string

Returns

cleaned string

toCamelCase (string)

Transforms string from space, dash, or underscore notation to camel-case.

Parameters

String string a string

Returns

String the resulting string

toDashes (string)

Transforms string from camel-case to dash notation.

Parameters

String string a string

Returns

String the resulting string

toDate (string, format, timezone)

parse a timestamp into a date object. This is used when users want to set createtime explicitly when creating/editing stories.

Parameters

String string the string
String format date format to be applied
Object timezone Java TimeZone Object (optional)

Returns

Object the resulting date

toFileName (string)

function cleans the string passed as argument from any characters that are forbidden or shouldn't be used in filenames

Parameters

String string the string

Returns

Boolean

toHexColor (string)

converts a string into a hexadecimal color representation (e.g. "ffcc33"). also knows how to convert a color string like "rgb (255, 204, 51)".

Parameters

String string the string

Returns

String the resulting hex color (w/o "#")

toUnderscores (string)

Transforms string from camel-case to underscore notation.

Parameters

String string a string

Returns

String the resulting string

unwrap (flag, replacement)

replace all linebreaks and optionally all w/br tags

Parameters

Boolean flag indicating if html tags should be replaced
String replacement for the linebreaks / html tags

Returns

String the unwrapped string