Functions - lang.value

clone
I

Returns a clone of v.

cloneReadOnly
I

Returns a clone of v that is read-only, i.e.

cloneWithType
I

Constructs a value with a specified type by cloning another value.

ensureType
I
fromBalString
I

Parses and evaluates a subset of Ballerina expression syntax.

fromJsonDecimalString
I

Parses a string in JSON format and returns the value that it represents.

fromJsonFloatString
I

Parses a string in JSON format and returns the value that it represents.

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
I

Tests whether v is read-only, i.e.

mergeJson
I

Merges two json values.

toBalString
I

Converts a value to a string that describes the value in Ballerina syntax.

toJson
I

Converts a value of type anydata to json.

toJsonString
I

Returns the string that represents v in JSON format.

toString
I

Performs a direct conversion of a value to a string.

clone

(null v)

returns null
Isolated Function

Returns a clone of v. 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) operation, defined in the Ballerina Language Specification.

Parameters

  • v null
  • source value

  • Return Type

    (null)
  • clone of v

cloneReadOnly

(null v)

returns null
Isolated Function

Returns a clone of v that is read-only, i.e. immutable. It corresponds to the ImmutableClone(v) operation, defined in the Ballerina Language Specification.

Parameters

  • v null
  • source value

  • Return Type

    (null)
  • immutable clone of v

cloneWithType

(anydata v, typedesc t)

returns null | error
Isolated Function

Constructs a value with a specified type by cloning another value.

Parameters

  • v anydata
  • the value to be cloned

  • t typedesc
  • the type for the cloned to be constructed

  • Return Type

    (null | error)
  • a new value that belongs to t, or an error if this cannot be done

    When v is a structural value, the inherent type of the value to be constructed comes from t. When 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 constructFrom operation is recursively applied to each member of 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, except for error values (which are always immutable)
    • 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

ensureType

(any | error v, typedesc t)

returns any | error
Isolated Function

Parameters

  • v any | error
  • t typedesc
  • Return Type

    (any | error)

fromBalString

(string s)

returns anydata | error
Isolated Function

Parses and evaluates a subset of Ballerina expression syntax.

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 The subset of Ballerina expression syntax supported is that produced by toBalString when applied to an anydata value.

fromJsonDecimalString

(string str)

returns json | error
Isolated Function

Parses a string in JSON format and returns the value that it represents. All numbers in the JSON will be represented as decimal values. Returns an error if the string cannot be parsed.

Parameters

  • str string
  • string representation of json

  • Return Type

    (json | error)
  • str parsed to json or error

fromJsonFloatString

(string str)

returns json | error
Isolated Function

Parses a string in JSON format and returns the value that it represents. All numbers in the JSON will be represented as float values. Returns an error if the string cannot be parsed.

Parameters

  • str string
  • string representation of json

  • Return Type

    (json | error)
  • str parsed to json or error

fromJsonString

(string str)

returns json | error
Isolated Function

Parses a string in JSON format and returns the the value that it represents. All integer numbers in the JSON will be represented as integer values. All decimal numbers except -0.0 in the JSON will be represent as decimal values. -0.0 in the JSON will be represent as float value. Returns an error if the string cannot be parsed.

Parameters

  • str string
  • string representation of json

  • Return Type

    (json | error)
  • str parsed to json or error

fromJsonStringWithType

(string str, typedesc t)

returns t | error
Isolated Function

Converts a string in JSON format to a user-specified type. This is a combination of fromJsonString followed by fromJsonWithType.

Parameters

  • str string
  • string in JSON format

  • t typedesc
  • type to convert to

  • Return Type

    (t | error)
  • value belonging to t, or error if this cannot be done

fromJsonWithType

(json v, typedesc t)

returns t | error
Isolated Function

Converts a value of type json to a user-specified type. This works the same as cloneWithType, except that it also does the inverse of the conversions done by toJson.

Parameters

  • v json
  • json value

  • t typedesc
  • type to convert to

  • Return Type

    (t | error)
  • value belonging to t, or error if this cannot be done

isReadOnly

(anydata v)

returns boolean
Isolated Function

Tests whether v 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

mergeJson

(json j1, json j2)

returns json | error
Isolated Function

Merges two json values.

Parameters

  • j1 json
  • json value

  • j2 json
  • json value

  • Return Type

    (json | error)
  • the merge of j1 with j2 or an error if the merge fails

    The merge of j1 with j2 is defined as follows:

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

toBalString

(any | error v)

returns string
Isolated Function

Converts a value to a string that describes the value in Ballerina syntax.

Parameters

  • v any | error
  • the value to be converted to a string

  • Return Type

    (string)
  • a string resulting from the conversion

    If 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 v.

    The details of the conversion are specified by the ToString abstract operation defined in the Ballerina Language Specification, using the expression style.

toJson

(anydata v)

returns json
Isolated Function

Converts a value of type anydata to json. This does a deep copy of 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.

Parameters

  • v anydata
  • anydata value

  • Return Type

    (json)
  • representation of v as value of type json This panics if v has cycles.

toJsonString

(anydata v)

returns string
Isolated Function

Returns the string that represents v in JSON format. v is first converted to json as if by the toJson function.

Parameters

  • v anydata
  • anydata value

  • Return Type

    (string)
  • string representation of json

toString

(any | error v)

returns string
Isolated Function

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.

Parameters

  • v any | error
  • the value to be converted to a string

  • Return Type

    (string)
  • a string resulting from the conversion

    The details of the conversion are specified by the ToString abstract operation defined in the Ballerina Language Specification, using the direct style.