/*	
 *	clipbuf.h
 *
 *	ユーティリティ：リングバッファ
 *
 *	CLiP - Common Library for P/ECE
 *	Copyright (C) 2015 Naoyuki Sawa
 *
 *	* Tue Jan 06 21:26:41 JST 2015 Naoyuki Sawa
 *	- 新規作成。
 *	- 「ユーティリティ：リングバッファ」を、clipmisc.*⇒clipbuf.*へ分離しました。
 *	  使用頻度が低いので、無駄にリンクして容量が増加する事を防ぐためです。
 */
#ifndef __CLIP_BUF_H__
#define __CLIP_BUF_H__

/*****************************************************************************
 *	ユーティリティ：リングバッファ
 *****************************************************************************/

/* 2005/08/26現在の実装は、実際にはリング構造でなく、メモリ移動を使った簡易実装となっています。
 * もしも今後、速度性能が問題となった場合は、実際にリング構造を使って再実装する予定です。
 * その際に、内部処理を変更しても、プログラムインターフェイスは変化しないはずです。
 */
typedef struct _BUFFER {
	int capacity;	/* ストレージの総容量 */
	int size;	/* ストレージの使用量 */
	/*unsigned char storage[capacity]*/
} BUFFER;

/* バッファを作成します。
 * [in]
 *	capacity	ストレージサイズ。
 * [out]
 *	戻り値		作成したバッファ。
 * [note]
 *	* バッファの使用が終わったら、delete_buffer()で削除してください。
 */
BUFFER* create_buffer(int capacity);

/* バッファを削除します。
 * [in]
 *	buffer		削除するバッファ。
 */
void delete_buffer(BUFFER* buffer);

/* バッファを空にします。
 * [in]
 *	queue		空にするバッファ。
 */
void clear_buffer(BUFFER* buffer);

/* バッファにデータを書き込みます。
 * [in]
 *	buffer		バッファ。
 *	data		書き込むデータ。
 *	length		書き込むデータ長。
 * [out]
 *	戻り値		実際に書き込んだデータ長を返します。(0≦戻り値≦length)
 *			ストレージの空き容量が不足している場合、部分的な書き込みとなります。
 *			部分的な書き込みを行った場合、戻り値は、lengthよりも小さくなります。
 */
int write_buffer(BUFFER* buffer, const void* data/*[length]*/, int length);

/* バッファからデータを読み出します。
 * [in]
 *	buffer		バッファ。
 *	data		読み出したデータを格納するメモリ領域。
 *			NULLを指定すると、読み出したデータを破棄します。
 *	maxlength	読み出すデータの最大長。
 * [out]
 *	戻り値		実際に読み出したデータ長を返します。(0≦戻り値≦length)
 */
int read_buffer(BUFFER* buffer, void* data/*[maxlength]*/, int maxlength);

/* バッファのデータを参照します。
 * [in]
 *	buffer		バッファ。
 *	length		データ長を格納する変数へのポインタ。
 *			NULLを指定すると、データ長を格納しません。
 * [out]
 *	戻り値		ストレージの先頭アドレス。
 * [note]
 *	* この関数は、必ず成功します。
 *	  バッファが空の場合も、ストレージの先頭アドレスを返し、データ長に0を格納します。
 */
const void* peek_buffer(BUFFER* buffer, int* length);

/* バッファに書き込み可能な、最大データ長を求めます。
 * [in]
 *	buffer		バッファ。
 * [out]
 *	戻り値		最大データ長。
 */
int buffer_space(BUFFER* buffer);

#endif//__CLIP_BUF_H__
