String Formatting

This shows different approaches for string formatting.

Direct Formatting

Methods for direct formatting modify the string directly:

#include <evo/string.h>
using namespace evo;

int main() {
    String str;

    // Append a separator, if applicable
    str.addsep(',');    // ignored, string is empty

    // Set as formatted integer
    str.setn(123);
    str.setn(0xFF, 16); // hex

    // Set as formatted floating point
    str.setn(1.23);     // default precision
    str.setn(1.23, 2);  // 2 digit precision

    // Append a separator, if applicable
    str.addsep(',');    // add separator
    str.addsep(',');    // ignored, already ends with separator

    // Append formatted number with similar methods
    str.addn(123);
    str.addn(1.23);

    // Prepend formatted number with similar methods
    str.prependn(123);
    str.prependn(1.23);

    // Insert formatted number with similar methods, at position 1
    str.insertn(1, 123);
    str.insertn(1, 1.23);

    return 0;
}

Stream Style Formatting

Strings can be appended to using the stream operator (<<), similar to output Stream Formatting:

#include <evo/string.h>
using namespace evo;

int main() {
    String str;

    // Append string and number
    str << "Testing " << 123;

    // Clear string and append new string and number
    str.clear() << "Foobar " << 1.23;

    return 0;
}

Strings can also use explicit stream formatting to customize the output:

#include <evo/string.h>
using namespace evo;

int main() {
    String str;

    // Format str as: Testing aaaa...
    str.clear() << "Testing " << FmtChar('a', 4) << "...";

    // Format str as: Testing 0123...
    str.clear() << "Testing " << FmtInt(123, fDEC, 4) << "...";

    // Format str as: Testing 0x07B...
    str.clear() << "Testing " << FmtUInt(0x7B, fHEX, fPREFIX2, 3) << "...";

    // Format str as: Testing 1.230...
    str.clear() << "Testing " << FmtFloat(1.23f, 3) << "...";

    // Format str as: Testing 01.230...
    str.clear() << "Testing " << FmtFloatD(1.23, 3, 6) << "...";

    return 0;
}

Formatting attributes must be explicitly passed with each value – String doesn't keep any formatting state.

Formatting types used with operator<<():

• Newline: NL, NL_SYS, nLF, nCRLF, etc
• FmtInt, FmtInt32, FmtLong, FmtUInt, FmtUInt32, FmtULong – for more int variants see FmtIntT
• FmtFloat, FmtFloatD, FmtFloatL
• FmtChar, FmtString, FmtStringWrap
• FmtDump

Stream Style Formatting With State

Create a String::Format object to keep formatting state and make formatting "sticky" through that object, similar to Stream::Format:

#include <evo/string.h>
using namespace evo;

int main() {
    String str;
    String::Format out(str);

    // Set int formatting to use hex with prefix, padded to 2 digits
    out << FmtSetInt(fHEX, fPREFIX2, 2);

    // Format some numbers as: 0x01,0x02,0x03
    out << 1 << ',' << 2 << ',' << 3;

    // Set int formatting to use octal with no prefix
    out << fOCT << fPREFIX0;

    // Format some numbers in octal as: 7,10,11
    out.str.clear();
    out << 7 << ',' << 8 << ',' << 9;

    // Set int formatting to use decimal and pad to 3 digits, set field width to 5 and align-right
    out << FmtSetInt(fDEC, 3) << FmtSetField(fRIGHT, 5, '.');

    // Format some numbers in decimal as: ..012,..034
    out.str.clear();
    out << 12 << ',' << 34;

    return 0;
}

This can also be done as a one-liner using a temporary formatter:

#include <evo/string.h>
using namespace evo;

int main() {
    String str;

    // Format some numbers as hex with prefix: 0x1,0x2,0x3
    String::Format(str) << fHEX << fPREFIX2 << 1 << ',' << 2 << ',' << 3;

    return 0;
}

Sticky formatting is useful for applying the same formatting to many fields. You may still use explicit stream formatting (see previous section) to override sticky formatting.

Formatting types for setting attributes with operator<<()

• FmtBase: fDEC, fHEX, etc – can cast an int to this type for base
• FmtBasePrefix: fPREFIX0, fPREFIX1, fPREFIX2
• FmtPrecision: fPREC_AUTO, fPREC0, fPREC2, fPREC6, etc – can cast an int to this type for precision
• FmtAlign: fLEFT, fCENTER, fRIGHT
• FmtWidth: fWIDTH0 – cast an int to this type for field width
• FmtSetNull
• FmtSetField
• FmtSetInt
• FmtSetFloat

Generic Conversion Formatting

Generic conversion and formatting is supported via templates:

#include <evo/string.h>
using namespace evo;

int main() {
    String str;

    // set
    str.convert_set<Bool>(true);
    str.convert_set<Int>(123);
    str.convert_set<FloatD>(1.2);
    str.convert_set<int>(123);
    str.convert_set<double>(1.2);

    // append
    str.convert_add<Bool>(true);
    str.convert_add<Int>(123);
    str.convert_add<FloatD>(1.2);
    str.convert_add<int>(123);
    str.convert_add<double>(1.2);

    return 0;
}

See also: String Conversion and Smart Quoting