Module numeric 

Numeric field decoding and encoding (zoned decimal, packed decimal, binary).

Numeric Type Codecs for COBOL Data

This module provides encoding and decoding functions for the three main COBOL numeric data types:

• Zoned Decimal (PIC 9 with optional SIGN SEPARATE): External decimal format where each digit is stored in a byte with a zone nibble and a digit nibble. The sign may be encoded via overpunch or stored in a separate byte.

• Packed Decimal (COMP-3): Compact binary format where each byte contains two decimal digits (nibbles), with the last nibble containing the sign.

• Binary Integer (COMP-4, COMP-5, BINARY): Standard binary integer encoding in big-endian byte order.

Module Organization

The module is organized into three main categories:

Decoding Functions

• decode_zoned_decimal - Decode zoned decimal fields
• decode_zoned_decimal_sign_separate - Decode SIGN SEPARATE zoned decimals
• decode_zoned_decimal_with_encoding - Decode with encoding detection
• decode_packed_decimal - Decode COMP-3 packed decimals
• decode_binary_int - Decode binary integer fields

Encoding Functions

• encode_zoned_decimal - Encode zoned decimal fields
• encode_zoned_decimal_with_format - Encode with explicit encoding format
• encode_zoned_decimal_with_format_and_policy - Encode with format and policy
• encode_zoned_decimal_with_bwz - Encode with BLANK WHEN ZERO support
• encode_packed_decimal - Encode COMP-3 packed decimals
• encode_binary_int - Encode binary integer fields

Utility Functions

• get_binary_width_from_digits - Map digit count to binary width
• validate_explicit_binary_width - Validate explicit BINARY(n) widths
• should_encode_as_blank_when_zero - Check BLANK WHEN ZERO policy

Performance Considerations

This module is optimized for high-throughput enterprise data processing:

• Hot path optimization: Common cases (1-5 byte COMP-3, ASCII zoned) use specialized fast paths
• Branch prediction: Manual hints mark error paths as unlikely
• Zero-allocation: Scratch buffer variants avoid repeated allocations in loops
• Saturating arithmetic: Prevents panics while maintaining correctness

Encoding Formats

Zoned Decimal Encoding

Zoned decimals support two primary encoding formats:

Format	Zone Nibble	Example Digits	Sign Encoding
ASCII	0x3	0x30-0x39	Overpunch or separate
EBCDIC	0xF	0xF0-0xF9	Overpunch or separate

Packed Decimal Sign Nibbles

COMP-3 uses the last nibble for sign encoding:

Sign	Nibble	Description
Positive	0xC, 0xA, 0xE, 0xF	Positive values
Negative	0xB, 0xD	Negative values
Unsigned	0xF	Unsigned fields only

Binary Integer Widths

Binary integers use the following width mappings:

Digits	Width	Bits	Range (signed)
1-4	2 bytes	16	-32,768 to 32,767
5-9	4 bytes	32	-2,147,483,648 to 2,147,483,647
10-18	8 bytes	64	-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

Examples

Decoding a Zoned Decimal

use copybook_codec::numeric::{decode_zoned_decimal};
use copybook_codec::options::Codepage;

// ASCII zoned decimal: "123" = [0x31, 0x32, 0x33]
let data = b"123";
let result = decode_zoned_decimal(data, 3, 0, false, Codepage::ASCII, false)?;
assert_eq!(result.to_string(), "123");

Encoding a Packed Decimal

use copybook_codec::numeric::{encode_packed_decimal};

// Encode "123.45" as 7-digit COMP-3 with 2 decimal places
let encoded = encode_packed_decimal("123.45", 7, 2, true)?;
// Result: [0x12, 0x34, 0x5C] (12345 positive)

See Also

• crate::zoned_overpunch - Zoned decimal overpunch encoding/decoding
• crate::SmallDecimal - Decimal representation without floating-point precision loss
• crate::memory::ScratchBuffers - Reusable buffers for zero-allocation processing

Structs

SmallDecimal

Small decimal structure for parsing/formatting without floats This avoids floating-point precision issues for financial data

ZonedEncodingInfo

Comprehensive encoding detection result for zoned decimal fields

Functions

decode_binary_int

Decode binary integer field (COMP-4, COMP-5, BINARY)

decode_binary_int_fast

Decode a COBOL binary integer (USAGE BINARY / COMP) with optimized fast paths for 16-, 32-, and 64-bit widths.

decode_float_double

Decode a COMP-2 float with default IEEE-754 big-endian interpretation.

decode_float_double_ibm_hex

Decode a COMP-2 field in IBM hexadecimal floating-point format.

decode_float_double_ieee_be

Decode a COMP-2 field in IEEE-754 big-endian format.

decode_float_double_with_format

Decode a COMP-2 float with explicit format selection.

decode_float_single

Decode a COMP-1 float with default IEEE-754 big-endian interpretation.

decode_float_single_ibm_hex

Decode a COMP-1 field in IBM hexadecimal floating-point format.

decode_float_single_ieee_be

Decode a COMP-1 field in IEEE-754 big-endian format.

decode_float_single_with_format

Decode a COMP-1 float with explicit format selection.

decode_packed_decimal

Decode packed decimal (COMP-3) field with comprehensive error context

decode_packed_decimal_to_string_with_scratch

Decode a packed decimal (COMP-3) directly to a String, bypassing the intermediate SmallDecimal allocation.

decode_packed_decimal_with_scratch

Optimized packed decimal decoder using scratch buffers Minimizes allocations by reusing digit buffer

decode_zoned_decimal

Decode a zoned decimal using the configured code page with detailed error context.

decode_zoned_decimal_sign_separate

Decode a zoned decimal field with SIGN SEPARATE clause

decode_zoned_decimal_to_string_with_scratch

Decode a zoned decimal directly to a String, bypassing the intermediate SmallDecimal allocation.

decode_zoned_decimal_with_encoding

Decode zoned decimal field with encoding detection and preservation

decode_zoned_decimal_with_scratch

Decode a zoned decimal using the configured code page and policy while reusing scratch buffers.

encode_alphanumeric

Encode an alphanumeric (PIC X) field with right-padding to the declared length.

encode_binary_int

Encode binary integer field (COMP-4, COMP-5, BINARY)

encode_float_double

Encode a COMP-2 float with default IEEE-754 big-endian format.

encode_float_double_ibm_hex

Encode a COMP-2 value in IBM hexadecimal floating-point format.

encode_float_double_ieee_be

Encode a COMP-2 value in IEEE-754 big-endian format.

encode_float_double_with_format

Encode a COMP-2 float with explicit format selection.

encode_float_single

Encode a COMP-1 float with default IEEE-754 big-endian format.

encode_float_single_ibm_hex

Encode a COMP-1 value in IBM hexadecimal floating-point format.

encode_float_single_ieee_be

Encode a COMP-1 value in IEEE-754 big-endian format.

encode_float_single_with_format

Encode a COMP-1 float with explicit format selection.

encode_packed_decimal

Encode packed decimal (COMP-3) field

encode_packed_decimal_with_scratch

Encode a packed decimal (COMP-3) while reusing caller-owned scratch buffers to minimize per-call allocations.

encode_zoned_decimal

Encode a zoned decimal using the configured code page defaults.

encode_zoned_decimal_sign_separate

Encode a zoned decimal value with SIGN SEPARATE clause.

encode_zoned_decimal_with_bwz

Encode a zoned decimal with COBOL BLANK WHEN ZERO support.

encode_zoned_decimal_with_format

Encode a zoned decimal using an explicit encoding override when supplied.

encode_zoned_decimal_with_format_and_policy

Encode a zoned decimal using a caller-resolved format and zero-sign policy.

encode_zoned_decimal_with_scratch

Encode a zoned decimal while reusing caller-owned scratch buffers to avoid per-call heap allocations on the hot path.

format_binary_int_to_string_with_scratch

Format a binary integer into the caller-owned scratch buffer.

get_binary_width_from_digits

Map a COBOL PIC digit count to the corresponding USAGE BINARY storage width in bits (NORMATIVE).

should_encode_as_blank_when_zero

Determine whether a value should be encoded as all spaces under the COBOL BLANK WHEN ZERO clause.

validate_explicit_binary_width

Validate an explicit USAGE BINARY(n) byte-width declaration and return the equivalent bit width (NORMATIVE).