function clone(readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0:CloneableType>> v) returns readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0: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.

int[] arr = [1, 2, 3, 4];
int[] clone = arr.clone();
clone ⇒ [1,2,3,4]
arr === clone ⇒ false

function cloneReadOnly(readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0:CloneableType>> v) returns readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0: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.

int[] arr = [1, 2, 3, 4];
int[] & readonly immutableClone = arr.cloneReadOnly();
immutableClone ⇒ [1,2,3,4]
immutableClone is readonly ⇒ true

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

anydata[] arr = [1, 2, 3, 4];
int[] intArray = check arr.cloneWithType();
intArray ⇒ [1,2,3,4]
arr === intArray ⇒ false
type Vowels string:Char[];
string[] vowels = ["a", "e", "i", "o", "u"];
vowels.cloneWithType(Vowels) ⇒ ["a","e","i","o","u"]
vowels.cloneWithType(string) ⇒ error

function count(any|error... vs) returns int

Returns the number of arguments.

value:count(1, 2, 3) ⇒ 3

function ensureType(any|error v, typedesc<any> t) returns t|error

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.

json student = {name: "Jo", subjects: ["CS1212", "CS2021"]};
json[] subjects = check student.subjects.ensureType();
subjects ⇒ ["CS1212","CS2021"]
anydata vowel = "I";
vowel.ensureType(string:Char) ⇒ I;
vowel.ensureType(int) ⇒ error

function first(any|error v, any|error... vs) returns any|error

Returns the first argument.

value:first(1, 2, 3) ⇒ 1

function fromBalString(string s) returns anydata|error

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.

string a = "12.12d";
a.fromBalString() ⇒ 12.12
string b = "[1, 2, !]";
b.fromBalString() ⇒ error

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.

"[12, true, 123.4, \"hello\"]".fromJsonDecimalString() ⇒ [12.0,true,123.4,"hello"]
"[12, true, 12.5, !]".fromJsonDecimalString() ⇒ error

function fromJsonFloatString(string str) returns JsonFloat|error

Parses a string in JSON format, using float to represent numbers.

Returns an error if the string cannot be parsed.

"[12, true, 123.4, \"hello\"]".fromJsonFloatString() ⇒ [12.0,true,123.4,"hello"]
"[12, true, 12.5, !]".fromJsonFloatString() ⇒ error

function fromJsonString(string str) returns json|error

Parses a string in JSON format and returns 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.

"{\"id\": 12, \"name\": \"John\"}".fromJsonString() ⇒ {"id":12,"name":"John"}
"{12: 12}".fromJsonString() ⇒ error

function fromJsonStringWithType(string str, typedesc<anydata> t) returns t|error

Converts a string in JSON format to a user-specified type.

This is a combination of function fromJsonString followed by function fromJsonWithType.

int[] intArray = check "[1, 2, 3, 4]".fromJsonStringWithType(); 
intArray ⇒ [1,2,3,4]
"2022".fromJsonStringWithType(int) ⇒ 2022
"2022".fromJsonStringWithType(boolean) ⇒ error

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.

json arr = [1, 2, 3, 4];
int[] intArray = check arr.fromJsonWithType();
intArray ⇒ [1,2,3,4]
type Vowels string:Char[];
json vowels = ["a", "e", "i", "o", "u"];
vowels.fromJsonWithType(Vowels) ⇒ ["a","e","i","o","u"]
vowels.fromJsonWithType(string) ⇒ error

function isReadOnly(anydata v) returns boolean

Tests whether a value is read-only, i.e., immutable.

Returns true if read-only, false otherwise.

int[] scores = <readonly> [21, 12, 33, 45, 81];
scores.isReadOnly() ⇒ true
string[] sports = ["cricket", "football", "rugby"];
sports.isReadOnly() ⇒ false

function last(any|error v, any|error... vs) returns any|error

Returns the last argument.

value:last(1, 2, 3) ⇒ 3

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 parameter j2
• if parameter j2 is (), then the result is parameter j1
• if parameter j1 is a mapping and parameter j2 is a mapping, then for each entry [k, j] in parameter j2, set j1[k] to the merge of j1[k] with j
• if j1[k] is undefined, then set j1[k] to j
• if any merge fails, then the merge of parameter j1 with parameter j2 fails
• otherwise, the result is parameter j1.
• otherwise, the merge fails If the merge fails, then parameter j1 is unchanged.

json student = {name: "John", age: 23};
json location = {city: "Colombo", country: "Sri Lanka"};
student.mergeJson(location) ⇒ {"name":"John","age":23,"city":"Colombo","country":"Sri Lanka"}
value:mergeJson(student, location) ⇒ {"name":"John","age":23,"city":"Colombo","country":"Sri Lanka"}
json city = "Colombo";
student.mergeJson(city) ⇒ error

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.

decimal value = 12.12d;
value.toBalString() ⇒ 12.12d
anydata[] data = [1, "Sam", 12.3f, 12.12d, {value: 12}];
data.toBalString() ⇒ [1,"Sam",12.3,12.12d,{"value":12}]

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.

anydata student = {name: "Jo", age: 11};
student.toJson() ⇒ {"name":"Jo","age":11}
anydata[] array = [];
array.push(array);
array.toJson() ⇒ panic

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.

anydata marks = {"Alice": 90, "Bob": 85, "Jo": 91};
marks.toJsonString() ⇒ {"Alice":90, "Bob":85, "Jo":91}

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.

decimal value = 12.12d;
value.toString() ⇒ 12.12
anydata[] data = [1, "Sam", 12.3f, 12.12d, {value: 12}];
data.toString() ⇒ [1,"Sam",12.3,12.12,{"value":12}]