This page has been translated automatically.
Video Tutorials
Interface
Essentials
Advanced
How To
Basics
Rendering
Professional (SIM)
UnigineEditor
Interface Overview
Assets Workflow
Version Control
Settings and Preferences
Working With Projects
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Lighting
Sandworm
Using Editor Tools for Specific Tasks
Extending Editor Functionality
Built-in Node Types
Nodes
Objects
Effects
Decals
Light Sources
Geodetics
World Nodes
Sound Objects
Pathfinding Objects
Players
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Plugins
File Formats
Materials and Shaders
Rebuilding the Engine Tools
GUI
Double Precision Coordinates
API
Animations-Related Classes
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
VR-Related Classes
Content Creation
Content Optimization
Materials
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Tutorials

Unigine::String class

Header: #include <UnigineString.h>

Provides an interface to work with input and output data packed into the internal (not C++ standard) String class. Strings are stored in a heap, so they are slower than StringStack strings.

Such strings are typically used in the following cases:

  • When you create a string to be passed to a container.
    Source code (C++)
    #include <UnigineString.h>
    #include <UnigineVector.h>
    
    using namespace Unigine;
    
    String AppWorldLogic::get_title()
    {
    	String s = WindowManager::getMainWindow()->getTitle();
    	s += " Window";
    
    	return s;
    }
    
    int AppWorldLogic::init()
    {
    	Vector<String> v;
    	// create a string
    	String s = "Modifier ";
    	s += get_title();
    	
    	// add it to the vector
    	v.append(std::move(s));
    
    
    	// do something with the vector
    	// ...
    
    	return 1;
    }
  • When you create a string to be used as the return value of the function.
    Source code (C++)
    String AppWorldLogic::get_title()
    {
    	String s = WindowManager::getMainWindow()->getTitle();
    	s += " Window";
    
    	return s;
    }
  • When you store a string that represents the function return value, and you don't intend to modify it.
    Source code (C++)
    void AppWorldLogic::log_file_guid(const UGUID &guid)
    {
    	// string that stores an external function return value
    	const String str = FileSystem::getAbsolutePath(guid);
    	Log::message("Path: %s\n", str.get());
    }
    Notice
    Pay attention to the type of the function return value to optimally use it. It may help you to avoid addressing the cleared memory or another issue.
    Source code (C++)
    // String returned by this function will be automatically deleted
    const char *s = FileSystem::getAbsolutePath(guid);
    // and the s pointer will now point to the freed memory
    Log::message("Path: %s\n", s); 		// the application may crash
  • When you store large texts (for example, read from a file).

Strings support Small String Optimization (SSO): you can store 7 characters along with the null termination symbol. It means that the following code will not cause dynamic memory allocation:

Source code (C++)
String s = “1234567”;

String Class

Members


String ( ) #

Default constructor that creates an empty string.

String ( const String & s ) #

Copy constructor.

Arguments

  • const String & s - String to be copied.

String ( const char * s ) #

Copy constructor.

Arguments

  • const char * s - Pointer to the null-terminated string.

String ( const wchar_t * s ) #

Explicit constructor for a wide-character string.

Arguments

  • const wchar_t * s - Pointer to the wide-character null-terminated string.

String ( const unsigned int * s ) #

Explicit constructor for a string from unsigned characters.

Arguments

  • const unsigned int * s - Pointer to the null-terminated string from unsigned characters.

String ( String && s ) #

Constructor. Creates a string by copying a source string.

Arguments

  • String && s - Source string.

String ( const char * s, int size ) #

Constructor. Creates a string of a defined size from the array of symbols.

Arguments

  • const char * s - Pointer to the null-terminated string.
  • int size - Size of the string.

const char * get ( ) #

Returns the pointer to the null-terminated string.

Return value

The null-terminated string.

char get ( int index ) #

Returns an n-th character of the string.

Arguments

  • int index - index of a character in range [0;string_length - 1].
    Notice
    If the given index is out of the range bounds, the engine assertion will occur.

Return value

An n-th character.

char & get ( int index ) #

Returns an n-th character of the string.

Arguments

  • int index - index of a character in range [0;string_length - 1].
    Notice
    If the given index is out of the range bounds, the engine assertion will occur.

Return value

An n-th character.

static bool isalpha ( int code ) #

Checks whether code is an alphabetic letter.

Arguments

  • int code - Character to be checked, cast to an int.

Return value

true if the code is an alphabetic character; otherwise, false.

static bool isdigit ( int code ) #

Checks whether code is a decimal digit character.

Arguments

  • int code - Character to be checked, cast to an int.

Return value

true if the code is a decimal digit character; otherwise, false.

double getDouble ( ) #

Returns the current string as a double value.

Return value

The value of the variable.

float getFloat ( ) #

Returns the current string as a float value.

Return value

The value of the variable.

int getInt ( ) #

Returns the current string as an integer value.

Return value

The value of the variable.

long long getLong ( ) #

Returns the current string as a long long value.

Return value

The value of the variable.

StringStack<> getLower ( ) #

Returns the string stack with all letters being lower-case.

Return value

Lower-cased string stack.

StringStack<> getUpper ( ) #

Returns the string stack with all letters being upper-case.

Return value

Upper-cased string stack.

static bool islower ( int code ) #

Checks whether code is a lower-case letter.

Arguments

  • int code - Character to be checked, cast to an int.

Return value

true if the code is a lower-case character; otherwise, false.

static bool isspace ( int code ) #

Checks whether code is a space or a horizontal tab character.

Arguments

  • int code - Character to be checked, cast to an int.

Return value

true if the code is a space a horizontal tab character; otherwise, false.

static bool isupper ( int code ) #

Checks whether code is an upper-case letter.

Arguments

  • int code - Character to be checked, cast to an int.

Return value

true if the code is an upper-case character; otherwise, false.

static StringStack<> absname ( const char * path, const char * str ) #

Returns an absolute path for given paths.

Arguments

  • const char * path - A working directory path.
  • const char * str - A destination path.

Return value

An absolute pathname.

Examples

Source code (C++)
String path = String::absname(engine.engine->getDataPath().get(), "bake_lighting/");
//path: C:/Projects/Sample/data/bake_lighting/

static StringStack<> addslashes ( const char * str ) #

Modifies a string by putting backslashes before control characters that need escaping.

Arguments

  • const char * str - A string with control characters that need escaping.

Return value

The modified str string with escaped control characters.

void allocate ( int size ) #

Allocates the required memory.

Arguments

  • int size - Size of the allocated memory in bytes.

String & append ( const String & s, int size ) #

Appends a given string to the end of the string.

Arguments

  • const String & s - String to append.
  • int size - Length of the string to be appended.

Return value

Resulting string.

String & append ( char c ) #

Appends a given symbol to the end of the string.

Arguments

  • char c - Symbol to append.

Return value

Resulting string.

String & append ( int pos, char c ) #

Inserts a given symbol at the specified position.

Arguments

  • int pos - Insertion position.
  • char c - Symbol to insert.

Return value

Resulting string.

String & append ( const char * s, int size ) #

Appends a given null-terminated string to the end of the string.

Arguments

  • const char * s - Null-terminated string to append.
  • int size - Length of the null-terminated string to be appended.

Return value

Resulting string.

String & append ( int pos, const char * s, int size ) #

Inserts a given null-terminated string at the specified position.

Arguments

  • int pos - Insertion position.
  • const char * s - Null-terminated string to insert.
  • int size - Length of the null-terminated string to be inserted.

Return value

Resulting string.

String & append ( int pos, const String & s, int size ) #

Inserts a given string at the specified position.

Arguments

  • int pos - Insertion position.
  • const String & s - String to insert.
  • int size - Length of the string to be inserted.

Return value

Resulting string.

String & append ( String && s, int size ) #

Appends a given string to the end of the string.

Arguments

  • String && s - String to append.
  • int size - Length of the string to be appended.

Return value

Resulting string.

static double atod ( const char * str ) #

Parses the str string and returns it as a double value.

Arguments

  • const char * str - A string.

Return value

Double value of the str string.

static float atof ( const char * str ) #

Parses the str string and returns it as a float value.

Arguments

  • const char * str - A string.

Return value

Float value of the str string.

static int atoi ( const char * str ) #

Parses the str string and returns it as an integer value.

Arguments

  • const char * str - A string.

Return value

Integer value of the str string.

static long long atol ( const char * str ) #

Parses the str string and returns it as a long long value.

Arguments

  • const char * str - A string.

Return value

Long long value of the str string.

String basename ( ) #

Returns a filename with extension extracted from the current string.

Return value

A string containing filename with extension.

static StringStack<> basename ( const char * str ) #

Extracts filename with extension from the str string and returns it.

Arguments

  • const char * str - Path to file.

Return value

Filename with extension.
Notice
If the input string does not contain a full stop ('.'), the same value as the str value will be returned.

Examples

Source code (C++)
String base = String::basename("C:/Projects/Sample/data/textures/albedo.png");
//base: albedo.png

void clear ( ) #

Clears the string.

static int compare ( const char * str0, const char * str1 ) #

Compares the string str0 to the string str1 character by character.

Arguments

  • const char * str0 - a string to be compared.
  • const char * str1 - a string to be compared.

Return value

A value indicating the relationship between the strings:
  • 0 — the contents of both strings are equal.
  • other value — the contents of strings do not coincide.

static int compare ( const char * str0, const char * str1, int case_sensitive ) #

Compares the string str0 to the string str1 character by character taking into account the character case — upper or lower.

Arguments

  • const char * str0 - a string to be compared.
  • const char * str1 - a string to be compared.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise, case is ignored.

Return value

A value indicating the relationship between the strings:
  • 0 — the contents of both strings are equal.
  • another value — the contents of strings do not coincide.

int contains ( const char * s, int case_sensitive ) #

Checks whether the current string contains the s substring.

Arguments

  • const char * s - A string.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

1 if the current string contains the s substring; otherwise, 0.

int contains ( const String & s, int case_sensitive ) #

Checks whether the current string contains the s substring.

Arguments

  • const String & s - A string.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

1 if the current string contains the s substring; otherwise, 0.

int contains ( char c, int case_sensitive ) #

Checks whether the current string contains the c character.

Arguments

  • char c - A character.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

1 if the current string contains the c character; otherwise, 0.

void copy ( const char * s, int size ) #

Copies size characters from the s string to the current string.

Arguments

  • const char * s - A source string.
  • int size - Number of characters to be copied.

void copy ( const String & s, int size ) #

Copies size characters from the s string to the current string.

Arguments

  • const String & s - A source string.
  • int size - Number of characters to be copied.

void destroy ( ) #

Destroys the string.

String dirname ( ) #

Returns a parent directory's path from the current string.

Return value

The directory's path without filename and extension.

static StringStack<> dirname ( const char * str ) #

Returns a parent directory's path extracted from the str string.

Arguments

  • const char * str - Path to file

Return value

The directory's path without filename and extension.
Notice
If the str string does not meet path syntax, an empty value will be returned.

Examples

Source code (C++)
String dir = String::dirname("C:/Projects/Sample/data/textures/albedo.png");
// dir: C:/Projects/Sample/data/textures/

void do_append ( char c ) #

Appends a given symbol to the end of the current string.

Arguments

  • char c - Symbol to append.

void do_append ( int pos, char c ) #

Inserts a given symbol at the specified position of the current string.

Arguments

  • int pos - Insertion position.
  • char c - Symbol to insert.

void do_append ( int pos, const char * s, int size ) #

Inserts a given null-terminated string at the specified position of the current string.

Arguments

  • int pos - Insertion position.
  • const char * s - Null-terminated string to insert.
  • int size - Length of the null-terminated string to be inserted.

void do_append ( const char * s, int size ) #

Appends a given null-terminated string to the end of the string.

Arguments

  • const char * s - Null-terminated string to append.
  • int size - Length of the null-terminated string to be appended.

void do_assign ( const char * s, int size ) #

Assigns a new value to the string, replacing its current contents with first size characters pointed by s.

Arguments

  • const char * s - The null-terminated string.
  • int size - Number of characters.

void do_copy ( const char * s, int size ) #

Copies size characters from the s string to the current string.

Arguments

  • const char * s - A source null-terminated string.
  • int size - Number of characters to be copied.

static StringStack<> dtoa ( double value, int precision, int use_inf ) #

Converts a double value to a string using specified precision.

Arguments

  • double value - An input value.
  • int precision - Precision in the range [-1; 17]. Data is represented the following way:
    Precision Representation Example
    -1 The shortest representation: decimal floating point or scientific notation (mantissa/exponent). 2.6265e+2
    0-8 Decimal floating point. 262.65
    9-17 The shortest representation: decimal floating point or scientific notation (mantissa/exponent) with the precision digits to be printed after the decimal point. 2.6264999e+2
  • int use_inf - A flag indicating whether to use -inf and inf values if the input value is out of the range (-1e9; 1e9).

Return value

A string representation of the value.

int empty ( ) #

Returns an empty flag.

Return value

1 if the string is empty; otherwise, 0.

int endsWith ( const char * s, int case_sensitive, int size ) #

Checks whether the current string ends with size characters of the s substring.

Arguments

  • const char * s - A string.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.
  • int size - Number of characters to be checked starting from the beginning.

Return value

1 if the current string ends with the specified substring; otherwise, 0.

int endsWith ( const String & s, int case_sensitive, int size ) #

Checks whether the current string ends with size characters of the s substring.

Arguments

  • const String & s - A string.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.
  • int size - Number of characters to be checked starting from the beginning.

Return value

1 if the current string ends with the specified substring; otherwise, 0.

static int endsWith ( const char * data, const char * str, int case_sensitive, int data_size, int str_size ) #

Checks whether the data string ends with the str substring.

Arguments

  • const char * data - A string.
  • const char * str - A substring.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.
  • int data_size - Size of the string to be checked.
  • int str_size - Number of substring characters to be checked starting from the beginning.

Return value

1 if the string ends with the specified substring; otherwise, 0.

String extension ( ) #

Parses the current string as a path and returns a filename extension.

Return value

Extension name if there is one in the current string; otherwise, empty string.

static StringStack<> extension ( const char * str ) #

Parses a given string as a path and returns a filename extension.

Arguments

  • const char * str - A string to be parsed.

Return value

Extension name if there is one in the given string; otherwise, empty string.

Examples

Source code (C++)
String ext = String::extension("C:/Projects/Sample/data/textures/albedo.png");
// ext: png

static StringStack<> extension ( const char * str, const char * ext ) #

Modifies a given path by replacing a file extension with a specified one.

Arguments

  • const char * str - A path.
  • const char * ext - An extension.

Return value

A modified path.

Examples

Source code (C++)
String ext = String::extension("/textures/albedo.png", "tif");
// ext: /textures/albedo.tif

String filename ( ) #

Returns a filename extracted from the current string without extension.

Return value

A string containing filename without extension.

static StringStack<> filename ( const char * str ) #

Extracts filename from the str string and returns it without extension.
Notice
If the input string does not contain a full stop, an empty string will be returned.

Arguments

  • const char * str - Path to file.

Return value

Filename without extension.

Examples

Source code (C++)
String filename = String::filename("/textures/albedo.png");
// filename: albedo

int find ( char c, int case_sensitive ) #

Searches the string for the first occurrence of c character and returns its index.

Arguments

  • char c - A character.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

Index of a specified character if at least one match was found; otherwise, -1.

int find ( const String & s, int case_sensitive ) #

Searches the string for the first occurrence of s substring and returns its index.

Arguments

  • const String & s - A substring.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

Index of the first character of a specified string if at least one match was found; otherwise, -1.

int find ( const char * s, int case_sensitive ) #

Searches the string for the first occurrence of s substring and returns its index.

Arguments

  • const char * s - A substring.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

Index of the first character of a specified string if at least one match was found; otherwise, -1.

char first ( ) #

Returns the first character of the current string.

Return value

The first character.

char & first ( ) #

Returns the first character of the current string.

Return value

The first character.

static StringStack<> format ( const char * format, va_list argptr ) #

Returns a stack of formatted strings. A format string is composed of zero or more ordinary characters (excluding %) that are copied directly to the result string and control sequences, each of which results in fetching its own parameter. Each control sequence consists of a percent sign (%) followed by one or more of these elements, in order:
  • An optional number, a width specifier, that says how many characters (minimum) this conversion should result in.
  • An optional precision specifier that says how many decimal digits should be displayed for floating-point numbers.
  • A type specifier that says what type the argument data should be treated as. Possible types:
    • c: the argument is treated as an integer and presented as a character with that ASCII value.
    • d or i: the argument is treated as an integer and presented as a (signed) decimal number.
    • o: the argument is treated as an integer and presented as an octal number.
    • u: the argument is treated as an integer and presented as an unsigned decimal number.
    • x: the argument is treated as an integer and presented as a hexadecimal number (with lower-case letters).
    • X: the argument is treated as an integer and presented as a hexadecimal number (with upper-case letters).
    • f: the argument is treated as a float and presented as a floating-point number.
    • g: the same as e or f, the shortest one is selected.
    • G: the same as E or F, the shortest one is selected.
    • e: the argument is treated as using the scientific notation with lower-case 'e' (e.g. 1.2e+2).
    • E: the argument is treated as using the scientific notation with upper-case 'E' (e.g. 1.2E+2).
    • s: the argument is treated as and presented as a string.
    • p: the argument is treated as and presented as a pointer address.
    • %: a literal percent character. No argument is required.

Arguments

  • const char * format - Format string.
  • va_list argptr - Arguments pointer.

Return value

Stack of formatted strings.

StringStack<> format ( const char * format ) #

Returns a stack of formatted strings. A format string is composed of zero or more ordinary characters (excluding %) that are copied directly to the result string and control sequences, each of which results in fetching its own parameter. Each control sequence consists of a percent sign (%) followed by one or more of these elements, in order:
  • An optional number, a width specifier, that says how many characters (minimum) this conversion should result in.
  • An optional precision specifier that says how many decimal digits should be displayed for floating-point numbers.
  • A type specifier that says what type the argument data should be treated as. Possible types:
    • c: the argument is treated as an integer and presented as a character with that ASCII value.
    • d or i: the argument is treated as an integer and presented as a (signed) decimal number.
    • o: the argument is treated as an integer and presented as an octal number.
    • u: the argument is treated as an integer and presented as an unsigned decimal number.
    • x: the argument is treated as an integer and presented as a hexadecimal number (with lower-case letters).
    • X: the argument is treated as an integer and presented as a hexadecimal number (with upper-case letters).
    • f: the argument is treated as a float and presented as a floating-point number.
    • g: the same as e or f, the shortest one is selected.
    • G: the same as E or F, the shortest one is selected.
    • e: the argument is treated as using the scientific notation with lower-case 'e' (e.g. 1.2e+2).
    • E: the argument is treated as using the scientific notation with upper-case 'E' (e.g. 1.2E+2).
    • s: the argument is treated as and presented as a string.
    • p: the argument is treated as and presented as a pointer address.
    • %: a literal percent character. No argument is required.

Arguments

  • const char * format - Format string.

Return value

Stack of formatted strings.

static StringStack<> ftoa ( float value, int precision ) #

Converts a float value to a string using specified precision.

Arguments

  • float value - An input value.
  • int precision - Precision in the range [-1; 17]. Data is represented the following way:
    Precision Representation Example
    -1 The shortest representation: decimal floating point or scientific notation (mantissa/exponent). 2.6265e+2
    0-8 Decimal floating point. 262.65
    9-17 The shortest representation: decimal floating point or scientific notation (mantissa/exponent) with the precision digits to be printed after the decimal point. 2.6264999e+2

Return value

A string representation of the value.

int grow_to ( int new_length ) #

Returns the actual length of a string corresponding to amount of memory which is enough to contain at least the specified number of items.

Arguments

  • int new_length - Minimum string length.

Return value

String length.

static unsigned int hash ( const char * str, int size ) #

Returns a hash value of a given string.

Arguments

  • const char * str - A string.
  • int size - Length of string to be hashed.

Return value

Hash value.

static StringStack<> itoa ( int value, int radix ) #

Returns string representation of a given decimal value.

Arguments

  • int value - An input decimal value.
  • int radix - Numerical base used to represent the value as a string, between 2 and 16, where 10 means decimal base, 16 hexadecimal, 8 octal, and 2 binary.

Return value

String representation of a specified integer.

static StringStack<> joinPaths ( const char * p0, const char * p1 ) #

Concatenates two paths and returns normalized result.

Arguments

  • const char * p0 - First part of the path (mainly a directory path).
  • const char * p1 - Second part of the path.

Return value

Resulting path.

static StringStack<> joinPaths ( const char * p0, const String & p1 ) #

Concatenates two paths and returns a normalized result.

Arguments

  • const char * p0 - the first part of the path.
  • const String & p1 - the second part of the path.

Return value

Resulting path.

static StringStack<> joinPaths ( const String & p0, const char * p1 ) #

Concatenates two paths and returns a normalized result.

Arguments

  • const String & p0 - the first part of the path.
  • const char * p1 - the second part of the path.

Return value

Resulting path.

static StringStack<> joinPaths ( const String & p0, const String & p1 ) #

Concatenates two paths and returns normalized result.

Arguments

  • const String & p0 - the first part of the path.
  • const String & p1 - the second part of the path.

Return value

Resulting path.

static String & joinPaths ( String & ret, const char * p0, const char * p1, int size0, int size1 ) #

Concatenates two paths of a defined size and returns a normalized result.

Arguments

  • String & ret - a string to store the result.
  • const char * p0 - the first part of the path (a directory path).
  • const char * p1 - the second part of the path.
  • int size0 - the size of the first part of the path.
  • int size1 - the size of the second part of the path.

Return value

Resulting path.

char last ( ) #

Returns the last character of the current string.

Return value

The current character.

char & last ( ) #

Returns the last character of the current string.

Return value

The current character.

String & lower ( ) #

Returns a lower-case equivalent of the current string. Non-alphabetic characters remain unchanged.

Return value

A lower-cased string.

static StringStack<> ltoa ( long long value, int radix ) #

Returns string representation of a given long long value.

Arguments

  • long long value - An input long long value.
  • int radix - Numerical base used to represent the value as a string, between 2 and 16, where 10 means decimal base, 16 hexadecimal, 8 octal, and 2 binary.

Return value

String representation of a specified long long value.

static int match ( const char * pattern, const char * str ) #

Checks whether a str string matches a pattern.

Arguments

  • const char * pattern - A string with Regular expression.
  • const char * str - A string to be checked.

Return value

1 if str matches pattern; otherwise, 0.

static StringStack<> memory ( size_t memory ) #

Returns a stack of strings containing information on memory consumption for the string.

Arguments

  • size_t memory - Amount of memory.

Return value

Stack of strings containing information on memory consumption for the string.

static StringStack<> normalizeDirPath ( const char * path ) #

Returns normalized path string and ensures that it is a path to a directory (ends with a forward slash).

Arguments

  • const char * path - An input path string.

Return value

Normalized path to a directory.

static String & normalizeDirPath ( String & ret, const char * path, int size ) #

Returns normalized path string and ensures that it is a path to a directory (ends with a forward slash).

Arguments

  • String & ret - a string to store the result.
  • const char * path - an input path string.
  • int size - the size of the resulting string.

Return value

Normalized path to a directory.

static StringStack<> normalizePath ( const char * path ) #

Returns a de-escaped path string where all double backslashes are replaced with forward ones.

Arguments

  • const char * path - A string.

Return value

Normalized path string.

static String & normalizePath ( String & ret, const char * path, int size ) #

Returns a de-escaped path string where all double backslashes are replaced with forward ones.

Arguments

  • String & ret - a string to store the result.
  • const char * path - a path to the file to be normalized.
  • int size - the size of the resulting string.

Return value

Normalized path string.

const char * operator const char * ( ) #

Returns the pointer to the current string.

Return value

The pointer to the current string.

const void * operator const void * ( ) #

Returns the pointer to the current string.

String & operator+= ( const String & s ) #

String addition.

Arguments

  • const String & s - The second string.

String & operator+= ( const char * s ) #

Symbol addition.

Arguments

  • const char * s - The symbol.

String & operator+= ( char c ) #

Symbol addition.

Arguments

  • char c - The symbol.

String & operator= ( const char * s ) #

Assignment operator for the string.

Arguments

  • const char * s - The null-terminated string.

String & operator= ( const String & s ) #

Assignment operator for the string.

Arguments

  • const String & s - The value of the string.

String & operator= ( String && s ) #

Move assignment operator for the string.

Arguments

  • String && s - The string reference.

char & operator[] ( int index ) #

Array access.

Arguments

  • int index - Array item index.

Return value

The array item.

char operator[] ( int index ) #

Constant array access.

Arguments

  • int index - Array item index.

Return value

The array item.

String pathname ( ) #

Parses the current string and returns path to a directory.

Return value

Directory name.

static StringStack<> pathname ( const char * str ) #

Parses an input string and returns path to a directory.
Notice
Unlike the dirname function, the pathname is able to process the path syntax with parent directories ("../").

Arguments

  • const char * str - A path string.

Return value

Directory name.
Notice
If the str string does not meet path syntax, an empty value will be returned.

Examples

Source code (C++)
String pathname = String::pathname("C:/Projects/Sample/data/../../textures/albedo.png");
// pathname: C:/Projects/textures/

void printf ( const char * format, ... ) #

Initializes a formatted string.

Arguments

  • const char * format - Format string.

static StringStack<> relname ( const char * path, const char * str ) #

Returns a relative path for str relatively to path. Both paths can be either absolute or relative.

Arguments

  • const char * path - The path of a working directory.
  • const char * str - A destination path.

Return value

A relative pathname.

Examples

Source code (C++)
String path = "C:/projects/sample/data/";
String str = "C:/projects/sample/data/textures/albedo.png";
String result = String::relname(path, str);
// result: textures/albedo.png

String path = "C:/projects/sample/data/textures/";
String str = "C:/projects/sample/";
String result = String::relname(path, str);
// result: ../../

String path = "data/";
String str = "data/textures/albedo.png";
String result = String::relname(path, str);
// result: textures/albedo.png

String & remove ( ) #

Removes the last symbol of the string.

Return value

Resulting string.

String & remove ( int pos, int size ) #

Removes the specified number of symbols at the given position from the string.

Arguments

  • int pos - Position.
  • int size - Number of symbols to remove.

Return value

Resulting string.

static StringStack<> removeExtension ( const char * str ) #

Returns an input string without the file extension name.

Arguments

  • const char * str - A path string.

Return value

Pathname without an extension.

String replace ( const char * before, const char * after, int case_sensitive ) #

Replaces all occurrences of a substring in the current string with the specified new string.

Arguments

  • const char * before - String to be replaced.
  • const char * after - String to replace the old one.
  • int case_sensitive - Case sensitivity flag. If set to 1, the replacement is case-sensitive; otherwise case is ignored.

Return value

Resulting string.

static StringStack<> replace ( const char * str, const char * before, const char * after, int case_sensitive ) #

Replaces all occurrences of a substring in a given string with the specified new string.

Arguments

  • const char * str - An original string.
  • const char * before - String to be replaced.
  • const char * after - String to replace the old one.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

Resulting string.

static StringStack<> replace ( const char * str, char before, char after, int case_sensitive ) #

Replaces all occurrences of a character in a given string with the specified new string.

Arguments

  • const char * str - An original string.
  • char before - A character to be replaced.
  • char after - A character to replace the old one.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

Resulting string.

String replace ( char before, char after, int case_sensitive ) #

Replaces all occurrences of a character in the current string with the specified new string.

Arguments

  • char before - A character to be replaced.
  • char after - A character to replace the old one.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

Resulting string.

void reserve ( int size ) #

Requests that the string capacity be adapted to a planned change in size to a length of up to n characters. The function has no effect on the length or content of the string.

Arguments

  • int size - Planned length for the string, in characters.

void resize ( int size ) #

Resizes the string to a length of n characters.

Arguments

  • int size - New string length, in characters.

static void reverseUtf8BiDirectional ( String & string ) #

Reverses the order of the characters in the bi-directional string containing mixed left-to-right and right-to-left scripts.

Arguments

  • String & string - An input string.

int rfind ( const String & s, int case_sensitive ) #

Searches the string for the last occurrence of s substring and returns the index of its last character.

Arguments

  • const String & s - A substring to be located.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

An index of the first symbol of a substring if at least one match was found; otherwise, -1.

int rfind ( char c, int case_sensitive ) #

Searches the string for the last occurrence of c character and returns its index.

Arguments

  • char c - A character to be located.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

An index of the character if at least one match was found; otherwise, -1.

int rfind ( const char * s, int case_sensitive ) #

Searches the string for the last occurrence of s substring and returns the index of its last character.

Arguments

  • const char * s - A substring to be located.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.

Return value

An index of the first symbol of a substring if at least one match was found; otherwise, -1.

int scanf ( const char * format, ... ) #

Scans a formatted string.

Arguments

  • const char * format - Format string.

Return value

Number of arguments successfully read, or EOF, if failure occurs.

void shrink ( ) #

Requests the string to reduce its capacity to fit its size.

int size ( ) #

Returns the size of the string.

Return value

The size of the string.

int space ( ) #

Returns the capacity of the string.

Return value

The capacity of the string.

static StringArray<> split ( const char * str, const char * delimiters ) #

Splits an input string into an array of substrings using a specified set of separator characters.

Arguments

  • const char * str - A string.
  • const char * delimiters - A string each character of which is a separator denoting a point at which a split should occur.

Return value

An array of substrings.

static int sscanf ( const char * str, const char * format ) #

Scans a formatted string.

Arguments

  • const char * str - An input string.
  • const char * format - Format string.

Return value

Number of arguments successfully read, or EOF, if failure occurs.

static int startsWith ( const char * data, const char * str, int case_sensitive, int data_size, int str_size ) #

Checks whether a given string starts with a specified substring.

Arguments

  • const char * data - A string.
  • const char * str - A substring.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.
  • int data_size - Length of the string.
  • int str_size - Length of the substring.

Return value

1 if the string starts with the specified substring; otherwise, 0.

int startsWith ( const String & s, int case_sensitive, int size ) #

Checks whether the current string starts with a specified substring.

Arguments

  • const String & s - A substring.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.
  • int size - Length of the substring.

Return value

1 if the string starts with the specified substring; otherwise, 0.

int startsWith ( const char * s, int case_sensitive, int size ) #

Checks whether the current string starts with a specified substring.

Arguments

  • const char * s - A substring.
  • int case_sensitive - Case sensitivity flag. If set to 1, the operation is case-sensitive; otherwise case is ignored.
  • int size - Length of the substring.

Return value

1 if the string starts with the specified substring; otherwise, 0.

static StringStack<> stripslashes ( const char * str ) #

Removes backslashes from a string.

Arguments

  • const char * str - A string.

Return value

Unquoted (de-escaped) string.

String substr ( int pos, int size ) #

Returns the substring of the current string.

Arguments

  • int pos - Starting position.
  • int size - Substring length.

Return value

A Substring.

static StringStack<> substr ( const char * str, int pos, int size ) #

Returns the substring of a given string.

Arguments

  • const char * str - A string.
  • int pos - Starting position.
  • int size - Substring length.

Return value

A Substring.

static StringStack<> substr ( const String & str, int pos, int size ) #

Returns the substring of a given string.

Arguments

  • const String & str - A string.
  • int pos - Starting position.
  • int size - Substring length.

Return value

A Substring.

static char toLower ( char c ) #

Returns a lower-case equivalent of a character, if possible. If not, the character is returned unchanged.

Arguments

  • char c - A character.

Return value

A lower-cased character.

static char toUpper ( char c ) #

Returns an upper-case equivalent of a character, if possible. If not, the character is returned unchanged.

Arguments

  • char c - A character.

Return value

An upper-cased character.

String trim ( const char * symbols ) #

Removes the specified symbols from the beginning and the ending of the current string.

Arguments

  • const char * symbols - A string with symbols to remove.
    Notice
    If the symbols argument is not specified, the function removes white spaces from the string.

Return value

Resulting string.

Examples

Source code (C++)
// Example 1
const String string("     My Important String           ");
string.trim() // will return "My Important String" without spaces

// Example 2
const String string("%c$abc%%cbaMy Important String%c$baacbb%$a");
string.trim("abc$%") // will return "My Important String" without the specified symbols at the begging and the end

static StringStack<> trim ( const char * str, const char * symbols ) #

Removes the specified symbols from the beginning and the ending of a given string.

Arguments

  • const char * str - A string.
  • const char * symbols - A string with symbols to remove.
    Notice
    If the symbols argument is not specified, the function removes white spaces from the string.

Return value

Resulting string.

static String trimFirst ( const char * symbols ) #

Removes the specified symbols only from the beginning of the current string.

Arguments

  • const char * symbols - A string with symbols to remove.
    Notice
    If the symbols argument is not specified, the function removes white spaces from the string.

Return value

Resulting string.

Examples

Source code (C++)
// Example 1
const String string("     My Important String     ");
string.trim() // will return "My Important String     " without spaces at the beggining

// Example 2
const String string("%c$abc%%cbaMy Important String%c$baacbb%$a");
string.trim("abc$%") // will return "My Important String%c$baacbb%$a" without the specified symbols at the begging

static StringStack<> trimFirst ( const char * str, const char * symbols ) #

Removes the specified symbols only from the beginning of a given string.

Arguments

  • const char * str - A string.
  • const char * symbols - A string with symbols to remove.
    Notice
    If the symbols argument is not specified, the function removes white spaces from the string.

Return value

Resulting string.

String trimLast ( const char * symbols ) #

Removes the specified symbols only from the end of the current string.

Arguments

  • const char * symbols - A string with symbols to remove.
    Notice
    If the symbols argument is not specified, the function removes white spaces from the string.

Return value

Resulting string.

Examples

Source code (C++)
// Example 1
const String string("     My Important String     ");
string.trim() // will return "     My Important String" without spaces at the end

// Example 2
const String string("%c$abc%%cbaMy Important String%c$baacbb%$a");
string.trim("abc$%") // will return "%c$abc%%cbaMy Important String" without the specified symbols at the end

static StringStack<> trimLast ( const char * str, const char * symbols ) #

Removes the specified symbols only from the end of a given string.

Arguments

  • const char * str - A string.
  • const char * symbols - A string with symbols to remove.
    Notice
    If the symbols argument is not specified, the function removes white spaces from the string.

Return value

Resulting string.

static String::Direction unicodeGetDirection ( unsigned int code ) #

Returns the type of a unicode character.

Arguments

  • unsigned int code - A unicode character.

Return value

An item of the String::Direction enumerator. The following types are possible:
  • LTR - left-to-right characters.
  • RTL - right-to-left characters.
  • Neutral - non-directional characters.
  • Digit - numeric characters.

static int unicodeToUtf8 ( unsigned int code, char * dest ) #

Converts a unicode character to UTF-8.

Arguments

  • unsigned int code - A unicode character.
  • char * dest - A destination pointer.

Return value

Length of the wide-character string.

static StringStack<> unicodeToUtf8 ( const wchar_t * src ) #

Converts a string to UTF-8.

Arguments

  • const wchar_t * src - A string.

Return value

Resulting string.

static StringStack<> unicodeToUtf8 ( const unsigned int * src ) #

Converts a set of unicode characters to a UTF-8-encoded string.

Arguments

  • const unsigned int * src - A set of characters.

Return value

Resulting string.

static StringStack<> unicodeToUtf8 ( unsigned int code ) #

Converts a unicode character to a UTF-8-encoded string.

Arguments

  • unsigned int code - A unicode character.

Return value

Resulting string.

String & upper ( ) #

Returns an upper-case equivalent of the current string. Non-alphabetic characters remain unchanged.

Return value

An upper-cased string.

int utf8strlen ( ) #

Returns the wide-character length of the current string.

Return value

Length of the wide-character string.

static int utf8strlen ( const char * str ) #

Returns the wide-character length of a string.

Arguments

  • const char * str - A string.

Return value

Length of the wide-character string.

String utf8substr ( int pos, int size ) #

Returns the wide-character substring.

Arguments

  • int pos - Starting position.
  • int size - Substring length.

Return value

The substring.

static StringStack<> utf8substr ( const char * str, int pos, int size ) #

Returns the wide-character substring of a given string.

Arguments

  • const char * str - An input string.
  • int pos - Starting position.
  • int size - Substring length.

Return value

The substring.

int utf8ToUnicode ( wchar_t * dest, int size ) #

Converts a string into the wide-character string.

Arguments

  • wchar_t * dest - Pointer to the wide-character string.
  • int size - Size of wide-character string in symbols.

Return value

Length of the wide-character string.

int utf8ToUnicode ( unsigned int * dest, int size ) #

Converts a string into the wide-character string.

Arguments

  • unsigned int * dest - Pointer to the wide-character string.
  • int size - Size of wide-character string in symbols.

Return value

Length of the wide-character string.

static int utf8ToUnicode ( const char * src, wchar_t * dest, int size ) #

Converts a string into the wide-character string.

Arguments

  • const char * src - A source string.
  • wchar_t * dest - Pointer to the wide-character string.
  • int size - Size of wide-character string in symbols.

Return value

Length of the wide-character string.

static int utf8ToUnicode ( const char * src, unsigned int & code ) #

Converts a string into the wide-character string.

Arguments

  • const char * src - A source string.
  • unsigned int & code - A character.

Return value

Length of the wide-character string.

static int utf8ToUnicode ( const char * src, unsigned int * dest, int size ) #

Converts a string into the wide-character string.

Arguments

  • const char * src - A source string.
  • unsigned int * dest - Pointer to the set of characters.
  • int size - Size of wide-character string in symbols.

Return value

Length of the wide-character string.

void vprintf ( const char * format, va_list argptr ) #

Initializes a formatted string.

Arguments

  • const char * format - Format string.
  • va_list argptr - Arguments pointer.

int vscanf ( const char * format, va_list argptr ) #

Scans a formatted string.

Arguments

  • const char * format - Format string.
  • va_list argptr - Arguments pointer.

Return value

Number of arguments successfully read, or EOF if failure occurs.

static int vsscanf ( const char * str, const char * format, va_list argptr ) #

Scans a formatted string.

Arguments

  • const char * str - An input string.
  • const char * format - Format string.
  • va_list argptr - Arguments pointer.

Return value

Number of arguments successfully read, or EOF if failure occurs.
Last update: 2023-08-02
Build: ()