view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

integers.

`id` is is the channel id within the file/stream. It relates to a definition
file. 0 indicates a meta data point which is JSON or other structured data,
which alters the processing of the file. 

Optionally a namespace can be used to provide dynamic ID generation. The ids
are mapped from a name/label/topic/ to an integer. Additional mapping messages
are inserted into the stream to facilitate this mapping at both ends.

`len` is the length of the payload. If the length is larger than 2^32 then it
must be fragmented at the 'application level'.

`payload` is the data.

`padding` Every record is padded to an 8 byte bounadary, with nulls, if nessicary

# API Usage

## Encoding and Decoding

### encode\_fastpack

```
encode_fastpack $buf, $inputs, $limit, $namespace
```

Encodes and array ref of an array refs `[time, ID, payload]` in to the buffer
`$buf`.  `$buf` is aliased internally, and not copied. All need encoded
messages are appended to the buffer.

If `limit` is supplied, and less then the length of the `$input`
array, only this number of inputs will be consumed.  Inputs consumed are
spliced out of the input array to allow the same array to be appended to
externally

If `$namespace` is provided, all messages are encoded assuming the id is name
and dynamically allocates an ID to the name space.  Note `$limit` must be
provided  (even if undefended) to use this argument.

Namespace if prevented from using `0`, `"0"`, or `undef` as names. Messages
with these names issue a warning.

If a `$namespace` is utilised, the ID/name  of the message can be any string.
It is mapped to an integer code. If the message is the first one to use the
ID, an extra message mapping the integer to the name (id becomes the integer
value, payload becomes the name), in inserted into the output. 

If the message has and ID of "0", and a payload with no length, this resets the
mappings in the namespace and is output as normal

### decode\_fastpack

```
decode_fastpack $buf,$output, $limit, $namespace
```

Decodes FastPack messages from `$buf`, consuming it as it progresses. `$buf`
is aliases so new messages can be added to it externally.

`$output` is a reference to an array to store the decoded messages. The
messages are decoded into  `[time, id, payload]`.

If `$limit` is provided, this is the maximum number of messages to decode
during a single call. If not provided or undef, 4096 is the default.

`$namespace` if provided, int  enables named ids. Decoded messages have the id
mapped to a name stored in the names space. If its the id has not been
encountered before, it uses the payload as the name to update the internal
mapping. This message is not sent to the output, as it is intended to update
the mapping only.

If the message has and ID of "0", and a payload with no length, this resets the
mappings in the namespace and is not forward past the decoder

## Namspaces

### create\_namespace

```
create_namespace
```

Returns a name space structure for named ids. Separate name spaces structure
are needed for encoding and decoding ends, even withing the same program.

### id\_for\_name

```
id_for_name $namespace, $name
```

Returns the integer id in `$namespace` for  `$name`. Useful for testing and
optimisation when multiple of the same messages are being encoded.

### name\_for\_id

```
name_for_id $namespace, $id
```

Returns the name id in `$namespace` for  `$id`. Useful for testing and
optimisation when multiple of the same messages are being encoded.

# AUTHOR

Ruben Westerberg, <drclaw@mac.com>

# REPOSITORTY and BUGS

Please report any bugs via git hub: [https://github.com/drclaw1394/perl-data-fastpack](https://github.com/drclaw1394/perl-data-fastpack)

# COPYRIGHT AND LICENSE

Copyright (C) 2025 by Ruben Westerberg

Licensed under MIT

# DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND