aboutsummaryrefslogtreecommitdiffstats
path: root/erts
diff options
context:
space:
mode:
authorPatrik Nyblom <pan@erlang.org>2010-05-10 16:27:58 +0200
committerBjörn Gustavsson <bjorn@erlang.org>2010-05-17 15:51:50 +0200
commit97ab480df55cf574ab42a87b6927ef5bba83000e (patch)
treea19bfd73bfb45d772c4fd54cad13c1050a6b59a3 /erts
parentdce00e268eb36048a729db9a2a9aebd4df0e7395 (diff)
downloadotp-97ab480df55cf574ab42a87b6927ef5bba83000e.tar.gz
otp-97ab480df55cf574ab42a87b6927ef5bba83000e.tar.bz2
otp-97ab480df55cf574ab42a87b6927ef5bba83000e.zip
Add documentation for binary module
Correct behaviour of copy/2 witn 0 copies.
Diffstat (limited to 'erts')
-rw-r--r--erts/doc/src/erlang.xml53
-rw-r--r--erts/emulator/beam/erl_bif_binary.c3
2 files changed, 55 insertions, 1 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index cd9bb85f5c..e90160dfd7 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -253,6 +253,54 @@ iolist() = [char() | binary() | iolist()]
</desc>
</func>
<func>
+ <name>binary_part(Subject, PosLen) -> binary()</name>
+ <fsummary>Extracts a part of a binary</fsummary>
+ <type>
+ <v>Subject = binary()</v>
+ <v>PosLen = {Start,Length}</v>
+ <v>Start = int()</v>
+ <v>Length = int()</v>
+ </type>
+ <desc>
+ <p>Extracts the part of the binary described by <c>PosLen</c>.</p>
+
+ <p>Negative length can be used to extract bytes at the end of a binary:</p>
+
+<code>
+1> Bin = &lt;&lt;1,2,3,4,5,6,7,8,9,10&gt;&gt;.
+2> binary_part(Bin,{byte_size(Bin), -5)).
+&lt;&lt;6,7,8,9,10&gt;&gt;
+</code>
+
+ <p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p>
+
+ <p><c>Start</c> is zero-based, i.e:</p>
+<code>
+1> Bin = &lt;&lt;1,2,3&gt;&gt;
+2> binary_part(Bin,{0,2}).
+&lt;&lt;1,2&gt;&gt;
+</code>
+
+ <p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p>
+
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>binary_part(Subject, Start, Length) -> binary()</name>
+ <fsummary>Extracts a part of a binary</fsummary>
+ <type>
+ <v>Subject = binary()</v>
+ <v>Start = int()</v>
+ <v>Length = int()</v>
+ </type>
+ <desc>
+ <p>The same as <c>binary_part(Subject, {Pos, Len})</c>.</p>
+
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
<name>binary_to_atom(Binary, Encoding) -> atom()</name>
<fsummary>Convert from text representation to an atom</fsummary>
<type>
@@ -318,6 +366,11 @@ iolist() = [char() | binary() | iolist()]
corresponding to the bytes from position <c>Start</c> to
position <c>Stop</c> in <c>Binary</c>. Positions in the
binary are numbered starting from 1.</p>
+
+ <note><p>This functions indexing style of using one-based indices for
+ binaries is deprecated. New code should use the functions in
+ the STDLIB module <c>binary</c> instead. They consequently
+ use the same (zero-based) style of indexing.</p></note>
</desc>
</func>
<func>
diff --git a/erts/emulator/beam/erl_bif_binary.c b/erts/emulator/beam/erl_bif_binary.c
index 0a40e28474..3e8480324c 100644
--- a/erts/emulator/beam/erl_bif_binary.c
+++ b/erts/emulator/beam/erl_bif_binary.c
@@ -2369,7 +2369,8 @@ static BIF_RETTYPE do_binary_copy(Process *p, Eterm bin, Eterm en)
goto badarg;
}
if (!n) {
- goto badarg;
+ Eterm res_term = erts_new_heap_binary(p,NULL,0,&bytes);
+ BIF_RET(res_term);
}
ERTS_GET_BINARY_BYTES(bin,bytes,bit_offs,bit_size);
if (bit_size != 0) {