Description

Extensions of std::string.

Author: Juan-Antonio Fernandez-Madrigal. http://jafma.net

Date: 2018-2020

Copyright: Copyright (c), Individual contributors, see AUTHORS file. This program is free for non-commercial uses. For the rest, contact the AUTHORS. Please include a mention in your programs to the main developer and the web page of the library.

Collaboration diagram for String extensions:

Classes
struct	elementa::base::is_charlike< T >
	Return TRUE if type T is char, wchar_t, char16_t or char32_t. More...

struct	elementa::base::is_charlike< char >
	Specialization of is_charlike for char. More...

struct	elementa::base::is_charlike< wchar_t >
	Specialization of is_charlike for wchar_t. More...

struct	elementa::base::is_charlike< char16_t >
	Specialization of is_charlike for char16_t. More...

struct	elementa::base::is_charlike< char32_t >
	Specialization of is_charlike for char32_t. More...

struct	elementa::base::IsStringHelperPriv< T >
	A struct with a void member. More...

struct	elementa::base::is_string< T, Enable >
	Template class to check whether T is derived from std::basic_string. More...

struct	elementa::base::is_string< T, typename IsStringHelperPriv< typename T::value_type, typename T::traits_type, typename T::allocator_type >::type >

class	elementa::base::Strings
	A number of strings. More...

Functions
bool	elementa::base::is_all_upper (const std::string &s) noexcept
	Return TRUE if all characters in S are uppercase. More...

bool	elementa::base::is_all_lower (const std::string &s) noexcept
	Return TRUE if all characters in S are lowercase. More...

constexpr bool	elementa::base::is_hex_digit (char c) noexcept
	Return TRUE if C is an hexadecimal digit, either in lower or uppercase. More...

bool	elementa::base::is_identifier (const std::string &s)
	Return TRUE if S is a standard identifier. More...

bool	elementa::base::is_number (const std::string &s, uint8_t base=10, bool onlyint=false)
	Return TRUE if S contains a number (possibly with sign) in some base. More...

constexpr bool	elementa::base::is_linechanger (char c)
	Return TRUE if C is a character involved in changing to new lines of text. More...

constexpr bool	elementa::base::is_blank (char c)
	Return TRUE if C is a tab or space character. More...

constexpr bool	elementa::base::is_separator (char c)
	Return TRUE if C is a separator character. More...

const std::vector< uint8_t > &	elementa::base::bytes_for_eol (void)
	Return a vector containing the bytes that form std::endl in this machine.

template<typename NumType >
std::string	elementa::base::to_string_dec (NumType n, bool padding=true)
	Convert an integral number to string in decimal format. More...

template<>
std::string	elementa::base::to_string_dec (uint8_t n, bool padding)
	Convert an integral number to string in decimal format. More...

template<typename NumType >
std::string	elementa::base::to_string_hex (NumType n, bool padding=true)
	Convert an integral number to string in hexadecimal format, without preffix. More...

template<typename NumType >
std::string	elementa::base::to_string_bin (NumType n, bool padding=true)
	Convert an integral number to string in binary format. More...

template<typename NumType >
std::string	elementa::base::to_string_oct (NumType n, bool padding=true)
	Convert an integral number to string in octal format. More...

template<typename NumType >
NumType	elementa::base::from_string_hex (const std::string &txt)
	Return the unsigned int. value of a number expressed in hexadecimal form. More...

template<typename NumType >
NumType	elementa::base::from_string_bin (const std::string &txt)
	Return the unsigned int. value of a number expressed in binary form. More...

std::string	elementa::base::real_to_string (LongestReal n)
	Convert a N to string with high precision. More...

std::string	elementa::base::real_to_string_fixdec (LongestReal n, unsigned ds)
	Convert N to string with a fixed number of decimal digits. *‍/.

std::string	elementa::base::char_to_string (char c)
	Convert a char to a string of 1 char. More...

template<typename PointedType >
std::string	elementa::base::hexdump (const PointedType *data, size_t howmany, bool toupp=true, bool sepelems=true)
	Return a string that represents all hex codes of the pointed bytes. More...

std::string	elementa::base::toCase (const std::string &s, char to)
	Convert a string into upper ('U') or lower ('L') case.

std::string &	elementa::base::ltrim_mut (std::string &s)
	Remove left space-like characters, modifying the input string directly. More...

std::string	elementa::base::ltrim (const std::string &s)
	Remove left space-like characters, creating a new string with the result. More...

std::string &	elementa::base::rtrim_mut (std::string &s)
	Remove right space-like characters, modifying the input string directly. More...

std::string	elementa::base::rtrim (const std::string &s)
	Remove right space-like characters, creating a new string with the result. More...

std::string &	elementa::base::trim_mut (std::string &s)
	Remove both right and left space-like characters, directly on input string. More...

std::string	elementa::base::trim (const std::string &s)
	Remove both right and left space-like characters, creating new string. More...

void	elementa::base::pad (std::string &s, size_t len, bool leftorright=false, char padding=' ')
	Pad S with character PADDING if shorter than LEN. More...

void	elementa::base::chop (std::string &s, size_t len, char excess=0x00, bool leftorright=false, char padding=' ')
	Chop S to a string of length LEN, padding it if necessary. More...

std::vector< std::string >	elementa::base::split (const std::string &s, char delim)
	Split a string through a given delimiter. More...

std::string	elementa::base::concatWithMiddle (const std::string &s1, const std::string &s2, const std::string &m=". ")
	Concatenate two strings putting a middle one only if the second is not empty.

std::string	elementa::base::indentlinedtext (const std::string &txt, bool atstarttoo=false, std::string::size_type maxlinelength=80, const std::string &newlinepreffix=" ", const std::string &newlinetext="\n")
	Return a string after splitting it into a number of indented lines. More...

Class Documentation

◆ elementa::base::is_charlike

struct elementa::base::is_charlike

template<typename T>
struct elementa::base::is_charlike< T >

Return TRUE if type T is char, wchar_t, char16_t or char32_t.

This is the general case of the template, for when T is not any of those.

Definition at line 63 of file strings.h.

Static Public Attributes
static constexpr bool	value = false

Member Data Documentation

◆ value

template<typename T >

constexpr bool elementa::base::is_charlike< T >::value = false

staticconstexpr

Definition at line 63 of file strings.h.

◆ elementa::base::is_charlike< char >

struct elementa::base::is_charlike< char >

Specialization of is_charlike for char.

Definition at line 67 of file strings.h.

Static Public Attributes
static constexpr bool	value = true

Member Data Documentation

◆ value

constexpr bool elementa::base::is_charlike< char >::value = true

staticconstexpr

Definition at line 67 of file strings.h.

◆ elementa::base::is_charlike< wchar_t >

struct elementa::base::is_charlike< wchar_t >

Specialization of is_charlike for wchar_t.

Definition at line 71 of file strings.h.

Static Public Attributes
static constexpr bool	value = true

Member Data Documentation

◆ value

constexpr bool elementa::base::is_charlike< wchar_t >::value = true

staticconstexpr

Definition at line 71 of file strings.h.

◆ elementa::base::is_charlike< char16_t >

struct elementa::base::is_charlike< char16_t >

Specialization of is_charlike for char16_t.

Definition at line 75 of file strings.h.

Static Public Attributes
static constexpr bool	value = true

Member Data Documentation

◆ value

constexpr bool elementa::base::is_charlike< char16_t >::value = true

staticconstexpr

Definition at line 75 of file strings.h.

◆ elementa::base::is_charlike< char32_t >

struct elementa::base::is_charlike< char32_t >

Specialization of is_charlike for char32_t.

Definition at line 79 of file strings.h.

Static Public Attributes
static constexpr bool	value = true

Member Data Documentation

◆ value

constexpr bool elementa::base::is_charlike< char32_t >::value = true

staticconstexpr

Definition at line 79 of file strings.h.

◆ elementa::base::IsStringHelperPriv

struct elementa::base::IsStringHelperPriv

template<typename... T>
struct elementa::base::IsStringHelperPriv< T >

A struct with a void member.

A struct that, whatever template parameters we use, has a type member that is void

Definition at line 92 of file strings.h.

Class Members
typedef void	type

◆ elementa::base::is_string

struct elementa::base::is_string

template<typename T, class Enable = void>
struct elementa::base::is_string< T, Enable >

Template class to check whether T is derived from std::basic_string.

Note: - Do not use anything in the second parameter: leave it by default.; - This is taken from https://stackoverflow.com/a/5095898

Definition at line 101 of file strings.h.

Inheritance diagram for elementa::base::is_string< T, Enable >:

[legend]

Collaboration diagram for elementa::base::is_string< T, Enable >:

[legend]

◆ elementa::base::is_string< T, typename IsStringHelperPriv< typename T::value_type, typename T::traits_type, typename T::allocator_type >::type >

struct elementa::base::is_string< T, typename IsStringHelperPriv< typename T::value_type, typename T::traits_type, typename T::allocator_type >::type >

template<typename T>
struct elementa::base::is_string< T, typename IsStringHelperPriv< typename T::value_type, typename T::traits_type, typename T::allocator_type >::type >

Definition at line 105 of file strings.h.

Inheritance diagram for elementa::base::is_string< T, typename IsStringHelperPriv< typename T::value_type, typename T::traits_type, typename T::allocator_type >::type >:

[legend]

Collaboration diagram for elementa::base::is_string< T, typename IsStringHelperPriv< typename T::value_type, typename T::traits_type, typename T::allocator_type >::type >:

[legend]

◆ elementa::base::Strings

class elementa::base::Strings

A number of strings.

Definition at line 563 of file strings.h.

Inheritance diagram for elementa::base::Strings:

[legend]

Collaboration diagram for elementa::base::Strings:

[legend]

Public Types
using	Base = std::vector< std::string >

Public Attributes
T	elements
	STL member.

Public Member Functions
std::string	to_string (const std::string &preffix="", const std::string &beg="{", const std::string &end="}") const
	Return a string formed by all the strings as a set. More...

Member Typedef Documentation

◆ Base

using elementa::base::Strings::Base = std::vector<std::string>

Definition at line 567 of file strings.h.

Member Function Documentation

◆ to_string()

std::string elementa::base::Strings::to_string	(	const std::string &	preffix = `""`,
		const std::string &	beg = `"{"`,
		const std::string &	end = `"}"`
	)		const

Return a string formed by all the strings as a set.

Creates a string that contains the sequece of strings separated by ", " and with PREFFIX appended before each of the strings. The result begins with BEG and ends with END.

Function Documentation

◆ is_all_upper()

bool elementa::base::is_all_upper ( const std::string & s )

noexcept

#include <elementa/base/strings.h>

Return TRUE if all characters in S are uppercase.

Characters that cannot be upper or lower case (e.g., space, digits, underscore) are ignored. An empty S produces TRUE.

◆ is_all_lower()

bool elementa::base::is_all_lower ( const std::string & s )

noexcept

#include <elementa/base/strings.h>

Return TRUE if all characters in S are lowercase.

Characters that cannot be upper or lower case (e.g., space, digits, underscore) are ignored. An empty S produces TRUE.

◆ is_hex_digit()

constexpr bool elementa::base::is_hex_digit ( char c )

constexprnoexcept

#include <elementa/base/strings.h>

Return TRUE if C is an hexadecimal digit, either in lower or uppercase.

Definition at line 152 of file strings.h.

◆ is_identifier()

bool elementa::base::is_identifier ( const std::string & s )

#include <elementa/base/strings.h>

Return TRUE if S is a standard identifier.

A standard identifier is an non-empty, any-length string that only contains digits, letters (upper or lower) and '_', and does not begin with a digit.

◆ is_number()

bool elementa::base::is_number	(	const std::string &	s,
		uint8_t	base = `10`,
		bool	onlyint = `false`
	)

#include <elementa/base/strings.h>

Return TRUE if S contains a number (possibly with sign) in some base.

Return FALSE if S is empty.

Parameters

base	is the base. It can be 2,8,10,16.
onlyint	indicates whether to test for integers only, or also for reals. It is ignored and testing done only for integers in the case that base is not 10.

Note: - Scientific notation is not supported.

◆ is_linechanger()

constexpr bool elementa::base::is_linechanger ( char c )

constexpr

#include <elementa/base/strings.h>

Return TRUE if C is a character involved in changing to new lines of text.

Definition at line 174 of file strings.h.

Referenced by elementa::base::is_separator().

◆ is_blank()

constexpr bool elementa::base::is_blank ( char c )

constexpr

#include <elementa/base/strings.h>

Return TRUE if C is a tab or space character.

Definition at line 178 of file strings.h.

Referenced by elementa::base::is_separator().

◆ is_separator()

constexpr bool elementa::base::is_separator ( char c )

constexpr

#include <elementa/base/strings.h>

Return TRUE if C is a separator character.

Definition at line 182 of file strings.h.

References elementa::base::is_blank(), and elementa::base::is_linechanger().

◆ to_string_dec() [1/2]

template<typename NumType >

std::string elementa::base::to_string_dec	(	NumType	n,
		bool	padding = `true`
	)

#include <elementa/base/strings.h>

Convert an integral number to string in decimal format.

If PADDING, fill with 0 the most significant part of the number up to the length of the greatest number of that size; otherwise, get rid of those 0's.

Definition at line 209 of file strings.h.

◆ to_string_dec() [2/2]

template<>

std::string elementa::base::to_string_dec	(	uint8_t	n,
		bool	padding
	)

#include <elementa/base/strings.h>

Convert an integral number to string in decimal format.

If PADDING, fill with 0 the most significant part of the number up to the length of the greatest number of that size; otherwise, get rid of those 0's.

◆ to_string_hex()

template<typename NumType >

std::string elementa::base::to_string_hex	(	NumType	n,
		bool	padding = `true`
	)

#include <elementa/base/strings.h>

Convert an integral number to string in hexadecimal format, without preffix.

If PADDING, fill with 0 the most significant part of the number up to the length of the greatest number of that size; otherwise, get rid of those 0's.

Definition at line 234 of file strings.h.

Referenced by elementa::base::hexdump().

◆ to_string_bin()

template<typename NumType >

std::string elementa::base::to_string_bin	(	NumType	n,
		bool	padding = `true`
	)

#include <elementa/base/strings.h>

Convert an integral number to string in binary format.

If PADDING, fill with 0 the most significant part of the number up to the length of the greatest number of that size; otherwise, get rid of those 0's.

Definition at line 253 of file strings.h.

◆ to_string_oct()

template<typename NumType >

std::string elementa::base::to_string_oct	(	NumType	n,
		bool	padding = `true`
	)

#include <elementa/base/strings.h>

Convert an integral number to string in octal format.

If PADDING, fill with 0 the most significant part of the number up to the length of the greatest number of that size; otherwise, get rid of those 0's.

Definition at line 267 of file strings.h.

◆ from_string_hex()

template<typename NumType >

NumType elementa::base::from_string_hex ( const std::string & txt )

#include <elementa/base/strings.h>

Return the unsigned int. value of a number expressed in hexadecimal form.

The hexadecimal string may contain letters a-f in upper or lower case, and the calculation ends when, scanning from its end to its start, a non-digit, non a-f character is found.

Definition at line 286 of file strings.h.

◆ from_string_bin()

template<typename NumType >

NumType elementa::base::from_string_bin ( const std::string & txt )

#include <elementa/base/strings.h>

Return the unsigned int. value of a number expressed in binary form.

The binary string may contain digits 0-1 only, and the calculation ends when, scanning from its end to its start, a non-0-1-digit is found.

Definition at line 315 of file strings.h.

◆ real_to_string()

std::string elementa::base::real_to_string ( LongestReal n )

#include <elementa/base/strings.h>

Convert a N to string with high precision.

The std::to_string only works with 6 decimal places.

◆ char_to_string()

std::string elementa::base::char_to_string ( char c )

#include <elementa/base/strings.h>

Convert a char to a string of 1 char.

This methods should only be used to create a char into a new string; for concatenating a char to an existing string, just use the string '+' operator.

◆ hexdump()

template<typename PointedType >

std::string elementa::base::hexdump	(	const PointedType *	data,
		size_t	howmany,
		bool	toupp = `true`,
		bool	sepelems = `true`
	)

#include <elementa/base/strings.h>

Return a string that represents all hex codes of the pointed bytes.

Each element is separated from the next one by a space if SEPELEMS == TRUE.

Definition at line 349 of file strings.h.

References elementa::base::to_string_hex().

◆ ltrim_mut()

std::string & elementa::base::ltrim_mut ( std::string & s )

inline

#include <elementa/base/strings.h>

Remove left space-like characters, modifying the input string directly.

Note: - Code taken from https://stackoverflow.com/questions/216823/whats-the-best-way-to-trim-stdstring

Definition at line 400 of file strings.h.

Referenced by elementa::base::ltrim(), and elementa::base::trim_mut().

◆ ltrim()

std::string elementa::base::ltrim ( const std::string & s )

inline

#include <elementa/base/strings.h>

Remove left space-like characters, creating a new string with the result.

Definition at line 413 of file strings.h.

References elementa::base::ltrim_mut().

◆ rtrim_mut()

std::string & elementa::base::rtrim_mut ( std::string & s )

inline

#include <elementa/base/strings.h>

Remove right space-like characters, modifying the input string directly.

Note: - Code taken from https://stackoverflow.com/questions/216823/whats-the-best-way-to-trim-stdstring

Definition at line 425 of file strings.h.

Referenced by elementa::base::rtrim(), and elementa::base::trim_mut().

◆ rtrim()

std::string elementa::base::rtrim ( const std::string & s )

inline

#include <elementa/base/strings.h>

Remove right space-like characters, creating a new string with the result.

Definition at line 433 of file strings.h.

References elementa::base::rtrim_mut().

◆ trim_mut()

std::string & elementa::base::trim_mut ( std::string & s )

inline

#include <elementa/base/strings.h>

Remove both right and left space-like characters, directly on input string.

Definition at line 441 of file strings.h.

References elementa::base::ltrim_mut(), and elementa::base::rtrim_mut().

Referenced by elementa::base::trim().

◆ trim()

std::string elementa::base::trim ( const std::string & s )

inline

#include <elementa/base/strings.h>

Remove both right and left space-like characters, creating new string.

Definition at line 447 of file strings.h.

References elementa::base::trim_mut().

◆ pad()

void elementa::base::pad	(	std::string &	s,
		size_t	len,
		bool	leftorright = `false`,
		char	padding = `' '`
	)

#include <elementa/base/strings.h>

Pad S with character PADDING if shorter than LEN.

Pad to the right if LEFTORRIGHT == FALSE or to the left if TRUE. If the size of the string is greater or equal to LEN, do nothing.

◆ chop()

void elementa::base::chop	(	std::string &	s,
		size_t	len,
		char	excess = `0x00`,
		bool	leftorright = `false`,
		char	padding = `' '`
	)

#include <elementa/base/strings.h>

Chop S to a string of length LEN, padding it if necessary.

If EXCESS is not 0x00 and S is longer than LEN, the last character will be EXCESS after chopping to LEN characters.

◆ split()

std::vector< std::string > elementa::base::split	(	const std::string &	s,
		char	delim
	)

#include <elementa/base/strings.h>

Split a string through a given delimiter.

Split a given (immutable) string into several ones, guided by a delimiter character. The delimiter is not included in the resulting strings. A delimiter followed by the end of the string and an empty part followed by a delimiter are counted as parts of the splitting.

Referenced by elementa::base::EnumExtPriv< BaseID, HelperIDString >::IdName().

◆ indentlinedtext()

std::string elementa::base::indentlinedtext	(	const std::string &	txt,
		bool	atstarttoo = `false`,
		std::string::size_type	maxlinelength = `80`,
		const std::string &	newlinepreffix = `" "`,
		const std::string &	newlinetext = `"\n"`
	)

#include <elementa/base/strings.h>

Return a string after splitting it into a number of indented lines.

This routine is very useful to format tabulated long texts with limited number of columns. It scans the original text to produce the split one. It substitutes any sequence of blanks (the ones identified by is_blank()) by 1 space, and then make the splitting. If it finds a line changing character (is_linechanger()) forces a splitting there, dropping that character and any other consecutive one that is also line changing but different (i.e., sequences "'\n\r'" or "'\r\n'"). Any other character is considered a non-separator.

If a line scanned that way extends beyond MAXLINELENGTH characters, or a line changing char is found, the text NEWLINETEXT + NEWLINEPREFFIX will substitute the previous last found separator along the line. NEWLINEPREFFIX cannot contain line changing characters.

Notice that this way of working prevents the recursive use of this function to split/indent already split/indented texts.

An exception is thrown if there is no separators along a line that needs to be splitted, since in that case no place to do the splitting can be chosen.

If MAXLINELENGTH == 0, no split will be done after any length.

If ATSTARTTOO == TRUE, NEWLINEPREFFIX will be also inserted at the beginning of the text.

Examples:

\code
    // This prints in console a text tabulated 4 spaces before each line,
    // including the first one, but without maximum length in lines:
    // (note that any ending \n in TXT will do the newline PLUS adding the
    // tabs in that new line.

    std:: cout << indentboundtext(txt,true,0,"    ");

    // This prints in console a text splitted at correct word-endings with
    // longest lines of 80 characters, and tabulated 8 spaces each line,
    // without indenting the first one:

    std::cout << indentboundtext(txt,false,80,"        ");
\endcode

Description

Classes

Functions

Class Documentation

◆ elementa::base::is_charlike

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_charlike< char >

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_charlike< wchar_t >

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_charlike< char16_t >

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::is_charlike< char32_t >

Static Public Attributes

Member Data Documentation

◆ value

◆ elementa::base::IsStringHelperPriv

◆ elementa::base::is_string

◆ elementa::base::is_string< T, typename IsStringHelperPriv< typename T::value_type, typename T::traits_type, typename T::allocator_type >::type >

◆ elementa::base::Strings

Public Types

Public Attributes

Public Member Functions

Member Typedef Documentation

◆ Base

Member Function Documentation

◆ to_string()

Function Documentation

◆ is_all_upper()

◆ is_all_lower()

◆ is_hex_digit()

◆ is_identifier()

◆ is_number()

◆ is_linechanger()

◆ is_blank()

◆ is_separator()

◆ to_string_dec() [1/2]

◆ to_string_dec() [2/2]

◆ to_string_hex()

◆ to_string_bin()

◆ to_string_oct()

◆ from_string_hex()

◆ from_string_bin()

◆ real_to_string()

◆ char_to_string()

◆ hexdump()

◆ ltrim_mut()

◆ ltrim()

◆ rtrim_mut()

◆ rtrim()

◆ trim_mut()

◆ trim()

◆ pad()

◆ chop()

◆ split()

◆ indentlinedtext()