The cl-intbytes Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-intbytes Reference Manual

This is the cl-intbytes Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 03:44:11 2022 GMT+0.

Table of Contents


1 Introduction

cl-intbytes - Convert between any-base integers and byte arrays interchangeably

Quicklisp Build Status Circle CI Coverage Status

Inspired by cl-mongo.

Usage

* (ql:quickload :cl-intbytes)
; => (:CL-INTBYTES)
* (use-package :intbytes)
; => T

For easy/ready encoding/decoding, use int32->octets/octets->int32 and int64->octets/octets->int64. All accept an &optional (start 0) value:

* (int32->octets 84215045)
; => #(5 5 5 5)
* (octets->int32 *)
; => 84215045
* (octets->int32 #(0 5 5 5 5) 1)
; => 84215045
* (int64->octets 578437695752307201)
; => #(1 2 3 4 5 6 7 8)
* (octets->int64 *)
; => 578437695752307201

For unsigned values, there are equivalent unsigned functions octets->uint32 and octets->uint64:

* (int32->octets -123)
; => #(133 255 255 255)
* (octets->uint32 *)
; => 4294967173
* (int64->octets -1)
; => #(255 255 255 255 255 255 255 255)
* (octets->uint64 *)
; => 18446744073709551615
* (octets->int64 **)
; => -1

You can create your own functions with int->octets and octets->int:

* (defun int16->octets (int16)
    (int->octets int16 2))
; => INT16->OCTETS
* (defun octets->int16 (array &optional (start 0))
    (octets->int array 2 start))
; => OCTETS->INT16
* (defun octets->uint16 (array &optional (start 0))
    (octets->uint array 2 start))
; => OCTETS->UINT16
* (int16->octets -3)
; => #(253 255)
* (octets->uint16 *)
; => 65533
* (octets->int16 **)
; => -3
* (octets->int16 #(0 253 255) 1)
; => -3

If you want to encode floats to bytes, use ieee-floats:

* (int64->octets (ieee-floats:encode-float64 1.5d0))
; => #(0 0 0 0 0 0 248 63)
* (ieee-floats:decode-float64 (octets->int64 *))
; => 1.5d0

Dependencies

This library depends on fast-io.

The test package uses the prove test library.

cl-intbytes is used by cl-BSON.

Installation

(ql:quickload :cl-intbytes)

Bugs

If you find any bug or inconsistency in the code, or if you find it too hard to use, please, feel free to open an issue.

Tests

This library is tested under SBCL and CCL Common Lisp implementations.

To run all the defined tests, use:

* (asdf:test-system :cl-intbytes)
; prints lots of (colorful) stuff...
; => T

Tests are ran with Travis CI and Circle CI using cl-travis, CIM, cl-coveralls and Roswell. Check it out!

Author

License

LLGPL.


2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-intbytes

Encode/decode any-base integers and byte arrays interchangeably.

Maintainer

André Miranda

Author

André Miranda

Contact

andremiramor@gmail.com

Home Page

https://github.com/EuAndreh/cl-intbytes

Source Control

(GIT git@github.com:EuAndreh/cl-intbytes.git)

Bug Tracker

https://github.com/EuAndreh/cl-intbytes/issues

License

LLGPL

Long Description

# cl-intbytes - Convert between any-base integers and byte arrays interchangeably
[![Quicklisp](http://quickdocs.org/badge/cl-intbytes.svg)](http://quickdocs.org/cl-intbytes/)
[![Build Status](https://travis-ci.org/EuAndreh/cl-intbytes.svg?branch=master)](https://travis-ci.org/EuAndreh/cl-intbytes)
[![Circle CI](https://circleci.com/gh/EuAndreh/cl-intbytes.svg?style=svg)](https://circleci.com/gh/EuAndreh/cl-intbytes)
[![Coverage Status](https://coveralls.io/repos/EuAndreh/cl-intbytes/badge.svg?branch=master)](https://coveralls.io/r/EuAndreh/cl-intbytes?branch=master)

Inspired by [cl-mongo](https://github.com/fons/cl-mongo/blob/bb1f807a17c960dc81bebd5e8a2df5d0886d422a/src/octets.lisp).

## Usage
“‘lisp
* (ql:quickload :cl-intbytes)
; => (:CL-INTBYTES)
* (use-package :intbytes)
; => T
“‘

For easy/ready encoding/decoding, use ‘int32->octets‘/‘octets->int32‘ and ‘int64->octets‘/‘octets->int64‘. All accept an ‘&optional (start 0)‘ value:
“‘lisp
* (int32->octets 84215045)
; => #(5 5 5 5)
* (octets->int32 *)
; => 84215045
* (octets->int32 #(0 5 5 5 5) 1)
; => 84215045
* (int64->octets 578437695752307201)
; => #(1 2 3 4 5 6 7 8)
* (octets->int64 *)
; => 578437695752307201
“‘

For unsigned values, there are equivalent unsigned functions ‘octets->uint32‘ and ‘octets->uint64‘:
“‘lisp
* (int32->octets -123)
; => #(133 255 255 255)
* (octets->uint32 *)
; => 4294967173
* (int64->octets -1)
; => #(255 255 255 255 255 255 255 255)
* (octets->uint64 *)
; => 18446744073709551615
* (octets->int64 **)
; => -1
“‘

You can create your own functions with ‘int->octets‘ and ‘octets->int‘:
“‘lisp
* (defun int16->octets (int16)
(int->octets int16 2))
; => INT16->OCTETS
* (defun octets->int16 (array &optional (start 0))
(octets->int array 2 start))
; => OCTETS->INT16
* (defun octets->uint16 (array &optional (start 0))
(octets->uint array 2 start))
; => OCTETS->UINT16
* (int16->octets -3)
; => #(253 255)
* (octets->uint16 *)
; => 65533
* (octets->int16 **)
; => -3
* (octets->int16 #(0 253 255) 1)
; => -3
“‘

If you want to encode floats to bytes, use [‘ieee-floats‘](https://github.com/marijnh/ieee-floats):
“‘lisp
* (int64->octets (ieee-floats:encode-float64 1.5d0))
; => #(0 0 0 0 0 0 248 63)
* (ieee-floats:decode-float64 (octets->int64 *))
; => 1.5d0
“‘
## Dependencies
This library depends on [fast-io](https://github.com/rpav/fast-io).

The test package uses the [prove](https://github.com/fukamachi/prove) test library.

cl-intbytes is used by [cl-BSON](https://github.com/EuAndreh/cl-BSON).

## Installation
“‘lisp
(ql:quickload :cl-intbytes)
“‘

## Bugs
If you find any bug or inconsistency in the code, or if you find it too hard to use, please, feel free to open an issue.

## Tests
This library is tested under [SBCL](http://www.sbcl.org/) and [CCL](http://ccl.clozure.com/) Common Lisp implementations.

To run all the defined tests, use:
“‘lisp
* (asdf:test-system :cl-intbytes)
; prints lots of (colorful) stuff...
; => T
“‘

Tests are ran with [Travis CI](https://travis-ci.org/EuAndreh/cl-intbytes) and [Circle CI](https://circleci.com/gh/EuAndreh/cl-intbytes) using [cl-travis](https://github.com/luismbo/cl-travis), [CIM](https://github.com/KeenS/CIM), [cl-coveralls](https://github.com/fukamachi/cl-coveralls) and [Roswell](https://github.com/snmsts/roswell). Check it out! ## Author
+ [André Miranda](https://github.com/EuAndreh)

## License
[LLGPL](https://tldrlegal.com/license/lisp-lesser-general-public-license#fulltext).

Version

0.1.0

Dependency

fast-io (system).

Source

cl-intbytes.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Next: , Previous: , Up: Files   [Contents][Index]

3.1 Lisp


3.1.1 cl-intbytes/cl-intbytes.asd

Source

cl-intbytes.asd.

Parent Component

cl-intbytes (system).

ASDF Systems

cl-intbytes.


3.1.2 cl-intbytes/src/cl-intbytes.lisp

Source

cl-intbytes.asd.

Parent Component

cl-intbytes (system).

Packages

cl-intbytes.

Public Interface
Internals

uint->int (function).


Previous: , Up: Files   [Contents][Index]

3.2 Static


Previous: , Up: Static   [Contents][Index]

3.2.1 cl-intbytes/README.md

Source

cl-intbytes.asd.

Parent Component

cl-intbytes (system).


4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-intbytes

This package defines general-purpose functions to encode integers into octets-vectors of given sizes and functions decode them back. Also, it defines functions for common encoding formats (‘INT32->OCTETS‘, ‘INT64->OCTETS‘) and functions for common decoding formats (‘OCTETS->INT32‘, ‘OCTETS->INT64‘, ‘OCTETS->UINT32‘, ‘OCTETS->UINT64‘).

Source

src/cl-intbytes.lisp.

Nickname

intbytes

Use List

common-lisp.

Public Interface
Internals

uint->int (function).


5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Public Interface


5.1.1 Ordinary functions

Function: int->octets (int n-bytes)

Writes all the bytes of a given ‘INT‘ into an array of type ’(UNSIGNED-BYTE 8) with length of ‘N-BYTES‘.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: int32->octets (int32)

Writes ‘INT32‘ into an array of type ’(UNSIGNED-BYTE 8) with 4 elements.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: int64->octets (int64)

Writes ‘INT64‘ into an array of type ’(UNSIGNED-BYTE 8) with 8 elements.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: octets->int (array n-bytes &optional start)

Interprets ‘N-BYTES‘ of a given ‘ARRAY‘ as an unsigned integer using ‘OCTETS->UINT‘, then converts to a signed value using ‘UINT->INT‘.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: octets->int32 (array &optional start)

Interprets 4 bytes of the given ‘ARRAY‘ as a signed integer, starting from ‘(START 0)‘.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: octets->int64 (array &optional start)

Inteprets 8 bytes of the given ‘ARRAY‘ as a signed integer, starting from ‘(START 0)‘.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: octets->uint (array n-bytes &optional start)

Interprets ‘N-BYTES‘ of a given ‘ARRAY‘ as an unsigned integer.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: octets->uint32 (array &optional start)

Inteprets 4 bytes of the given ‘ARRAY‘ as a unsigned integer, starting from ‘(START 0)‘.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.

Function: octets->uint64 (array &optional start)

Interprets 8 bytes of the given ‘ARRAY‘ as a unsigned integer, starting from ‘(START 0).

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.


5.2 Internals


Previous: , Up: Internals   [Contents][Index]

5.2.1 Ordinary functions

Function: uint->int (uint int-size)

Converts a given ‘UINT‘ into a signed int based on the given ‘INT-SIZE‘.

Package

cl-intbytes.

Source

src/cl-intbytes.lisp.


Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts


Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables