Skip to main content

Data Conversion

The following set of functions are used to convert values from one type to another.

to_s​

Syntax​

to_s($value)

Description​

Convert value to string. The semantic for each type is summarized in the following table:

TypeResultExample
stringno changeto_s("foo") == "foo"
numberstring representation of numberto_s(1) == "1"
booleanstring representation of booleanto_s(true) == "true"
datetimestring representation of datetimeto_s(d"1/1/2012 6:59 PM") == "d\"2012/01/01 18:59\""
nullstring “null”to_s(null) == "null"
arrayJSON representation of an arrayto_s([1, 2, "3"]) == "[1,2,\"3\"]"
hashJSON representation of a hashto_s({ "one": 1, "two": 2, "three": 3 }) == "{\"one\":1,\"two\":2,\"three\":3}"

to_n​

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.

TypeResultExample
stringcorresponding number or 0 if string does not represent a numberto_n("1.23123") == 1.23123
to_n("foo") == 0
numberno changeto_n(1) == 1
boolean1 for true, 0 for falseto_n(true) == 1
datetimenumber of seconds since the epochto_n(d"2012/01/26 1:49:35") == 1327542575
null0to_n(null) == 0

to_b​

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.

TypeResultExample
stringtrue if string is “true”, false otherwiseto_b("true") == true
to_b("foo") == false
numbertrue if non 0, false otherwiseto_b(42) == true
to_b(0) == false
booleanno changeto_b(true) == true

to_d​

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.

TypeResultExample
stringcorresponding datetime if syntax is correct, error otherwiseto_d("1/1/2012") == d"1/1/2012"
numberdatetime with corresponding unix timestampto_d(42) == d"1/1/1970 00:00:42"
datetimeno change

to_a​

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.

TypeResultExample
hashCorresponding array of pairs, ordering is randomto_a({ "one": 1, "two": 2, "three": 3 }) == [ ["two", 2], ["one", 1], ["three", 3] ]
rangeArray of the given rangeto_a([1..3]) == [1, 2, 3]

to_object​

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.

TypeResultExample
Collection
-OR
Declaration		JSON object containing declaration or collection fields
Note: Objects created from declarations may be assigned back to a reference.		$data = to_object(@servers)

to_json​

Syntax​

to_json($value)

Description​

Convert a value into a JSON string.

TypeResultExample
anyJSON stringto_json({ "one": 1, "two": 2, "three": 3 }) == '{"one":1,"two":2,"three":3}'

from_json​

Syntax​

from_json($value)

Description​

Convert a string value into a RCL value.

TypeResultExample
stringRCL valuefrom_json('{"one":1,"two":2,"three":3}') == { "one": 1, "two": 2, "three": 3 }

strftime​

Syntax​

strftime($date, $format_string)

Description​

Converts the given datetime to a string using the format/directives provided.

Arguments​

PositionPossible ValuesRequiredDefault ValueComment
1Datetime valueYesNone
2String valueYesNoneUse 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)​

DirectiveDescription
%YYear with century if provided, will pad result at least 4 digits. \-0001 , 0000 , 1995 , 2009 , 14292 , etc.
%Cyear / 100 (rounded down such as 20 in 2009 )
%yyear % 100 (00..99)
%mMonth of the year, zero-padded (01..12)
%_mblank-padded ( 1..12)
%-mno-padded (1..12)
%BThe full month name ( January )
%^Buppercased ( JANUARY )
%bThe abbreviated month name ( Jan )
%^buppercased abbreviated month name ( JAN )
%hEquivalent to %b
%dDay of the month, zero-padded (01..31)
%-dno-padded (1..31)
%eDay of the month, blank-padded ( 1..31)
%jDay of the year (001..366)

Time (Hour, Minute, Second, Subsecond)​

DirectiveDescription
%HHour of the day, 24-hour clock, zero-padded (00..23)
%kHour of the day, 24-hour clock, blank-padded ( 0..23)
%IHour of the day, 12-hour clock, zero-padded (01..12)
%lHour of the day, 12-hour clock, blank-padded ( 1..12)
%pMeridian indicator, uppercase (AM or PM)
%MMinute of the hour (00..59)
%SSecond of the minute (00..60)
%LMillisecond of the second (000..999). The digits under millisecond are truncated to not produce 1000 .
%NFractional seconds digits, default is 9 digits (nanosecond)
%3Nmillisecond (3 digits)
%6Nmicrosecond (6 digits)
%9Nnanosecond (9 digits)
%12Npicosecond (12 digits)
%15Nfemtosecond (15 digits)
%18Nattosecond (18 digits)
%21Nzeptosecond (21 digits)
%24Nyoctosecond (24 digits). The digits under the specified length are truncated to avoid carry up.

Weekday​

DirectiveDescription
%AThe full weekday name ( Sunday )
%^AUppercased full weekday name ( SUNDAY )
%aThe abbreviated weekday name ( Sun )
%^aUppercased abbreviated weekday name ( SUN )
%uDay of the week (Monday is 1, 1..7)
%wDay 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.

DirectiveDescription
%GThe week-based year
%gThe last 2 digits of the week-based year (00..99)
%VWeek number of the week-based year (01..53)

Week Number​

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.

DirectiveDescription
%UWeek number of the year. The week starts with Sunday. (00..53)
%WWeek number of the year. The week starts with Monday. (00..53)

Seconds Since the Epoch​

DirectiveDescription
%sNumber of seconds since 1970-01-01 00:00:00 UTC.

Literal String​

DirectiveDescription
%nNewline character ( \\n )
%tTab character ( \\t )
%%Literal % character

Combination​

DirectiveDescription
%cDate and time ( %a %b %e %T %Y )
%DDate ( %m/%d/%y )
%FThe ISO 8601 date format ( %Y\-%m\-%d )
%vVMS date ( %e\-%^b\-%4Y )
%xSame as %D
%XSame as %T
%r12-hour time ( %I:%M:%S %p )
%R24-hour time ( %H:%M )
%T24-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")

to_base64​

Syntax​

to_base64($value)

Description​

Encodes a string into a Base64 string

TypeResultExample
stringstringto_base64("a string") == "YSBzdHJpbmc="

from_base 64​

Syntax​

from_base64($value)

Description​

Decodes a Base64 string into a string.

TypeResultExample
stringstringfrom_base64("YSBzdHJpbmc=") == "a string"

to_html​

Syntax​

to_html($value)

Description​

Encodes a string into an html-encoded string.

TypeResultExample
stringstringto_html("&") == "&amp;"

from_html​

Syntax​

from_html($value)

Description​

Decodes an html string into a string.

TypeResultExample
stringstringfrom_html("&amp;") == "&"

to_uri​

Syntax​

to_uri($value)

Description​

Encodes a string into a Uri-encoded string.

TypeResultExample
stringstringto_uri("http://example.com/?a=\11\15") == "http://example.com/?a=%09%0D"

to_uri_esc​

to_uri_esc($value)

Description​

Encodes a string into a Uri-encoded String with all non-alphabet or number characters escaped.

TypeResultExample
stringstringto_uri_esc("http://example.com/?a=\11\15") == "http%3A%2F%2Fexample.com%2F%3Fa%3D%09%0D"

from_uri​

Syntax​

from_uri($value)

Description​

Decodes a uri-encoded string into a string.

TypeResultExample
stringstringfrom_uri("http://example.com/?a=%09%0D") == "http://example.com/?a=\t\r"