File 0831-Improve-documentation-of-the-binary-module.patch of Package erlang
From 0ac7a386fc95cb1967ab6461810de39dd66da5e5 Mon Sep 17 00:00:00 2001
From: Maria Scott <maria-12648430@hnc-agency.org>
Date: Wed, 23 Aug 2023 12:56:00 +0200
Subject: [PATCH] Improve documentation of the binary module
---
lib/stdlib/doc/src/binary.xml | 140 +++++++++-------------------------
1 file changed, 35 insertions(+), 105 deletions(-)
diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml
index 5ed7babc7b..00f22381d3 100644
--- a/lib/stdlib/doc/src/binary.xml
+++ b/lib/stdlib/doc/src/binary.xml
@@ -91,19 +91,16 @@
<func>
<name name="bin_to_list" arity="1" since="OTP R14B"/>
- <fsummary>Convert a binary to a list of integers.</fsummary>
- <desc>
- <p>Same as <c>bin_to_list(<anno>Subject</anno>, {0,byte_size(<anno>Subject</anno>)})</c>.</p>
- </desc>
- </func>
-
- <func>
<name name="bin_to_list" arity="2" since="OTP R14B"/>
+ <name name="bin_to_list" arity="3" since="OTP R14B"/>
<fsummary>Convert a binary to a list of integers.</fsummary>
+ <type name="part"/>
<desc>
<p>Converts <c><anno>Subject</anno></c> to a list of <c>byte()</c>s, each
- representing the value of one byte. <c>part()</c> denotes which part of
- the <c>binary()</c> to convert.</p>
+ representing the value of one byte. <c><anno>PosLen</anno></c> or alternatively
+ <c><anno>Pos</anno></c> and <c><anno>Len</anno></c> denote which part of the
+ <c><anno>Subject</anno></c> binary to convert. By default, the entire
+ <c><anno>Subject</anno></c> binary is converted.</p>
<p><em>Example:</em></p>
@@ -112,16 +109,9 @@
"rla"
%% or [114,108,97] in list notation.</code>
- <p>If <c><anno>PosLen</anno></c> in any way references outside the binary,
- a <c>badarg</c> exception is raised.</p>
- </desc>
- </func>
-
- <func>
- <name name="bin_to_list" arity="3" since="OTP R14B"/>
- <fsummary>Convert a binary to a list of integers.</fsummary>
- <desc>
- <p>Same as<c> bin_to_list(<anno>Subject</anno>, {<anno>Pos</anno>, <anno>Len</anno>})</c>.</p>
+ <p>If <c><anno>PosLen</anno></c> or alternatively <c><anno>Pos</anno></c> and
+ <c><anno>Len</anno></c> in any way reference outside the binary, a <c>badarg</c>
+ exception is raised.</p>
</desc>
</func>
@@ -160,18 +150,12 @@
<func>
<name name="copy" arity="1" since="OTP R14B"/>
- <fsummary>Create a duplicate of a binary.</fsummary>
- <desc>
- <p>Same as <c>copy(<anno>Subject</anno>, 1)</c>.</p>
- </desc>
- </func>
-
- <func>
<name name="copy" arity="2" since="OTP R14B"/>
<fsummary>Duplicate a binary <c>N</c> times and create a new.</fsummary>
<desc>
<p>Creates a binary with the content of <c><anno>Subject</anno></c>
- duplicated <c><anno>N</anno></c> times.</p>
+ duplicated <c><anno>N</anno></c> times. The default for <c><anno>N</anno></c>
+ is <c>1</c>.</p>
<p>This function always creates a new binary, even if <c><anno>N</anno> =
1</c>. By using <seemfa marker="#copy/1"><c>copy/1</c></seemfa>
@@ -187,29 +171,33 @@
large binaries are no longer used in any process, deliberate
copying can be a good idea.</p>
</note>
-
- <p>If <c><anno>N</anno></c> < <c>0</c>, a <c>badarg</c> exception is
- raised.</p>
</desc>
</func>
<func>
- <name name="decode_unsigned" arity="1" since="OTP R14B"/>
- <fsummary>Decode a whole binary into an integer of arbitrary size.
- </fsummary>
+ <name name="decode_hex" arity="1" since="OTP 24.0"/>
+ <fsummary>Decodes a hex encoded binary into a binary.</fsummary>
<desc>
- <p>Same as <c>decode_unsigned(<anno>Subject</anno>, big)</c>.</p>
+ <p>Decodes a hex encoded binary into a binary.</p>
+
+ <p><em>Example</em></p>
+
+ <code>
+1> binary:decode_hex(<<"66">>).
+<<"f">></code>
</desc>
</func>
<func>
+ <name name="decode_unsigned" arity="1" since="OTP R14B"/>
<name name="decode_unsigned" arity="2" since="OTP R14B"/>
<fsummary>Decode a whole binary into an integer of arbitrary size.
</fsummary>
<desc>
<p>Converts the binary digit representation, in big endian or little
endian, of a positive integer in <c><anno>Subject</anno></c> to an Erlang
- <c>integer()</c>.</p>
+ <c>integer()</c>. The default <c><anno>Endianness</anno></c> is
+ <c>big</c>.</p>
<p><em>Example:</em></p>
@@ -219,30 +207,6 @@
</desc>
</func>
- <func>
- <name name="encode_unsigned" arity="1" since="OTP R14B"/>
- <fsummary>Encode an unsigned integer into the minimal binary.</fsummary>
- <desc>
- <p>Same as <c>encode_unsigned(<anno>Unsigned</anno>, big)</c>.</p>
- </desc>
- </func>
-
- <func>
- <name name="encode_unsigned" arity="2" since="OTP R14B"/>
- <fsummary>Encode an unsigned integer into the minimal binary.</fsummary>
- <desc>
- <p>Converts a positive integer to the smallest possible
- representation in a binary digit representation, either big endian
- or little endian.</p>
-
- <p><em>Example:</em></p>
-
- <code>
-1> binary:encode_unsigned(11111111, big).
-<<169,138,199>></code>
- </desc>
- </func>
-
<func>
<name name="encode_hex" arity="1" since="OTP 24.0"/>
<fsummary>Encodes a binary into a hex encoded binary.</fsummary>
@@ -266,16 +230,20 @@
</func>
<func>
- <name name="decode_hex" arity="1" since="OTP 24.0"/>
- <fsummary>Decodes a hex encoded binary into a binary.</fsummary>
+ <name name="encode_unsigned" arity="1" since="OTP R14B"/>
+ <name name="encode_unsigned" arity="2" since="OTP R14B"/>
+ <fsummary>Encode an unsigned integer into the minimal binary.</fsummary>
<desc>
- <p>Decodes a hex encoded binary into a binary.</p>
+ <p>Converts a positive integer to the smallest possible
+ representation in a binary digit representation, either big endian
+ or little endian. The default <c><anno>Endianness</anno></c> is
+ <c>big</c>.</p>
- <p><em>Example</em></p>
+ <p><em>Example:</em></p>
<code>
-1> binary:decode_hex(<<"66">>).
-<<"f">></code>
+1> binary:encode_unsigned(11111111, big).
+<<169,138,199>></code>
</desc>
</func>
@@ -353,14 +321,6 @@
<func>
<name name="match" arity="2" since="OTP R14B"/>
- <fsummary>Search for the first match of a pattern in a binary.</fsummary>
- <desc>
- <p>Same as <c>match(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.
- </p>
- </desc>
- </func>
-
- <func>
<name name="match" arity="3" since="OTP R14B"/>
<fsummary>Search for the first match of a pattern in a binary.</fsummary>
<type name="part"/>
@@ -410,14 +370,6 @@
<func>
<name name="matches" arity="2" since="OTP R14B"/>
- <fsummary>Search for all matches of a pattern in a binary.</fsummary>
- <desc>
- <p>Same as <c>matches(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.
- </p>
- </desc>
- </func>
-
- <func>
<name name="matches" arity="3" since="OTP R14B"/>
<fsummary>Search for all matches of a pattern in a binary.</fsummary>
<type name="part"/>
@@ -463,7 +415,9 @@
<func>
<name name="part" arity="2" since="OTP R14B"/>
+ <name name="part" arity="3" since="OTP R14B"/>
<fsummary>Extract a part of a binary.</fsummary>
+ <type name="part"/>
<desc>
<p>Extracts the part of binary <c><anno>Subject</anno></c> described by
<c><anno>PosLen</anno></c>.</p>
@@ -489,15 +443,6 @@
</desc>
</func>
- <func>
- <name name="part" arity="3" since="OTP R14B"/>
- <fsummary>Extract a part of a binary.</fsummary>
- <desc>
- <p>Same as <c>part(<anno>Subject</anno>, {<anno>Pos</anno>,
- <anno>Len</anno>})</c>.</p>
- </desc>
- </func>
-
<func>
<name name="referenced_byte_size" arity="1" since="OTP R14B"/>
<fsummary>Determine the size of the binary pointed out by a subbinary.
@@ -564,13 +509,6 @@ store(Binary, GBSet) ->
<func>
<name name="replace" arity="3" since="OTP R14B"/>
- <fsummary>Replace bytes in a binary according to a pattern.</fsummary>
- <desc>
- <p>Same as <c>replace(<anno>Subject</anno>, <anno>Pattern</anno>, <anno>Replacement</anno>,[])</c>.</p>
- </desc>
- </func>
-
- <func>
<name name="replace" arity="4" since="OTP R14B"/>
<fsummary>Replace bytes in a binary according to a pattern.</fsummary>
<type_desc variable="OnePos">An integer() =< byte_size(<anno>Replacement</anno>)
@@ -614,14 +552,6 @@ store(Binary, GBSet) ->
<func>
<name name="split" arity="2" since="OTP R14B"/>
- <fsummary>Split a binary according to a pattern.</fsummary>
- <desc>
- <p>Same as <c>split(<anno>Subject</anno>, <anno>Pattern</anno>,
- [])</c>.</p>
- </desc>
- </func>
-
- <func>
<name name="split" arity="3" since="OTP R14B"/>
<fsummary>Split a binary according to a pattern.</fsummary>
<desc>
--
2.35.3
