apn_mojo.common¶

Use ConversionLimits to bound a conversion's resource use, and FloatKey, ComplexKey, or BallKey for dictionary keys that distinguish stored representations. This page also covers the shared text and JSON rules. For an introduction, see Text and JSON.

Conversion limits shared by every family's text and JSON conversion.

Text and JSON conversion is exact unless a context asks for rounding. Parsers, to_string, to_json and from_json accept an optional limits= that bounds one call.

Summary¶

Structs¶

BallKey¶

Source: apn_mojo/common/keys.mojo

struct BallKey(Comparable, Hashable, ImplicitlyCopyable, Writable)

A Ball as a dictionary key, compared and hashed by its representation.

Keys are equal when Ball.same_representation holds: the kind, the midpoint's representation and the radius all match. They order by Ball.representation_cmp.

Implements

Comparable, Copyable, Equatable, Hashable, ImplicitlyCopyable, Writable

BallKey.__init__ { #BallKey.init .api-name }¶

def __init__(out self, value: Ball)

Wrap a Ball.

Arguments

• value (Ball): The ball.

BallKey.value¶

def value(self) -> Ball

The wrapped Ball.

Returns

Ball: The ball.

BallKey.write_to¶

def write_to(self, mut writer: Some[Writer])

Write BallKey( and the ball, as print does.

Arguments

• writer (mut Some[Writer]): The destination.

ComplexKey¶

Source: apn_mojo/common/keys.mojo

struct ComplexKey(Comparable, Hashable, ImplicitlyCopyable, Writable)

A Complex as a dictionary key, compared and hashed by its representation.

Keys are equal when Complex.same_representation holds, order by Complex.representation_cmp, and hash by stable_hash.

Implements

Comparable, Copyable, Equatable, Hashable, ImplicitlyCopyable, Writable

ComplexKey.__init__ { #ComplexKey.init .api-name }¶

def __init__(out self, value: Complex)

Wrap a Complex.

Arguments

• value (Complex): The Complex number.

ComplexKey.value¶

def value(self) -> Complex

The wrapped Complex.

Returns

Complex: The Complex number.

ComplexKey.write_to¶

def write_to(self, mut writer: Some[Writer])

Write ComplexKey( and the Complex number, as print does.

Arguments

• writer (mut Some[Writer]): The destination.

ConversionLimits¶

Source: apn_mojo/common/conversion.mojo

struct ConversionLimits(ImplicitlyCopyable)

Limits for one text or JSON conversion.

Pass it as limits= to a parser, to_string, to_json or from_json. Each limit is inclusive, and None means unlimited; zero is a real limit. Counters start fresh on every call and are shared by everything the call does, so a batch's elements share one allowance. Limits are never stored in the result.

Implements

Copyable, ImplicitlyCopyable

ConversionLimits.__init__ { #ConversionLimits.init .api-name }¶

def __init__(
    out self,
    *,
    max_input_bytes: Optional[Int] = None,
    max_output_bytes: Optional[Int] = None,
    max_digits: Optional[Int] = None,
    max_values: Optional[Int] = None,
    max_allocated_bytes: Optional[Int] = None,
) raises

Limits for a conversion; omit a setting for no limit.

Arguments

• max_input_bytes (Optional[Int]): The whole input string, before trimming or unescaping.
• max_output_bytes (Optional[Int]): The whole returned string, including JSON framing.
• max_digits (Optional[Int]): Numeric digits across the whole call.
• max_values (Optional[Int]): One for a scalar, the logical length for a batch.
• max_allocated_bytes (Optional[Int]): Bytes newly requested during the call, cumulatively; freed temporaries are not refunded.

Raises

Error: When a setting is negative.

FloatKey¶

Source: apn_mojo/common/keys.mojo

struct FloatKey(Comparable, Hashable, ImplicitlyCopyable, Writable)

A Float as a dictionary key, compared and hashed by its representation.

Keys are equal when Float.same_representation holds, order by Float.representation_cmp, and hash by stable_hash, so a sorted list of keys is the same in every run.

Implements

Comparable, Copyable, Equatable, Hashable, ImplicitlyCopyable, Writable

FloatKey.__init__ { #FloatKey.init .api-name }¶

def __init__(out self, value: Float)

Wrap a Float.

Arguments

• value (Float): The Float.

FloatKey.value¶

def value(self) -> Float

The wrapped Float.

Returns

Float: The Float.

FloatKey.write_to¶

def write_to(self, mut writer: Some[Writer])

Write FloatKey( and the Float, as print does.

Arguments

• writer (mut Some[Writer]): The destination.

Integer text¶

Integer parsing accepts ASCII digits and, for bases above ten, letters without case distinctions. A sign precedes any prefix. Leading zeros are accepted, but the whole input must match the grammar. base=0 detects binary, octal, and hexadecimal prefixes, with decimal as the fallback.

With an explicit base and prefixes disabled, prefix-like characters are just digits when that base permits them: Integer.parse("0b10", 16) is 2832. Whitespace and underscores require their respective options; internal whitespace, repeated underscores, and trailing characters are invalid. Formatting produces unpadded digits; printing an Integer uses decimal.

Other grammars are documented under Rational, Float, Complex, ExactComplex, Ball, and ComplexBall.

JSON¶

An integer record stores its value as a canonical decimal string:

{"version":1,"family":"integer","value":"18446744073709551616"}

A rank-one batch uses version 1:

{"version":1,"family":"integer-batch","values":["18446744073709551616","-7"]}

Other ranks use version 2 with a shape and flat row-major values:

{"version":2,"family":"integer-batch","shape":["2","3"],"values":["1","2","3","4","5","6"]}

Shape dimensions must multiply to the number of values. Rational, Float, and Complex batches use the corresponding family records; see wire formats. Float and Complex batches also save default formats for empty containers. Real and complex balls have scalar JSON records; ball batches do not yet have JSON. ExactComplex has a scalar record with two canonical Rational records; there is no ExactComplex batch type.

• version is a JSON integer, not a string.
• family and the allowed fields must match the target type.
• Numeric payload strings use canonical decimal integers: 0 or an optional minus followed by nonzero-leading digits. Fields such as Float sign and class have their own grammar.
• Decoders accept field reordering, JSON whitespace, and valid escapes, but reject duplicate or unknown fields, comments, and trailing commas.
• Encoders write compact ASCII in a fixed field order.

Parse errors report byte offsets and, where applicable, logical element indices.

What limits count¶

Float JSON counts significand and value-exponent digits, but not format metadata such as precision or exponent bounds. Batch shape metadata does not count toward the digit limit either; byte and allocation limits still cover it.

One budget covers the whole call, including nested components and final output. Freeing temporary storage does not restore the allocation budget. Error messages have a separate 8 KiB allowance, and each new call starts with a fresh budget.

These limits do not cover memory used to receive a payload, later arithmetic, or elapsed time. Apply input-size limits before buffering large records.

Representation keys¶

FloatKey, ComplexKey, and BallKey compare and hash stored representations. This preserves distinctions such as zero signs, formats, and special-value classes. It is useful for caches that must distinguish values ordinary numeric equality would merge. The representation chapter explains identity, ordering, and stable_hash.