Data Conversion
The following set of functions are used to convert values from one type to another.
| • | to_s |
| • | to_n |
| • | to_b |
| • | to_d |
| • | to_a |
| • | to_object |
| • | to_json |
| • | from_json |
| • | strftime |
| • | to_base64 |
| • | from_base 64 |
| • | to_html |
| • | from_html |
| • | to_uri |
| • | to_uri_esc |
| • | from_uri |
Syntax
to_s($value)
Description
Convert value to string. The semantic for each type is summarized in the following table:
|
Type |
Result |
Example |
|
string |
no change |
to_s("foo") == "foo" |
|
number |
string representation of number |
to_s(1) == "1" |
|
boolean |
string representation of boolean |
to_s(true) == "true" |
|
datetime |
string representation of datetime |
to_s(d"1/1/2012 6:59 PM") == "d\"2012/01/01 18:59\"" |
|
null |
string “null” |
to_s(null) == "null" |
|
array |
JSON representation of an array |
to_s([1, 2, "3"]) == "[1,2,\"3\"]" |
|
hash |
JSON representation of a hash |
to_s({ "one": 1, "two": 2, "three": 3 }) == "{\"one\":1,\"two\":2,\"three\":3}" |
Syntax
to_n($value)
Description
Convert a value to a number. The only types that can be converted to numbers are strings, booleans, and datetimes. Attempting to convert a value of a different type (e.g. an array) will result in an error.
|
Type |
Result |
Example |
|
string |
corresponding number or 0 if string does not represent a number |
to_n("1.23123") == 1.23123 to_n("foo") == 0 |
|
number |
no change |
to_n(1) == 1 |
|
boolean |
1 for true, 0 for false |
to_n(true) == 1 |
|
datetime |
number of seconds since the epoch |
to_n(d"2012/01/26 1:49:35") == 1327542575 |
|
null |
0 |
to_n(null) == 0 |
Syntax
to_b($value)
Description
Convert value to boolean. The only types that can be converted to booleans are strings and numbers. Attempting to convert a value of a different type (e.g. an array) will result in an error.
|
Type |
Result |
Example |
|
string |
true if string is “true”, false otherwise |
to_b("true") == true to_b("foo") == false |
|
number |
true if non 0, false otherwise |
to_b(42) == true to_b(0) == false |
|
boolean |
no change |
to_b(true) == true |
Syntax
to_d($value)
Description
Convert value to datetime. The only types that can be converted to datetimes are strings and numbers. Attempting to convert a value of a different type (e.g., an array) will result in an error. The accepted syntax for strings representing datetime is:
year/month/day [h:m[:s]] [AM|PM]
Trying to coerce a string that does not match this syntax to a datetime value results in an error.
|
Type |
Result |
Example |
|
string |
corresponding datetime if syntax is correct, error otherwise |
to_d("1/1/2012") == d"1/1/2012" |
|
number |
datetime with corresponding unix timestamp |
to_d(42) == d"1/1/1970 00:00:42" |
|
datetime |
no change |
|
Syntax
to_a($value)
Description
Convert hash to array of pairs or a range to an array. Converting a value of type other than hash or range will result in an error.
|
Type |
Result |
Example |
|
hash |
Corresponding array of pairs, ordering is random |
to_a({ "one": 1, "two": 2, "three": 3 }) == [ ["two", 2], ["one", 1], ["three", 3] ] |
|
range |
Array of the given range |
to_a([1..3]) == [1, 2, 3] |
Syntax
to_object(@declaration or @collection)
Description
Convert given resource declaration or resource collection into a JSON object. Especially useful to convert a declaration into an object, manipulate that object and assign it back to a declaration so that for example, provision() may be called on it.
|
Type |
Result |
Example |
||||||
-OR-
|
JSON object containing declaration or collection fields Note:Objects created from declarations may be assigned back to a reference. |
$data = to_object(@servers) |
Syntax
to_json($value)
Description
Convert a value into a JSON string.
|
Type |
Result |
Example |
|
any |
JSON string |
to_json({ "one": 1, "two": 2, "three": 3 }) == '{"one":1,"two":2,"three":3}' |
Syntax
from_json($value)
Description
Convert a string value into a RCL value.
|
Type |
Result |
Example |
|
string |
RCL value |
from_json('{"one":1,"two":2,"three":3}') == { "one": 1, "two": 2, "three": 3 } |
Syntax
strftime($date, $format_string)
Description
Converts the given datetime to a string using the format/directives provided.
Arguments
|
Position |
Possible Values |
Required |
Default Value |
Comment |
|
1 |
Datetime value |
Yes |
None |
|
|
2 |
String value |
Yes |
None |
Use any of the directives specified below when creating the string |
The directive consists of a percent (%) character, zero or more flags, optional minimum field width, and a conversion specifier as follows:
%<flags><width><conversion>
Flags
| • | - don't pad a numerical output |
| • | _ use spaces for padding |
| • | 0 use zeros for padding |
| • | ^ upcase the result string |
| • | # change case |
The minimum field width specifies the minimum width.
Format Directives
| • | Date (Year, Month, Day) |
| • | Time (Hour, Minute, Second, Subsecond) |
| • | Weekday |
| • | ISO 8601 Week-Based Year and Week Number |
| • | Week Number |
| • | Seconds Since the Epoch |
| • | Literal String |
| • | Combination |
| • | Examples |
|
Directive |
Description |
|
%Y |
Year with century if provided, will pad result at least 4 digits. -0001, 0000, 1995, 2009, 14292, etc. |
|
%C |
year / 100 (rounded down such as 20 in 2009) |
|
%y |
year % 100 (00..99) |
|
%m |
Month of the year, zero-padded (01..12) |
|
%_m |
blank-padded ( 1..12) |
|
%-m |
no-padded (1..12) |
|
%B |
The full month name (January) |
|
%^B |
uppercased (JANUARY) |
|
%b |
The abbreviated month name (Jan) |
|
%^b |
uppercased abbreviated month name (JAN) |
|
%h |
Equivalent to %b |
|
%d |
Day of the month, zero-padded (01..31) |
|
%-d |
no-padded (1..31) |
|
%e |
Day of the month, blank-padded ( 1..31) |
|
%j |
Day of the year (001..366) |
Time (Hour, Minute, Second, Subsecond)
|
Directive |
Description |
|
%H |
Hour of the day, 24-hour clock, zero-padded (00..23) |
|
%k |
Hour of the day, 24-hour clock, blank-padded ( 0..23) |
|
%I |
Hour of the day, 12-hour clock, zero-padded (01..12) |
|
%l |
Hour of the day, 12-hour clock, blank-padded ( 1..12) |
|
%p |
Meridian indicator, uppercase (AM or PM) |
|
%M |
Minute of the hour (00..59) |
|
%S |
Second of the minute (00..60) |
|
%L |
Millisecond of the second (000..999). The digits under millisecond are truncated to not produce 1000. |
|
%N |
Fractional seconds digits, default is 9 digits (nanosecond) |
|
%3N |
millisecond (3 digits) |
|
%6N |
microsecond (6 digits) |
|
%9N |
nanosecond (9 digits) |
|
%12N |
picosecond (12 digits) |
|
%15N |
femtosecond (15 digits) |
|
%18N |
attosecond (18 digits) |
|
%21N |
zeptosecond (21 digits) |
|
%24N |
yoctosecond (24 digits). The digits under the specified length are truncated to avoid carry up. |
|
Directive |
Description |
|
%A |
The full weekday name (Sunday) |
|
%^A |
Uppercased full weekday name (SUNDAY) |
|
%a |
The abbreviated weekday name (Sun) |
|
%^a |
Uppercased abbreviated weekday name (SUN) |
|
%u |
Day of the week (Monday is 1, 1..7) |
|
%w |
Day of the week (Sunday is 0, 0..6) |
ISO 8601 Week-Based Year and Week Number
The first week of YYYY starts with a Monday and includes YYYY-01-04. The days in the year before the first week are in the last week of the previous year.
|
Directive |
Description |
|
%G |
The week-based year |
|
%g |
The last 2 digits of the week-based year (00..99) |
|
%V |
Week number of the week-based year (01..53) |
The first week of YYYY that starts with a Sunday or Monday (according to %U or %W). The days in the year before the first week are in week 0.
|
Directive |
Description |
|
%U |
Week number of the year. The week starts with Sunday. (00..53) |
|
%W |
Week number of the year. The week starts with Monday. (00..53) |
|
Directive |
Description |
|
%s |
Number of seconds since 1970-01-01 00:00:00 UTC. |
|
Directive |
Description |
|
%n |
Newline character (\n) |
|
%t |
Tab character (\t) |
|
%% |
Literal % character |
|
Directive |
Description |
|
%c |
Date and time (%a %b %e %T %Y) |
|
%D |
Date (%m/%d/%y) |
|
%F |
The ISO 8601 date format (%Y-%m-%d) |
|
%v |
VMS date (%e-%^b-%4Y) |
|
%x |
Same as %D |
|
%X |
Same as %T |
|
%r |
12-hour time (%I:%M:%S %p) |
|
%R |
24-hour time (%H:%M) |
|
%T |
24-hour time (%H:%M:%S) |
Example
# Format the current date for CM API 1.5
$time = now()
$api_time = strftime($time, "%Y/%m/%d %H:%M:%S +0000")
Syntax
to_base64($value)
Description
Encodes a string into a Base64 string
|
Type |
Result |
Example |
|
string |
string |
to_base64("a string") == "YSBzdHJpbmc=" |
Syntax
from_base64($value)
Description
Decodes a Base64 string into a string.
|
Type |
Result |
Example |
|
string |
string |
from_base64("YSBzdHJpbmc=") == "a string" |
Syntax
to_html($value)
Description
Encodes a string into an html-encoded string.
|
Type |
Result |
Example |
|
string |
string |
to_html("&") == "&" |
Syntax
from_html($value)
Description
Decodes an html string into a string.
|
Type |
Result |
Example |
|
string |
string |
from_html("&") == "&" |
Syntax
to_uri($value)
Description
Encodes a string into a Uri-encoded string.
|
Type |
Result |
Example |
|
string |
string |
to_uri("http://example.com/?a=\11\15") == "http://example.com/?a=%09%0D" |
to_uri_esc($value)
Description
Encodes a string into a Uri-encoded String with all non-alphabet or number characters escaped.
|
Type |
Result |
Example |
|
string |
string |
to_uri_esc("http://example.com/?a=\11\15") == "http%3A%2F%2Fexample.com%2F%3Fa%3D%09%0D" |
Syntax
from_uri($value)
Description
Decodes a uri-encoded string into a string.
|
Type |
Result |
Example |
|
string |
string |
from_uri("http://example.com/?a=%09%0D") == "http://example.com/?a=\t\r" |