The cl-intbytes Reference Manual

Table of Contents

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 2.3 "Robert April" on Tue Feb 20 08:07:06 2018 GMT+0.


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

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.


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

2 Systems

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


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

2.1 cl-intbytes

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

Description

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

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

Source

cl-intbytes.asd (file)

Components

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

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


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-intbytes.asd

Location

cl-intbytes.asd

Systems

cl-intbytes (system)


Previous: , Up: Lisp files   [Contents][Index]

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

Parent

cl-intbytes (system)

Location

src/cl-intbytes.lisp

Packages

cl-intbytes

Exported Definitions
Internal Definitions

uint->int (function)


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

3.2 Other


Previous: , Up: Other files   [Contents][Index]

3.2.1 cl-intbytes/README.md

Parent

cl-intbytes (system)

Location

README.md


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

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 (file)

Nickname

intbytes

Use List

common-lisp

Exported Definitions
Internal Definitions

uint->int (function)


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

5 Definitions

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


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

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)

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 (file)


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

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 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 (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   O  
Index Entry  Section

C
cl-intbytes.asd: The cl-intbytes<dot>asd file
cl-intbytes/README.md: The cl-intbytes/readme<dot>md file
cl-intbytes/src/cl-intbytes.lisp: The cl-intbytes/src/cl-intbytes<dot>lisp file

F
File, Lisp, cl-intbytes.asd: The cl-intbytes<dot>asd file
File, Lisp, cl-intbytes/src/cl-intbytes.lisp: The cl-intbytes/src/cl-intbytes<dot>lisp file
File, other, cl-intbytes/README.md: The cl-intbytes/readme<dot>md file

L
Lisp File, cl-intbytes.asd: The cl-intbytes<dot>asd file
Lisp File, cl-intbytes/src/cl-intbytes.lisp: The cl-intbytes/src/cl-intbytes<dot>lisp file

O
Other File, cl-intbytes/README.md: The cl-intbytes/readme<dot>md file

Jump to:   C   F   L   O  

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

A.2 Functions

Jump to:   F   I   O   U  
Index Entry  Section

F
Function, int->octets: Exported functions
Function, int32->octets: Exported functions
Function, int64->octets: Exported functions
Function, octets->int: Exported functions
Function, octets->int32: Exported functions
Function, octets->int64: Exported functions
Function, octets->uint: Exported functions
Function, octets->uint32: Exported functions
Function, octets->uint64: Exported functions
Function, uint->int: Internal functions

I
int->octets: Exported functions
int32->octets: Exported functions
int64->octets: Exported functions

O
octets->int: Exported functions
octets->int32: Exported functions
octets->int64: Exported functions
octets->uint: Exported functions
octets->uint32: Exported functions
octets->uint64: Exported functions

U
uint->int: Internal functions

Jump to:   F   I   O   U  

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

A.3 Variables


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

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-intbytes: The cl-intbytes system
cl-intbytes: The cl-intbytes package

P
Package, cl-intbytes: The cl-intbytes package

S
System, cl-intbytes: The cl-intbytes system

Jump to:   C   P   S