UXStr

UXStr covers the minimum: joining two strings, and turning integers into text and back.

Building a label, a status line or an alert body means concatenating and formatting, and xtc’s Stdio has no snprintf to format into a buffer. Every application would otherwise write this code, so it lives here.

#use <UXKit>            // or #import "UXString.xc"

Overview

UXStr.append((u8*)"Zoom: ", UXStr.fromInt(150));    // "Zoom: 150"
UXStr.cat((u8*)"Ada", (u8)' ', (u8*)"Lovelace");    // "Ada Lovelace"
UXStr.toInt((u8*)"  -17px");                        // -17
UXStr.fromHex((u32)0xDEADBEEF);                     // "deadbeef"

All methods are static and return fresh buffers.

`cat` skips the separator when the left side is empty

This rule is why the method has three arguments instead of two:

u8* list = (u8*)"";
list = UXStr.cat(list, (u8)',', (u8*)"red");      // "red"       — no leading comma
list = UXStr.cat(list, (u8)',', (u8*)"green");    // "red,green"
list = UXStr.cat(list, (u8)',', (u8*)"blue");     // "red,green,blue"

Accumulating a separated list needs no “is this the first one” test, the check that is easy to forget and that leaves a stray comma at the front. Start from "" and the first item gets no separator.

append is cat with no separator, for building one string instead of a list.

`toInt` is a reader, not a validator

UXStr.toInt((u8*)"  -17px");    // -17   leading blanks, sign, digits, then stop
UXStr.toInt((u8*)"12.9");       // 12    stops at the dot
UXStr.toInt((u8*)"+8");         // 8     an explicit plus is allowed
UXStr.toInt((u8*)"abc");        // 0     no digits at all
UXStr.toInt((u8*)0);            // 0     null-safe

It reads what it can and stops at the first character that is not part of a number.

Topics

len · cat · append · dup · toInt · fromInt · fromHex

len

static u16 len(u8* s)

Byte length.

cat

static u8* cat(u8* a, u8 sep, u8* b)

a + sep + b in a fresh buffer. A sep of 0 means none, and the separator is skipped when a is empty; see above.

The separator is a single byte, so it is one character, not a string.

append

static u8* append(u8* a, u8* b)

cat with no separator.

dup

static u8* dup(u8* s)

A private copy.

Use it for a string that came out of a shared scratch buffer and must outlive the next call that fills it. UXKeyValueStore does this when it reads a value out of the settings store. If you are holding onto a u8* that a driver handed you, copy it.

toInt

static i32 toInt(u8* s)

Leading blanks, one optional sign, then digits, stopping at the first character that is none of these. Null-safe, returning 0.

It is a reader, not a validator: see above for why 0 cannot be told apart from “not a number”, and why that suits a settings value.

fromInt

static u8* fromInt(i32 v)

Decimal, with a - for negatives. Handles 0 and the full 32-bit range.

fromHex

static u8* fromHex(u32 v)

Lowercase hex, with no 0x prefix and no leading zeros: 255 is "ff", 0 is "0". Add a prefix yourself if you want one. Without it the result serves a colour literal, a byte dump and an address alike.

Example

accumulated: red,green,blue
label: Zoom: 150%
fromInt: 0 -42 2147483647
fromHex: 0 ff deadbeef
toInt: '  -17px'=-17 'abc'=0 '12.9'=12 '+8'=8

The program is website/site/examples/uxkit/strings.xc; the doc-examples gate compiles it, and the output above is its real output.

UXStr or UXText?

Both do string work, split by weight:


`UXStr`	joining two strings, numbers to and from text
`UXText`	trim, split, tokenize, join, case, search

The toolkit itself uses UXStr to build labels, so it depends on almost nothing. UXText is the fuller toolbox and pulls in Array and UXCharacterSet.

Conforms to

A plain class (not an Object subclass); all methods are static