Skip to content

Commit

Permalink
Improve documentation of the binary module
Browse files Browse the repository at this point in the history
  • Loading branch information
@Maria-12648430
Maria-12648430 committed Aug 23, 2023
1 parent dec8215 commit 0ac7a38
Showing 1 changed file with 35 additions and 105 deletions.
140 changes: 35 additions & 105 deletions lib/stdlib/doc/src/binary.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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>

Expand Down Expand Up @@ -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>
Expand All @@ -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> &lt; <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(&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>
<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>

Expand All @@ -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).
&lt;&lt;169,138,199&gt;&gt;</code>
</desc>
</func>

<func>
<name name="encode_hex" arity="1" since="OTP 24.0"/>
<name name="encode_hex" arity="2" since="OTP 26.0"/>
Expand All @@ -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(&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>

Expand Down Expand Up @@ -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"/>
Expand Down Expand Up @@ -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"/>
Expand Down Expand Up @@ -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>
Expand All @@ -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.
Expand Down Expand Up @@ -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() =&lt; byte_size(<anno>Replacement</anno>)
Expand Down Expand Up @@ -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>
Expand Down

0 comments on commit 0ac7a38

Please sign in to comment.