RingoJS

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 substring 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

null 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

null 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

isFloat (string)

returns true if the string is a floating point literal

Parameters

String string

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

isInt (string)

returns true if the string is an integer literal

Parameters

String string

isLowerCase (string)

returns true if the string is lowercase

Parameters

String string

isNumeric (string)

function returns true if the string contains only 0-9

Parameters

null string

Returns

Boolean true in case string is numeric, false otherwise

isUpperCase (string)

returns true if the string is uppercase

Parameters

String string

isUrl (string)

function checks if the string is an URL validating. Only HTTP, HTTPS and FTP are allowed protocols.

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

null 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.

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

y64decode (string, encoding)

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

Parameters

String string

the Y64 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

y64encode (string, encoding)

Encode a string or binary to a Y64 encoded string. Y64 is an URL-safe Base64 encoding and prevents any URL escaping. It replaces the plus (+), slash (/) and equals (=) with dot (.), underscore (_) and dash (-).

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 Y64 encoded string

RingoJS 0.11

• Overview • Module Index