String Manual

Table of Contents

• About
• Creation and Construction
• Output
• Content
• Conversion
• Compare
• Substring
• Search
• Utility
• Utility Classes
  • StringPosition
  • StringCount
• Further Reading

About

maxon::String is the universal string class of the MAXON API. Is is based on maxon::StringInterface and maxon::StringTemplate.

Note

The classic String class is based on maxon::String. See String Manual (Classic).

Creation and Construction

A maxon::String can easily be created on the stack and constructed using the "+=" operator:

• maxon::String::String(): Creates a new maxon::String object.
• maxon::String::operator+=(): Appends the given maxon::String.

Note

A constant maxon::String can also be created using the "_s" operator.

    // This example creates and constructs a simple maxon::String.
 
    // create the string
    maxon::String message { "Hello" };
 
    // extend the string
    message += maxon::String(" ");
    message += "World!"_s;
 

A maxon::String can also be constructed with:

• maxon::StringTemplate::Init(): Initializes the maxon::String with the given character.
• maxon::StringTemplate::Append(): Appends the given maxon::String.
• maxon::StringTemplate::AppendChar(): Appends the given Character.

    // This example creates a string and adds to it.
 
    // create string
    maxon::String message;
 
    // init
    message.Init(2, '9') iferr_return;
 
    // append
    message.Append(" bottles of beer on the wall"_s) iferr_return;
    message.AppendChar('!') iferr_return;

Integer values can be added to the maxon::String with:

• maxon::StringTemplate::AppendInt(): Appends the given maxon::Int.
• maxon::StringTemplate::AppendUInt(): Appends the given maxon::UInt.

    // This example creates a string and adds a number to it
 
    maxon::String message;
 
    message.AppendInt(maxon::Int(99));
    message.Append(" bottles of beer!"_s) iferr_return;

A maxon::String can also be constructed with FormatString().

// This example function creates a new String based on the input data.
 
static maxon::String FormatObjectData(const maxon::String objectName, maxon::Int polyCount, maxon::Int pointCount)
{
  const maxon::String res = FormatString("Object \"@\" (@ Polygons, @ Points)", objectName, polyCount, pointCount);
  return res;
}

Output

A given maxon::String can easily printed to the debug console with DiagnosticOutput() or similar functions. See Debug and Output Functions.

Content

It is easily possible to iterate over all characters stored in a given maxon::String:

• maxon::String::Begin(): Returns the iterator at the beginning of the string.
• maxon::String::End(): Returns the iterator at the end of the string.

    // This example prints each character of the given string to the debug console.
 
    // some string
    const maxon::String message { "Hello World!" };
 
    // get each character
    for (const maxon::Utf32Char& c : message)
    {
      maxon::String str;
      str.AppendChar(c) iferr_return;
 
      DiagnosticOutput("Character: @ (@)", str, c);
    }

The content of the maxon::String can also be accessed with these functions:

• maxon::String::IsEmpty(): Returns true if the maxon::String is empty.
• maxon::StringTemplate::GetLength(): Returns the number of stored characters.
• maxon::String::operator[](): Returns the character at the given index.
• maxon::StringTemplate::GetChar(): Returns the character at the given index.
• maxon::StringTemplate::SetChar(): Sets the character at the given index.

    // This example checks if the given string is empty. If not it will
    // access and print each character to the debug console.
 
    if (!message.IsEmpty())
    {
      const maxon::Int length = message.GetLength();
 
      // get each character
      for (maxon::Int i = 0; i < length; ++i)
      {
        // get character
        const maxon::Utf32Char c = message[i];
 
        maxon::String str;
        str.AppendChar(c) iferr_return;
 
        DiagnosticOutput("Character: @ (@)", str, c);
      }
    }

A maxon::String can be edited with:

• maxon::StringTemplate::Erase(): Erases a given count of characters from the maxon::String.
• maxon::StringTemplate::Insert(): Inserts the given maxon::String (or substring) at the given position.

    // This example removes and adds character to the given string.
 
    maxon::String message { "Alice and Bob" };
 
    message.Erase(6, 3) iferr_return;
    message.Insert(6, '&') iferr_return;

Conversion

A maxon::String can be converted to many other data formats but it also can be constructed by converting another data type to a maxon::String.

Note

MAXON API data types and interfaces typically implement a ToString() function.

A maxon::String can be converted to a upper-case or lower-case version of itself:

• maxon::StringTemplate::ToUpper(): Returns the upper-case version.
• maxon::StringTemplate::ToLower(): Returns the lower-case version.

See also MAXON_CONSTEXPR_TOLOWER.

    // This example turns the given string into a lower-case string.
 
    const maxon::String originalMessage { "Hello World!" };
 
    const maxon::String lowerMessage = originalMessage.ToLower();
 
    DiagnosticOutput(lowerMessage);

If the maxon::String describes a numeric value, this value can be converted to a numeric data type:

• maxon::StringTemplate::ToFloat64(): Converts the maxon::String to a maxon::Float64 value.
• maxon::StringTemplate::ToFloat32(): Converts the maxon::String to a maxon::Float32 value.
• maxon::StringTemplate::ToFloat(): Converts the maxon::String to a maxon::Float value.
• maxon::StringTemplate::ToInt64(): Converts the maxon::String to a maxon::Int64 value.
• maxon::StringTemplate::ToInt32(): Converts the maxon::String to a maxon::Int32 value.
• maxon::StringTemplate::ToInt(): Converts the maxon::String to a maxon::Int value.
• maxon::StringTemplate::ToUInt64(): Converts the maxon::String to a maxon::UInt64 value.
• maxon::StringTemplate::ToUInt32(): Converts the maxon::String to a maxon::UInt32 value.
• maxon::StringTemplate::ToUInt(): Converts the maxon::String to a maxon::UInt value.

    // This example converts the string into the numerical value it describes.
 
    const maxon::String message("100.1");
 
    maxon::Float floatValue = message.ToFloat() iferr_return;

Also numbers can be converted to a maxon::String:

• maxon::StringTemplate::FloatToString(): Converts the given maxon::Float value to a string.
• maxon::StringTemplate::IntToString(): Converts the given maxon::Int value to a string.
• maxon::StringTemplate::UIntToString(): Converts the given maxon::UInt value to a string.
• maxon::StringTemplate::MemorySizeToString(): Converts the given maxon::UInt64 value to a string describing memory information.
• maxon::StringTemplate::HexToString(): Converts the given maxon::UInt32 value to a hexadecimal string representation.
• maxon::StringTemplate::PointerToString(): Converts the given void pointer to a hexadecimal string representation.

See also maxon::StringConversion.

    // This example converts the given number to a string representation.
 
    const maxon::String value = maxon::String::FloatToString(maxon::Float(123.4));
 
    maxon::String message { "Value: " };
    message += value;
 

If needed, a maxon::String can be converted to a C-string. This might be useful to convert it into std:string.

• maxon::StringInterface::GetCStringBlock(): Writes the C string into the given maxon::Block.
• maxon::StringInterface::GetCStringAppendArray(): Writes the C string into the given maxon::BaseArray.
• maxon::StringInterface::GetCString(): Returns a C string as a maxon::BaseArray<maxon::Char>.
• maxon::StringInterface::SetCString(): Initializes the maxon::String from the given C string.

The content of the maxon::String can also be converted into special encodings:

• maxon::StringInterface::GetSystemEncoding(): Returns a copy of the string as a system-specific character array.
• maxon::StringInterface::SetSystemEncoding(): Initializes the maxon::String with the given system-specific character string.
• maxon::StringTemplate::GetUtf32(): Copies the maxon::String as UTF-32 encoded characters into the given array.
• maxon::StringInterface::SetUtf32(): Initializes the maxon::String with the given 32-bit Unicode character string.
• maxon::StringInterface::GetUtf16(): Copies the maxon::String as UTF-16 encoded characters into the given array.
• maxon::StringInterface::SetUtf16(): Initializes the maxon::String with the given 16-bit Unicode character string.

Values of enumeration classes can be converted to maxon::String using a function template defined with the MAXON_ENUM_LIST / MAXON_ENUM_ORDERED_LIST attributes:

    // This example compares two strings. The COMPARERESULT
    // is converted to a string to print it to the console.
 
    // compare strings
    const maxon::COMPARERESULT res = textA.Compare(textB);
 
    // print compare result
    DiagnosticOutput("The string is @", res);

Further functions are:

• maxon::StringInterface::GetVariableInternalData(): Returns the internal character array.
• maxon::StringInterface::GetCharacterWidth(): Returns the string's character width.
• maxon::StringInterface::ConvertString(): Converts the maxon::String using the given maxon::StreamConversionRef.

Compare

A given maxon::String can be compared with another maxon::String:

• maxon::StringTemplate::Compare(): Compares the given maxon::String and returns a result. See maxon::COMPARERESULT.
• maxon::StringTemplate::ComparePart(): Compares a substring with the given maxon::String.
• maxon::StringTemplate::IsEqual(): Returns true if the given maxon::String is equal.
• maxon::StringTemplate::GetHashCode(): Returns a UInt hash value.

The comparison modes are:

• maxon::STRINGCOMPARISON::MEMORY: Directly compares the memory block. This does not result in a correct alphabetical order.
• maxon::STRINGCOMPARISON::UNICODE_LETTERS: Strings are compared using correct Unicode decomposition.
• maxon::STRINGCOMPARISON::UNICODE_NUMBERS: Strings are compared using correct Unicode decomposition. Numbers in strings are identified, so "2" is smaller than "10".
• maxon::STRINGCOMPARISON::CASEINSENSITIVE: Strings are compared case-insensitive using correct Unicode decomposition.
• maxon::STRINGCOMPARISON::CASEINSENSITIVE_NUMBERS: Strings are compared case-insensitive using correct Unicode decomposition. Numbers in strings are identified, so "2" is smaller than "10".

Note

To compare C-strings see maxon::CStringCompare.

    // This example compares the two maxon::String objects. If they are not equal
    // they are compared and the result is printed to the debug console.
 
    if (!stringA.IsEqual(stringB))
    {
      const maxon::COMPARERESULT res = stringA.Compare(stringB);
      DiagnosticOutput("Compare result: @", res);
    }

Substring

A defined substring can be obtained from a given maxon::String.

• maxon::StringTemplate::GetPart(): Returns a substring of the given length.
• maxon::StringTemplate::Split(): Splits the maxon::String at the given symbol and writes the parts into the given maxon::BaseArray.
• maxon::StringTemplate::GetLeftPart(): Returns the substring left of the given position.
• maxon::StringTemplate::GetRightPart(): Returns the substring right of the given position.

Often it is useful to remove special characters like space, tab, line feed etc. from a maxon::String.

• maxon::StringTemplate::Trim(): Removes control characters and spaces from the beginning and end of the string.
• maxon::StringTemplate::TrimLeft(): Removes control characters and spaces at the beginning of the string.
• maxon::StringTemplate::TrimRight(): Removes control characters and spaces at the end of the string.

    // This example removes white spaces from the given string and splits the result into two new strings.
 
    maxon::String message { "       Hello World. This is some string." };
 
    // remove spaces
    message.Trim() iferr_return;
 
    // break down into sentences
    maxon::BaseArray<maxon::String> sentences;
    message.Split("."_s, true, sentences) iferr_return;
 
    for (const maxon::String& sentence : sentences)
      DiagnosticOutput(sentence);

Search

A typical string operation is to check if a given maxon::String contains given substring.

• maxon::StringTemplate::Find(): Returns true if the maxon::String contains the given search string and gives the index of the first occurrence.
• maxon::StringTemplate::FindIndex(): Returns the position of the first occurrence of the given search string.
• maxon::StringTemplate::FindLast(): Returns true if the maxon::String contains the given search string and gives the index of the last occurrence.
• maxon::StringTemplate::FindLastIndex(): Returns the position of the last occurrence of the given search string.
• maxon::StringTemplate::FindUpper(): Returns true if the maxon::String contains the given upper-case search string and gives the index of the first occurrence.
• maxon::StringTemplate::FindUpperIndex(): Returns the position of the first occurrence of the given upper-case search string.
• maxon::StringTemplate::FindLastUpper(): Returns true if the maxon::String contains the given upper-case search string and gives the index of the last occurrence.
• maxon::StringTemplate::FindLastUpperIndex(): Returns the position of the last occurrence of the given upper-case search string.
• maxon::StringTemplate::StartsWith(): Returns true if the maxon::String starts with the given character or string.
• maxon::StringTemplate::EndsWith(): Returns true if the maxon::String ends with the given character or string.
• maxon::StringTemplate::Replace(): Replaces all occurrences of the given character or string with the given string.

    // This example searches for the first occurrence of the given sub-string in the string.
    // If found, the remaining part of the string is copied.
 
    // check if http://
    maxon::Int pos = NOTOK;
    const maxon::String http("http://");
 
    if (webAdress.Find(http, &pos))
    {
      maxon::String domain = webAdress.GetPart(http.GetLength(), maxon::StringEnd());
 
      webAdress = "https://"_s;
      webAdress.Append(domain) iferr_return;
    }

Utility

Further utility functions are:

• maxon::String::GetLineEnd(): Returns a maxon::String with the platform specific line ending.
• maxon::StringTemplate::Shrink(): Optimizes the memory usage.
• maxon::IsSpace(): Returns true if the passed character is a space.
• maxon::IsTab(): Returns true if the passed character is a tab.
• maxon::IsSpaceOrTab(): Returns true if the passed character is a space or tab.
• maxon::IsLineEnd(): Returns true if the passed character is a line end.
• maxon::IsNumeric(): Returns true if the passed character is a digit.
• maxon::IsAlphabetic(): Returns true if the passed character is a Latin character.
• maxon::IsAlphanumeric(): Returns true if the passed character is alphabetic or numeric.
• maxon::IsHexadecimal(): Returns true if the passed character is alphabetic or numeric.
• maxon::GetHexadecimalValue(): Returns the value from a hexadecimal character. See also Hex.
• maxon::JoinElements(): Concatenates multiple elements to create a string.

Utility Classes

Substring functions use maxon::StringPosition and maxon::StringCount to define the needed arguments.

StringPosition

A StringPosition object defines a position within a maxon::String.

• maxon::StringPosition::StringPosition(): Creates a new StringPosition object.
• maxon::StringPosition::ResolvePosition(): Calculates the absolute position in a string based on the content and the given length.
• maxon::StringEnd: Symbolizes the end position of any maxon::String.

    // this example gets a sub-string of the given string and prints it to the debug console.
 
    const maxon::String webAdress { "https://www.maxon.net" };
 
    const maxon::StringPosition offset(8);
    const maxon::String         domain = webAdress.GetPart(offset, maxon::StringEnd());
 
    DiagnosticOutput("Domain: @", domain);

StringCount

A StringCount object defines a range of characters within a maxon::String.

• maxon::StringCount::StringCount(): Creates a new StringCount object.
• maxon::StringCount::ResolvePosition(): Calculates the end position of a range based on the given start position and string length.
• maxon::StringCount::ResolveCount(): Calculates the character count of a range based on the given start position and string length.

Further Reading

• Data & Algorithms
• String Manual (Classic)