Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve documentation of the binary module #7585

Merged
merged 1 commit into from
Aug 29, 2023
Merged

Improve documentation of the binary module #7585

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 35 additions & 105 deletions lib/stdlib/doc/src/binary.xml
View file
Open in desktop
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
Loading