Module ringo/utils/strings
Adds useful methods to the JavaScript String type.
Functions
- Sorter(field, order)
- b16decode(str, encoding)
- b16encode(str, encoding)
- b64decode(string, encoding)
- b64encode(string, encoding)
- capitalize(the, amount)
- compose(one)
- contains(string, substring, fromIndex)
- count(string, pattern)
- digest(string, algorithm)
- endsWith(string, substring)
- entitize(string)
- escapeHtml(string)
- escapeRegExp(str)
- format(format)
- getCommonPrefix(str1, str2)
- group(string, interval, string, ignoreWhiteSpace)
- isAlpha(string)
- isAlphanumeric(string)
- isDateFormat(string)
- isEmail(string)
- isFileName(string)
- isHexColor(string)
- isNumeric(string)
- isUrl(string)
- join(the, the, the)
- pad(string, fill, length, mode)
- random(len, mode)
- repeat(string, num)
- startsWith(string, substring)
- stripTags(string)
- titleize(string)
- toAlphanumeric(string)
- toCamelCase(string)
- toDashes(string)
- toDate(string, format, timezone)
- toFileName(string)
- toHexColor(string)
- toUnderscores(string)
- unwrap(flag, replacement)
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
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 |
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
null | 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
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. 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 |