Skip to content
Newer
Older
100644 128 lines (92 sloc) 4.31 KB
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
1 EEP: 4
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
2 Title: New BIFs for bit-level binaries (bit strings)
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
3 Version: $Revision$
4 Last-Modified: $Date$
5 Author: Per Gustafsson
6 Status: Draft
7 Type: Standards Track
8 Content-Type: text/x-rst
9 Created: 10-Aug-2007
10 Erlang-Version: R12B-0
11 Post-History:
12
13 Abstract
14 ========
15
16 This EEP describes the introduction of bit level binaries to the
17 Erlang programming language. They can be constructed and manipulated
18 using the bit syntax and a new set of BIFs which operate on bit-level
19 binaries. These new BIFs are introduced in order to not alter the semantics of
20 existing BIFs which operate on binaries, but instead implement similar
21 operations for bit level binaries using new BIFs.
22
23 Definitions
24 ===========
25
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
26 A bit-level binary in this document called a *bit string* is a sequence of
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
27 bits of any length. A *binary* on the other hand is a sequence of bits
28 where the number of bits is evenly divisible by eight. These
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
29 definitions implies that any binary is also a bit string.
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
30
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
31 Manipulating bit strings using the bit syntax
da8e5c5 @RaimoNiskanen Fixed a heading underline that gave warning.
RaimoNiskanen authored
32 =============================================
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
33
34 A bit syntax expression:
35
36 ``<<Seg1,...,SegN>>``
37
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
38 Evaluates to a bit string, if the sum of the sizes of all segments in the
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
39 expression is divisible by eight the result is also a
40 binary. Previously such expression could only evaluate to binaries and
41 a runtime error was raised if this was not the case.
42
43 With this extension the expression ``Bin = <<1:9>>`` which previously caused a
44 runtime error now creates a 9-bit binary. To be able to use this
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
45 bit string to build a new bigger bit string we can write:
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
46
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
47 ``<<Bin/bitstring, 0:1>>``
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
48
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
49 Note the use of bitstring as the type. This expands to binary-unit:1 where as
50 the binary type would have expanded to binary-unit:8. Since bitstring is a long
51 word to write in a binary pattern there is an alias *bits* which is used in the
52 rest of this proposal, similarily for binary there is a shorthand *bytes*.
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
53
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
54 To match out a bit-level binary we also use the bit string type as in ::
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
55
56 case Bin of
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
57 <<1:1,Rest/bits>> -> Rest;
58 <<0:1,_/bits>> -> 0
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
59 end
60
61 This allows us to avoid situations were we would have to calculate
62 padding.
63
64
65 Specifications
66 ==============
67
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
68 ``bitsize/1::bitstring() -> integer()``
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
69
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
70 Returns the size of a bit string in bits. This BIF is allowed in guards.
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
71
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
72 ``list_to_bitstring/1::bitstring_list() -> bitstr()``
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
73
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
74 ``bitstring_list = cons(char() | bitstring()| bitstring_list(), bitstring() | bitstring_list) | nil()``
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
75
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
76 Concatenates the bit strings and chars in the bitstring_list to create a bit
77 string, each char becomes an 8-bit bit string.
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
78
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
79 ``is_bitstring/1::any() -> bool()``
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
80
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
81 Returns true if the argument is a bit string, otherwise it returns
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
82 false. This BIF is allowed in guards.
83
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
84 ``bitstring_to_list/1::bitstring() -> [char()|bitstring()]``
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
85
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
86 Turns a bit string into a list of characters and if the number of bits
87 in the bit string is not evenly divisible by eight the last element in
88 the list is a bit string consisting of the last 1-7 bits of the original
89 bit string.
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
90
91 Rationale
92 =========
93
94 The current definition of binaries makes it complicated to use the bit
95 syntax for decoding when the format is not byte oriented, because the
96 programmer is always forced to pad the binaries that he is using to
97 become a sequence of bytes. Allowing bit-level binaries alleviates
98 this problem.
99
100 The new BIFs proposed here are intended to give programmers the same
101 tools to manipulate bit-level binaries as they are used to when
102 manipulating binaries without changing the semantics of already
103 existing BIFs and maintain properties such as if this statement:
104
105 ``is_binary(X) andalso size(X) =:= 0``
106
107 evaluates to true then that implies that ``X = <<>>``.
108
109 Implementation
110 ==============
111
112 The extensions described in this document are either already
113 implemented in R11B-4, but protected by a compiler switched or can be
114 easily implemented.
115
116 Backwards Compatibility
117 =======================
118
119 This change will not be entirely backward compatible for example:
120 ``N=9, <<1:N>>`` would cause an error in the old system and now it would
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
121 evaluate to a bit string.
e085f33 @RaimoNiskanen Added EEPs 4..6
RaimoNiskanen authored
122
123 The new BIFs are intended to give the same expressiveness for handling
124 bit-level binaries as we have for ordinary binaries without changing
125 the semantics of the BIFs for binaries such as size/1,
126 binary_to_list/1, list_to_binary/1 etc.. This means that all such BIFs
a929c1a changed bitstr to bitstring or bits
Per Gustafsson authored
127 will throw an exception if their arguments contains bit strings.
Something went wrong with that request. Please try again.