PrecisionSerializer

Usage

use PrecisionSerializer;

or

import PrecisionSerializer;

Support for controlling I/O precision and padding.

Provides the precisionSerializer type, whose formatting is identical to the defaultSerializer, except numbers are printed with the specified precision and padding.

record precisionSerializer

Warning

‘precisionSerializer’ is an experimental feature. Its behavior and/or API may change in future releases.

A variation of the defaultSerializer that provides finer control over formatting of numerical values.

For example, the following code snippet:

use PrecisionSerializer;
var x = [i in 1..5] i + 0.123456789;
stdout.withSerializer(new precisionSerializer(precision=7, padding=12)).write(x);

would produce the output:

1.1234568    2.1234568    3.1234568    4.1234568    5.1234568

whereas the default serializer would output:

1.12346 2.12346 3.12346 4.12346 5.12346

See the serializers technote for a general overview of Serializers and their usage.

proc init()

Create a default precisionSerializer with a precision of 15 and no padding.

proc init(precision: int, padding: int = 0)

Create a precisionSerializer with particular precision and padding settings for formatting numeric values.

Arguments:

  • precision – The number of digits to display after the decimal point when serializing real values.

  • padding – The number of columns to left-pad the number with when serializing real values, or the minimum column width when serializing integral values (left padding used). If zero, no padding/width is enforced.

proc ref serializeValue(writer: fileWriter, const val: ?t) : void throws

Serialize val with writer.

Real values are serialized with either %*.*dr or %.*dr depending on whether a non-zero padding was specified. Left padding is used if specified.

Integral values are serialized with either %*i or %i depending on whether a non-zero padding was specified. Left padding is used if specified.

Complex numbers are serialized as %z.

Booleans are serialized as the literal strings true or false.

string values are serialized using the same format as %s — that is, literally and without quotes. bytes values are also serialized literally without extra formatting.

Enums are serialized using the name of the corresponding value. For example with an enum like enum colors {red, green blue}, the value red would simply be serialized as red.

The nil value and nilable class variables storing nil will be serialized as the text nil.

Classes and records will have their serialize method invoked, passing in writer and this Serializer as arguments. Please see the serializers technote for more information.

Classes and records are expected to implement the writeSerializable or serializable interface.

Arguments:

  • writer – The fileWriter used to write serialized output.

  • val – The value to be serialized.

proc startClass(writer: fileWriter, name: string, size: int) throws

Start serializing a class by writing the character {.

Arguments:

  • writer – The fileWriter to be used when serializing.

  • name – The name of the class type.

  • size – The number of fields in the class.

Returns:

A new AggregateSerializer

proc startRecord(writer: fileWriter, name: string, size: int) throws

Start serializing a record by writing the character (.

Arguments:

  • writer – The fileWriter to be used when serializing.

  • name – The name of the record type.

  • size – The number of fields in the record.

Returns:

A new AggregateSerializer

record AggregateSerializer

Returned by startClass or startRecord to provide the API for serializing classes or records.

A class with integer fields ‘x’ and ‘y’ with values ‘0’ and ‘5’ would be serialized as:

{x = 0, y = 5}

A record with matching fields would be serialized in the same way, but would use ( and ) instead of { and }.

proc ref writeField(name: string, const field: ?) throws

Serialize field named name.

Serializes fields in the form ‘<name> = <field>’. Adds a comma before the name if this is not the first field.

proc ref startClass(writer: fileWriter, name: string, size: int) throws

Start serializing a nested class inside the current class. In this format inheritance is not represented and parent fields are printed before child fields. For example, the following classes with values x=5 and y=2.0:

class Parent {
  var x : int;
}

class Child: Parent {
  var y : real;
}

would be serialized as:

{x = 5, y = 2.000000000000000}
Arguments:

  • writer – The fileWriter to be used when serializing. Must match the writer used to create the current AggregateSerializer.

  • name – The name of the class type.

  • size – The number of fields in the class.

Returns:

A new AggregateSerializer

proc endClass() throws

Ends serialization of the current class by writing the character }

Note

It is an error to call methods on an AggregateSerializer after invoking ‘endClass’.

proc endRecord() throws

Ends serialization of the current record by writing the character )

Note

It is an error to call methods on an AggregateSerializer after invoking endRecord.

proc startTuple(writer: fileWriter, size: int) throws

Start serializing a tuple by writing the character (.

Arguments:

  • writer – The fileWriter to be used when serializing.

  • size – The number of elements in the tuple.

Returns:

A new TupleSerializer

record TupleSerializer

Returned by startTuple to provide the API for serializing tuples.

A tuple will be serialized as a comma-separated list between two parentheses. For example, the tuple literal (1, 2, 3) would be serialized as:

(1, 2, 3)

A 1-tuple will be serialized with a trailing comma. For example, the literal (4,) would be serialized as (4,).

proc ref writeElement(const element: ?) throws

Serialize element.

Writes a leading comma before serializing the element if this is not the first element in the tuple.

proc endTuple() throws

Ends serialization of the current tuple by writing the character ).

Adds a comma between the last value and ) if there was only one element.

Note

It is an error to call methods on an TupleSerializer after invoking endTuple.

proc startList(writer: fileWriter, size: int) throws

Start serializing a list by writing the character [.

Arguments:

  • writer – The fileWriter to be used when serializing.

  • size – The number of elements in the list.

Returns:

A new ListSerializer

record ListSerializer

Returned by PrecisionSerializer.precisionSerializer.startList to provide the API for serializing lists.

A list will be serialized as a comma-separated series of serialized elements between two square brackets. For example, serializing a list with elements 1, 2, and 3 will produce the text:

[1, 2, 3]

Empty lists will be serialized as [].

proc ref writeElement(const element: ?) throws

Serialize element.

Writes a leading comma before serializing the element if this is not the first element in the list.

proc endList() throws

Ends serialization of the current list by writing the character ].

Note

It is an error to call methods on an ListSerializer after invoking endList.

proc startArray(writer: fileWriter, size: int) throws

Start serializing an array.

Arguments:

  • writer – The fileWriter to be used when serializing.

  • size – The number of elements in the array.

Returns:

A new ArraySerializer

record ArraySerializer

Returned by startArray to provide the API for serializing arrays.

In the default format, an array will be serialized as a whitespace-separated series of serialized elements. This serializer can add additional whitespace between elements if padding is specified.

A 1D array is serialized simply using spaces plus any additional padding:

1.123   2.123   3.123   4.123

A 2D array is serialized using spaces between elements in a row, and prints newlines for new rows:

1.123   2.123   3.123
4.123   5.123   6.123
7.123   8.123   9.123

Arrays with three or more dimensions will be serialized as a series of 2D “panes”, with multiple newlines separating new dimensions:

1.123   2.123   3.123
4.123   5.123   6.123
7.123   8.123   9.123

10.12   11.12   12.12
13.12   14.12   15.12
16.12   17.12   18.12

19.12   20.12   21.12
22.12   23.12   24.12
25.12   26.12   27.12

Empty arrays result in no output to the fileWriter.

proc ref startDim(size: int) throws

Inform the ArraySerializer to start serializing a new dimension of size size.

proc ref endDim() throws

End the current dimension.

proc ref writeElement(const element: ?) throws

Serialize element.

Adds a space if this is not the first element in the row.

proc endArray() throws

Ends serialization of the current array.

Note

It is an error to call methods on an ArraySerializer after invoking endArray.

proc startMap(writer: fileWriter, size: int) throws

Start serializing a map by writing the character {.

Arguments:

  • writer – The fileWriter to be used when serializing.

  • size – The number of entries in the map.

Returns:

A new MapSerializer

record MapSerializer

Returned by startMap to provide the API for serializing maps.

Maps are serialized as a comma-separated series of pairs between curly braces. Pairs are serialized with a : separating the key and value. For example, the keys 1, 2, and 3 with values corresponding to their squares would be serialized as:

{1: 1, 2: 4, 3: 9}

Empty maps will be serialized as {}.

proc ref writeKey(const key: ?) throws

Serialize key.

Adds a leading comma if this is not the first pair in the map.

proc writeValue(const val: ?) throws

Serialize val, preceded by the character :.

proc endMap() throws

Ends serialization of the current map by writing the character }

Note

It is an error to call methods on an MapSerializer after invoking endMap.