File 0831-Improve-documentation-of-the-binary-module... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0831-Improve-documentation-of-the-binary-module.patch of Package erlang (Revision ae7c61fa16cae062aca447553cd4f215)

Currently displaying revision ae7c61fa16cae062aca447553cd4f215 , Show latest

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>
- Same as <c>bin_to_list(<anno>Subject</anno>, {0,byte_size(<anno>Subject</anno>)})</c>.
- </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>
 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.
+ 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.
 
 Example:
 
@@ -112,16 +109,9 @@
 "rla"
 %% or [114,108,97] in list notation.</code>
 
- If <c><anno>PosLen</anno></c> in any way references outside the binary,
- a <c>badarg</c> exception is raised.
- </desc>
- </func>
-
- <func>
- <name name="bin_to_list" arity="3" since="OTP R14B"/>
- <fsummary>Convert a binary to a list of integers.</fsummary>
- <desc>
- Same as<c> bin_to_list(<anno>Subject</anno>, {<anno>Pos</anno>, <anno>Len</anno>})</c>.
+ 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.
 </desc>
 </func>
 
@@ -160,18 +150,12 @@
 
 <func>
 <name name="copy" arity="1" since="OTP R14B"/>
- <fsummary>Create a duplicate of a binary.</fsummary>
- <desc>
- Same as <c>copy(<anno>Subject</anno>, 1)</c>.
- </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>
 Creates a binary with the content of <c><anno>Subject</anno></c>
- duplicated <c><anno>N</anno></c> times.
+ duplicated <c><anno>N</anno></c> times. The default for <c><anno>N</anno></c>
+ is <c>1</c>.
 
 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.
 </note>
-
- If <c><anno>N</anno></c> &lt; <c>0</c>, a <c>badarg</c> exception is
- raised.
 </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>
- Same as <c>decode_unsigned(<anno>Subject</anno>, big)</c>.
+ Decodes a hex encoded binary into a binary.
+
+ Example
+
+ <code>
+1> binary:decode_hex(&lt;&lt;"66"&gt;&gt;).
+&lt;&lt;"f"&gt;&gt;</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>
 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>.
+ <c>integer()</c>. The default <c><anno>Endianness</anno></c> is
+ <c>big</c>.
 
 Example:
 
@@ -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>
- Same as <c>encode_unsigned(<anno>Unsigned</anno>, big)</c>.
- </desc>
- </func>
-
- <func>
- <name name="encode_unsigned" arity="2" since="OTP R14B"/>
- <fsummary>Encode an unsigned integer into the minimal binary.</fsummary>
- <desc>
- Converts a positive integer to the smallest possible
- representation in a binary digit representation, either big endian
- or little endian.
-
- Example:
-
- <code>
-1> binary:encode_unsigned(11111111, big).
-&lt;&lt;169,138,199&gt;&gt;</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>
- Decodes a hex encoded binary into a binary.
+ 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>.
 
- Example
+ Example:
 
 <code>
-1> binary:decode_hex(&lt;&lt;"66"&gt;&gt;).
-&lt;&lt;"f"&gt;&gt;</code>
+1> binary:encode_unsigned(11111111, big).
+&lt;&lt;169,138,199&gt;&gt;</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>
- Same as <c>match(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.
- 
- </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>
- Same as <c>matches(<anno>Subject</anno>, <anno>Pattern</anno>, [])</c>.
- 
- </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>
 Extracts the part of binary <c><anno>Subject</anno></c> described by
 <c><anno>PosLen</anno></c>.
@@ -489,15 +443,6 @@
 </desc>
 </func>
 
- <func>
- <name name="part" arity="3" since="OTP R14B"/>
- <fsummary>Extract a part of a binary.</fsummary>
- <desc>
- Same as <c>part(<anno>Subject</anno>, {<anno>Pos</anno>,
- <anno>Len</anno>})</c>.
- </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>
- Same as <c>replace(<anno>Subject</anno>, <anno>Pattern</anno>, <anno>Replacement</anno>,[])</c>.
- </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() =&lt; 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>
- Same as <c>split(<anno>Subject</anno>, <anno>Pattern</anno>,
- [])</c>.
- </desc>
- </func>
-
- <func>
 <name name="split" arity="3" since="OTP R14B"/>
 <fsummary>Split a binary according to a pattern.</fsummary>
 <desc>
-- 
2.35.3

Places

File 0831-Improve-documentation-of-the-binary-module.patch of Package erlang (Revision ae7c61fa16cae062aca447553cd4f215)

Places