forked from simplegeo/zbase32
-
Notifications
You must be signed in to change notification settings - Fork 0
/
base32.h
122 lines (112 loc) · 5.22 KB
/
base32.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
/**
* copyright 2002-2007 Zooko "Zooko" Wilcox-O'Hearn
* mailto:[email protected]
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this work to deal in this work without
* restriction (including the rights to use, modify, distribute,
* sublicense, and/or sell copies).
*/
#ifndef __INCL_base32_h
#define __INCL_base32_h
static int const base32_vermaj = 0;
static int const base32_vermin = 9;
static int const base32_vermicro = 14;
static char const* const base32_vernum = "0.9.14";
#include "zstr.h" /* http://zooko.com/repos/libzstr */
#include "zutil.h" /* http://zooko.com/repos/libzutil */
#include <assert.h>
#include <stddef.h>
/**
* @param lengthinbits the length of the data in bits
*
* @return the length of the base-32 encoding of the data in characters
*
* @precondition lengthinbits must not be greater than
*/
size_t const b2alen(const size_t lengthinbits);
size_t const B2ALEN(const size_t lengthinbits);
#ifdef NDEBUG
#define b2alen(lengthinbits) ldivceil(lengthinbits, 5)
#define B2ALEN(lengthinbits) (LDIVCEIL((lengthinbits), 5))
#endif /* #ifdef NDEBUG */
/**
* @param os the data to be encoded in a zstr
*
* @return the contents of `os' in base-32 encoded form in a (newly allocated) zstr
*/
zstr b2a(const czstr os);
#ifndef NDEBUG
zstr B2A(const czstr os);
#else
#define B2A(x) b2a_l((x), (x).len*8)
#endif /* #ifndef NDEBUG */
/**
* @param cs the base-32 encoded data (a string)
*
* @return the binary data that was encoded into `cs' (a string)
*/
zstr a2b(const czstr cs);
#ifndef NDEBUG
zstr A2B(const czstr cs);
#else
#define A2B(x) a2b_l((x), (((x).len*5+3)/8)*8)
#endif /* #ifndef NDEBUG */
/**
* @param os the data to be encoded in a zstr
* @param lengthinbits the number of bits of data in `os' to be encoded
*
* b2a_l() will generate a base-32 encoded string big enough to encode lengthinbits bits. So for
* example if os is 2 bytes long and lengthinbits is 15, then b2a_l() will generate a 3-character-
* long base-32 encoded string (since 3 quintets is sufficient to encode 15 bits). If os is 2 bytes
* long and lengthinbits is 16 (or None), then b2a_l() will generate a 4-character string. Note
* that `b2a_l()' does not mask off unused least-significant bits, so for example if os is 2 bytes
* long and lengthinbits is 15, then you must ensure that the unused least-significant bit of os is
* a zero bit or you will get the wrong result. This precondition is tested by assertions if
* assertions are enabled.
*
* Warning: if you generate a base-32 encoded string with `b2a_l()', and then someone else tries to
* decode it by calling `a2b()' instead of `a2b_l()', then they will (probably) get a different
* string than the one you encoded! So only use `b2a_l()' when you are sure that the encoding and
* decoding sides know exactly which `lengthinbits' to use. If you do not have a way for the
* encoder and the decoder to agree upon the lengthinbits, then it is best to use `b2a()' and
* `a2b()'. The only drawback to using `b2a()' over `b2a_l()' is that when you have a number of
* bits to encode that is not a multiple of 8, `b2a()' can sometimes generate a base-32 encoded
* string that is one or two characters longer than necessary.
*
* @return the contents of `os' in base-32 encoded form in a (newly allocated) zstr
*
* On memory exhaustion, if Z_EXHAUST_EXIT is not defined, return a "null" zstr with .buf == NULL
* and .len == 0.
*/
zstr b2a_l(const czstr cs, const size_t lengthinbits);
zstr b2a_l_extra_Duffy(const czstr cs, const size_t lengthinbits);
/**
*
* @param lengthinbits the number of bits of data in encoded into `cs'
*
* a2b_l() will return a result big enough to hold lengthinbits bits. So for example if cs is
* 4 characters long (encoding at least 15 and up to 20 bits) and lengthinbits is 16, then a2b_l()
* will return a string of length 2 (since 2 bytes is sufficient to store 16 bits). If cs is
* 4 characters long and lengthinbits is 20, then a2b_l() will return a string of length 3 (since
* 3 bytes is sufficient to store 20 bits). Note that `b2a_l()' does not mask off unused least-
* significant bits, so for example if cs is 4 characters long and lengthinbits is 17, then you must
* ensure that all three of the unused least-significant bits of cs are zero bits or you will get
* the wrong result. This precondition is tested by assertions if assertions are enabled.
* (Generally you just require the encoder to ensure this consistency property between the least
* significant zero bits and value of `lengthinbits', and reject strings that have a length-in-bits
* which isn't a multiple of 8 and yet don't have trailing zero bits, as improperly encoded.)
*
* Please see the warning in the documentation of `b2a_l()' regarding the use of `b2a()' versus
* `b2a_l()'.
*
* @return a newly allocated zstr containing the data encoded in `cs'
*
* @precondition `cs' must be possibly base32 encoded data.: could_be_base32_encoded_l(cs, lengthinbits)
*
* On memory exhaustion, if Z_EXHAUST_EXIT is not defined, return a "null" zstr with .buf == NULL
* and .len == 0.
*/
zstr a2b_l(const czstr cs, const size_t lengthinbits);
zstr a2b_l_very_Duffy(const czstr cs, const size_t lengthinbits);
#endif /* #ifndef __INCL_base32_h */