cstr.h File Reference

Declaration of the C-string types, related constants and functions. More...

#include "ds/char.h"
#include "ds/result.h"
#include "ds/usize.h"

Include dependency graph for cstr.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	DS_CSTR_BYTES   ((ds_usize_t)sizeof (ds_cstr_t))
	The size of C-strings in bytes. More...
#define	DS_SCN_CSTR(len)   DS_SCN_CSTR_INTERNAL_IMPL (len)
	C-string notation. Can be used in scanf to parse and read len + 1 (len = size - 1) sized C-string values. More...
#define	DS_PRI_CSTR   "s"
	C-string notation. Can be used in printf to format and write C-string values. More...

Typedefs
typedef ds_char_t const *	ds_cstr_t
	An immutable C-string type. More...
typedef ds_char_t *	ds_cstr_mut_t
	A mutable C-string type. More...

Functions
ds_result_t	ds_cstr_allocate (ds_cstr_mut_t *self, ds_usize_t size)
	Attempts to allocate a C-string. More...
ds_result_t	ds_cstr_reallocate (ds_cstr_mut_t *src_cstr_ptr, ds_usize_t src_size, ds_cstr_mut_t *dst_cstr_ptr, ds_usize_t dst_size)
	Attempts to reallocate (extend, shrink) the C-string. More...
ds_result_t	ds_cstr_deallocate (ds_cstr_mut_t *self)
	Deallocates the C-string referenced by self. More...

Detailed Description

Declaration of the C-string types, related constants and functions.

Author

Avinash Maddikonda (svass.nosp@m.saka.nosp@m.vi@gm.nosp@m.ail..nosp@m.com)

Since

0.5.0

Date

2023-07-31

Definition in file cstr.h.

Macro Definition Documentation

DS_CSTR_BYTES

#define DS_CSTR_BYTES   ((ds_usize_t)sizeof (ds_cstr_t))

The size of C-strings in bytes.

Examples

Basic usage:

assert (DS_CSTR_BYTES == sizeof (ds_char_t *));

Definition at line 97 of file cstr.h.

DS_PRI_CSTR

#define DS_PRI_CSTR   "s"

C-string notation. Can be used in printf to format and write C-string values.

Examples

Basic usage:

ds_cstr_t const x = "abc";
printf ("%" DS_PRI_CSTR, x);

Definition at line 139 of file cstr.h.

DS_SCN_CSTR

#define DS_SCN_CSTR

(

len

)

DS_SCN_CSTR_INTERNAL_IMPL (len)

C-string notation. Can be used in scanf to parse and read len + 1 (len = size - 1) sized C-string values.

Parameters

len	The length of the C-string (excluding the null-terminator).

Warning

len must be (a macro constant containing) an unsigned integer literal (with no suffixes or preceding zeroes). Any other kind of value, expression, or statement is strictly disallowed.

Returns

C-string notation for the given string length len.

Warning

It is strongly advised to use fgets instead of scanf to read input.

Examples

Basic usage:

#define SIZE 15
char x[SIZE + 1];
scanf("%" DS_SCN_CSTR(SIZE), x);

Definition at line 126 of file cstr.h.

Typedef Documentation

ds_cstr_mut_t

typedef ds_char_t* ds_cstr_mut_t

A mutable C-string type.

The mutable C-string type represents a pointer to a mutable char array.

See also

https://en.wikipedia.org/wiki/Immutable_object

https://en.wikipedia.org/wiki/C_string_handling

Definition at line 37 of file cstr.h.

ds_cstr_t

typedef ds_char_t const* ds_cstr_t

An immutable C-string type.

The immutable C-string type represents a pointer to an immutable char array.

See also

https://en.wikipedia.org/wiki/Immutable_object

https://en.wikipedia.org/wiki/C_string_handling

Definition at line 28 of file cstr.h.

Function Documentation

ds_cstr_allocate()

ds_result_t ds_cstr_allocate	(	ds_cstr_mut_t *	self,
		ds_usize_t	size
	)

Attempts to allocate a C-string.

Warning

Always pair a ds_cstr_allocate call with a ds_cstr_reallocate or ds_cstr_deallocate call (passing the same pointer). Failing to do so will lead to memory leaks.

Parameters

[out]	self	The allocated C-string on success.
	size	The size of the C-string to allocate.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Definition at line 18 of file cstr.c.

Here is the call graph for this function:

Here is the caller graph for this function:

ds_cstr_deallocate()

ds_result_t ds_cstr_deallocate

(

ds_cstr_mut_t *

self

)

Deallocates the C-string referenced by self.

Warning

Only pass pointers allocated using ds_cstr_allocate or ds_cstr_reallocate. Passing other pointers may lead to undefined behavior.

Parameters

[out]

self

A reference to the C-string to deallocate.

Returns

Ok on success.

Err(PtrIsNull) if self is NULL.

Definition at line 84 of file cstr.c.

Here is the caller graph for this function:

ds_cstr_reallocate()

ds_result_t ds_cstr_reallocate	(	ds_cstr_mut_t *	src_cstr_ptr,
		ds_usize_t	src_size,
		ds_cstr_mut_t *	dst_cstr_ptr,
		ds_usize_t	dst_size
	)

Attempts to reallocate (extend, shrink) the C-string.

Warning

Always pair a ds_cstr_reallocate call with a ds_cstr_reallocate or ds_cstr_deallocate call (passing the same pointer). Failing to do so ***will** lead to memory leaks.

Parameters

	src_cstr_ptr	A reference to the C-string to reallocate.
	src_size	The old size of the C-string to reallocate.
[out]	dst_cstr_ptr	A reference to the reallocated C-string.
	dst_size	The new size of the reallocated C-string.

Returns

Ok on success.

Err(PtrIsNull) if src_cstr_ptr or dst_cstr_ptr is NULL.

Err(MemAllocFailed) if a memory allocation fails.

Definition at line 41 of file cstr.c.

Here is the call graph for this function:

Here is the caller graph for this function: