Data functions

Defines
#define	rxv_spin_multi(d)   (!rxv_spin_string(d) && rxv_spin_size(d)>0)
#define	rxv_spin_single(d)   (!rxv_spin_multi(d))
#define	rxv_spin_strim2(s)   rxv_spin_strim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))
#define	rxv_spin_striml(s)   rxv_spin_strim((s),(RXV_SPIN_TRIM_LEFT))
#define	rxv_spin_strimr(s)   rxv_spin_strim((s),(RXV_SPIN_TRIM_RIGHT))
#define	rxv_spin_lower(s)
#define	rxv_spin_upper(s)
#define	rxv_spin_trim(s, w)
#define	rxv_spin_trim2(s)   rxv_spin_trim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))
#define	rxv_spin_triml(s)   rxv_spin_trim((s),(RXV_SPIN_TRIM_LEFT))
#define	rxv_spin_trimr(s)   rxv_spin_trim((s),(RXV_SPIN_TRIM_RIGHT))
Typedefs
typedef struct rxv_spin_data	rxv_spin_data_t
typedef struct rxv_spin_curs	rxv_spin_curs_t
Enumerations
enum	rxv_spin_trim_e { RXV_SPIN_TRIM_LEFT = 1, RXV_SPIN_TRIM_RIGHT }
Functions
rxv_spin_data_t *	rxv_spin_datum (apr_pool_t *pool, const char *str, rxv_spin_data_t *data)
rxv_spin_data_t *	rxv_spin_mdatum (apr_pool_t *pool, const char *str, apr_size_t size, rxv_spin_data_t *data)
char *	rxv_spin_string (rxv_spin_data_t *single)
apr_hash_t *	rxv_spin_guts (rxv_spin_data_t *rows)
apr_size_t	rxv_spin_size (rxv_spin_data_t *data)
rxv_spin_data_t *	rxv_spin_column (apr_pool_t *pool, const char *name, rxv_spin_data_t *data,...)
rxv_spin_data_t *	rxv_spin_parse (apr_pool_t *pool, const char *name, char *str, const char *sep, rxv_spin_data_t *data)
rxv_spin_data_t *	rxv_spin_array (apr_pool_t *pool, const char *name, apr_array_header_t *arr, rxv_spin_data_t *data)
rxv_spin_data_t *	rxv_spin_brigade (apr_pool_t *pool, const char *name, apr_bucket_brigade *bb, rxv_spin_data_t *data)
rxv_spin_data_t *	rxv_spin_null (apr_pool_t *pool, const char *name, apr_size_t size, rxv_spin_data_t *data)
rxv_spin_data_t *	rxv_spin_rows (apr_pool_t *pool, rxv_spin_data_t *data,...)
apr_size_t	rxv_spin_first (apr_pool_t *pool, rxv_spin_data_t *rows,...)
apr_size_t	rxv_spin_next (rxv_spin_curs_t *curs)
rxv_spin_data_t *	rxv_spin_this (rxv_spin_curs_t *curs)
rxv_spin_data_t *	rxv_spin_entry (rxv_spin_data_t *rows, const char *name, apr_size_t index)
rxv_spin_data_t *	rxv_spin_resize (rxv_spin_data_t *data, apr_size_t size)
rxv_spin_data_t *	rxv_spin_copy (apr_pool_t *pool, rxv_spin_data_t *src, rxv_spin_data_t *data)
char *	rxv_spin_slower (const char *str)
char *	rxv_spin_supper (const char *str)
char *	rxv_spin_strim (const char *str, rxv_spin_trim_e what)

---

Detailed Description

Data functions (mod_spin API)

---

Define Documentation

#define rxv_spin_multi

(

d

)

(!rxv_spin_string(d) && rxv_spin_size(d)>0)

check if data is of rows type

#define rxv_spin_single

(

d

)

(!rxv_spin_multi(d))

check if data is of single type

#define rxv_spin_strim2

(

s

)

rxv_spin_strim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))

trim string on both sides

#define rxv_spin_striml

(

s

)

rxv_spin_strim((s),(RXV_SPIN_TRIM_LEFT))

trim string on the left side

#define rxv_spin_strimr

(

s

)

rxv_spin_strim((s),(RXV_SPIN_TRIM_RIGHT))

trim string on the right side

#define rxv_spin_lower

(

s

)

Value:

((s)?(rxv_spin_single(s)                                            \
              ?rxv_spin_datum(NULL,rxv_spin_slower(rxv_spin_string(s)),(s)) \
              :NULL)                                                        \
            :NULL)

convert single to lowercase

#define rxv_spin_upper

(

s

)

Value:

((s)?(rxv_spin_single(s)                                            \
              ?rxv_spin_datum(NULL,rxv_spin_supper(rxv_spin_string(s)),(s)) \
              :NULL)                                                        \
            :NULL)

convert single to uppercase

#define rxv_spin_trim	(	s,
		w		)

Value:

((s)?(rxv_spin_single(s)                                               \
              ?rxv_spin_datum(NULL,rxv_spin_strim(rxv_spin_string(s),(w)),(s)) \
              :NULL)                                                           \
            :NULL)

trim single

#define rxv_spin_trim2

(

s

)

rxv_spin_trim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))

trim single on both sides

#define rxv_spin_triml

(

s

)

rxv_spin_trim((s),(RXV_SPIN_TRIM_LEFT))

trim single on the left side

#define rxv_spin_trimr

(

s

)

rxv_spin_trim((s),(RXV_SPIN_TRIM_RIGHT))

trim single on the right side

---

Typedef Documentation

typedef struct rxv_spin_data rxv_spin_data_t

data type

typedef struct rxv_spin_curs rxv_spin_curs_t

cursor type

---

Enumeration Type Documentation

enum rxv_spin_trim_e

Enumerator:

RXV_SPIN_TRIM_LEFT	trim whitespace on the left
RXV_SPIN_TRIM_RIGHT	trim whitespace on the right

---

Function Documentation

rxv_spin_data_t* rxv_spin_datum	(	apr_pool_t *	pool,
		const char *	str,
		rxv_spin_data_t *	data
	)

Create single data from from a nul terminated string. String is not copied.

Parameters:

	pool	Pool for allocation of data structure
	str	String to create data from
	data	Pointer to existing data or NULL to allocate anew

Returns:

rxv_spin_data_t pointer, structure allocated from the pool, NULL on error

Example:

 rxv_spin_datum(pool,"some string",NULL);

Remarks:

Pool can be NULL is data is not NULL.

rxv_spin_data_t* rxv_spin_mdatum	(	apr_pool_t *	pool,
		const char *	str,
		apr_size_t	size,
		rxv_spin_data_t *	data
	)

Create single data from from a counted string. Although the string is counted, it has to end with a nul character. This function will check for it and if it isn't there, it'll refuse to create the single. Keep in mind that the memory allocated for the counted string will be size + 1, meaning, if it isn't, the check for that nul character at the end may cause a segfault. String is not copied.

Parameters:

	pool	Pool for allocation of data structure
	str	String to create data from
	size	Size of the string, not counting the ending nul character
	data	Pointer to existing data or NULL to allocate anew

Returns:

rxv_spin_data_t pointer, structure allocated from the pool, NULL on error

Example:

 rxv_spin_mdatum(pool,"1234567890",10,NULL);

Remarks:

Pool can be NULL is data is not NULL.

char* rxv_spin_string

(

rxv_spin_data_t *

single

)

Get a nul terminated string from single data. String is not copied.

Parameters:

single

Single data

Returns:

nul terminated string, NULL on error

Example:

 rxv_spin_string(data);

apr_hash_t* rxv_spin_guts

(

rxv_spin_data_t *

rows

)

Get a hash table from rows data. Hash table is not copied.

Parameters:

rows

Rows data

Returns:

pointer to hash table NULL on error

Example:

 rxv_spin_guts(data);

Remarks:

Values in the hash table are apr_array_header_t pointers. The arrays contain rxv_spin_data_t (meaning: array->elts is rxv_spin_data_t pointer), so it is possible to use this mechanism to iterate through individual colums as well. If you do modify data this way, make sure all arrays contained in the hash have the same size, or you may get segfaults when you try to access the data. Keep in mind that although you can find out the size of the rxv_spin_data_t this way, it is still an opaque type that should be accessed through mod_spin API.

apr_size_t rxv_spin_size

(

rxv_spin_data_t *

data

)

Get the size of data. This does not include terminating nul byte for single. Number of rows is returned for rows.

Parameters:

data

Data

Returns:

size of single or rows or 0 on error

Example:

 rxv_spin_size(data);

rxv_spin_data_t* rxv_spin_column	(	apr_pool_t *	pool,
		const char *	name,
		rxv_spin_data_t *	data,
			...
	)

Create a column of data from other data. The data returned is of type rows. Data is not copied.

Parameters:

	pool	Pool for allocation of data structure
	name	Name of the column
	data	Pointer to existing data or NULL to allocate anew
	...	List of rxv_spin_data_t pointers, ending with NULL

Returns:

rxv_spin_data_t pointer, structures allocated from the pool, NULL on error

Example:

 rxv_spin_column(pool,"column1",NULL,
                 rxv_spin_rows(pool,NULL,x,y,z,NULL),
                 rxv_spin_rows(pool,NULL,u,v,w,NULL),
                 rxv_spin_single(pool,"some important data",NULL),
                 NULL);

rxv_spin_data_t* rxv_spin_parse	(	apr_pool_t *	pool,
		const char *	name,
		char *	str,
		const char *	sep,
		rxv_spin_data_t *	data
	)

Create a column of data by parsing a string. The data returned is of type rows. String to parse is NOT copied into pool storage before parsing, therefore, if you want to parse constant strings, you MUST copy them. This function actually chops up the string that is passed into it, so if the string is supposed to be used somewhere else, you may get a nasty surprise after calling this function. It is safer to make a copy.

Parameters:

	pool	Pool for allocation of data structure
	name	Name of the column
	str	String to parse
	sep	Separators to use when parsing
	data	Pointer to existing data or NULL to allocate anew

Returns:

rxv_spin_data_t pointer, structures allocated from the pool, NULL on error

Example:

 rxv_spin_parse(pool,"column1",
                apr_pstrdup(pool,"first str,second str/third str"),
                ",/",NULL);

rxv_spin_data_t* rxv_spin_array	(	apr_pool_t *	pool,
		const char *	name,
		apr_array_header_t *	arr,
		rxv_spin_data_t *	data
	)

Create a column of data from an array of nul terminated strings. The data returned is of type rows. Strings are not copied.

Parameters:

	pool	Pool for allocation of data structure
	name	Name of the column
	arr	Array of pointers to nul terminated strings
	data	Pointer to existing data or NULL to allocate anew

Returns:

rxv_spin_data_t pointer, structures allocated from the pool, NULL on error

Example:

 rxv_spin_array(pool,"column1",arr,NULL);

rxv_spin_data_t* rxv_spin_brigade	(	apr_pool_t *	pool,
		const char *	name,
		apr_bucket_brigade *	bb,
		rxv_spin_data_t *	data
	)

Create a column of data by reading a bucket brigade. The data returned is of type rows. All read data is copied into the storage allocated from the pool.

Parameters:

	pool	Pool for allocation of data structure
	name	Name of the column
	bb	Bucket brigade to read
	data	Pointer to existing data or NULL to allocate anew

Returns:

rxv_spin_data_t pointer, structures allocated from the pool, NULL on error

Example:

 rxv_spin_brigade(pool,"column1",bb,NULL);

rxv_spin_data_t* rxv_spin_null	(	apr_pool_t *	pool,
		const char *	name,
		apr_size_t	size,
		rxv_spin_data_t *	data
	)

Create an empty column of data.

Parameters:

	pool	Pool for allocation of data structures
	name	Name of the column
	size	Size (number of elements) of the column to create
	data	Pointer to existing data or NULL to allocate anew

Returns:

rxv_spin_data_t pointer, structures allocated from the pool, NULL on error

Example:

 rxv_spin_null(pool,"column1",rxv_spin_rws_len(r),NULL);

Remarks:

This function is useful for creating boilerplate columns.

rxv_spin_data_t* rxv_spin_rows	(	apr_pool_t *	pool,
		rxv_spin_data_t *	data,
			...
	)

Merge rows of data. If rows contain different array lengths, the biggest size will be used. Data is not copied.

Parameters:

	pool	Pool for allocation of data structure
	data	Pointer to existing data or NULL to allocate anew
	...	List of rxv_spin_data_t pointers, ending with NULL

Returns:

rxv_spin_data_t pointer, structures allocated from the pool, NULL on error

Example:

 rxv_spin_rows(pool,NULL,def,ghi,xyz,NULL);

Remarks:

Rows that appear later in the argument list override columns of the same name from earlier arguments. If columns need to have their size adjusted, empty elements will be pushed to the end of the arrays that columns point to. Note that give that data isn't copied, this resizing affects original columns too.

apr_size_t rxv_spin_first	(	apr_pool_t *	pool,
		rxv_spin_data_t *	rows,
			...
	)

Get first row of data.

Parameters:

	pool	Pool for allocation of data structure
	rows	Data to get the first row from
	...	List of column names (constant pointer to nul terminated string) and cursors (pointer to pointer of rxv_spin_curs_t), ending with NULL

Returns:

1 if successful, or 0 if no rows available

Example:

 rxv_spin_curs_t *c1=NULL,*c2=NULL;

 rxv_spin_first(pool,rows,"column1",&c1,"column2",&c2,NULL);

apr_size_t rxv_spin_next

(

rxv_spin_curs_t *

curs

)

Get next row of data.

Parameters:

curs

Pointer to the cursor

Returns:

current row number, counted from 1, or 0 if no more available

Example:

 for(r=rxv_spin_first(p,rws,"c1",&c1,NULL);r;r=rxv_spin_next(c1)){
   ...
 }

Remarks:

Note that it is sufficient to call rxv_spin_next() just once on any of the cursors that have been initialised through rxv_spin_first() to get the next row on all of them.

rxv_spin_data_t* rxv_spin_this

(

rxv_spin_curs_t *

curs

)

Get data from the cursor.

Parameters:

curs

Pointer to to the cursor

Returns:

rxv_spin_data_t pointer, NULL on error

Example:

 data=rxv_spin_this(curs);

rxv_spin_data_t* rxv_spin_entry	(	rxv_spin_data_t *	rows,
		const char *	name,
		apr_size_t	index
	)

Get an entry from rows of data.

Parameters:

	rows	Rows data
	name	Name of the column
	index	Row number, starting at 1

Returns:

rxv_spin_data_t pointer, NULL on error

Example:

 data=rxv_spin_entry(rows,"thiscolumn",3);

rxv_spin_data_t* rxv_spin_resize	(	rxv_spin_data_t *	data,
		apr_size_t	size
	)

Resize rows.

Parameters:

	pool	Pool for all memory allocation
	data	Data, rows or metadata type only
	size	New size

Returns:

resized data, NULL on error

Example:

 rxv_spin_resize(data,100);

Remarks:

If the requested size is smaller than original size, only the size field will be adjusted. If the requested size is larger, the structures containing pointers to data will be copied to the newly allocated memory space. If you rely on the old data (i.e. before resizing) in any way, you might create big problems, even security related ones.

rxv_spin_data_t* rxv_spin_copy	(	apr_pool_t *	pool,
		rxv_spin_data_t *	src,
		rxv_spin_data_t *	data
	)

Make a copy of data. The result is a full, deep copy (i.e. there is not a single byte in common with the original).

Parameters:

	pool	Pool for all memory allocation
	src	Data to copy, any type
	data	Pointer to existing data or NULL to allocate anew

Returns:

copy of the data, NULL on error

Example:

 rxv_spin_copy(pool,data,NULL);

Remarks:

If you're using this function on rows, the copying might take a while, as all memory is going to be allocated from the pool and all data and structures are going to be copied, down to the last string. In such a scenario, only use this function if you are planning on putting the result into context as a new item, or you need to keep the original data for some other reason.

char* rxv_spin_slower

(

const char *

str

)

Convert a string to lowercase. String pushed into the function is modified, no copy is made.

Parameters:

str

String to convert, nul terminated

Returns:

the same string in lowercase, NULL on error

Example:

 rxv_spin_slower(single);

char* rxv_spin_supper

(

const char *

str

)

Convert a string to uppercase. String pushed into the function is modified, no copy is made.

Parameters:

str

String to convert, nul terminated

Returns:

the same string in uppercase, NULL on error

Example:

 rxv_spin_supper(single);

char* rxv_spin_strim	(	const char *	str,
		rxv_spin_trim_e	what
	)

Trim whitespace from a string. No copy is made. You MUST copy the string if you're trimming constant strings.

Parameters:

	str	String
	what	Trim left: RXV_SPIN_TRIM_LEFT, trim right: RXV_SPIN_TRIM_RIGHT

Returns:

the same string trimmed, NULL on error

Example:

 rxv_spin_strim(apr_strdup(pool,"  string with whitespace   ",
                RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT);