目錄
4.元素函數
羣、環、域的元素都存儲在element_t數據結構中。這種類型的變量在使用之前必須進行初始化，並且不再需要時要進行釋放（clear）。
使用element_函數必須謹慎。就像0作被除數對於整數沒有意義一樣，某些操作可能對特定元素沒有意義。例如，在環上，元素一般不能求逆。
另一個警告是，許多函數假設他們的參數來自於相同的環、羣或者域。不執行隱式的類型轉換。
對於調試構建，通過在包含pbc.h之前定義PBC_DEBUG來進行run-time檢查：
#define PBC_DEBUG
#include <pbc.h>
當PBC_DEBUG被定義時，以下的宏命令可用。通常他們會被空語句替換。
PBC_ASSERT(expr, msg), Macro: 如果expr賦值爲0，打印msg並退出。
PBC_ASSERT_MATCH2(a, b), Macro: 如果元素a和b來自不同的域則退出。
PBC_ASSERT_MATCH3(a, b, c), Macro: 如果元素a、b和c來自不同的域則退出。
4.1 元素初始化
當初始化一個元素時，它與代數結構相關聯，例如一個特定的有限域或者橢圓曲線。
我們用G1和G2表示pairing的輸入羣，用GT表示輸出羣。他們都是r階的，Zr表示以r爲摸的整數環。G1是較小的羣（基本域點上的羣）。對於對稱pairing，G1=G2。
void element_init_G1(element_t e, pairing_t pairing)
void element_init_G2(element_t e, pairing_t pairing)
void element_init_GT(element_t e, pairing_t pairing)
初始化e爲pairing上的羣G1、G2或GT上的元素。
void element_init_Zr(element_t e, pairing_t pairing)
初始化e爲pairing上的環Z_r上的元素。r是pairing中涉及的羣G1、G2和GT的階。
void element_init_same_as(element_t e, element_t e2)
初始化e爲e2元素所在的代數結構的一個元素。
void element_clear(element_t e)
釋放元素e所佔用的空間。當變量e不再需要時調用這個函數。
4.2.元素賦值
這些函數用於給元素賦值。當整數被賦值時，如果有意義，將被映射到代數結構（例如環和域）。
void element_set0(element_t e) // 將e設置爲0
void element_set1(element_t e) // 將e設置爲1
void element_set_si(element_t e, signed long int i) // 將e設置爲i
void element_set_mpz(element_t e, mpz_t z) // 將e設置爲z
void element_set(element_t e. element_t a) // 將e設置爲a
4.3.元素轉換
// 如果這樣操作有意義，將e轉換爲GMP整數z
void element_to_mpz(mpz_t z, element_t e)
從長度爲len個字節的緩衝區data中確定性的生成元素e
void element_from_hash(element_t e, void *data, int len)
4.4.元素的算數運算
除非另外有說明，所有的element_t函數參數都必須已經被初始化爲相同的代數結構。當其中一個函數期望其參數來自特定的代數結構時，會在函數名中體現。
加法和乘法函數在環和域中執行加法和乘法運算。而對於橢圓曲線上的羣（例如與pairing相關的G1和G2羣），加法和乘法代表羣操作（類似地，0和1代表單位元）。
相比之下，GT羣目前是作爲有限域上的子羣來實現的，因此GT只需要使用乘法運算。
// 設置n = a+b
void element_add(element_t n, element_t a, element_t b)
// 設置n = a-b
void element_sub(element_t n, element_t a, element_t b)
// 設置n = ab
void element_mul(element_t n, element_t a, element_t b)
// 設置n = az，即a+a+...+a, 其中z個a。
void element_mul_mpz(element_t n, element_t a, mpz_t z)
void element_mul_si(element_t n, element_t a, signed long int z)
void element_mul_zn(element_t c,element_t a, element_t z)
z必須整數模環的一個元素（即Zn for some n)。設置c= az，即a+a+...+a,其中z個a。
// 設置n = a/b
void element_div(element_t n, element_a, element_b)
// 設置n = a+a
void element_double(element_t n, element_t a)
// 設置n = a/2
void element_halve(element_t n, element_t a)
// 設置n = a^2(a的平方)
void element_square(element_t n, element_t a)
// 設置n = -a
void element_neg(element_t n, element_t a)
// 設置n爲a的逆
void element_invert(element_t n, element_t a)
4.5.元素的冪運算
冪函數和多冪函數。如果預先知道某個特定元素在將來會被多次求冪，那麼從長遠來看，可以通過先調用預處理函數來節省時間：
element_pp_t g_pp;
element_pp_init(g_pp, g);
element_pp_pow(h, pow1, g_pp); // h = g^pow1
element_pp_pow(h, pow2, g_pp); // h = g^pow2
element_pp_pow(h, pow3, g_pp); // h = g^pow3
element_pp_clear(g_pp);
void element_pow_mpz(element_t x, element_t a, mpz_t n)
設置x = a^n，即a * a * ... * a，其中有n個a。
void element_pow_zn(element_t x,element_t a, element_t n)
設置x = a^n，其中n是某個N的環Zn的元素（通常階是x所在的代數結構的階） 。
// 設置x = (a1^n1)(a2^n2)，並且通常比分別求冪要快
void element_pow2_mpz(element_t x,element_t a1, mpz_t n1, element_t a2, mpz_t n2)
// 同上，只是n的類型不同
void element_pow2_zn(element_t x, element_t a1, element_t n1, element_t a2, element_t n2)
// 設置x = (a1^n1)(a2^n2)(a3^n3),且速度比分別求冪要快
void element_pow3_mpz(element_t x, element_t a1, mpz_t n1, element_t a2, mpz_t n2, element_t a3, mpz_t n3)
// 同上
void element_pow3_zn(element_t x, element_t a1, element_t n1, element_t a2, element_t n2, element_t a3, element_t n3)
// 準備對一個元素求冪，並將預處理信息存在p中
void element_pp_init(element_pp_t p, element_t in)
// 當p不再需要後釋放p
void element_pp_clear(element_pp_t p)
// 將in求power冪並將結果存儲在power中，其中in是預先處理過的元素，即第二個參數預先調用過element_pp_init。
void element_pp_pow(element_t out, mpz_t power, element_pp_t p)
// 同上，power類型不同
void element_pp_pow_zn(element_t out, element_t power, element_pp_t p)
// 通過暴力計算x使，g^x = h，其中x屬於element_set_mpz()有意義的域
void element_dlog_brute_force(element_t x, element_t g, element_t h)
// 通過Pollard rho方法計算x，使g^ = h,其中x屬於element_set_mpz()有意義的域
void element_dlog_pollard_rho(element_t x, element_t g, element_t h)
4.6.元素比較
這類函數比較來自相同代數結構的元素。
// 如果n=1返回true
int element_is1(element_t n)
// n=0返回true
int element_is0(element_t n)
// 如果a和b相同則返回0，否則返回非零
int element_cmp(element_t a, element_t b)
// 如果a是完全平方數（二次剩餘）則返回非零，否則返回0
int element_is_sqr(element_t a)
int element_sgn(element_ a)
int element_sign(element_t a)
如果a是0那麼返回0。a不是0，其操作取決於代數結構，但是有屬性：element_sgn(a) = -element_sgn(-a)，element_sgn(a) = 0意味着有壓倒性的概率使a=0。
4.7.元素I/O
這類函數主要爲了使元素生成人類可讀的輸出。之後將討論元素與字節之間的轉換。
size_t element_out_str(FILE* stream, int base, element_t e)
以基數（進制）base將e輸出到流stream上，base必須在2-36之間。
int element_printf(const char *format)
int element_fprintf(FILE *stream, const char *format, ...)
int element_snprintf(char *buf, size_t size, const char *fmt, ...)
int element_vsnprintf(char *buf, size_t size, const char *fmt, va_list ap)
除了有用於element_t類型專門的轉換說明符B，和用於mpz_t的轉換說明符Y、Z之外，與printf族函數相同。例如，如果e是element_t類型，那麼element_printf("%B\n", e);會打印e的值爲人類可讀的形式到標準輸出。
int element_snprint(char *s, size_t n, element_t e)
將元素轉換爲人類友好的字符串。表現爲snprintf，但是每次只能對一個元素。
int element_set_str(element_t e, const char *s, int base)
以字符串s設置元素e，其中s是以null結尾（這裏應該只以'\0'結尾）的C風格字符串且是base進制。空格將被忽略。點的形式爲“ [x，y]”或“ O”，而多項式的形式爲“ [a0，...，an]”。返回讀取的字符數（不像GMP的 mpz_set_str）。
4.8.隨機元素
只適用於有限代數結構。對於多項式環和特徵零的域等的影響未定義。
PBC如何獲得隨機bit見6.1節。
void element_random(element_t e)
如果e屬於一個有限代數結構，那麼均勻地給e賦值隨機元素。
4.9.元素導入與導出
用於序列化和反序列化元素的函數。
// 返回元素e將要佔用的字節長度
int element_length_in_bytes(element_t e)
int element_to_bytes(unsigned char *data, element_t e)
將e轉換爲字節，將結果寫入緩衝區data中。佔用的字節數可以通過調用element_length_in_bytes()來確定。
// 從緩衝區data中讀取元素e，並且返回讀取的字節數
int element_from_bytes(element_t e, unsigned char *data)
// 假設e是橢圓曲線上的一個點。將e的x座標寫入到緩衝區data中
int element_to_bytes_x_only(unsigned char *data, element_t e)
int element_from_bytes_x_only(element_t e, unsigned char *data)
假設e是橢圓曲線上的一個點。將e設置爲一個點，其x座標用緩衝區data表示。這並不是唯一的。對於每個x座標，都存在兩個不同的點，至少對於PBC中的橢圓曲線。（它們互逆。）
// 假設e是橢圓曲線上的點，返回e的x座標需要佔用的字節長度
int element_length_in_bytes_x_only(element_t e)
// 如果可能，輸出元素e的一個壓縮形式到字節緩衝區data中。目前僅適用於橢圓曲線上的點。
int element_to_bytes_compressed(unsigned char *data, element_t e)
// 以字節數據緩衝區中元素的壓縮形式爲元素e賦值，目前僅實現了橢圓曲線上的點。
int element_from_bytes_compressed(element_t e, unsigned char *data)
// 返回以壓縮形式保存元素e需要佔用的字節數。目前僅適用於橢圓曲線上的點
int element_length_in_bytes_compressed(element_t e)
// 對於點，返回座標的數目。對於多項式，返回係數的數目。其它情況返回0
element_item_count(element_t e)
// 對於點，返回第n個座標，對於多項式，返回x^n的係數（n次項的係數），其它情況返回NULL.返回值指向的函數值可能被改變
element_t element_item(element_t e, int i)
// 等價於 element_item(a, 0)
element_t element_x(element_t a)
// 等價於 element_item(a, 1)
element_t element_y(element_t a)
注：刪除線部分是翻譯不通順或者可能有錯誤的地方。