% limb manual
% u64_pack_trim(3)
% limb 0.1.0
% 2023-07-24

# NAME

u64_pack_trim, u64_unpack_trim - store/read an u64 into/from a byte array

# SYNOPSIS

    #include <limb/u64.h>

```pre hl
int u64_pack_trim(char *<em>dst</em>, size_t <em>dlen</em>, u64 <em>val</em>)
int u64_unpack_trim(u64 *<em>val</em>, const char *<em>sce</em>, size_t <em>slen</em>)
```

# DESCRIPTION

The `u64_pack_trim`() function will store the number `val` into the byte
array pointed by `dst` of length `dlen`, /trimming/ the "unneeded" bits, i.e.
all most significant bits set to zero need not be included.

In other words, it will only use as many bytes as necessary: The value is
stored in little-endian mode using only 7 bits per byte, with the last (most
significant) bit used as indicator whether or not an additional byte is
required.

Therefore the encoded number will take from only 1 up to 9 bytes.


The `u64_unpack_trim`() function performs the reverse, reading bytes from the
memory pointed by `sce` to get the encoded value, which will be placed into the
memory pointed by `val`.

It will therefore read from 1 up to 9 bytes, depending on the actual value.
However it will only ever read up to `slen` bytes.

# RETURN VALUE

The `u64_pack_trim`() function returns the number of bytes written to into `dst`
to pack `val` on success.
Otherwise - i.e. more than `dlen` bytes are necessary - it returns -1.

The `u64_unpack_trim`() function returns the number of bytes read from `sce` to
unpack `val` on success.
Otherwise - i.e. more than `slen` bytes were needed to be read - it returns -1.

# SEE ALSO

[u64_pack](3)