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 of15
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
withwriter
.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
orfalse
.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 valuered
would simply be serialized asred
.The
nil
value and nilable class variables storingnil
will be serialized as the textnil
.Classes and records will have their
serialize
method invoked, passing inwriter
and this Serializer as arguments. Please see the serializers technote for more information.Classes and records are expected to implement the
writeSerializable
orserializable
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
orstartRecord
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
namedname
.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
andy=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 currentAggregateSerializer
.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 invokingendRecord
.
- 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 invokingendTuple
.
- 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
, and3
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 invokingendList
.
- 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 sizesize
.- 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 invokingendArray
.
- 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 keys1
,2
, and3
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 invokingendMap
.