nvdialog_string.h File Reference

#include <stddef.h>
#include "nvdialog_platform.h"

Go to the source code of this file.

Macros
#define	__nvdialog_string_h__   1
#define	NVD_STRING(s)
	A shortcut macro to create a new NvdDynamicString out of a simple string.
#define	NVD_CSTR(s)
	A shortcut macro to get a C string out of the NvdDynamicString given.

Typedefs
typedef struct _NvdDynamicString	NvdDynamicString
	A string type that can be resized, manipulated, converted and read from.

Functions
NVD_API NvdDynamicString *	nvd_string_new (const char *data)
	Creates a new NvdDynamicString and returns it, optionally with the data given in contents.
NVD_API void	nvd_string_set_data (NvdDynamicString *string, const char *data)
	Sets the actual string inside the given NvdDynamicString.
NVD_API NvdDynamicString *	nvd_duplicate_string (NvdDynamicString *other)
	Duplicates the given NvdDynamicString without modifying it.
NVD_API void	nvd_append_to_string (NvdDynamicString *string, NvdDynamicString *new_data)
	Appends the contents of new_data to the end of string.
NVD_API const char *	nvd_string_to_cstr (NvdDynamicString *string)
	Returns a const char* representation of the given NvdDynamicString.
NVD_API void	nvd_string_reserve (NvdDynamicString *string, size_t bytes)
	Preallocates memory for at least bytes inside the string 's data. No data will be lost.
NVD_API size_t	nvd_strlen (NvdDynamicString *string)
	Returns the length of the given NvdDynamicString.
NVD_API void	nvd_string_clear (NvdDynamicString *string)
	Clears the contents of the given NvdDynamicString.
NVD_API void	nvd_delete_string (NvdDynamicString *string)
	Deletes the string from memory and casts it invalid to use.

Macro Definition Documentation

__nvdialog_string_h__

#define __nvdialog_string_h__   1

NVD_CSTR

#define NVD_CSTR

(

s

)

Value:

nvd_string_to_cstr(s)

A shortcut macro to get a C string out of the NvdDynamicString given.

Warning

The returned string is only valid as long as s is. See nvd_string_to_cstr for details.

Since

v0.10

Examples

/home/acs/Projects/nvdialog/include/dialogs/nvdialog_file_dialog.h.

NVD_STRING

#define NVD_STRING

(

s

)

Value:

nvd_string_new(s)

A shortcut macro to create a new NvdDynamicString out of a simple string.

Since

v0.10

Typedef Documentation

NvdDynamicString

typedef struct _NvdDynamicString NvdDynamicString

A string type that can be resized, manipulated, converted and read from.

NvdDynamicString is a recent addition to the library that allows various kinds of strings across various operating systems to be abstracted and represented by a single type. Whereas const char* is widely used throughout the library, an NvdDynamicString is useful when strings are returned - Simple character literals cannot be returned since they are allocated on the stack. It is also simple to use and convert from and to char buffers, making it compatible with almost all existing APIs.

Note

Do not pass this to any parameters that require a char* without explicit conversion (See nvd_string_to_cstr()).

Internally, this dynamic string maintains a capacity variable, that may allocate more memory than needed to store the string. This is done to avoid multiple allocations.

Since

v0.10.0

Examples

/home/acs/Projects/nvdialog/include/dialogs/nvdialog_file_dialog.h.

Function Documentation

nvd_append_to_string()

NVD_API void nvd_append_to_string	(	NvdDynamicString *	string,
		NvdDynamicString *	new_data )

Appends the contents of new_data to the end of string.

Parameters

string	The NvdDynamicString to append to. Must not be NULL.
new_data	The string whose contents will be appended. Must not be NULL.

Note

This function automatically resizes string if needed.

Since

v0.10.0

nvd_delete_string()

NVD_API void nvd_delete_string

(

NvdDynamicString *

string

)

Deletes the string from memory and casts it invalid to use.

Note

For security and safety reasons, all the data of the pointer will be zeroed-out first.

Parameters

string

The string to delete. This function does nothing if string is NULL

Since

v0.10.0

nvd_duplicate_string()

NVD_API NvdDynamicString * nvd_duplicate_string

(

NvdDynamicString *

other

)

Duplicates the given NvdDynamicString without modifying it.

You might find this useful when you wish to give the duplicated string in a function that needs to temporarily modify it, or simply modify the string yourself without losing the original contents. In most cases, reusing the same string is enough.

Parameters

other

The string to copy from.

Note

The returned object is completely unique from other and any modifications in one won't impact the other.

Since

v0.10.0

nvd_string_clear()

NVD_API void nvd_string_clear

(

NvdDynamicString *

string

)

Clears the contents of the given NvdDynamicString.

Parameters

string

The string to clear. Must not be NULL.

Note

Any data inside will be lost, but no additional (re)allocations will be performed.

Since

v0.10.0

nvd_string_new()

NVD_API NvdDynamicString * nvd_string_new

(

const char *

data

)

Creates a new NvdDynamicString and returns it, optionally with the data given in contents.

Parameters

data	A C-style string to convert into a dynamic string, optional. Pass NULL to create an empty NvdDynamicString.

Returns

A new NvdDynamicString on success, otherwise NULL and the internal error code is set.

Since

v0.10.0

nvd_string_reserve()

NVD_API void nvd_string_reserve	(	NvdDynamicString *	string,
		size_t	bytes )

Preallocates memory for at least bytes inside the string 's data. No data will be lost.

Parameters

string	The string to increase the capacity of.
bytes	The minimum number of bytes to reserve.

Note

While optional and implicitly done internally when extra space is needed, this can help with performance if you know the size of the data that must be appended.

Since

v0.10.0

nvd_string_set_data()

NVD_API void nvd_string_set_data	(	NvdDynamicString *	string,
		const char *	data )

Sets the actual string inside the given NvdDynamicString.

Parameters

string	The NvdDynamicString to modify.
data	The string to set as the contents of the NvdDynamicString.

Note

This will discard any existing data in the string. If you wish to simply append data to the string, see nvd_append_to_string

Since

v0.10.0

nvd_string_to_cstr()

NVD_API const char * nvd_string_to_cstr

(

NvdDynamicString *

string

)

Returns a const char* representation of the given NvdDynamicString.

Parameters

string

The NvdDynamicString to convert. Must not be NULL.

Returns

A pointer to a null-terminated C string. The pointer is valid as long as the dynamic string exists and is not modified. Do NOT modify the returned buffer.

Note

Do not modify or free the returned pointer, as it may be used elsewhere. Use nvd_duplicate_string() if a mutable copy is needed.

Since

v0.10.0

nvd_strlen()

NVD_API size_t nvd_strlen

(

NvdDynamicString *

string

)

Returns the length of the given NvdDynamicString.

Parameters

string

The string whose length will be measured. Must not be NULL.

Returns

The number of characters in the string, excluding the null-terminator.

Since

v0.10.0