コンテンツにスキップ

C言語/標準ライブラリ/stdbit.h

出典: フリー教科書『ウィキブックス(Wikibooks)』

ビット・バイトユーティリティー <stdbit.h>

[編集]

<stdbit.h> ヘッダーは、C言語の標準ライブラリの一部であり、バイトとビットの表現を扱うためのマクロ、型、および関数を定義します。主に整数型などの多くの型のバイトとビット表現を扱うために使用されます[1]

このヘッダーには、以下のようなマクロ、型、および関数が定義されています。

  • サイズや型に応じた最も有効なビットのインデックスと最も無効なビットのインデックスを計算するためのマクロや関数。
  • ビット操作に関連するマクロや関数。

また、__STDC_VERSION_STDBIT_H__ というマクロも定義されており、これは定数式で、値が 202311L に等しいです。これは、この機能が規格の一部として導入されたC言語のバージョンを示します。

ただし、 <stdbit.h> で宣言された汎用関数がマクロか外部リンケージを持つ識別子かは未規定(unspecified)です。マクロの定義が抑制されて実際の関数にアクセスするか、またはプログラムが汎用関数の名前で外部識別子を定義する場合、その動作は未規定(unspecified)です。

エンディアン

[編集]

複数バイトのスカラー型のバイト順序には、リトルエンディアンとビッグエンディアンという2つの一般的な方法があります。リトルエンディアンは、バイナリデータの格納や転送において、最も重要でないバイトが最初に配置され、残りのバイトが昇順に配置される形式です。つまり、最も重要でないバイトが最小のメモリアドレスに配置されます。一方、ビッグエンディアンは、バイナリデータの格納や転送において、最も重要なバイトが最初に配置され、残りのバイトが降順に配置される形式です。つまり、最も重要なバイトが最小のメモリアドレスに配置されます。他のバイト順序も可能です。

以下のマクロが定義されています。

  • __STDC_ENDIAN_LITTLE__:最も重要でないバイトが最初に配置され、残りが昇順に配置されるバイト順序を表すマクロで、整数定数式です。
  • __STDC_ENDIAN_BIG__:最も重要なバイトが最初に配置され、残りが降順に配置されるバイト順序を表すマクロで、整数定数式です。
  • __STDC_ENDIAN_NATIVE__:実行環境のバイト順序を表すマクロで、整数定数式です。__STDC_ENDIAN_NATIVE__ は、ビット精度の整数型、標準整数型、およびパディングビットを持たない拡張整数型に関して、実行環境のエンディアンを記述します。

__STDC_ENDIAN_NATIVE__ は以下のように定義されます。

  • もし実行環境がリトルエンディアンである場合、__STDC_ENDIAN_NATIVE____STDC_ENDIAN_LITTLE__ の値と等しい整数定数式に展開されます。
  • もし実行環境がビッグエンディアンである場合、__STDC_ENDIAN_NATIVE____STDC_ENDIAN_BIG__ の値と等しい整数定数式に展開されます。
  • もし実行環境がリトルエンディアンでもビッグエンディアンでもない場合、その他の実装定義済みのバイト順序があり、__STDC_ENDIAN_NATIVE____STDC_ENDIAN_LITTLE____STDC_ENDIAN_BIG__ の値と異なる整数定数式に展開されます。

このように、エンディアンに関する情報を提供するマクロが <stdbit.h> ヘッダーに定義されています。

先頭のゼロの数

[編集]

この部分では、先頭のゼロの数を計算するための関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_leading_zeros_uc(unsigned char value);
unsigned int stdc_leading_zeros_us(unsigned short value);
unsigned int stdc_leading_zeros_ui(unsigned int value);
unsigned int stdc_leading_zeros_ul(unsigned long value);
unsigned int stdc_leading_zeros_ull(unsigned long long value);
generic_return_type stdc_leading_zeros(generic_value_type value);

これらの関数は、値の最上位ビットから連続する0ビットの数を返します。また、型ごとに適切な関数が提供されており、unsigned charunsigned shortunsigned intunsigned longunsigned long long 型をサポートしています。さらに、ジェネリック関数 stdc_leading_zeros も提供されており、適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

先頭の1の数

[編集]

この部分では、先頭の1の数を計算するための関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_leading_ones_uc(unsigned char value);
unsigned int stdc_leading_ones_us(unsigned short value);
unsigned int stdc_leading_ones_ui(unsigned int value);
unsigned int stdc_leading_ones_ul(unsigned long value);
unsigned int stdc_leading_ones_ull(unsigned long long value);
generic_return_type stdc_leading_ones(generic_value_type value);

これらの関数は、値の最上位ビットから連続する1ビットの数を返します。先頭の0の数を計算する関数と同様に、型ごとに適切な関数が提供されており、ジェネリック関数 stdc_leading_ones も提供されています。

ジェネリック関数の引数 generic_value_type は、先頭の0の数を計算する関数と同様に、適切な型に基づいて入力値に対応する値を返します。

これらの関数は、ビット操作やデータのビットパターンの解析など、さまざまなアプリケーションで使用されることがあります。

末尾のゼロの数

[編集]

この部分では、末尾のゼロの数を計算するための関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_trailing_zeros_uc(unsigned char value);
unsigned int stdc_trailing_zeros_us(unsigned short value);
unsigned int stdc_trailing_zeros_ui(unsigned int value);
unsigned int stdc_trailing_zeros_ul(unsigned long value);
unsigned int stdc_trailing_zeros_ull(unsigned long long value);
generic_return_type stdc_trailing_zeros(generic_value_type value);

これらの関数は、値の最下位ビットから連続する0ビットの数を返します。また、型ごとに適切な関数が提供されており、unsigned charunsigned shortunsigned intunsigned longunsigned long long 型をサポートしています。さらに、ジェネリック関数 stdc_trailing_zeros も提供されており、適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

末尾の1の数

[編集]

この部分では、与えられた整数の末尾から連続する1ビットの数を数える関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_trailing_ones_uc(unsigned char value);
unsigned int stdc_trailing_ones_us(unsigned short value);
unsigned int stdc_trailing_ones_ui(unsigned int value);
unsigned int stdc_trailing_ones_ul(unsigned long value);
unsigned int stdc_trailing_ones_ull(unsigned long long value);
generic_return_type stdc_trailing_ones(generic_value_type value);

これらの関数は、指定された整数内の末尾から連続する1ビットの数を返します。各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

最初の先頭の0の位置

[編集]

この部分では、与えられた整数の中で最初に現れる0ビットの位置(最も上位のビットから数えて)を返す関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_first_leading_zero_uc(unsigned char value);
unsigned int stdc_first_leading_zero_us(unsigned short value);
unsigned int stdc_first_leading_zero_ui(unsigned int value);
unsigned int stdc_first_leading_zero_ul(unsigned long value);
unsigned int stdc_first_leading_zero_ull(unsigned long long value);
generic_return_type stdc_first_leading_zero(generic_value_type value);

これらの関数は、指定された整数の中で最初に現れる0ビットの位置を返します。最も上位のビットから数えて、最初の0ビットが見つかった位置に1を加えた値が返されます。もし0ビットが見つからない場合は、この関数は0を返します。

各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

最初の先頭の1の位置

[編集]

この部分では、与えられた整数の中で最初に現れる1ビットの位置(最も上位のビットから数えて)を返す関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_first_leading_one_uc(unsigned char value);
unsigned int stdc_first_leading_one_us(unsigned short value);
unsigned int stdc_first_leading_one_ui(unsigned int value);
unsigned int stdc_first_leading_one_ul(unsigned long value);
unsigned int stdc_first_leading_one_ull(unsigned long long value);
generic_return_type stdc_first_leading_one(generic_value_type value);

これらの関数は、指定された整数の中で最初に現れる1ビットの位置を返します。最も上位のビットから数えて、最初の1ビットが見つかった位置に1を加えた値が返されます。もし1ビットが見つからない場合は、この関数は0を返します。

各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

最初の末尾のゼロの位置

[編集]

この部分では、与えられた整数の最下位ビットから始まる最初のゼロの位置を探す関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_first_trailing_zero_uc(unsigned char value);
unsigned int stdc_first_trailing_zero_us(unsigned short value);
unsigned int stdc_first_trailing_zero_ui(unsigned int value);
unsigned int stdc_first_trailing_zero_ul(unsigned long value);
unsigned int stdc_first_trailing_zero_ull(unsigned long long value);
generic_return_type stdc_first_trailing_zero(generic_value_type value);

これらの関数は、指定された整数の最下位ビットから始まる最初のゼロの位置を返します。見つかった場合はその位置を、見つからなかった場合は0を返します。

また、ジェネリック関数 stdc_first_trailing_zero も提供されており、適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

ゼロの数

[編集]

この部分では、与えられた整数内の0ビットの総数を数える関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_count_zeros_uc(unsigned char value);
unsigned int stdc_count_zeros_us(unsigned short value);
unsigned int stdc_count_zeros_ui(unsigned int value);
unsigned int stdc_count_zeros_ul(unsigned long value);
unsigned int stdc_count_zeros_ull(unsigned long long value);
generic_return_type stdc_count_zeros(generic_value_type value);

これらの関数は、指定された整数内の0ビットの総数を返します。各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

1の数

[編集]

この部分では、与えられた整数内の1ビットの総数を数える関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_count_ones_uc(unsigned char value);
unsigned int stdc_count_ones_us(unsigned short value);
unsigned int stdc_count_ones_ui(unsigned int value);
unsigned int stdc_count_ones_ul(unsigned long value);
unsigned int stdc_count_ones_ull(unsigned long long value);
generic_return_type stdc_count_ones(generic_value_type value);

これらの関数は、指定された整数内の1ビットの総数を返します。各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

単一ビットのチェック

[編集]

この部分では、与えられた整数が単一の1ビットを持つかどうかをチェックする関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
bool stdc_has_single_bit_uc(unsigned char value);
bool stdc_has_single_bit_us(unsigned short value);
bool stdc_has_single_bit_ui(unsigned int value);
bool stdc_has_single_bit_ul(unsigned long value);
bool stdc_has_single_bit_ull(unsigned long long value);
bool stdc_has_single_bit(generic_value_type value);

これらの関数は、指定された整数が単一の1ビットを持つ場合にtrueを返し、それ以外の場合はfalseを返します。各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

これらの関数は、特定のビットが1であり、他のビットが0である場合に有用です。たとえば、特定のビットが有効であるかどうかを確認するために使用できます。

ビット幅

[編集]

この部分では、与えられた整数を格納するのに必要なビット数を計算する関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned int stdc_bit_width_uc(unsigned char value);
unsigned int stdc_bit_width_us(unsigned short value);
unsigned int stdc_bit_width_ui(unsigned int value);
unsigned int stdc_bit_width_ul(unsigned long value);
unsigned int stdc_bit_width_ull(unsigned long long value);
generic_return_type stdc_bit_width(generic_value_type value);

これらの関数は、指定された整数を格納するのに必要な最小のビット数を計算します。各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

これらの関数は、与えられた値が0の場合は0を返します。それ以外の場合は、値が0でない場合に必要な最小ビット数を計算して返します。計算式は1 + ⌊log2(value)⌋です。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

また、generic_return_type 型は、計算された結果を表すのに適した大きな符号なし整数型でなければなりません。

ビットの床

[編集]

この部分では、与えられた整数より大きくない最大の2の累乗を計算する関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned char stdc_bit_floor_uc(unsigned char value);
unsigned short stdc_bit_floor_us(unsigned short value);
unsigned int stdc_bit_floor_ui(unsigned int value);
unsigned long stdc_bit_floor_ul(unsigned long value);
unsigned long long stdc_bit_floor_ull(unsigned long long value);
generic_value_type stdc_bit_floor(generic_value_type value);

これらの関数は、与えられた整数より大きくない最大の2の累乗を計算します。各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

これらの関数は、与えられた値が0の場合は0を返します。それ以外の場合は、値より大きくない最大の2の累乗を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

ビットの天井

[編集]

この部分では、与えられた整数より小さくない最小の2の累乗を計算する関数が定義されています。以下のシグネチャで関数が提供されています。

#include <stdbit.h>
unsigned char stdc_bit_ceil_uc(unsigned char value);
unsigned short stdc_bit_ceil_us(unsigned short value);
unsigned int stdc_bit_ceil_ui(unsigned int value);
unsigned long stdc_bit_ceil_ul(unsigned long value);
unsigned long long stdc_bit_ceil_ull(unsigned long long value);
generic_value_type stdc_bit_ceil(generic_value_type value);

これらの関数は、与えられた整数より小さくない最小の2の累乗を計算します。各型に対応する関数とジェネリック関数が提供されており、ジェネリック関数は適切な型に基づいて入力値に対応する値を返します。

これらの関数は、与えられた値より小さくない最小の2の累乗を返します。

ジェネリック関数の引数 generic_value_type は、次のいずれかである場合に適切な値を返します。

  • 標準の符号なし整数型(boolを除く)。
  • 拡張符号なし整数型。
  • 標準または拡張整数型に一致するビット精度の符号なし整数型(boolを除く)。

なお、計算結果が指定された返り値の型に収まらない場合、その動作は未定義です。

歴史

[編集]

ヘッダー <stdbit.h> は、ISO/IEC 9899:2023(通称:C23)で追加される予定。

脚註

[編集]
  1. ^ N3096 working draft — April 1, 2023 ISO/IEC 9899:2023 (E). ISO/IEC JTC1/SC22/WG14. p. 302, §7.18 Bit and byte utilities. https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3096.pdf.