lang.value
Module lang.value
ballerina/lang.value Ballerina library
Module overview
The lang.value
module provides functions that work on values of more than one basic type.
Functions
clone
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
Parameters
- v readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0:CloneableType>> - source value
Return Type
- readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0:CloneableType>> - clone of parameter
v
cloneReadOnly
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
Parameters
- v readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0:CloneableType>> - source value
Return Type
- readonly|xml|CloneableType[]|map<CloneableType>|table<map<ballerina/lang.value:0.0.0:CloneableType>> & readonly - immutable clone of parameter
v
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 ifv
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
Parameters
- v anydata - the value to be cloned
- t typedesc<anydata> (default <>) - the type for the cloned to be constructed
Return Type
- t|error - a new value that belongs to parameter
t
, or an error if this cannot be done
count
Returns the number of arguments.
value:count(1, 2, 3) ⇒ 3
Parameters
- vs any|error... - arguments that are counted
Return Type
- int - number of arguments
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.
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
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 parametert
, or an error, if the cast cannot be done
first
Returns the first argument.
value:first(1, 2, 3) ⇒ 1
Return Type
- any|error - first argument
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.
string a = "12.12d"; a.fromBalString() ⇒ 12.12 string b = "[1, 2, !]"; b.fromBalString() ⇒ error
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.
"[12, true, 123.4, \"hello\"]".fromJsonDecimalString() ⇒ [12.0,true,123.4,"hello"] "[12, true, 12.5, !]".fromJsonDecimalString() ⇒ error
Parameters
- str string - string in JSON format
Return Type
- JsonDecimal|error - parameter
str
parsed to JsonDecimal or error
fromJsonFloatString
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
Parameters
- str string - string in JSON format
fromJsonString
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
Parameters
- str string - string in JSON format
Return Type
- json|error -
str
parsed to json or error
fromJsonStringWithType
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
Return Type
- t|error - value belonging to type parameter
t
or error if this cannot be done
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
.
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
Parameters
- v json - json value
- t typedesc<anydata> (default <>) - type to convert to
Return Type
- t|error - value belonging to type parameter
t
or error if this cannot be done
isReadOnly
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
Parameters
- v anydata - source value
Return Type
- boolean - true if read-only, false otherwise
Deprecated
This function will be removed in a future release.
last
Returns the last argument.
value:last(1, 2, 3) ⇒ 3
Return Type
- any|error - last argument
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.
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
Parameters
- j1 json - json value
- j2 json - json value
Return Type
- json|error - the merge of parameter
j1
with parameterj2
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.
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}]
Parameters
- v any - the value to be converted to a string
Return Type
- string - a string resulting from the conversion
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.
anydata student = {name: "Jo", age: 11}; student.toJson() ⇒ {"name":"Jo","age":11} anydata[] array = []; array.push(array); array.toJson() ⇒ panic
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
.
anydata marks = {"Alice": 90, "Bob": 85, "Jo": 91}; marks.toJsonString() ⇒ {"Alice":90, "Bob":85, "Jo":91}
Parameters
- v anydata - anydata value
Return Type
- string - string representation of parameter
v
converted tojson
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.
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}]
Parameters
- v (any) - the value to be converted to a string
Return Type
- string - a string resulting from the conversion
Union types
lang.value: Cloneable
Cloneable
The type of value to which clone
and cloneReadOnly
can be applied.
lang.value: JsonFloat
JsonFloat
Subtype of json
that allows only float numbers.
lang.value: JsonDecimal
JsonDecimal
Subtype of json
that allows only decimal numbers.
lang.value: Type
Type
Anydata types
lang.value: AnydataType
AnydataType
A type parameter that is a subtype of anydata
.
Has the special semantic that when used in a declaration
all uses in the declaration must refer to same type.
Simple name reference types
lang.value: CloneableType
CloneableType
A type parameter that is a subtype of Cloneable
.
Has the special semantic that when used in a declaration
all uses in the declaration must refer to same type.