String Handling. More...

Collaboration diagram for OyjlCore String:

Functions
void	oyjlStr_SetCharAt (oyjl_str str, char c, int pos)
	set the char at position More...

char **	oyjlStringSplit (const char text, const char delimiter, int count, void (alloc)(size_t))
	convert a string into list More...

char **	oyjlStringSplit2 (const char text, const char delimiter, const char (splitFunc)(const char text, const char delimiter, int length), int count, int index, void (*alloc)(size_t))
	convert a string into list More...

char *	oyjlStringCopy (const char string, void (*alloc)(size_t))
	duplicate a string with custom allocator More...

int	oyjlStringAdd (char *string, void (alloc)(size_t size), void(deAlloc)(void data), const char format,...)
	sprintf with de-/allocator More...

char *	oyjlStringAppendN (const char text, const char append, int append_len, void (alloc)(size_t size))
	append to the string end More...

void	oyjlStringAddN (char *text, const char append, int append_len, void (alloc)(size_t), void(deAlloc)(void ))
	append to the string end More...

int	oyjlStringReplace (char *text, const char search, const char replacement, void (alloc)(size_t), void(deAlloc)(void *))
	substitute pattern in a string More...

char **	oyjlStringListCatList (const char list, int n_alt, const char append, int n_app, int count, void (*alloc)(size_t))
	append a string list to an other string list More...

void	oyjlStringListRelease (char **l, int size, void(deAlloc)(void *))
	free a string list More...

void	oyjlStringListPush (char **list, int n, const char string, void (alloc)(size_t), void(deAlloc)(void *))
	append a string to a string list More...

int	oyjlStringListAdd (char **list, int n, void (alloc)(size_t), void(deAlloc)(void ), const char *format,...)
	add a variable string to a string list More...

void	oyjlStringListFreeDoubles (char *list, int list_n, void(deAlloc)(void ))
	filter doubles out More...

void	oyjlStringListAddList (char **list, int n, const char *append, int n_app, void (alloc)(size_t), void(deAlloc)(void *))
	append a string list to an other and handle memory More...

int	oyjlStringToLong (const char text, long value, const char **end)

int	oyjlStringToDouble (const char text, double value, const char **end, int flags)
	text to double conversion More...

int	oyjlStringsToDoubles (const char text, const char delimiter, int count, void (alloc)(size_t), double *value)
	text to double list More...

char *	oyjlRegExpFind (char text, const char regex, int *length)
	search for pattern More...

int	oyjlRegExpReplace (char *text, const char regex, const char *replacement)
	replace pattern More...

char *	oyjlRegExpEscape (const char *text)
	use a pattern literaly More...

int	oyjlStringStartsWith (const char text, const char pattern)
	simple and fast test More...

int	oyjlStringSplitUTF8 (const char text, char *mbchars, void (*alloc)(size_t))
	split letters of a UTF-8 string More...

oyjl_str	oyjlStr_New (size_t length, void (alloc)(size_t), void(deAlloc)(void ))
	allocate string object More...

oyjl_str	oyjlStr_NewFrom (char *text, size_t length, void (alloc)(size_t), void(deAlloc)(void *))
	allocate string object from chars More...

int	oyjlStr_AppendN (oyjl_str string, const char *append, int append_len)
	fast append to the string end More...

int	oyjlStr_Push (oyjl_str string, const char *text)
	fast append to the string end More...

int	oyjlStr_Add (oyjl_str string, const char *format,...)
	sprintf for oyjl_str More...

int	oyjlStr_Replace (oyjl_str text, const char search, const char replacement, void(modifyReplacement)(const char text, const char start, const char end, const char search, const char replace, int replace_len, void user_data), void user_data)
	substitute pattern in a string More...

char *	oyjlStr_Pull (oyjl_str str)
	move the wrapped char array out of the object More...

void	oyjlStr_Clear (oyjl_str string)
	clear text in a string object More...

void	oyjlStr_Release (oyjl_str *string_ptr)
	release a string object More...

const char *	oyjlStr (oyjl_str string)
	read only the wrapped char array More...

const char *	oyjlTermColorToPlain (const char *text, int flags)
	remove term color marks More...

Detailed Description

String Handling.

A convinient set of string API's is available in the oyjlStringXXX family. Those API's handle plain string arrays. oyjlStringAdd() uses variable args to format and append to a existing string. oyjlStringListXXX API's handle plain arrays of strings.

The oyjl_str based oyStrXXX API's use a more careful memory management and thus perform way faster on larger memory arrays as they need fewer allocations and copies. oyjlStr_New() allocates a new object, or oyjlStr_NewFrom() wrappes a existing string array into a new object. oyjlStr() lets you see the contained char array. oyjlStr_Push() performs fast concatenation. oyjlStr_Replace() uses the object advantages. oyjlStr_Pull() directly takes the char array out of control of the oyjl_str object and oyjlStr_Release() frees the object and all memory.

Function Documentation

◆ oyjlRegExpEscape()

char * oyjlRegExpEscape ( const char * text )

use a pattern literaly

This function detects OYJL_HAVE_REGEX_H macro internally to fit the oyjlRegExpMatch() implementation.

It is escaping:
.$*+?()[{|

Parameters

text	string to escape

Returns: escaped string

Version: Oyjl: 1.0.0

Date: 2020/08/14

Since: 2020/08/14 (Oyjl: 1.0.0)

◆ oyjlRegExpFind()

char * oyjlRegExpFind	(	char *	text,
		const char *	regex,
		int *	length
	)

search for pattern

This function behaves like strstr(), but extends to regular expressions. Test for OYJL_HAVE_REGEX_H macro to see if regexec() API is used. Otherwise only C strstr() API will be called.

Parameters

text	string to search in
regex	regular expression to try with text
length	length of returned value

Returns

result:

0: no match
>0: first string adress in text

Version: Oyjl: 1.0.0

Date: 2022/10/19

Since: 2020/07/28 (Oyjl: 1.0.0)

◆ oyjlRegExpReplace()

int oyjlRegExpReplace	(	char **	text,
		const char *	regex,
		const char *	replacement
	)

replace pattern

Test for OYJL_HAVE_REGEX_H macro to see if regexec() API is used.

Parameters

text	string to search in
regex	regular expression to try with text
replacement	substitute all matches of regex in text; it may contain up to two occurences of s regex matching placeholders, e.g. "%s=%s"

Returns: count of replacements

Version: Oyjl: 1.0.0

Date: 2022/10/21

Since: 2021/09/29 (Oyjl: 1.0.0)

Referenced by oyjlPrintSub(), oyjlPrintSubProfiling(), and oyjlTermColorToPlain().

◆ oyjlStr()

const char* oyjlStr ( oyjl_str string )

read only the wrapped char array

The returned array might become invalid with each further call to the string object.

Version: Oyjl: 1.0.0

Date: 2019/02/14

Since: 2019/02/14 (Oyjl: 1.0.0)

Referenced by oyjlStr_Replace().

◆ oyjlStr_Add()

int oyjlStr_Add	(	oyjl_str	string,
		const char *	format,
			...
	)

sprintf for oyjl_str

The function adds memory management over standard sprintf().

Parameters

[in]	string	source string
[in]	format	printf style format string
[in]	...	argument list for format

Returns: error

References OYJL_CREATE_VA_STRING, and oyjlStr_Push().

Referenced by oyjlTreeToCsv().

◆ oyjlStr_AppendN()

int oyjlStr_AppendN	(	oyjl_str	string,
		const char *	append,
		int	append_len
	)

fast append to the string end

Parameters

[in]	string	string object
[in]	append	to be added text to string
[in]	append_len	length of append

Returns: error

Referenced by oyjlStr_Push(), oyjlStr_Replace(), and oyjlTreeToCsv().

◆ oyjlStr_Clear()

void oyjlStr_Clear ( oyjl_str string )

clear text in a string object

Version: Oyjl: 1.0.0

Date: 2021/10/24

Since: 2019/06/14 (Oyjl: 1.0.0)

Referenced by oyjlStr_Release().

◆ oyjlStr_New()

oyjl_str oyjlStr_New	(	size_t	length,
		void ()(size_t)	alloc,
		void()(void )	deAlloc
	)

allocate string object

Parameters

[in]	length	the preallocation length
[in]	alloc	custom allocator; optional, default is malloc
[in]	deAlloc	custom deallocator; optional, default is free

Returns: the object

Version: Oyjl: 1.0.0

Date: 2021/10/24

Since: 2019/02/14 (Oyjl: 1.0.0)

Referenced by oyjlStr_Replace(), oyjlTermColorToHtml(), oyjlTreeToCsv(), oyjlTreeToJson(), and oyjlUi_s::oyjlUiJsonToCode().

◆ oyjlStr_NewFrom()

oyjl_str oyjlStr_NewFrom	(	char **	text,
		size_t	length,
		void ()(size_t)	alloc,
		void()(void )	deAlloc
	)

allocate string object from chars

Use this function to avoid allocation of already in memory char array. Be careful, that the memory alloc and deAlloc args match the text storage.

Parameters

[in]	text	text to pull into new object
[in]	length	the preallocation size of text or zero if unknown
[in]	alloc	custom allocator; optional, default is malloc
[in]	deAlloc	custom deallocator; optional, default is free

Returns: the object

Version: Oyjl: 1.0.0

Date: 2021/10/24

Since: 2019/02/15 (Oyjl: 1.0.0)

Referenced by oyjlStringReplace().

◆ oyjlStr_Pull()

char* oyjlStr_Pull ( oyjl_str str )

move the wrapped char array out of the object

This function might be usefull if a plain string copy is too expensive and the object memory allocation can be further handled for the returned char pointer. After the operation the objects internal char array will be reset to zero length.

Parameters

[in,out] str the object, which will be reseted

Returns: the char array from str

Version: Oyjl: 1.0.0

Date: 2021/10/24

Since: 2019/02/15 (Oyjl: 1.0.0)

Referenced by oyjlStringReplace().

◆ oyjlStr_Push()

int oyjlStr_Push	(	oyjl_str	string,
		const char *	text
	)

fast append to the string end

Parameters

[in]	string	string object
[in]	text	to be added text to string

Returns: error

References oyjlStr_AppendN().

Referenced by oyjlStr_Add(), oyjlStr_Replace(), and oyjlTermColorToHtml().

◆ oyjlStr_Release()

void oyjlStr_Release ( oyjl_str * string_ptr )

release a string object

All references from previous oyjlStr() calls will be void.

Version: Oyjl: 1.0.0

Date: 2021/10/24

Since: 2019/02/14 (Oyjl: 1.0.0)

References oyjlStr_Clear().

Referenced by oyjlStringReplace().

◆ oyjlStr_Replace()

int oyjlStr_Replace	(	oyjl_str	text,
		const char *	search,
		const char *	replacement,
		void()(const char text, const char start, const char end, const char search, const char replace, int replace_len, void *user_data)	modifyReplacement,
		void *	user_data
	)

substitute pattern in a string

Parameters

[in,out]	text	source string for in place manipulation
[in]	search	pattern to be tested in text
[in]	replacement	string to be put in place of search sub string
[in]	modifyReplacement	hook to dynamically modify the replacement text; optional text: the full search text start: current start inside text; on first occurence it provides &text[0] end: current end inside text; the actual occurence of search in text search: used term replace: possibly modified replacement text for search replace_len: length of original replace; can be changed context: user data
[in,out]	user_data	optional user data for modifyReplacement

Returns: number of occurences

Version: Oyjl: 1.0.0

Date: 2022/09/04

Since: 2019/02/15 (Oyjl: 1.0.0)

References oyjlStr(), oyjlStr_AppendN(), oyjlStr_New(), and oyjlStr_Push().

Referenced by oyjlStringReplace(), and oyjlTermColorToHtml().

◆ oyjlStr_SetCharAt()

void oyjlStr_SetCharAt	(	oyjl_str	str,
		char	c,
		int	pos
	)

set the char at position

Parameters

[in,out] str the object, which will be modified

Returns

Version: Oyjl: 1.0.0

Date: 2022/10/19

Since: 2022/10/19 (Oyjl: 1.0.0)

◆ oyjlStringAdd()

int oyjlStringAdd	(	char **	string,
		void ()(size_t size)	alloc,
		void()(void data)	deAlloc,
		const char *	format,
			...
	)

sprintf with de-/allocator

The function adds memory management over standard sprintf().

Parameters

[in]	string	source string
[in]	alloc	custom allocator; optional, default is malloc
[in]	deAlloc	custom deallocator matching alloc; optional, default is free
[in]	format	printf style format string
[in]	...	argument list for format

Returns: error

Examples:: image_display.cpp.

References OYJL_CREATE_VA_STRING.

Referenced by oyjlTreeGetNewValueFromArray(), oyjlTreeToXml(), oyjlTreeToYaml(), oyjlValueSetDouble(), oyjlValueSetInt(), oyjlValueSetString(), and oyjlValueText().

◆ oyjlStringAddN()

void oyjlStringAddN	(	char **	text,
		const char *	append,
		int	append_len,
		void ()(size_t)	alloc,
		void()(void )	deAlloc
	)

append to the string end

Parameters

[in]	text	source string
[in]	append	to be added text to string
[in]	append_len	length of append
[in]	alloc	custom allocator; optional, default is malloc
[in]	deAlloc	custom deallocator matching alloc; optional, default is free

Returns: constructed string+append

References oyjlStringAppendN().

◆ oyjlStringAppendN()

char* oyjlStringAppendN	(	const char *	text,
		const char *	append,
		int	append_len,
		void ()(size_t size)	alloc
	)

append to the string end

For a plain memory duplication use:

void * copy = oyjlStringAppendN( NULL, (const char*)ptr, ptr_len, malloc );

Parameters

[in]	text	source string; optional
[in]	append	to be added text to string; optional
[in]	append_len	length of append
[in]	alloc	custom allocator; optional, default is malloc

Returns: constructed string+append

Referenced by oyjlStringAddN(), and oyjlUi_s::oyjlUi_Copy().

◆ oyjlStringCopy()

char* oyjlStringCopy	(	const char *	string,
		void ()(size_t)	alloc
	)

duplicate a string with custom allocator

The function adds the allocator over standard strdup().

Parameters

[in]	string	source string
[in]	alloc	custom allocator; optional, default is malloc

Returns: copy

Referenced by l2cmsFilterNode_GetText(), oyjlOptionStringToJson(), oyjlStringToDouble(), oyjlTermColorToPlain(), oyjlTreeClearValue(), oyjlTreeToYaml(), oyjlValueSetDouble(), and oyStringCopy().

◆ oyjlStringListAdd()

int oyjlStringListAdd	(	char ***	list,
		int *	n,
		void ()(size_t)	alloc,
		void()(void )	deAlloc,
		const char *	format,
			...
	)

add a variable string to a string list

References OYJL_CREATE_VA_STRING, and oyjlStringListPush().

◆ oyjlStringListAddList()

void oyjlStringListAddList	(	char ***	list,
		int *	n,
		const char **	append,
		int	n_app,
		void ()(size_t)	alloc,
		void()(void )	deAlloc
	)

append a string list to an other and handle memory

References oyjlStringListCatList(), and oyjlStringListRelease().

◆ oyjlStringListCatList()

char** oyjlStringListCatList	(	const char **	list,
		int	n_alt,
		const char **	append,
		int	n_app,
		int *	count,
		void ()(size_t)	alloc
	)

append a string list to an other string list

Referenced by oyjlStringListAddList().

◆ oyjlStringListFreeDoubles()

void oyjlStringListFreeDoubles	(	char **	list,
		int *	list_n,
		void()(void )	deAlloc
	)

filter doubles out

Version: Oyranos: 0.9.6

Date: 2015/08/04

Since: 2015/08/04 (Oyranos: 0.9.6)

◆ oyjlStringListPush()

void oyjlStringListPush	(	char ***	list,
		int *	n,
		const char *	string,
		void ()(size_t)	alloc,
		void()(void )	deAlloc
	)

append a string to a string list

Referenced by oyjlStringListAdd().

◆ oyjlStringListRelease()

void oyjlStringListRelease	(	char ***	l,
		int	size,
		void()(void )	deAlloc
	)

free a string list

Referenced by oyjlStringListAddList(), oyjlTreeGetPath(), and oyStringListRelease().

◆ oyjlStringReplace()

int oyjlStringReplace	(	char **	text,
		const char *	search,
		const char *	replacement,
		void ()(size_t)	alloc,
		void()(void )	deAlloc
	)

substitute pattern in a string

Parameters

[in,out]	text	source string for in place manipulation
[in]	search	pattern to be tested in text
[in]	replacement	string to be put in place of search sub string
[in]	alloc	custom allocator; optional, default is malloc
[in]	deAlloc	custom deallocator matching alloc; optional, default is free

Returns: number of occurences

References oyjlStr_NewFrom(), oyjlStr_Pull(), oyjlStr_Release(), and oyjlStr_Replace().

Referenced by oyjlTreeToYaml().

◆ oyjlStringSplit()

char ** oyjlStringSplit	(	const char *	text,
		const char	delimiter,
		int *	count,
		void ()(size_t)	alloc
	)

convert a string into list

Parameters

[in]	text	source string
[in]	delimiter	the char which marks the split; e.g. comma ','; optional; default zero: extract white space separated words
[out]	count	number of detected string segments; optional
[in]	alloc	custom allocator; optional, default is malloc

Returns: array of detected string segments

References oyjlStringSplit2().

Referenced by oyjlOptionStringToJson(), oyjlPathMatch(), oyjlTreeClearValue(), oyjlTreeToPaths(), and oyStringSplit().

◆ oyjlStringSplit2()

char** oyjlStringSplit2	(	const char *	text,
		const char *	delimiter,
		const char *	splitFunc)(const char text, const char delimiter, int *length,
		int *	count,
		int **	index,
		void ()(size_t)	alloc
	)

convert a string into list

Parameters

[in]	text	source string
[in]	delimiter	the ASCII char which marks the split; e.g. comma ","; optional; default zero: extract white space separated words
[in]	splitFunc	function for splitting, default is oyjlStringSplit(); optional
[out]	count	number of detected string segments; optional
[out]	index	to be allocated array of detected delimiter indexes; The array will contain the list of indexes in text, which lead to the actual split positional index.; optional
[in]	alloc	custom allocator; optional, default is malloc

Returns: array of detected string segments

Referenced by oyjlStringSplit(), and oyjlStringsToDoubles().

◆ oyjlStringSplitUTF8()

int oyjlStringSplitUTF8	(	const char *	text,
		char ***	mbchars,
		void ()(size_t)	alloc
	)

split letters of a UTF-8 string

Parameters

[in]	text	source string in UTF-8 format
[out]	mbchars	NULL terminated array of count letters in UTF-8 format; optional
[in]	alloc	custom allocator; optional, default is malloc

Returns: count of letters

Version: Oyjl: 1.0.0

Date: 2020/04/23

Since: 2020/04/23 (Oyjl: 1.0.0)

◆ oyjlStringStartsWith()

int oyjlStringStartsWith	(	const char *	text,
		const char *	pattern
	)

simple and fast test

Parameters

text	string to be searched in
pattern	string to search in text

Returns: result is match

Version: Oyjl: 1.0.0

Date: 2023/05/21

Since: 2023/05/21 (Oyjl: 1.0.0)

Referenced by oyjlDataFormat().

◆ oyjlStringsToDoubles()

int oyjlStringsToDoubles	(	const char *	text,
		const char *	delimiter,
		int *	count,
		void ()(size_t)	alloc,
		double **	value
	)

text to double list

Parameters

[in]	text	source string
[in]	delimiter	the ASCII char(s) which mark the split; e.g. comma ","
[out]	count	number of detected string segments; optional
[in]	alloc	custom allocator; optional, default is malloc
[out]	value	array of detected number of count elements

Returns

error

0 : text input was completely read as number
-1 : text input was read as number with white space or other text after
1 : missed text input
2 : no number detected

Version: Oyranos: 0.9.7

Date: 2019/07/30

Since: 2019/01/23 (Oyranos: 0.9.7)

References oyjlStringSplit2().

◆ oyjlStringToDouble()

int oyjlStringToDouble	(	const char *	text,
		double *	value,
		const char **	end,
		int	flags
	)

text to double conversion

Parameters

[in]	text	string
[out]	value	resulting number
[out]	end	possibly part after number
[in]	flags	OYJL_KEEP_LOCALE; default is to switch actual LC_NUMERIC to "C"

Returns

error

0 : text input was completely read as number
-1 : text input was read as number with white space or other text after; can be seen in end argument
1 : missed text input
2 : no number detected

Version: Oyjl: 1.0.0

Date: 2022/04/17

Since: 2011/11/17 (Oyranos: 0.2.0)

References oyjlStringCopy().

Referenced by oyjlTreeGetNewValueFromArray().

◆ oyjlStringToLong()

int oyjlStringToLong	(	const char *	text,
		long *	value,
		const char **	end
	)

show better const behaviour and return instant error status over strtol()

Parameters

[in]	text	string
[out]	value	resulting number
[out]	end	possibly part after number

Returns

error

0 : text input was completely read as number
-1 : text input was read as number with white space or other text after; can be seen in end argument
1 : missed text input
2 : no number detected

◆ oyjlTermColorToPlain()

const char* oyjlTermColorToPlain	(	const char *	text,
		int flags
	)

remove term color marks

The OYJL_REGEXP flag uses: int count = oyjlRegExpReplace( &t, "\033[[0-9;]*m", "" ); .

Parameters

[in]	text	input
[in]	flags	support OYJL_REGEXP slower but work as well outside Oyjl

Returns: cleaned text

Version: Oyjl: 1.0.0

Date: 2022/06/04

Since: 2022/04/03 (Oyjl: 1.0.0)

References OYJL_REGEXP, oyjlRegExpReplace(), and oyjlStringCopy().

Functions

Detailed Description

Function Documentation

◆ oyjlRegExpEscape()

◆ oyjlRegExpFind()

◆ oyjlRegExpReplace()

◆ oyjlStr()

◆ oyjlStr_Add()

◆ oyjlStr_AppendN()

◆ oyjlStr_Clear()

◆ oyjlStr_New()

◆ oyjlStr_NewFrom()

◆ oyjlStr_Pull()

◆ oyjlStr_Push()

◆ oyjlStr_Release()

◆ oyjlStr_Replace()

◆ oyjlStr_SetCharAt()

◆ oyjlStringAdd()

◆ oyjlStringAddN()

◆ oyjlStringAppendN()

◆ oyjlStringCopy()

◆ oyjlStringListAdd()

◆ oyjlStringListAddList()

◆ oyjlStringListCatList()

◆ oyjlStringListFreeDoubles()

◆ oyjlStringListPush()

◆ oyjlStringListRelease()

◆ oyjlStringReplace()

◆ oyjlStringSplit()

◆ oyjlStringSplit2()

◆ oyjlStringSplitUTF8()

◆ oyjlStringStartsWith()

◆ oyjlStringsToDoubles()

◆ oyjlStringToDouble()

◆ oyjlStringToLong()

◆ oyjlTermColorToPlain()