Data manipulation functions


Data Structures

struct  rxv_spin_data
 Data structure. More...

Defines

#define RXV_SPIN_DATA_SGL   0x01
#define RXV_SPIN_DATA_RWS   0x02
#define RXV_SPIN_DATA_MTA   0xFF
#define RXV_SPIN_TRIM_LEFT   0x01
#define RXV_SPIN_TRIM_RIGHT   0x02
#define rxv_spin_single_trimboth(s)   rxv_spin_single_trim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))
#define rxv_spin_single_trimleft(s)   rxv_spin_single_trim((s),(RXV_SPIN_TRIM_LEFT))
#define rxv_spin_single_trimright(s)   rxv_spin_single_trim((s),(RXV_SPIN_TRIM_RIGHT))
#define rxv_spin_column_del(rows, key)   rxv_spin_column_set((rows),(key),NULL)
#define rxv_spin_str_trimboth(s)   rxv_spin_str_trim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))
#define rxv_spin_str_trimleft(s)   rxv_spin_str_trim((s),(RXV_SPIN_TRIM_LEFT))
#define rxv_spin_str_trimright(s)   rxv_spin_str_trim((s),(RXV_SPIN_TRIM_RIGHT))

Typedefs

typedef struct
rxv_spin_data 
rxv_spin_data_t

Functions

rxv_spin_data_trxv_spin_single (apr_pool_t *pool, const char *str)
char * rxv_spin_single_get (rxv_spin_data_t *single)
rxv_spin_data_trxv_spin_single_set (rxv_spin_data_t *single, const char *str)
rxv_spin_data_trxv_spin_single_mem (apr_pool_t *pool, const char *str, size_t size)
rxv_spin_data_trxv_spin_single_memset (rxv_spin_data_t *single, const char *str, size_t size)
rxv_spin_data_trxv_spin_single_tolower (rxv_spin_data_t *single)
rxv_spin_data_trxv_spin_single_toupper (rxv_spin_data_t *single)
rxv_spin_data_trxv_spin_single_trim (rxv_spin_data_t *single, unsigned char what)
rxv_spin_data_trxv_spin_meta (apr_pool_t *pool,...)
rxv_spin_data_trxv_spin_meta_vstr (apr_pool_t *pool,...)
rxv_spin_data_trxv_spin_meta_parse (apr_pool_t *pool, char *str, const char *sep)
rxv_spin_data_trxv_spin_meta_empty (apr_pool_t *pool, size_t size)
apr_hash_t * rxv_spin_meta_hash (apr_pool_t *pool, rxv_spin_data_t *data)
rxv_spin_data_trxv_spin_meta_mark (rxv_spin_data_t *data, size_t element)
rxv_spin_data_trxv_spin_meta_markeach (rxv_spin_data_t *data, size_t off, size_t step)
rxv_spin_data_trxv_spin_meta_select (rxv_spin_data_t *data, rxv_spin_data_t *select, apr_hash_t *hash)
rxv_spin_data_trxv_spin_rows (apr_pool_t *pool,...)
apr_hash_t * rxv_spin_rows_hash (apr_pool_t *pool, rxv_spin_data_t *rows, const char *column)
rxv_spin_data_trxv_spin_rows_mark (rxv_spin_data_t *rows, const char *column, size_t element)
rxv_spin_data_trxv_spin_rows_markeach (rxv_spin_data_t *rows, const char *column, size_t off, size_t step)
rxv_spin_data_trxv_spin_rows_select (rxv_spin_data_t *rows, rxv_spin_data_t *select, const char *column, const char *marker, apr_hash_t *hash)
rxv_spin_data_trxv_spin_column_get (apr_pool_t *pool, rxv_spin_data_t *rows, const char *key)
rxv_spin_data_trxv_spin_column_set (rxv_spin_data_t *rows, const char *key, rxv_spin_data_t *column)
rxv_spin_data_trxv_spin_resize (apr_pool_t *pool, rxv_spin_data_t *data, size_t size)
rxv_spin_data_trxv_spin_copy (apr_pool_t *pool, rxv_spin_data_t *data)
char * rxv_spin_str_tolower (const char *str)
char * rxv_spin_str_toupper (const char *str)
char * rxv_spin_str_trim (char *str, unsigned char what)

Detailed Description

Data manipulation functions (mod_spin API)

Define Documentation

#define RXV_SPIN_DATA_SGL   0x01

single data type (size limited string)

#define RXV_SPIN_DATA_RWS   0x02

rows data type (named columns, numbered rows)

#define RXV_SPIN_DATA_MTA   0xFF

metadata type (not used in rendering)

#define RXV_SPIN_TRIM_LEFT   0x01

trim whitespace on the left

#define RXV_SPIN_TRIM_RIGHT   0x02

trim whitespace on the right

#define rxv_spin_single_trimboth (  )     rxv_spin_single_trim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))

trim single on both sides

#define rxv_spin_single_trimleft (  )     rxv_spin_single_trim((s),(RXV_SPIN_TRIM_LEFT))

trim single on the left side

#define rxv_spin_single_trimright (  )     rxv_spin_single_trim((s),(RXV_SPIN_TRIM_RIGHT))

trim single on the right side

#define rxv_spin_column_del ( rows,
key   )     rxv_spin_column_set((rows),(key),NULL)

delete a column from rows

#define rxv_spin_str_trimboth (  )     rxv_spin_str_trim((s),(RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT))

trim string on both sides

#define rxv_spin_str_trimleft (  )     rxv_spin_str_trim((s),(RXV_SPIN_TRIM_LEFT))

trim string on the left side

#define rxv_spin_str_trimright (  )     rxv_spin_str_trim((s),(RXV_SPIN_TRIM_RIGHT))

trim string on the right side


Typedef Documentation

typedef struct rxv_spin_data rxv_spin_data_t

data type


Function Documentation

rxv_spin_data_t* rxv_spin_single ( apr_pool_t *  pool,
const char *  str 
)

Create single data from from a nul terminated string. String is not copied - use apr_pstrdup() for that.

Parameters:
pool Pool for allocation of data structure
str String to create data from
Returns:
rxv_spin_data_t pointer, structure allocated from the pool, NULL on error
Example:
 rxv_spin_single(ctx->pool,"some string");

char* rxv_spin_single_get ( rxv_spin_data_t single  ) 

Get a nul terminated string from the single data. String is not copied, use apr_pstrdup() for that.

Parameters:
single Single data
Returns:
nul terminated string, NULL on error
Example:
Remarks:
You can, of course, completely ignore this function if you know that your data is a single and that it is not NULL. Simply doing data->data will return the same string.

rxv_spin_data_t* rxv_spin_single_set ( rxv_spin_data_t single,
const char *  str 
)

Replace data (string) in an already existing single. String is not copied - use apr_pstrdup() for that.

Parameters:
single Already exisiting single
str String to replace within single
Returns:
rxv_spin_data_t pointer, NULL on error
Example:
 rxv_spin_single_set(single,"some new string");
Remarks:
This function is useful for replacing singles while iterating through rows of data. In other words, for data postprocessing.

rxv_spin_data_t* rxv_spin_single_mem ( apr_pool_t *  pool,
const char *  str,
size_t  size 
)

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 - use apr_pstrmemdup() for that.

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
Returns:
rxv_spin_data_t pointer, structure allocated from the pool, NULL on error
Example:
 rxv_spin_single_mem(ctx->pool,"1234567890",10);

rxv_spin_data_t* rxv_spin_single_memset ( rxv_spin_data_t single,
const char *  str,
size_t  size 
)

Replace data (counted string) in an already existing single. 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 - use apr_pstrmemdup() for that.

Parameters:
single Already exisiting single
str String to replace within single
size Size of the string, not counting the ending nul character
Returns:
rxv_spin_data_t pointer, NULL on error
Example:
 rxv_spin_single_memset(single,"1234567890",10);
Remarks:
This function is useful for replacing singles while iterating through rows of data. In other words, for data postprocessing.

rxv_spin_data_t* rxv_spin_single_tolower ( rxv_spin_data_t single  ) 

Convert a single to lowercase. Single pushed into the function is modified, no copy is made.

Parameters:
single Single data
Returns:
the same single in lowercase, NULL on error
Example:

rxv_spin_data_t* rxv_spin_single_toupper ( rxv_spin_data_t single  ) 

Convert a single to uppercase. Single pushed into the function is modified, no copy is made.

Parameters:
single Single data
Returns:
the same single in uppercase, NULL on error
Example:

rxv_spin_data_t* rxv_spin_single_trim ( rxv_spin_data_t single,
unsigned char  what 
)

Trim whitespace from a single. No copy is made.

Parameters:
single Single data
what Trim left: RXV_SPIN_TRIM_LEFT, trim right: RXV_SPIN_TRIM_RIGHT
Returns:
the same single trimmed, NULL on error
Example:

rxv_spin_data_t* rxv_spin_meta ( apr_pool_t *  pool,
  ... 
)

Create metadata from data. Meta data is an array of rxv_spin_data_t. It is not used to place data into the context, but simply to facilitate the API. Data is not copied.

Parameters:
pool Pool for allocation of data structure
... List of rxv_spin_data_t*, ending with NULL
Returns:
rxv_spin_data_t pointer, structures allocated from the pool, NULL on error
Example:
 rxv_spin_meta(ctx->pool,
               rxv_spin_rows(ctx->pool,"x",x,"y",y,"z",z,NULL),
               rxv_spin_rows(ctx->pool,"u",u,"v",v,"w",w,NULL),
               NULL);

rxv_spin_data_t* rxv_spin_meta_vstr ( apr_pool_t *  pool,
  ... 
)

Create metadata from from nul terminated strings. Meta data is an array of rxv_spin_data_t. It is not used to place data into the context, but simply to facilitate the API. Strings are not copied - use apr_pstrdup() for that.

Parameters:
pool Pool for allocation of data structure
... List of char*, ending with NULL
Returns:
rxv_spin_data_t pointer, structures allocated from the pool, NULL on error
Example:
 rxv_spin_meta_vstr(ctx->pool,"first string","second string",NULL);

rxv_spin_data_t* rxv_spin_meta_parse ( apr_pool_t *  pool,
char *  str,
const char *  sep 
)

Create metadata by parsing a string. Meta data is an array of rxv_spin_data_t. It is not used to place data into the context, but simply to facilitate the API. String to parse is NOT copied into pool storage before parsing, therefore, if you want to parse constant strings, you MUST copy them using apr_pstrdup(). 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
str String to parse
sep Separators to use when parsing
Returns:
rxv_spin_data_t pointer, structures allocated from the pool, NULL on error
Example:
 rxv_spin_meta_parse(ctx->pool,
                     apr_pstrdup(ctx->pool,"first str,second str/third str"),
                     ",/");

rxv_spin_data_t* rxv_spin_meta_empty ( apr_pool_t *  pool,
size_t  size 
)

Create an empty column of data. The size of the column is usually picked up from an existing rows data type. The returned value is metadata and its size is embedded in it.

Parameters:
pool Pool for allocation of data structures
size Size (number of elements) of the column to create
Returns:
rxv_spin_data_t pointer, structures allocated from the pool, NULL on error
Example:
 rxv_spin_meta_empty(ctx->pool,rows->size);
Remarks:
This function is useful for creating boilerplate columns, used for various marker data.

apr_hash_t* rxv_spin_meta_hash ( apr_pool_t *  pool,
rxv_spin_data_t data 
)

Create a hash table of metadata. Keys will be strings from singles, values will be pointers to the actual singles. Data other than singles will not be hashed.

Parameters:
pool Pool for all memory allocation
data Meta data to hash
Returns:
a hash table of the data, NULL on error
Example:
 rxv_spin_meta_hash(ctx->pool,data);

rxv_spin_data_t* rxv_spin_meta_mark ( rxv_spin_data_t data,
size_t  element 
)

Mark an element in the metadata (associate an empty string to it). This is useful for creating markers for the presentation layer. The data passed into this function is metadata, meaning, the size is embedded in it.

Parameters:
data Data to mark
element The index of the element to mark
Returns:
rxv_spin_data_t pointer to data, NULL on error
Example:
 rxv_spin_meta_mark(data,rows->size-1);

rxv_spin_data_t* rxv_spin_meta_markeach ( rxv_spin_data_t data,
size_t  off,
size_t  step 
)

Mark each n-th element in the metadata (associate an empty string to it). This is useful for creating markers for the presentation layer. The data passed into this function metadata, meaning, the size is embedded in it.

Parameters:
data Data to mark
off Offset to start from
step Each n-th element to mark
Returns:
rxv_spin_data_t pointer to data, NULL on error
Example:

rxv_spin_data_t* rxv_spin_meta_select ( rxv_spin_data_t data,
rxv_spin_data_t select,
apr_hash_t *  hash 
)

Select (mark) data that matches given data set. Selection data set is either single or metadata. The select operation can use an optional hash of the data that is being matched. Otherwise, the search is linear (which is OK for small data sets).

Parameters:
data Data to select
select Single or metadata to use for selection
hash Optional hash of the data being matched or NULL
Returns:
rxv_spin_data_t pointer to data, NULL on error
Example:
 rxv_spin_meta_select(data,rxv_spin_str_parse(ctx->pool,"Australia,Japan",","),
                      rxv_spin_meta_hash(ctx->pool,data));

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

Create rows of data from metadata. The list supplied contains alternating column names, which are strings, and the actual data for the column, in form of metadata. If metadata contains different array lengths, the smallest size will be used. Data is not copied.

Parameters:
pool Pool for allocation of data structure
... List of char* and rxv_spin_data_t*, ending with NULL
Returns:
rxv_spin_data_t pointer, structures allocated from the pool, NULL on error
Example:
 rxv_spin_rows(ctx->pool,"def",def,"ghi",ghi,"xyz",xyz,NULL);

apr_hash_t* rxv_spin_rows_hash ( apr_pool_t *  pool,
rxv_spin_data_t rows,
const char *  column 
)

Create a hash table of a column of rows. Keys will be strings from singles, values will be pointers to the actual singles. Data other than singles will not be hashed.

Parameters:
pool Pool for all memory allocation
rows Rows to hash
column Column to hash
Returns:
a hash table of the data, NULL on error
Example:
 rxv_spin_rows_hash(ctx->pool,rows,"secondcolumn");

rxv_spin_data_t* rxv_spin_rows_mark ( rxv_spin_data_t rows,
const char *  column,
size_t  element 
)

Mark an element in the column of rows (associate an empty string to it). This is useful for creating markers for the presentation layer.

Parameters:
rows Rows to mark
column Name of the column to mark
element The index of the element to mark
Returns:
rxv_spin_data_t pointer to rows, NULL on error
Example:
 rxv_spin_rows_mark(rows,"lastrow",rows->size-1);

rxv_spin_data_t* rxv_spin_rows_markeach ( rxv_spin_data_t rows,
const char *  column,
size_t  off,
size_t  step 
)

Mark each n-th element in the column of rows (associate an empty string to it). This is useful for creating markers for the presentation layer.

Parameters:
rows Rows to mark
column Name of the column to mark
off Offset to start from
step Each n-th element to mark
Returns:
rxv_spin_data_t pointer to rows, NULL on error
Example:
 rxv_spin_rows_markeach(rows,"evenrow",0,2);

rxv_spin_data_t* rxv_spin_rows_select ( rxv_spin_data_t rows,
rxv_spin_data_t select,
const char *  column,
const char *  marker,
apr_hash_t *  hash 
)

Select (mark) rows of data that match given data set. Selection data set is either single or metadata. The select operation can use an optional hash of the column that is being matched. Otherwise, the search is linear (which is OK for small data sets).

Parameters:
rows Rows of data to select
select Single or metadata to use for selection
column Column used to match the data from select parameter
marker Column used to place markers for selected data
hash Optional hash of the column being matched or NULL
Returns:
rxv_spin_data_t pointer to rows, NULL on error
Example:
 rxv_spin_rows_select(rows,rxv_spin_str_parse(ctx->pool,"Australia,Japan",","),
                      "country","selected",
                      rxv_spin_rows_hash(ctx->pool,rows,"country"));

rxv_spin_data_t* rxv_spin_column_get ( apr_pool_t *  pool,
rxv_spin_data_t rows,
const char *  key 
)

Get a column from rows data type. The column is not copied, rather a pointer to the first element in the array is returned inside a metadata type. Being metadata, this column will have its size embedded in it.

Parameters:
pool Pool for allocation of data structure
rows Rows data type
key Name of the column to get
Returns:
rxv_spin_data_t pointer, NULL on error
Example:
 column=rxv_spin_column_get(rows,"firstfield");
 for(i=0;i<rows->size;i++)
   rxv_spin_single_toupper(column+i);

rxv_spin_data_t* rxv_spin_column_set ( rxv_spin_data_t rows,
const char *  key,
rxv_spin_data_t column 
)

Set a column in rows data type. The column passed into this function is metadata. The size of the column has to be equal of greater than the number of rows.

Parameters:
rows Rows data type
key Name of the column to set
column Column to set
Returns:
rxv_spin_data_t pointer to the column, NULL on error
Example:
 rxv_spin_column_set(rows,"newcolumn",rxv_spin_column(rows->size));
Remarks:
This function is also used for column removal, through a macro. In such a case, NULL return value is not necessarily a failure.

rxv_spin_data_t* rxv_spin_resize ( apr_pool_t *  pool,
rxv_spin_data_t data,
size_t  size 
)

Resize rows or metadata.

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(ctx->pool,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 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
data Data, any type
Returns:
copy of the data, NULL on error
Example:
 rxv_spin_copy(ctx->pool,data);
Remarks:
If you're using this function on rows or metadata, 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_str_tolower ( 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:

char* rxv_spin_str_toupper ( 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:

char* rxv_spin_str_trim ( char *  str,
unsigned char  what 
)

Trim whitespace from a string. No copy is made. You MUST copy the string into pool storage using apr_pstrdup() 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_str_trim(apr_strdup(ctx->pool,"  string with whitespace   ",
                   RXV_SPIN_TRIM_LEFT|RXV_SPIN_TRIM_RIGHT);


Generated on Sun Sep 9 04:54:12 2007 for mod_spin by  doxygen 1.5.3