From 037150979ff809df85757bd2b3f676e2e4c6be88 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Tue, 17 Jan 2012 12:28:32 +0100 Subject: Move types and specs from erl_bif_types.erl to modules --- lib/stdlib/doc/src/binary.xml | 226 +++++++++++++----------------------------- 1 file changed, 69 insertions(+), 157 deletions(-) (limited to 'lib/stdlib/doc/src/binary.xml') diff --git a/lib/stdlib/doc/src/binary.xml b/lib/stdlib/doc/src/binary.xml index 88ce77e0d0..06cfad0b0b 100644 --- a/lib/stdlib/doc/src/binary.xml +++ b/lib/stdlib/doc/src/binary.xml @@ -5,7 +5,7 @@
2009 - 2011 + 2012 Ericsson AB, All Rights Reserved @@ -77,41 +77,30 @@ - at(Subject, Pos) -> byte() + Returns the byte at a specific position in a binary - - Subject = binary() - Pos = integer() >= 0 - -

Returns the byte at position Pos (zero-based) in the binary - Subject as an integer. If Pos >= byte_size(Subject), +

Returns the byte at position Pos (zero-based) in the binary + Subject as an integer. If Pos >= byte_size(Subject), a badarg exception is raised.

 - bin_to_list(Subject) -> [byte()] + Convert a binary to a list of integers - - Subject = binary() - -

The same as bin_to_list(Subject,{0,byte_size(Subject)}).

+

The same as bin_to_list(Subject,{0,byte_size(Subject)}).

 - bin_to_list(Subject, PosLen) -> [byte()] + Convert a binary to a list of integers - - Subject = binary() - PosLen = part() - -

Converts Subject to a list of byte()s, each representing +

Converts Subject to a list of byte()s, each representing the value of one byte. The part() denotes which part of the binary() to convert. Example:

@@ -120,27 +109,19 @@ "rla" %% or [114,108,97] in list notation. -

If PosLen in any way references outside the binary, a badarg exception is raised.

+

If PosLen in any way references outside the binary, a badarg exception is raised.

 - bin_to_list(Subject, Pos, Len) -> [byte()] + Convert a binary to a list of integers - - Subject = binary() - Pos = integer() >= 0 - Len = integer() >= 0 - -

The same as bin_to_list(Subject,{Pos,Len}).

+

The same as bin_to_list(Subject,{Pos,Len}).

 - compile_pattern(Pattern) -> cp() + Pre-compiles a binary search pattern - - Pattern = binary() | [ binary() ] -

Builds an internal structure representing a compilation of a @@ -155,7 +136,7 @@

When a list of binaries is given, it denotes a set of alternative binaries to search for. I.e if [<<"functional">>,<<"programming">>] - is given as Pattern, this + is given as Pattern, this means "either <<"functional">> or <<"programming">>". The pattern is a set of alternatives; when only a single binary is given, the set has @@ -163,32 +144,25 @@

The list of binaries used for search alternatives shall be flat and proper.

-

If Pattern is not a binary or a flat proper list of binaries with length > 0, +

If Pattern is not a binary or a flat proper list of binaries with length > 0, a badarg exception will be raised.

 - copy(Subject) -> binary() + Creates a duplicate of a binary - - Subject = binary() - -

The same as copy(Subject, 1).

+

The same as copy(Subject, 1).

 - copy(Subject,N) -> binary() + Duplicates a binary N times and creates a new - - Subject = binary() - N = integer() >= 0 - -

Creates a binary with the content of Subject duplicated N times.

+

Creates a binary with the content of Subject duplicated N times.

-

This function will always create a new binary, even if N = +

This function will always create a new binary, even if N = 1. By using copy/1 on a binary referencing a larger binary, one might free up the larger binary for garbage collection.

@@ -201,32 +175,23 @@ large binaries are no longer used in any process, deliberate copying might be a good idea.

-

If N < 0, a badarg exception is raised.

+

If N < 0, a badarg exception is raised.

 - decode_unsigned(Subject) -> Unsigned + Decode a whole binary into an integer of arbitrary size - - Subject = binary() - Unsigned = integer() >= 0 - -

The same as decode_unsigned(Subject,big).

+

The same as decode_unsigned(Subject, big).

 - decode_unsigned(Subject, Endianess) -> Unsigned + Decode a whole binary into an integer of arbitrary size - - Subject = binary() - Endianess = big | little - Unsigned = integer() >= 0 -

Converts the binary digit representation, in big or little - endian, of a positive integer in Subject to an Erlang integer().

+ endian, of a positive integer in Subject to an Erlang integer().

Example:

@@ -237,22 +202,15 @@ - encode_unsigned(Unsigned) -> binary() + Encodes an unsigned integer into the minimal binary - - Unsigned = integer() >= 0 - -

The same as encode_unsigned(Unsigned,big).

+

The same as encode_unsigned(Unsigned, big).

 - encode_unsigned(Unsigned,Endianess) -> binary() + Encodes an unsigned integer into the minimal binary - - Unsigned = integer() >= 0 - Endianess = big | little -

Converts a positive integer to the smallest possible @@ -268,51 +226,39 @@ - first(Subject) -> byte() + Returns the first byte of a binary - - Subject = binary() - -

Returns the first byte of the binary Subject as an integer. If the - size of Subject is zero, a badarg exception is raised.

+

Returns the first byte of the binary Subject as an integer. If the + size of Subject is zero, a badarg exception is raised.

 - last(Subject) -> byte() + Returns the last byte of a binary - - Subject = binary() - -

Returns the last byte of the binary Subject as an integer. If the - size of Subject is zero, a badarg exception is raised.

+

Returns the last byte of the binary Subject as an integer. If the + size of Subject is zero, a badarg exception is raised.

 - list_to_bin(ByteList) -> binary() + Convert a list of integers and binaries to a binary - - ByteList = iodata() (see module erlang) -

Works exactly as erlang:list_to_binary/1, added for completeness.

 - longest_common_prefix(Binaries) -> integer() >= 0 + Returns length of longest common prefix for a set of binaries - - Binaries = [ binary() ] -

Returns the length of the longest common prefix of the - binaries in the list Binaries. Example:

+ binaries in the list Binaries. Example:

1> binary:longest_common_prefix([<<"erlang">>,<<"ergonomy">>]). @@ -321,19 +267,16 @@ 0 -

If Binaries is not a flat list of binaries, a badarg exception is raised.

+

If Binaries is not a flat list of binaries, a badarg exception is raised.

 - longest_common_suffix(Binaries) -> integer() >= 0 + Returns length of longest common suffix for a set of binaries - - Binaries = [ binary() ] -

Returns the length of the longest common suffix of the - binaries in the list Binaries. Example:

+ binaries in the list Binaries. Example:

1> binary:longest_common_suffix([<<"erlang">>,<<"fang">>]). @@ -347,35 +290,24 @@ - match(Subject, Pattern) -> Found | nomatch + Searches for the first match of a pattern in a binary - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Found = part() - -

The same as match(Subject, Pattern, []).

+

The same as match(Subject, Pattern, []).

 - match(Subject,Pattern,Options) -> Found | nomatch + + Searches for the first match of a pattern in a binary - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Found = part() - Options = [ Option ] - Option = {scope, part()} - -

Searches for the first occurrence of Pattern in Subject and +

Searches for the first occurrence of Pattern in Subject and returns the position and length.

-

The function will return {Pos,Length} for the binary - in Pattern starting at the lowest position in - Subject, Example:

+

The function will return {Pos, Length} for the binary + in Pattern starting at the lowest position in + Subject, Example:

1> binary:match(<<"abcde">>, [<<"bcde">>,<<"cd">>],[]). @@ -391,16 +323,16 @@

Summary of the options:

- {scope, {Start, Length}} + {scope, {Start, Length}}

Only the given part is searched. Return values still have - offsets from the beginning of Subject. A negative Length is - allowed as described in the TYPES section of this manual.

 + offsets from the beginning of Subject. A negative Length is + allowed as described in the DATA TYPES section of this manual.

If none of the strings in - Pattern is found, the atom nomatch is returned.

+ Pattern is found, the atom nomatch is returned.

-

For a description of Pattern, see +

For a description of Pattern, see compile_pattern/1.

If {scope, {Start,Length}} is given in the options @@ -412,32 +344,21 @@ - matches(Subject, Pattern) -> Found + Searches for all matches of a pattern in a binary - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Found = [ part() ] | [] - -

The same as matches(Subject, Pattern, []).

+

The same as matches(Subject, Pattern, []).

 - matches(Subject,Pattern,Options) -> Found + + Searches for all matches of a pattern in a binary - - Subject = binary() - Pattern = binary() | [ binary() ] | cp() - Found = [ part() ] | [] - Options = [ Option ] - Option = {scope, part()} - -

Works like match, but the Subject is searched until +

Works like match/2, but the Subject is searched until exhausted and a list of all non-overlapping parts matching - Pattern is returned (in order).

+ Pattern is returned (in order).

The first and longest match is preferred to a shorter, which is illustrated by the following example:

@@ -458,26 +379,22 @@

If none of the strings in pattern is found, an empty list is returned.

-

For a description of Pattern, see compile_pattern/1 and for a +

For a description of Pattern, see compile_pattern/1 and for a description of available options, see match/3.

-

If {scope, {Start,Length}} is given in the options such that - Start is larger than the size of Subject, Start + Length is - less than zero or Start + Length is larger than the size of - Subject, a badarg exception is raised.

+

If {scope, {Start,Length}} is given in the options such that + Start is larger than the size of Subject, Start + Length is + less than zero or Start + Length is larger than the size of + Subject, a badarg exception is raised.

 - part(Subject, PosLen) -> binary() + Extracts a part of a binary - - Subject = binary() - PosLen = part() - -

Extracts the part of the binary Subject described by PosLen.

+

Extracts the part of the binary Subject described by PosLen.

Negative length can be used to extract bytes at the end of a binary:

@@ -494,25 +411,20 @@ binary_part/3. Those BIFs are allowed in guard tests.

-

If PosLen in any way references outside the binary, a badarg exception +

If PosLen in any way references outside the binary, a badarg exception is raised.

 - part(Subject, Pos, Len) -> binary() + Extracts a part of a binary - - Subject = binary() - Pos = integer() >= 0 - Len = integer() >= 0 - -

The same as part(Subject, {Pos, Len}).

+

The same as part(Subject, {Pos, Len}).

 - referenced_byte_size(binary()) -> integer() >= 0 + Determines the size of the actual binary pointed out by a sub-binary -- cgit v1.2.3