ucx
UAP Common Extensions
Data Structures | Functions
properties.h File Reference

Load / store utilities for properties files. More...

#include "ucx.h"
#include "map.h"

Go to the source code of this file.

Data Structures

struct  UcxProperties
 UcxProperties object for parsing properties data. More...
 

Functions

UcxPropertiesucx_properties_new ()
 Constructs a new UcxProperties object. More...
 
void ucx_properties_free (UcxProperties *prop)
 Destroys a UcxProperties object. More...
 
void ucx_properties_fill (UcxProperties *prop, char *buf, size_t len)
 Sets the input buffer for the properties parser. More...
 
int ucx_properties_next (UcxProperties *prop, sstr_t *name, sstr_t *value)
 Retrieves the next key/value-pair. More...
 
int ucx_properties2map (UcxProperties *prop, UcxMap *map)
 Retrieves all available key/value-pairs and puts them into a UcxMap. More...
 
int ucx_properties_load (UcxMap *map, FILE *file)
 Loads a properties file to a UcxMap. More...
 
int ucx_properties_store (UcxMap *map, FILE *file)
 Stores a UcxMap to a file. More...
 

Detailed Description

Load / store utilities for properties files.

Author
Mike Becker
Olaf Wintermann

Function Documentation

◆ ucx_properties2map()

int ucx_properties2map ( UcxProperties prop,
UcxMap map 
)

Retrieves all available key/value-pairs and puts them into a UcxMap.

This is done by successive calls to ucx_properties_next() until no more key/value-pairs can be retrieved.

The memory for the map values is allocated by the map's own allocator.

Parameters
propthe UcxProperties object
mapthe target map
Returns
The UcxProperties.error code (i.e. 0 on success).
See also
ucx_properties_fill()
UcxMap.allocator

◆ ucx_properties_fill()

void ucx_properties_fill ( UcxProperties prop,
char *  buf,
size_t  len 
)

Sets the input buffer for the properties parser.

After calling this function, you may parse the data by calling ucx_properties_next() until it returns 0. The function ucx_properties2map() is a convenience function that reads as much data as possible by using this function.

Parameters
propthe UcxProperties object
bufa pointer to the new buffer
lenthe payload length of the buffer
See also
ucx_properties_next()
ucx_properties2map()

◆ ucx_properties_free()

void ucx_properties_free ( UcxProperties prop)

Destroys a UcxProperties object.

Parameters
propthe UcxProperties object to destroy

◆ ucx_properties_load()

int ucx_properties_load ( UcxMap map,
FILE *  file 
)

Loads a properties file to a UcxMap.

This is a convenience function that reads data from an input stream until the end of the stream is reached.

Parameters
mapthe map object to write the key/value-pairs to
filethe FILE* stream to read from
Returns
0 on success, or a non-zero value on error
See also
ucx_properties_fill()
ucx_properties2map()

◆ ucx_properties_new()

UcxProperties* ucx_properties_new ( )

Constructs a new UcxProperties object.

Returns
a pointer to the new UcxProperties object

◆ ucx_properties_next()

int ucx_properties_next ( UcxProperties prop,
sstr_t name,
sstr_t value 
)

Retrieves the next key/value-pair.

This function returns a nonzero value as long as there are key/value-pairs found. If no more key/value-pairs are found, you may refill the input buffer with ucx_properties_fill().

Attention: the sstr_t.ptr pointers of the output parameters point to memory within the input buffer of the parser and will get invalid some time. If you want long term copies of the key/value-pairs, use sstrdup() after calling this function.

Parameters
propthe UcxProperties object
namea pointer to the sstr_t that shall contain the property name
valuea pointer to the sstr_t that shall contain the property value
Returns
Nonzero, if a key/value-pair was successfully retrieved
See also
ucx_properties_fill()

◆ ucx_properties_store()

int ucx_properties_store ( UcxMap map,
FILE *  file 
)

Stores a UcxMap to a file.

The key/value-pairs are written by using the following format:

[key] = [value]\n

Parameters
mapthe map to store
filethe FILE* stream to write to
Returns
0 on success, or a non-zero value on error