Functions
clone | I Returns a clone of a value. |
cloneReadOnly | I Returns a clone of a value that is read-only, i.e., immutable. |
cloneWithType | I Constructs a value with a specified type by cloning another value. |
ensureType | I Safely casts a value to a type. |
fromBalString | I Parses and evaluates a subset of Ballerina expression syntax. |
fromJsonDecimalString | I Parses a string in JSON format, using decimal to represent numbers. |
fromJsonFloatString | I Parses a string in JSON format, using float to represent numbers. |
fromJsonString | I Parses a string in JSON format and returns the the value that it represents. |
fromJsonStringWithType | I Converts a string in JSON format to a user-specified type. |
fromJsonWithType | I Converts a value of type json to a user-specified type. |
isReadOnly | D I Tests whether a value is read-only, i.e., immutable. |
mergeJson | I Merges two |
toBalString | I Converts a value to a string that describes the value in Ballerina syntax. |
toJson | I Converts a value of type |
toJsonString | I Returns the string that represents a anydata value in JSON format. |
toString | I Performs a direct conversion of a value to a string. |
clone
function clone(CloneableType v) returns CloneableType
Returns a clone of a value.
A clone is a deep copy that does not copy immutable subtrees. A clone can therefore safely be used concurrently with the original. It corresponds to the Clone(v) abstract operation, defined in the Ballerina Language Specification.
Parameters
- v CloneableType
source value
cloneReadOnly
function cloneReadOnly(CloneableType v) returns CloneableType & readonly
Returns a clone of a value that is read-only, i.e., immutable.
It corresponds to the ImmutableClone(v) abstract operation, defined in the Ballerina Language Specification.
Parameters
- v CloneableType
source value
cloneWithType
function cloneWithType(anydata v, typedesc<anydata> t) returns t | error
Constructs a value with a specified type by cloning another value.
When parameter v
is a structural value, the inherent type of the value to be constructed
comes from parameter t
. When parameter t
is a union, it must be possible to determine which
member of the union to use for the inherent type by following the same rules
that are used by list constructor expressions and mapping constructor expressions
with the contextually expected type. If not, then an error is returned.
The cloneWithType
operation is recursively applied to each member of parameter v
using
the type descriptor that the inherent type requires for that member.
Like the Clone abstract operation, this does a deep copy, but differs in the following respects:
- the inherent type of any structural values constructed comes from the specified
type descriptor rather than the value being constructed
- the read-only bit of values and fields comes from the specified type descriptor
- the graph structure of
v
is not preserved; the result will always be a tree;
an error will be returned if v
has cycles
- immutable structural values are copied rather being returned as is; all
structural values in the result will be mutable.
- numeric values can be converted using the NumericConvert abstract operation
- if a record type descriptor specifies default values, these will be used
to supply any missing members
Parameters
- v anydata
the value to be cloned
- t typedesc<anydata> (default <>)
the type for the cloned to be constructed
ensureType
Safely casts a value to a type.
This casts a value to a type in the same way as a type cast expression, but returns an error if the cast cannot be done, rather than panicking.
Parameters
- v any | error
the value to be cast
- t typedesc<any> (default <>)
a typedesc for the type to which to cast it
Return Type
(t | error)v
cast to the type described by parameter t
, or an error, if the cast cannot be done
fromBalString
Parses and evaluates a subset of Ballerina expression syntax.
The subset of Ballerina expression syntax supported is that produced by toBalString when applied to an anydata value.
Parameters
- s string
the string to be parsed and evaluated
Return Type
(anydata | error)the result of evaluating the parsed expression, or an error if the string cannot be parsed
fromJsonDecimalString
function fromJsonDecimalString(string str) returns JsonDecimal | error
Parses a string in JSON format, using decimal to represent numbers.
Returns an error if the string cannot be parsed.
Parameters
- str string
string in JSON format
fromJsonFloatString
Parses a string in JSON format, using float to represent numbers.
Returns an error if the string cannot be parsed.
Parameters
- str string
string in JSON format
fromJsonString
Parses a string in JSON format and returns the the value that it represents.
Numbers in the JSON string are converted into Ballerina values of type
decimal except in the following two cases:
if the JSON number starts with -
and is numerically equal to zero, then it is
converted into float value of -0.0
;
otherwise, if the JSON number is syntactically an integer and is in the range representable
by a Ballerina int, then it is converted into a Ballerina int.
A JSON number is considered syntactically an integer if it contains neither
a decimal point nor an exponent.
Returns an error if the string cannot be parsed.
Parameters
- str string
string in JSON format
fromJsonStringWithType
Converts a string in JSON format to a user-specified type.
This is a combination of function fromJsonString
followed by function fromJsonWithType
.
fromJsonWithType
function fromJsonWithType(json v, typedesc<anydata> t) returns t | error
Converts a value of type json to a user-specified type.
This works the same as function cloneWithType
,
except that it also does the inverse of the conversions done by toJson
.
Parameters
- v json
json value
- t typedesc<anydata> (default <>)
type to convert to
isReadOnly
function isReadOnly(anydata v) returns boolean
Tests whether a value is read-only, i.e., immutable.
Returns true if read-only, false otherwise.
Parameters
- v anydata
source value
Return Type
(boolean)true if read-only, false otherwise
Deprecated
This function will be removed in a future release.
mergeJson
function mergeJson(json j1, json j2) returns json | error
Merges two json
values.
The merge of parameter j1
with parameter j2
is defined as follows:
- if parameter
j1
is()
, then the result is parameterj2
- if parameter
j2
is()
, then the result is parameterj1
- if parameter
j1
is a mapping and parameterj2
is a mapping, then for each entry [k, j] in parameterj2
, setj1[k]
to the merge ofj1[k]
withj
- if
j1[k]
is undefined, then setj1[k]
toj
- if any merge fails, then the merge of parameter
j1
with parameterj2
fails - otherwise, the result is parameter
j1
. - otherwise, the merge fails
If the merge fails, then parameter j1
is unchanged.
Parameters
- j1 json
json value
- j2 json
json value
Return Type
(json | error)the merge of parameter j1
with parameter j2
or an error if the merge fails
toBalString
function toBalString(any v) returns string
Converts a value to a string that describes the value in Ballerina syntax.
If parameter v
is anydata and does not have cycles, then the result will
conform to the grammar for a Ballerina expression and when evaluated
will result in a value that is == to parameter v
.
The details of the conversion are specified by the ToString abstract operation defined in the Ballerina Language Specification, using the expression style.
Parameters
- v any
the value to be converted to a string
toJson
function toJson(anydata v) returns json
Converts a value of type anydata
to json
.
This does a deep copy of parameter v
converting values that do
not belong to json into values that do.
A value of type xml
is converted into a string as if
by the toString
function.
A value of type table
is converted into a list of
mappings one for each row.
The inherent type of arrays in the return value will be
json[]
and of mappings will be map<json>
.
A new copy is made of all structural values, including
immutable values.
This panics if parameter v
has cycles.
Parameters
- v anydata
anydata value
Return Type
(json)representation of v
as value of type json
toJsonString
function toJsonString(anydata v) returns string
Returns the string that represents a anydata value in JSON format.
parameter v
is first converted to json
as if by the function toJson
.
Parameters
- v anydata
anydata value
toString
function toString((any) v) returns string
Performs a direct conversion of a value to a string.
The conversion is direct in the sense that when applied to a value that is already a string it leaves the value unchanged.
The details of the conversion are specified by the ToString abstract operation defined in the Ballerina Language Specification, using the direct style.
Parameters
- v (any)
the value to be converted to a string