diff mbox

manual: Rewrite the section on widths of integer types.

Message ID 20170727122226.9032-1-ricaljasan@pacific.net
State New
Headers show

Commit Message

Rical Jasan July 27, 2017, 12:22 p.m. UTC 
The manual contradicted itself by saying the number of bits in an
integer type needed to be computed, and then listing a number of
macros that later standards provided for exactly that.  The entire
section has been reworked to provide those macros first, while
preserving the documentation of CHAR_BIT and the associated examples
within that context.

	* manual/lang.texi
	(Computing the Width of an Integer Data Type): Rename section
	to "Width of an Integer Type".  Remove inaccurate statement
	regarding lack of C language facilities for determining width
	of integer types, and reorder content to improve flow and
	context of discussion.
---
 manual/lang.texi | 82 +++++++++++++++++++++++++++++---------------------------
 1 file changed, 42 insertions(+), 40 deletions(-)

Comments

Rical Jasan Aug. 10, 2017, 12:04 p.m. UTC | #1 
Ping

On 07/27/2017 05:22 AM, Rical Jasan wrote:
> The manual contradicted itself by saying the number of bits in an
> integer type needed to be computed, and then listing a number of
> macros that later standards provided for exactly that.  The entire
> section has been reworked to provide those macros first, while
> preserving the documentation of CHAR_BIT and the associated examples
> within that context.
> 
> 	* manual/lang.texi
> 	(Computing the Width of an Integer Data Type): Rename section
> 	to "Width of an Integer Type".  Remove inaccurate statement
> 	regarding lack of C language facilities for determining width
> 	of integer types, and reorder content to improve flow and
> 	context of discussion.
> ---
>  manual/lang.texi | 82 +++++++++++++++++++++++++++++---------------------------
>  1 file changed, 42 insertions(+), 40 deletions(-)
Florian Weimer Aug. 10, 2017, 4:32 p.m. UTC | #2 
On 07/27/2017 02:22 PM, Rical Jasan wrote:
> +A common reason that a program needs to know how many bits are in an
> +integer type is for using an array of @code{long int} as a bit vector.
> +You can access the bit at index @var{n} with:
> +
> +@smallexample
> +vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
> +@end smallexample
> +
> +@noindent
> +provided you define @code{LONGBITS} as the number of bits in a
> +@code{long int}.

This example should now use ULONG_WIDTH.  The type should be unsigned
long int, and the constant should be 1UL (not 1), to avoid shifting into
the sign position.

Thanks,
Florian
Rical Jasan Aug. 11, 2017, 3:36 a.m. UTC | #3 
On 08/10/2017 09:32 AM, Florian Weimer wrote:
> On 07/27/2017 02:22 PM, Rical Jasan wrote:
>> +A common reason that a program needs to know how many bits are in an
>> +integer type is for using an array of @code{long int} as a bit vector.
>> +You can access the bit at index @var{n} with:
>> +
>> +@smallexample
>> +vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
>> +@end smallexample
>> +
>> +@noindent
>> +provided you define @code{LONGBITS} as the number of bits in a
>> +@code{long int}.
> 
> This example should now use ULONG_WIDTH.  The type should be unsigned
> long int, and the constant should be 1UL (not 1), to avoid shifting into
> the sign position.

Thanks.  I left it generic, but had changed "The most common reason" to
"A common reason" because I wasn't 100% sure what the currently
recommended practice would be (and "the most common" seemed too
superlative regardless).

Committed.

Rical
diff mbox

Patch

diff --git a/manual/lang.texi b/manual/lang.texi
index 75af677dc9..f8e800c037 100644
--- a/manual/lang.texi
+++ b/manual/lang.texi
@@ -606,48 +606,17 @@  which give you this information in full detail.
 @end menu
 
 @node Width of Type
-@subsection Computing the Width of an Integer Data Type
+@subsection Width of an Integer Type
 @cindex integer type width
 @cindex width of integer type
 @cindex type measurements, integer
-
-The most common reason that a program needs to know how many bits are in
-an integer type is for using an array of @code{long int} as a bit vector.
-You can access the bit at index @var{n} with
-
-@smallexample
-vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
-@end smallexample
-
-@noindent
-provided you define @code{LONGBITS} as the number of bits in a
-@code{long int}.
-
 @pindex limits.h
-There is no operator in the C language that can give you the number of
-bits in an integer data type.  But you can compute it from the macro
-@code{CHAR_BIT}, defined in the header file @file{limits.h}.
-
-@deftypevr Macro int CHAR_BIT
-@standards{C90, limits.h}
-This is the number of bits in a @code{char}.  POSIX.1-2001 requires
-this to be 8.
 
-You can compute the number of bits in any data type @var{type} like
-this:
-
-@smallexample
-sizeof (@var{type}) * CHAR_BIT
-@end smallexample
-@end deftypevr
-
-That expression includes padding bits as well as value and sign bits.
-On all systems supported by @theglibc{}, standard integer types other
-than @code{_Bool} do not have any padding bits.  TS 18661-1:2014
-defines additional macros for the width of integer types (the number
-of value and sign bits); these macros can also be used in @code{#if}
-preprocessor directives, whereas @code{sizeof} cannot.  The following
-macros are defined in @file{limits.h}.
+TS 18661-1:2014 defines macros for the width of integer types (the
+number of value and sign bits).  One benefit of these macros is they
+can be used in @code{#if} preprocessor directives, whereas
+@code{sizeof} cannot.  The following macros are defined in
+@file{limits.h}.
 
 @vtable @code
 @item CHAR_WIDTH
@@ -662,7 +631,6 @@  macros are defined in @file{limits.h}.
 @itemx LLONG_WIDTH
 @itemx ULLONG_WIDTH
 @standards{ISO, limits.h}
-
 These are the widths of the types @code{char}, @code{signed char},
 @code{unsigned char}, @code{short int}, @code{unsigned short int},
 @code{int}, @code{unsigned int}, @code{long int}, @code{unsigned long
@@ -672,7 +640,7 @@  respectively.
 
 Further such macros are defined in @file{stdint.h}.  Apart from those
 for types specified by width (@pxref{Integers}), the following are
-defined.
+defined:
 
 @vtable @code
 @item INTPTR_WIDTH
@@ -683,12 +651,46 @@  defined.
 @itemx WCHAR_WIDTH
 @itemx WINT_WIDTH
 @standards{ISO, stdint.h}
-
 These are the widths of the types @code{intptr_t}, @code{uintptr_t},
 @code{ptrdiff_t}, @code{sig_atomic_t}, @code{size_t}, @code{wchar_t}
 and @code{wint_t}, respectively.
 @end vtable
 
+A common reason that a program needs to know how many bits are in an
+integer type is for using an array of @code{long int} as a bit vector.
+You can access the bit at index @var{n} with:
+
+@smallexample
+vector[@var{n} / LONGBITS] & (1 << (@var{n} % LONGBITS))
+@end smallexample
+
+@noindent
+provided you define @code{LONGBITS} as the number of bits in a
+@code{long int}.
+
+Before @code{LONG_WIDTH} was a part of the C language, @code{CHAR_BIT}
+was used to compute the number of bits in an integer data type.
+
+@deftypevr Macro int CHAR_BIT
+@standards{C90, limits.h}
+This is the number of bits in a @code{char}.  POSIX.1-2001 requires
+this to be 8.
+@end deftypevr
+
+The number of bits in any data type @var{type} can be computed like
+this:
+
+@smallexample
+sizeof (@var{type}) * CHAR_BIT
+@end smallexample
+
+That expression includes padding bits as well as value and sign bits.
+On all systems supported by @theglibc{}, standard integer types other
+than @code{_Bool} do not have any padding bits.
+
+@strong{Portability Note:} One cannot actually easily compute the
+number of usable bits in a portable manner.
+
 @node Range of Type
 @subsection Range of an Integer Type
 @cindex integer type range