added a test case for xma

qse/include/qse/awk/std.h

@@ -1,5 +1,5 @@
 /*
- * $Id: std.h 336 2010-07-24 12:43:26Z hyunghwan.chung $
+ * $Id: std.h 340 2010-08-01 13:13:38Z hyunghwan.chung $
  *
     Copyright 2006-2009 Chung, Hyung-Hwan.
     This file is part of QSE.
@@ -82,21 +82,29 @@ extern "C" {
 #endif
 
 /**
- * The qse_awk_openstd() function creates an awk object.
+ * The qse_awk_openstd() function creates an awk object using the default 
+ * memory manager and primitive functions. Besides, it adds a set of
+ * standard intrinsic functions like atan, system, etc. Use this function
+ * over qse_awk_open() if you don't need finer-grained customization.
  */
 qse_awk_t* qse_awk_openstd (
-	qse_size_t xtnsize /**< size of extension in bytes */
+	qse_size_t xtnsize  /**< extension size in bytes */
 );
 
+/**
+ * The qse_awk_openstdwithmmgr() function creates an awk object with a 
+ * user-defined memory manager. It is equivalent to qse_awk_openstd(), 
+ * except that you can specify your own memory manager.
+ */
 qse_awk_t* qse_awk_openstdwithmmgr (
-	qse_mmgr_t* mmgr,
+	qse_mmgr_t* mmgr,    /**< memory manager */
-	qse_size_t  xtnsize
+	qse_size_t  xtnsize  /**< extension size in bytes */
 );
 
 /**
  * The qse_awk_getxtnstd() gets the pointer to extension space. 
  * Note that you must not call qse_awk_getxtn() for an awk object
- * created with qse_awk_openstd().
+ * created with qse_awk_openstd() and qse_awk_openstdwithmmgr().
  */
 void* qse_awk_getxtnstd (
 	qse_awk_t* awk

qse/include/qse/cmn/fio.h

@@ -1,5 +1,5 @@
 /*
- * $Id: fio.h 287 2009-09-15 10:01:02Z hyunghwan.chung $
+ * $Id: fio.h 340 2010-08-01 13:13:38Z hyunghwan.chung $
  *
     Copyright 2006-2009 Chung, Hyung-Hwan.
     This file is part of QSE.
@@ -21,6 +21,10 @@
 #ifndef _QSE_CMN_FIO_H_
 #define _QSE_CMN_FIO_H_
 
+/** @file
+ * This file defines a simple file I/O interface.
+ */
+
 #include <qse/types.h>
 #include <qse/macros.h>
 
@@ -127,15 +131,10 @@ extern "C" {
 
 QSE_DEFINE_COMMON_FUNCTIONS (fio)
 
-/****f* Common/qse_fio_open
+/**
- * NAME
+ * The qse_fio_open() function opens a file.
- *  qse_fio_open - open a file
- *
- * DESCRIPTION
  * To open a file, you should set the flags with at least one of
  * QSE_FIO_READ, QSE_FIO_WRITE, QSE_FIO_APPEND.
- *
- * SYNOPSIS
  */
 qse_fio_t* qse_fio_open (
 	qse_mmgr_t*       mmgr,
@@ -144,19 +143,17 @@ qse_fio_t* qse_fio_open (
 	int               flags,
 	int               mode
 );
-/******/
 
-/****f* Common/qse_fio_close
+/***
- * NAME
+ * The qse_fio_close() function closes a file.
- *  qse_fio_close - close a file
- *
- * SYNOPSIS
  */
 void qse_fio_close (
 	qse_fio_t* fio
 );
-/******/
 
+/***
+ * The qse_fio_close() function opens a file into @a fio.
+ */
 qse_fio_t* qse_fio_init (
 	qse_fio_t*        fio,
 	qse_mmgr_t*       mmgr,
@@ -165,115 +162,95 @@ qse_fio_t* qse_fio_init (
 	int               mode
 );
 
+/***
+ * The qse_fio_close() function finalizes a file by closing the handle 
+ * stored in @a fio.
+ */
 void qse_fio_fini (
 	qse_fio_t* fio
 );
 
-/****f* Common/qse_fio_gethandle
+/**
- * NAME
+ * The qse_fio_gethandle() function returns the native file handle.
- *  qse_fio_gethandle - get the native file handle
- * SYNOPSIS
  */
 qse_fio_hnd_t qse_fio_gethandle (
 	qse_fio_t* fio
 );
-/******/
 
-/****f* Common/qse_fio_sethandle
+/**
- * NAME
+ * The qse_fio_sethandle() function sets the file handle
- *  qse_fio_sethandle - set the file handle
- * WARNING
  * Avoid using this function if you don't know what you are doing.
  * You may have to retrieve the previous handle using qse_fio_gethandle()
  * to take relevant actions before resetting it with qse_fio_sethandle().
- * SYNOPSIS
  */
 void qse_fio_sethandle (
 	qse_fio_t* fio,
 	qse_fio_hnd_t handle
 );
-/******/
 
+/**
+ * The qse_fio_seek() function changes the current file position.
+ */
 qse_fio_off_t qse_fio_seek (
 	qse_fio_t*    fio,
 	qse_fio_off_t offset,
 	qse_fio_ori_t origin
 );
 
+/**
+ * The qse_fio_truncate() function truncates a file to @a size.
+ */
 int qse_fio_truncate (
 	qse_fio_t*    fio,
 	qse_fio_off_t size
 );
 
-/****f* Common/qse_fio_read
+/**
- * NAME
+ * The qse_fio_read() function reads data.
- *  qse_fio_read - read data
- * SYNOPSIS
  */
 qse_ssize_t qse_fio_read (
 	qse_fio_t*  fio,
 	void*       buf,
 	qse_size_t  size
 );
-/******/
 
-/****f* Common/qse_fio_write
+/**
- * NAME
+ * The qse_fio_write() function writes data.
- *  qse_fio_write - write data
- *
- * DESCRIPTION
  * If QSE_FIO_TEXT is used and the size parameter is (qse_size_t)-1,
  * the function treats the data parameter as a pointer to a null-terminated
  * string.
- * 
- * SYNOPSIS
  */
 qse_ssize_t qse_fio_write (
 	qse_fio_t*  fio,
 	const void* data,
 	qse_size_t  size
 );
-/******/
 
 
-/****f* Common/qse_fio_flush
+/**
- * NAME
+ * The qse_fio_flush() function flushes data. It is useful if #QSE_FIO_TEXT is 
- *  qse_fio_flush - flush data
+ * set for the file handle @a fio.
- *
- * DESCRIPTION
- *  The qse_fio_flush() function is useful if QSE_FIO_TEXT is used in 
- *  qse_fio_open ().
- *
- * SYNOPSIS
  */
 qse_ssize_t qse_fio_flush (
         qse_fio_t*    fio
 );
-/******/
 
-/****f* Common/qse_fio_chmod
+/**
- * NAME
+ * The qse_fio_chmod() function changes the file mode.
- *  qse_fio_chmod - change the file mode
- * SYNOPSIS
  */
 int qse_fio_chmod (
 	qse_fio_t* fio,
 	int        mode
 );
-/******/
 
-/****f* Common/qse_fio_sync
+/**
- * NAME
+ * The qse_fio_sync() function synchronizes file contents into storage media
- *  qse_fio_sync - synchronize file contents into storage media
+ * It is useful in determining the media error, without which qse_fio_close() 
- * DESCRIPTION
+ * may succeed despite such an error.
- *  The qse_fio_sync() function is useful in determining the media error,
- *  without which qse_fio_close() may succeed despite such an error.
- * SYNOPSIS
  */
 int qse_fio_sync (
 	qse_fio_t* fio
 );
-/******/
 
 
 /* TODO: qse_fio_lock, qse_fio_unlock */

qse/include/qse/cmn/sio.h

@@ -1,5 +1,5 @@
 /*
- * $Id: sio.h 318 2009-12-18 12:34:42Z hyunghwan.chung $
+ * $Id: sio.h 340 2010-08-01 13:13:38Z hyunghwan.chung $
  *
     Copyright 2006-2009 Chung, Hyung-Hwan.
     This file is part of QSE.
@@ -71,15 +71,21 @@ extern qse_sio_t* qse_sio_err;
 #define QSE_SIO_OUT qse_sio_out
 #define QSE_SIO_ERR qse_sio_err
 
+/**
+ * The qse_sio_open() fucntion creates a stream object.
+ */
 qse_sio_t* qse_sio_open (
-        qse_mmgr_t*       mmgr,
+	qse_mmgr_t*       mmgr,    /**< memory manager */
-	qse_size_t        ext,
+	qse_size_t        xtnsize, /**< extension size in bytes */
-	const qse_char_t* file,
+	const qse_char_t* file,    /**< file name */
-	int               flags
+	int               flags    /**< number OR'ed of #qse_sio_open_flag_t */
 );
 
+/**
+ * The qse_sio_close() function destroys a stream object.
+ */
 void qse_sio_close (
-	qse_sio_t* sio
+	qse_sio_t* sio  /**< stream */
 );
 
 qse_sio_t* qse_sio_init (
@@ -138,25 +144,23 @@ qse_ssize_t qse_sio_putsn (
 	qse_size_t        size
 );
 
-/****f* Common/qse_sio_getpos
+/**
- * NAME
+ * The get_sio_getpos() gets the current position in a stream.
- *  qse_sio_getpos - get the stream position
+ * Note that it may not return the desired postion due to buffering.
- *
+ * @return 0 on success, -1 on failure
- * WARNING
- *  The getpos() function may not return the desired postion because of 
- *  buffering.
- *
- * SYNOPSIS
  */
 int qse_sio_getpos (
-	qse_sio_t*     sio, 
+	qse_sio_t*     sio,  /**< stream */
-	qse_sio_pos_t* pos
+	qse_sio_pos_t* pos   /**< position */
 );
-/******/
 
+/**
+ * The qse_sio_setpos() changes the current position in a stream.
+ * @return 0 on success, -1 on failure
+ */
 int qse_sio_setpos (
-	qse_sio_t*    sio, 
+	qse_sio_t*    sio,   /**< stream */
-	qse_sio_pos_t pos
+	qse_sio_pos_t pos    /**< position */
 );
 
 #if 0

qse/include/qse/cmn/xma.h

@@ -21,6 +21,9 @@
 #ifndef _QSE_CMN_XMA_H_
 #define _QSE_CMN_XMA_H_
 
+/** @file
+ * This file defines an extravagant memory allocator. Why? It may be so.
+ */
 #include <qse/types.h>
 #include <qse/macros.h>
 
@@ -60,6 +63,9 @@ extern "C" {
 
 QSE_DEFINE_COMMON_FUNCTIONS (xma)
 
+/**
+ * The qse_xma_open() function creates a memory allocator.
+ */
 qse_xma_t* qse_xma_open (
 	qse_mmgr_t* mmgr,
 	qse_size_t  ext,

qse/include/qse/sed/sed.h

@@ -1,5 +1,5 @@
 /*
- * $Id: sed.h 328 2010-07-08 06:58:44Z hyunghwan.chung $
+ * $Id: sed.h 340 2010-08-01 13:13:38Z hyunghwan.chung $
  *
     Copyright 2006-2009 Chung, Hyung-Hwan.
     This file is part of QSE.
@@ -210,11 +210,11 @@ QSE_DEFINE_COMMON_FUNCTIONS (sed)
  * with the object. See #QSE_DEFINE_COMMON_FUNCTIONS() for qse_sed_getxtn().
  * When done, you should destroy the object with the qse_sed_close() function
  * to avoid any resource leaks including memory. 
- * @return A pointer to a stream editor on success, QSE_NULL on failure
+ * @return pointer to a stream editor on success, QSE_NULL on failure
  */
 qse_sed_t* qse_sed_open (
-	qse_mmgr_t*    mmgr, /**< a memory manager */
+	qse_mmgr_t*    mmgr,   /**< memory manager */
-	qse_size_t     xtn   /**< the size of extension in bytes */
+	qse_size_t     xtnsize /**< extension size in bytes */
 );
 
 /**

qse/include/qse/sed/std.h

@@ -37,21 +37,29 @@ extern "C" {
 #endif
 
 /**
- * The qse_sed_openstd() function creates a stream editor.
+ * The qse_sed_openstd() function creates a stream editor with the default
+ * memory manager and initialized it for other qse_sed_xxxxstd functions.
+ * @return pointer to a stream editor on success, QSE_NULL on failure.
  */
 qse_sed_t* qse_sed_openstd (
-	qse_size_t xtnsize /**< size of extension in bytes */
+	qse_size_t xtnsize  /**< extension size in bytes */
 );
 
+/**
+ * The qse_sed_openstdwithmmgr() function creates a stream editor with a 
+ * user-defined memory manager. It is equivalent to qse_sed_openstd(), 
+ * except that you can specify your own memory manager.
+ * @return pointer to a stream editor on success, QSE_NULL on failure.
+ */
 qse_sed_t* qse_sed_openstdwithmmgr (
-	qse_mmgr_t* mmgr,
+	qse_mmgr_t* mmgr,    /**< memory manager */
-	qse_size_t  xtnsize /**< size of extension in bytes */
+	qse_size_t  xtnsize  /**< extension size in bytes */
 );
 
 /**
  * The qse_sed_getxtnstd() gets the pointer to extension space. 
  * Note that you must not call qse_sed_getxtn() for a stream editor
- * created with qse_sed_openstd().
+ * created with qse_sed_openstd() and qse_sed_openstdwithmmgr().
  */
 void* qse_sed_getxtnstd (
 	qse_sed_t* sed
@@ -60,6 +68,7 @@ void* qse_sed_getxtnstd (
 /**
  * The qse_sed_compstd() function compiles a null-terminated sed script.
  * Call qse_sed_comp() for a length delimited script.
+ * @return 0 on success, -1 on failure
  */
 int qse_sed_compstd (
 	qse_sed_t*        sed,
@@ -71,6 +80,7 @@ int qse_sed_compstd (
  * over an input file @a infile and an output file @a outfile.
  * If @a infile is QSE_NULL, the standard console input is used.
  * If @a outfile is QSE_NULL, the standard console output is used.
+ * @return 0 on success, -1 on failure
  */
 int qse_sed_execstd (
 	qse_sed_t*        sed,

qse/lib/cmn/sio.c

@@ -1,5 +1,5 @@
 /*
- * $Id: sio.c 287 2009-09-15 10:01:02Z hyunghwan.chung $
+ * $Id: sio.c 340 2010-08-01 13:13:38Z hyunghwan.chung $
  *
     Copyright 2006-2009 Chung, Hyung-Hwan.
     This file is part of QSE.
@@ -141,7 +141,7 @@ qse_sio_t* qse_sio_out = &__sio_out;
 qse_sio_t* qse_sio_err = &__sio_err;
 
 qse_sio_t* qse_sio_open (
-	qse_mmgr_t* mmgr, qse_size_t ext, const qse_char_t* file, int flags)
+	qse_mmgr_t* mmgr, qse_size_t xtnsize, const qse_char_t* file, int flags)
 {
 	qse_sio_t* sio;
 
@@ -155,7 +155,7 @@ qse_sio_t* qse_sio_open (
 		if (mmgr == QSE_NULL) return QSE_NULL;
 	}
 
-	sio = QSE_MMGR_ALLOC (mmgr, QSE_SIZEOF(qse_sio_t) + ext);
+	sio = QSE_MMGR_ALLOC (mmgr, QSE_SIZEOF(qse_sio_t) + xtnsize);
 	if (sio == QSE_NULL) return QSE_NULL;
 
 	if (qse_sio_init (sio, mmgr, file, flags) == QSE_NULL)

qse/samples/cmn/xma.c

@@ -145,6 +145,58 @@ static int test4 ()
 	qse_xma_close (xma);
 	return 0;
 }
+static int test5 ()
+{
+	int i;
+	void* ptr[100];
+	qse_mmgr_t xmammgr = 
+	{
+		qse_xma_alloc,
+		qse_xma_realloc,
+		qse_xma_free,
+		QSE_NULL
+	};
+
+	qse_xma_t* xma1, * xma2, * xma3;
+
+	xma1 = qse_xma_open (QSE_NULL, 0, 2000000L);
+	if (xma1 == QSE_NULL) 
+	{
+		qse_printf (QSE_T("cannot open outer xma\n"));
+		return -1;
+	}
+
+	xmammgr.udd = xma1;
+
+	xma2 = qse_xma_open (&xmammgr, 0, 500000L);
+	if (xma1 == QSE_NULL) 
+	{
+		qse_printf (QSE_T("cannot open inner xma\n"));
+		return -1;
+	}
+
+	xma3 = qse_xma_open (&xmammgr, 0, 500000L);
+	if (xma1 == QSE_NULL) 
+	{
+		qse_printf (QSE_T("cannot open inner xma\n"));
+		return -1;
+	}
+
+	qse_xma_alloc (xma2, 10345);
+	qse_xma_alloc (xma3, 200301);
+	qse_xma_alloc (xma2, 20000);
+	ptr[0] = qse_xma_alloc (xma3, 40031);
+	qse_xma_alloc (xma3, 8);
+	qse_xma_realloc (xma3, ptr[0], 40000);
+
+	qse_xma_dump (xma3, qse_printf);
+	qse_xma_dump (xma2, qse_printf);
+	qse_xma_dump (xma1, qse_printf);
+
+	qse_xma_close (xma3);
+	qse_xma_close (xma2);
+	qse_xma_close (xma1);
+}
 
 int main ()
 {
@@ -152,5 +204,6 @@ int main ()
 	R (test2);
 	R (test3);
 	R (test4);
+	R (test5);
 	return 0;
 }