decimal

Documentation

Overview

Package decimal implements methods to encode and decode BCD.

BCD (Binary-Coded Decimal) is a sequence of bytes representing decimal digits of the encoded number (each byte has two decimal digits each encoded using 4-bit nibbles), so byte >> 4 is the first digit and byte & 0x0f is the second digit. The leftmost digit in the array is the most significant. The rightmost digit in the array is the least significant.

The first byte of the BCD array contains the first digit of the number, represented as follows:

|  4 bits           |  4 bits           |
   = 0x                = the 1st digit

(The first nibble contains 0 if the decimal number has an even number of digits). The last byte of the BCD array contains the last digit of the number and the final nibble, represented as follows:

|  4 bits           |  4 bits           |
   = the last digit    = nibble

The final nibble represents the number's sign: 0x0a, 0x0c, 0x0e, 0x0f stand for plus, 0x0b and 0x0d stand for minus.

Examples:

The decimal -12.34 will be encoded as 0xd6, 0x01, 0x02, 0x01, 0x23, 0x4d:

| MP_EXT (fixext 4) | MP_DECIMAL | scale | 1 | 2,3 | 4 (minus) | | 0xd6 | 0x01 | 0x02 | 0x01 | 0x23 | 0x4d |

The decimal 0.000000000000000000000000000000000010 will be encoded as 0xc7, 0x03, 0x01, 0x24, 0x01, 0x0c:

| MP_EXT (ext 8) | length | MP_DECIMAL | scale | 1 | 0 (plus) | | 0xc7 | 0x03 | 0x01 | 0x24 | 0x01 | 0x0c |

See also:

* MessagePack extensions https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/

* An implementation in C language https://github.com/tarantool/decNumber/blob/master/decPacked.c

Package decimal with support of Tarantool's decimal data type.

Decimal data type supported in Tarantool since 2.2.

Since: 1.7.0

See also:

* Tarantool MessagePack extensions https://www.tarantool.io/en/doc/latest/dev_guide/internals/msgpack_extensions/#the-decimal-type

* Tarantool data model https://www.tarantool.io/en/doc/latest/book/box/data_model/

* Tarantool issue for support decimal type https://github.com/tarantool/tarantool/issues/692

* Tarantool module decimal https://www.tarantool.io/en/doc/latest/reference/reference_lua/decimal/

Example

To enable support of decimal in msgpack with https://github.com/shopspring/decimal, import tarantool/decimal submodule.

server := "127.0.0.1:3013"
opts := tarantool.Opts{
	Timeout:       500 * time.Millisecond,
	Reconnect:     1 * time.Second,
	MaxReconnects: 3,
	User:          "test",
	Pass:          "test",
}
client, err := tarantool.Connect(server, opts)
if err != nil {
	log.Fatalf("Failed to connect: %s", err.Error())
}

spaceNo := uint32(524)

number, err := NewDecimalFromString("-22.804")
if err != nil {
	log.Fatalf("Failed to prepare test decimal: %s", err)
}

resp, err := client.Replace(spaceNo, []interface{}{number})
if err != nil {
	log.Fatalf("Decimal replace failed: %s", err)
}
if resp == nil {
	log.Fatalf("Response is nil after Replace")
}

log.Println("Decimal tuple replace")
log.Println("Error", err)
log.Println("Code", resp.Code)
log.Println("Data", resp.Data)

Index

• type Decimal
  • func NewDecimal(decimal decimal.Decimal) *Decimal
  • func NewDecimalFromString(src string) (result *Decimal, err error)
  • func (decNum *Decimal) MarshalMsgpack() ([]byte, error)
  • func (decNum *Decimal) UnmarshalMsgpack(b []byte) error

Examples

• Package

Types

type Decimal

type Decimal struct {
	decimal.Decimal
}

func NewDecimal

func NewDecimal(decimal decimal.Decimal) *Decimal

NewDecimal creates a new Decimal from a decimal.Decimal.

func NewDecimalFromString

func NewDecimalFromString(src string) (result *Decimal, err error)

NewDecimalFromString creates a new Decimal from a string.

func (*Decimal) MarshalMsgpack

func (decNum *Decimal) MarshalMsgpack() ([]byte, error)

func (*Decimal) UnmarshalMsgpack

func (decNum *Decimal) UnmarshalMsgpack(b []byte) error

Decimal values can be encoded to fixext MessagePack, where buffer has a fixed length encoded by first byte, and ext MessagePack, where buffer length is not fixed and encoded by a number in a separate field:

+--------+-------------------+------------+===============+ | MP_EXT | length (optional) | MP_DECIMAL | PackedDecimal | +--------+-------------------+------------+===============+