OCString

group OCString

Immutable and mutable OCString operations.

Note

Ownership follows CoreFoundation conventions: The caller owns any OCStringRef returned from functions with “Create” in the name, and must call OCRelease() when done.

Defines

STR(cStr)

Macro to create a constant OCStringRef from a C string literal. 

OCStringRef hello = STR("Hello, world!");
// Use hello as a constant string
OCStringShow(hello);
// Do NOT release STR strings

Parameters:

  • cStr – C string literal.

Returns:

A compile-time constant OCStringRef; do not release.

Functions

static void OCStringAppendFormatWithArgumentsSafe(OCMutableStringRef result, OCStringRef format, va_list args, int max_args, OCStringRef *outError)

Appends formatted text to a mutable OCString.

Parameters:

  • result – Mutable OCString.

  • format – Format OCString.

  • args – Variable arguments for the format string.

  • max_args – Maximum number of arguments to process.

OCTypeID OCStringGetTypeID(void)

Returns the unique type identifier for OCString objects. 

OCTypeID stringTypeID = OCStringGetTypeID();
if (OCGetTypeID(someObject) == stringTypeID) {
    // The object is an OCString
}

Returns:

The OCTypeID for OCString.

OCStringRef OCStringCreateWithCString(const char *string)

Creates an immutable OCString from a C string. 

const char *cString = "Hello, world!";
OCStringRef myString = OCStringCreateWithCString(cString);

// Do operations with myString

// Release when done
OCRelease(myString);

Parameters:

  • string – Null-terminated UTF-8 C string.

Returns:

New OCStringRef, or NULL on failure.

OCMutableStringRef OCStringCreateMutableCopy(OCStringRef theString)

Creates a mutable copy of an immutable OCString. 

OCStringRef immutableString = OCStringCreateWithCString("Hello");
OCMutableStringRef mutableString = OCStringCreateMutableCopy(immutableString);

// Now we can modify mutableString
OCStringAppendCString(mutableString, ", world!");

// Release when done
OCRelease(immutableString);
OCRelease(mutableString);

Parameters:

  • theString – Immutable OCString to copy.

Returns:

New OCMutableStringRef (ownership transferred to caller).

cJSON *OCStringCopyAsJSON(OCStringRef str, bool typed, OCStringRef *outError)

Serialize an OCStringRef to JSON.

Creates a cJSON string node from the given OCStringRef. Since strings are native JSON types, both typed and untyped serialization produce the same result: a JSON string.

Parameters:

  • str – The OCStringRef to serialize.

  • typed – Whether to use typed serialization (ignored for strings).

  • outError – Optional pointer to receive error information if serialization fails.

Returns:

A cJSON string node or cJSON null on failure.

OCStringRef OCStringCreateFromJSON(cJSON *json, OCStringRef *outError)

Create an OCStringRef from a cJSON string node.

Parses the JSON value as a string. If the input is NULL or not a string, returns NULL. The returned string follows CoreFoundation ownership rules (caller must call OCRelease when done).

Parameters:

  • json – A cJSON node expected to be a string.

  • outError – Optional pointer to receive an error string on failure.

Returns:

A newly allocated OCStringRef, or NULL on failure.

OCStringRef OCStringCreateWithExternalRepresentation(OCDataRef data)

Creates an OCString by decoding raw data as UTF-8 text.

This function takes an OCDataRef containing UTF-8 encoded bytes and produces a newly allocated OCStringRef. On platforms without CFString, this performs a simple UTF-8 decode via OCStringCreateWithCString.

// Suppose 'raw' is a binary blob loaded from a file:
OCDataRef raw = OCDataCreateWithContentsOfFile("example.jdx");
OCStringRef text = OCStringCreateWithExternalRepresentation(raw);

// Use 'text' as needed...
printf("%s\n", OCStringGetCString(text, NULL));

// Clean up
OCRelease(raw);
OCRelease(text);

Parameters:

  • data – OCDataRef containing the raw UTF-8 bytes.

Returns:

A new OCStringRef representing the decoded text. Ownership is transferred to the caller and must be released with OCRelease().

OCStringRef OCStringCreateWithSubstring(OCStringRef str, OCRange range)

Creates an immutable OCString from a substring. 

OCStringRef fullString = OCStringCreateWithCString("Hello, world!");
OCRange range = {7, 5}; // Start at index 7, length 5 characters
OCStringRef substring = OCStringCreateWithSubstring(fullString, range);
// substring now contains "world"

// Release when done
OCRelease(fullString);
OCRelease(substring);

Parameters:

  • str – Source OCString.

  • range – Range of substring to extract.

Returns:

New OCStringRef, or NULL on failure.

void OCStringAppend(OCMutableStringRef theString, OCStringRef appendedString)

Appends an immutable OCString to a mutable OCString. 

OCMutableStringRef mutableString = OCStringCreateMutable(10);
OCStringRef hello = OCStringCreateWithCString("Hello");
OCStringRef world = OCStringCreateWithCString(" World");

OCStringAppend(mutableString, hello);
OCStringAppend(mutableString, world);
// mutableString now contains "Hello World"

// Release when done
OCRelease(hello);
OCRelease(world);
OCRelease(mutableString);

Parameters:

  • theString – Mutable OCString to append to.

  • appendedString – Immutable OCString to append.

void OCStringAppendCString(OCMutableStringRef theString, const char *cString)

Appends a C string to a mutable OCString. 

OCMutableStringRef mutableString = OCStringCreateMutable(10);
OCStringAppendCString(mutableString, "Hello");
OCStringAppendCString(mutableString, " World");
// mutableString now contains "Hello World"

// Release when done
OCRelease(mutableString);

Parameters:

  • theString – Mutable OCString to append to.

  • cString – Null-terminated UTF-8 C string to append.

OCMutableStringRef OCStringCreateMutable(unsigned long capacity)

Creates a new mutable OCString with specified initial capacity. 

// Create a mutable string with initial capacity of 50 characters
OCMutableStringRef mutableString = OCStringCreateMutable(50);

// Append content to the string
OCStringAppendCString(mutableString, "Initial content");

// Release when done
OCRelease(mutableString);

Parameters:

  • capacity – Initial capacity for the mutable string.

Returns:

New OCMutableStringRef (ownership transferred to caller).

OCMutableStringRef OCMutableStringCreateWithCString(const char *cString)

Creates a mutable OCString from a null-terminated C string. 

OCMutableStringRef mutableString = OCMutableStringCreateWithCString("Hello");

// Modify the string
OCStringAppendCString(mutableString, ", world!");
OCStringUppercase(mutableString);
// mutableString now contains "HELLO, WORLD!"

// Release when done
OCRelease(mutableString);

Parameters:

  • cString – Null-terminated UTF-8 C string.

Returns:

New OCMutableStringRef (ownership transferred to caller).

const char *OCStringGetCString(OCStringRef theString)

Returns a C string representation of an immutable OCString. 

OCStringRef myString = OCStringCreateWithCString("Hello, world!");

// Get the C string representation
const char *cString = OCStringGetCString(myString);

// Use the C string with standard C functions
printf("%s\n", cString);  // Outputs: Hello, world!

// Release when done
OCRelease(myString);
// Note: Do not free the C string returned by OCStringGetCString

Parameters:

  • theString – Immutable OfCString.

Returns:

Null-terminated UTF-8 C string.

OCStringRef OCStringCreateCopy(OCStringRef theString)

Creates a new immutable copy of an OCString. 

OCStringRef original = OCStringCreateWithCString("Hello, world!");

// Create a copy
OCStringRef copy = OCStringCreateCopy(original);

// Both strings have the same content but are separate objects
bool areEqual = OCStringEqual(original, copy);  // Returns true

// Release both strings when done
OCRelease(original);
OCRelease(copy);

Parameters:

  • theString – Source OCString.

Returns:

New OCStringRef (ownership transferred to caller).

OCComparisonResult OCStringCompare(OCStringRef theString1, OCStringRef theString2, OCStringCompareFlags compareOptions)

Compares two OCStrings with specified options. 

OCStringRef string1 = OCStringCreateWithCString("Apple");
OCStringRef string2 = OCStringCreateWithCString("APPLE");

// Case-sensitive comparison
OCComparisonResult result1 = OCStringCompare(string1, string2, 0);
// result1 will be kOCCompareGreaterThan because 'a' > 'A'

// Case-insensitive comparison
OCComparisonResult result2 = OCStringCompare(string1, string2, kOCCompareCaseInsensitive);
// result2 will be kOCCompareEqualTo

// Release when done
OCRelease(string1);
OCRelease(string2);

Parameters:

  • theString1 – First OCString.

  • theString2 – Second OCString.

  • compareOptions – Comparison options flags.

Returns:

Comparison result indicating order or equality.

unsigned long OCStringGetLength(OCStringRef theString)

Returns the length of an OCString. 

OCStringRef myString = OCStringCreateWithCString("Hello, world!");

uint64_t length = OCStringGetLength(myString);
// length will be 13

// Release when done
OCRelease(myString);

Parameters:

  • theString – OCString.

Returns:

Length of the string.

void OCStringLowercase(OCMutableStringRef theString)

Converts a mutable OCString to lowercase. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("Hello, WORLD!");

OCStringLowercase(myString);
// myString now contains "hello, world!"

// Release when done
OCRelease(myString);

Parameters:

  • theString – Mutable OCString.

void OCStringUppercase(OCMutableStringRef theString)

Converts a mutable OCString to uppercase. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("Hello, world!");

OCStringUppercase(myString);
// myString now contains "HELLO, WORLD!"

// Release when done
OCRelease(myString);

Parameters:

  • theString – Mutable OCString.

void OCStringTrim(OCMutableStringRef s, OCStringRef t)

Trims all occurrences of a specified substring from both ends of a mutable OCString. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("fooHello, world!foo");
OCStringRef      trimSub  = OCStringCreateWithCString("foo");

OCStringTrim(myString, trimSub);
// myString now contains "Hello, world!"

OCRelease(trimSub);
OCRelease(myString);

Parameters:

  • s – The mutable OCString to be trimmed.

  • t – The OCString substring to remove from the start and end.

void OCStringTrimWhitespace(OCMutableStringRef theString)

Trims whitespace characters from both ends of a mutable OCString. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("  Hello, world!   ");

OCStringTrimWhitespace(myString);
// myString now contains "Hello, world!"

// Release when done
OCRelease(myString);

Parameters:

  • theString – Mutable OCString.

bool OCStringTrimMatchingParentheses(OCMutableStringRef theString)

Trims matching parentheses from both ends of a mutable OCString if present. 

OCMutableStringRef string1 = OCMutableStringCreateWithCString("(Hello, world!)");
OCMutableStringRef string2 = OCMutableStringCreateWithCString("No parentheses");

bool trimmed1 = OCStringTrimMatchingParentheses(string1);
// trimmed1 will be true
// string1 now contains "Hello, world!"

bool trimmed2 = OCStringTrimMatchingParentheses(string2);
// trimmed2 will be false
// string2 remains unchanged

// Release when done
OCRelease(string1);
OCRelease(string2);

Parameters:

  • theString – Mutable OCString.

Returns:

true if parentheses were trimmed, false otherwise.

void OCStringDelete(OCMutableStringRef theString, OCRange range)

Deletes a substring from a mutable OCString. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("Hello, world!");

// Delete ", world" (characters 5-11)
OCRange deleteRange = {5, 7};
OCStringDelete(myString, deleteRange);
// myString now contains "Hello!"

// Release when done
OCRelease(myString);

Parameters:

  • theString – Mutable OCString.

  • range – Range of characters to delete.

void OCStringInsert(OCMutableStringRef str, int64_t idx, OCStringRef insertedStr)

Inserts an OCString into a mutable OCString at a specified index. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("Hello world!");
OCStringRef insertStr = OCStringCreateWithCString("beautiful ");

// Insert at position 6 (after "Hello ")
OCStringInsert(myString, 6, insertStr);
// myString now contains "Hello beautiful world!"

// Release when done
OCRelease(myString);
OCRelease(insertStr);

Parameters:

  • str – Mutable OCString to insert into.

  • idx – Index at which to insert.

  • insertedStr – OCString to insert.

void OCStringReplace(OCMutableStringRef str, OCRange range, OCStringRef replacement)

Replaces a range in a mutable OCString with another OCString. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("Hello world!");
OCStringRef replacement = OCStringCreateWithCString("everyone");

// Replace "world" (characters 6-11) with "everyone"
OCRange replaceRange = {6, 5};
OCStringReplace(myString, replaceRange, replacement);
// myString now contains "Hello everyone!"

// Release when done
OCRelease(myString);
OCRelease(replacement);

Parameters:

  • str – Mutable OCString.

  • range – Range to replace.

  • replacement – OCString to insert.

void OCStringReplaceAll(OCMutableStringRef str, OCStringRef replacement)

Replaces the entire contents of a mutable OCString with another OCString. 

OCMutableStringRef myString = OCMutableStringCreateWithCString("Hello world!");
OCStringRef replacement = OCStringCreateWithCString("Greetings, everyone!");

OCStringReplaceAll(myString, replacement);
// myString now contains "Greetings, everyone!"

// Release when done
OCRelease(myString);
OCRelease(replacement);

Parameters:

  • str – Mutable OCString.

  • replacement – OCString to set.

uint32_t OCStringGetCharacterAtIndex(OCStringRef theString, unsigned long index)

Returns the character at a specified index in an OCString. 

OCStringRef myString = OCStringCreateWithCString("Hello, world!");

uint32_t char0 = OCStringGetCharacterAtIndex(myString, 0);  // 'H'
uint32_t char7 = OCStringGetCharacterAtIndex(myString, 7);  // 'w'

// Release when done
OCRelease(myString);

Parameters:

  • theString – OCString.

  • index – Index of character.

Returns:

Character at index.

float _Complex OCStringGetFloatComplexValue(OCStringRef string)

Parses and returns the float complex value represented by the OCString. 

OCStringRef complexStr = OCStringCreateWithCString("3+4i");

float complex value = OCStringGetFloatComplexValue(complexStr);
// value is equal to 3.0f + 4.0fi

float real = crealf(value);      // 3.0f
float imag = cimagf(value);      // 4.0f

// Release when done
OCRelease(complexStr);

Parameters:

  • string – OCString containing complex arithmetic expression.

Returns:

Parsed float complex value.

double _Complex OCStringGetDoubleComplexValue(OCStringRef string)

Parses and returns the double complex value represented by the OCString. 

OCStringRef complexStr = OCStringCreateWithCString("2.5 * (3-2i) + 1.5i");

double complex value = OCStringGetDoubleComplexValue(complexStr);
// value is equal to 7.5 - 5.0i + 1.5i = 7.5 - 3.5i

double real = creal(value);      // 7.5
double imag = cimag(value);      // -3.5

// Release when done
OCRelease(complexStr);

Parameters:

  • string – OCString containing complex arithmetic expression.

Returns:

Parsed double complex value.

OCRange OCStringFind(OCStringRef string, OCStringRef stringToFind, OCOptionFlags compareOptions)

Finds a substring within an OCString with specified options. 

OCStringRef haystack = OCStringCreateWithCString("Hello, World! Hello again.");
OCStringRef needle = OCStringCreateWithCString("hello");

// Case-sensitive search (won't find it)
OCRange range1 = OCStringFind(haystack, needle, 0);
// range1 will be {0, 0} indicating not found

// Case-insensitive search
OCRange range2 = OCStringFind(haystack, needle, kOCCompareCaseInsensitive);
// range2 will be {0, 5} indicating found at position 0 with length 5

// Search for second occurrence
OCRange searchRange = {7, OCStringGetLength(haystack) - 7};
OCRange range3 = OCStringFind(haystack, needle, kOCCompareCaseInsensitive);
// range3 will be {14, 5} indicating found at position 14 with length 5

// Release when done
OCRelease(haystack);
OCRelease(needle);

Parameters:

  • string – Source OCString.

  • stringToFind – Substring to find.

  • compareOptions – Comparison options flags.

Returns:

Range of found substring or {0,0} if not found.

int64_t OCStringFindAndReplace2(OCMutableStringRef string, OCStringRef stringToFind, OCStringRef replacementString)

Finds and replaces all occurrences of a substring in a mutable OCString. 

OCMutableStringRef text = OCMutableStringCreateWithCString("Hello world! Hello again, world!");
OCStringRef find = OCStringCreateWithCString("Hello");
OCStringRef replace = OCStringCreateWithCString("Greetings");

// Replace all occurrences of "Hello" with "Greetings"
int64_t replacements = OCStringFindAndReplace2(text, find, replace);
// replacements will be 2
// text now contains "Greetings world! Greetings again, world!"

// Release when done
OCRelease(text);
OCRelease(find);
OCRelease(replace);

Parameters:

  • string – Mutable OCString to modify.

  • stringToFind – Substring to find.

  • replacementString – Replacement OCString.

Returns:

Number of replacements made.

int64_t OCStringFindAndReplace(OCMutableStringRef string, OCStringRef stringToFind, OCStringRef replacementString, OCRange rangeToSearch, OCOptionFlags compareOptions)

Finds and replaces occurrences of a substring within a specified range in a mutable OCString. 

OCMutableStringRef text = OCMutableStringCreateWithCString("Hello world! Hello again, world!");
OCStringRef find = OCStringCreateWithCString("world");
OCStringRef replace = OCStringCreateWithCString("everybody");

// Replace only the first occurrence of "world" (within first 15 characters)
OCRange searchRange = {0, 15};
int64_t replacements = OCStringFindAndReplace(text, find, replace, searchRange, 0);
// replacements will be 1
// text now contains "Hello everybody! Hello again, world!"

// Replace with case-insensitive search (rest of string)
OCRange searchRange2 = {15, OCStringGetLength(text) - 15};
OCStringRef findWorld = OCStringCreateWithCString("WORLD");
replacements = OCStringFindAndReplace(text, findWorld, replace, searchRange2, kOCCompareCaseInsensitive);
// replacements will be 1
// text now contains "Hello everybody! Hello again, everybody!"

// Release when done
OCRelease(text);
OCRelease(find);
OCRelease(findWorld);
OCRelease(replace);

Parameters:

  • string – Mutable OCString to modify.

  • stringToFind – Substring to find.

  • replacementString – Replacement OCString.

  • rangeToSearch – Range within string to search.

  • compareOptions – Comparison options flags.

Returns:

Number of replacements made.

OCArrayRef OCStringCreateArrayWithFindResults(OCStringRef string, OCStringRef stringToFind, OCRange rangeToSearch, OCOptionFlags compareOptions)

Creates an array of ranges where a substring is found within an OCString. 

OCStringRef text = OCStringCreateWithCString("Hello world! Hello again, world!");
OCStringRef find = OCStringCreateWithCString("world");

// Find all occurrences of "world" in the entire string
OCRange searchRange = {0, OCStringGetLength(text)};
OCArrayRef results = OCStringCreateArrayWithFindResults(text, find, searchRange, 0);

// results will contain 2 OCRange objects:
// range at index 0 = {6, 5} (first "world")
// range at index 1 = {26, 5} (second "world")
uint64_t count = OCArrayGetCount(results);  // 2

// Extract and use the ranges
for (int i = 0; i < count; i++) {
    OCRange *range = (OCRange *)OCArrayGetValueAtIndex(results, i);
    // Use range->location and range->length as needed
}

// Release when done
OCRelease(text);
OCRelease(find);
OCRelease(results);

Creates an array of ranges where a substring is found within an OCString.

Parameters:

  • string – Source OCString.

  • stringToFind – Substring to find.

  • rangeToSearch – Range within string to search.

  • compareOptions – Comparison options flags.

Returns:

OCArrayRef containing ranges of found substrings.

OCArrayRef OCStringCreateArrayBySeparatingStrings(OCStringRef string, OCStringRef separatorString)

Creates an array of OCStrings by splitting a string using a separator string. 

OCStringRef csv = OCStringCreateWithCString("apple,banana,orange,grape");
OCStringRef separator = OCStringCreateWithCString(",");

// Split string by comma
OCArrayRef fruits = OCStringCreateArrayBySeparatingStrings(csv, separator);

// fruits will contain 4 OCString objects:
// OCString at index 0 = "apple"
// OCString at index 1 = "banana"
// OCString at index 2 = "orange"
// OCString at index 3 = "grape"
uint64_t count = OCArrayGetCount(fruits);  // 4

// Access individual strings from the array
for (int i = 0; i < count; i++) {
    OCStringRef fruit = (OCStringRef)OCArrayGetValueAtIndex(fruits, i);
    OCStringShow(fruit);  // Print each fruit name
}

// Release when done
OCRelease(csv);
OCRelease(separator);
OCRelease(fruits);  // This releases the array, but not its contents

Parameters:

  • string – Source OCString.

  • separatorString – Separator OCString.

Returns:

OCArrayRef containing separated OCStrings.

void OCStringShow(OCStringRef theString)

Prints the OCString to standard output. 

OCStringRef myString = OCStringCreateWithCString("Hello, world!");

// Print the string to standard output
OCStringShow(myString);  // Outputs: Hello, world!

// Release when done
OCRelease(myString);

Parameters:

  • theString – OCString to display.

bool OCStringEqual(OCStringRef theString1, OCStringRef theString2)

Compares two OCStrings for equality. 

OCStringRef string1 = OCStringCreateWithCString("Hello");
OCStringRef string2 = OCStringCreateWithCString("Hello");
OCStringRef string3 = OCStringCreateWithCString("World");

bool equal1 = OCStringEqual(string1, string2);  // true
bool equal2 = OCStringEqual(string1, string3);  // false

// Note: This is a case-sensitive comparison
OCStringRef string4 = OCStringCreateWithCString("HELLO");
bool equal3 = OCStringEqual(string1, string4);  // false

// For case-insensitive comparison, use OCStringCompare with kOCCompareCaseInsensitive

// Release when done
OCRelease(string1);
OCRelease(string2);
OCRelease(string3);
OCRelease(string4);

Parameters:

  • theString1 – First OCString.

  • theString2 – Second OCString.

Returns:

true if equal, false otherwise.

OCStringRef OCStringCreateWithFormat(OCStringRef format, ...)

Creates an immutable OCString using a format string and arguments. 

OCStringRef s = OCStringCreateWithFormat(STR("%@ %d"), NULL, STR("Hello"), 123);
// s contains "Hello 123"

Warning

  • Passing fewer arguments than required will print a warning and insert “[MISSING]” at missing positions.

  • Passing extra arguments is safe but they are ignored.

  • Argument types must match format specifiers exactly—C99 varargs cannot check types at runtime.

  • For %@, if the OCStringRef is NULL, a warning is printed and nothing is inserted.

Parameters:

  • format – Format OCString (supports printf-style specifiers and %@ for OCStringRef).

  • ... – Arguments matching the format string.

Returns:

New OCStringRef (ownership transferred to caller).

void OCStringAppendFormat(OCMutableStringRef theString, OCStringRef format, ...)

Appends formatted text to a mutable OCString. 

OCMutableStringRef s = OCMutableStringCreateWithCString("Val: ");
OCStringAppendFormat(s, STR("%@ %d"), STR("foo"), 7);
// s now contains "Val: foo 7"

Warning

  • Too few arguments: warning printed, “[MISSING]” inserted.

  • Extra arguments: ignored.

  • Argument types must match the format exactly.

  • %@ with NULL: warning printed, nothing inserted.

Parameters:

  • theString – Mutable OCString.

  • format – Format OCString (supports printf-style specifiers and %@ for OCStringRef).

  • ... – Arguments matching the format string.

double _Complex OCComplexFromCString(const char *string)

Calculates and returns the double complex value represented by the complex arithmetic expression in the string. 

// Parse a simple complex number
double complex value1 = OCComplexFromCString("3+4i");
// value1 is equal to 3.0 + 4.0i

// Parse a complex expression
double complex value2 = OCComplexFromCString("(2-3i) * (4+2i)");
// value2 is equal to (2-3i) * (4+2i) = 8 + 4i - 12i - 6i² = 8 - 8i + 6 = 14 - 8i

double real = creal(value2);    // 14.0
double imag = cimag(value2);    // -8.0

Parameters:

  • string – A string that contains a complex arithmetic expression.

Returns:

The double complex value represented by string, or nan("") or nan(NULL) if there is a scanning error.

OCStringRef OCFloatCreateStringValue(float value)

Creates an OCString representing a float value. 

float pi = 3.14159f;
OCStringRef piString = OCFloatCreateStringValue(pi);
// piString now contains "3.14159"

OCStringShow(piString);  // Output: 3.14159

// Release when done
OCRelease(piString);

Parameters:

  • value – Float value.

Returns:

New OCStringRef representing the float.

OCStringRef OCDoubleCreateStringValue(double value)

Creates an OCString representing a double value. 

double e = 2.71828182845904;
OCStringRef eString = OCDoubleCreateStringValue(e);
// eString now contains "2.71828182845904"

OCStringShow(eString);  // Output: 2.71828182845904

// Release when done
OCRelease(eString);

Parameters:

  • value – Double value.

Returns:

New OCStringRef representing the double.

OCStringRef OCFloatComplexCreateStringValue(float _Complex value, OCStringRef format)

Creates an OCString representing a float complex value using a format. 

float complex z = 2.5f + 3.7fi;

// Format with default precision
OCStringRef format1 = STR("%.1f%+.1fi");
OCStringRef zString1 = OCFloatComplexCreateStringValue(z, format1);
// zString1 now contains "2.5+3.7i"

// Format with different precision
OCStringRef format2 = STR("%.2f%+.2fi");
OCStringRef zString2 = OCFloatComplexCreateStringValue(z, format2);
// zString2 now contains "2.50+3.70i"

// Release when done
OCRelease(zString1);
OCRelease(zString2);
// No need to release format strings created with STR macro

Parameters:

  • value – Float complex value.

  • format – Format OCString.

Returns:

New OCStringRef representing the complex value.

OCStringRef OCDoubleComplexCreateStringValue(double _Complex value, OCStringRef format)

Creates an OCString representing a double complex value using a format. 

double complex z = 1.234 - 5.678i;

// Format with default notation
OCStringRef format1 = STR("%.3f%+.3fi");
OCStringRef zString1 = OCDoubleComplexCreateStringValue(z, format1);
// zString1 now contains "1.234-5.678i"

// Format with scientific notation
OCStringRef format2 = STR("%e%+ei");
OCStringRef zString2 = OCDoubleComplexCreateStringValue(z, format2);
// zString2 now contains something like "1.234000e+00-5.678000e+00i"

// Release when done
OCRelease(zString1);
OCRelease(zString2);
// No need to release format strings created with STR macro

Parameters:

  • value – Double complex value.

  • format – Format OCString.

Returns:

New OCStringRef representing the complex value.

bool characterIsUpperCaseLetter(uint32_t character)

Checks if a character is an uppercase letter. 

bool isUpper1 = characterIsUpperCaseLetter('A');  // true
bool isUpper2 = characterIsUpperCaseLetter('a');  // false
bool isUpper3 = characterIsUpperCaseLetter('Z');  // true
bool isUpper4 = characterIsUpperCaseLetter('5');  // false
bool isUpper5 = characterIsUpperCaseLetter(' ');  // false

Parameters:

  • character – Character to check.

Returns:

true if uppercase letter, false otherwise.

bool characterIsLowerCaseLetter(uint32_t character)

Checks if a character is a lowercase letter. 

bool isLower1 = characterIsLowerCaseLetter('a');  // true
bool isLower2 = characterIsLowerCaseLetter('A');  // false
bool isLower3 = characterIsLowerCaseLetter('z');  // true
bool isLower4 = characterIsLowerCaseLetter('5');  // false
bool isLower5 = characterIsLowerCaseLetter('.');  // false

Parameters:

  • character – Character to check.

Returns:

true if lowercase letter, false otherwise.

bool characterIsDigitOrDecimalPoint(uint32_t character)

Checks if a character is a digit or decimal point. 

bool isDigitOrPoint1 = characterIsDigitOrDecimalPoint('0');  // true
bool isDigitOrPoint2 = characterIsDigitOrDecimalPoint('9');  // true
bool isDigitOrPoint3 = characterIsDigitOrDecimalPoint('.');  // true
bool isDigitOrPoint4 = characterIsDigitOrDecimalPoint('a');  // false
bool isDigitOrPoint5 = characterIsDigitOrDecimalPoint('-');  // false

Parameters:

  • character – Character to check.

Returns:

true if digit or decimal point, false otherwise.

bool characterIsDigitOrDecimalPointOrSpace(uint32_t character)

Checks if a character is a digit, decimal point, or space. 

bool isDigitPointSpace1 = characterIsDigitOrDecimalPointOrSpace('5');  // true
bool isDigitPointSpace2 = characterIsDigitOrDecimalPointOrSpace('.');  // true
bool isDigitPointSpace3 = characterIsDigitOrDecimalPointOrSpace(' ');  // true
bool isDigitPointSpace4 = characterIsDigitOrDecimalPointOrSpace('\\t'); // false (tab is not a space)
bool isDigitPointSpace5 = characterIsDigitOrDecimalPointOrSpace('a');  // false

Parameters:

  • character – Character to check.

Returns:

true if digit, decimal point, or space, false otherwise.

OCStringRef OCCreateISO8601Timestamp(void)

Creates an OCStringRef containing the current UTC date and time in ISO 8601 format.

Example: 

OCStringRef timestamp = OCCreateISO8601Timestamp();
// timestamp might contain "2024-06-30T23:45:12Z"
OCRelease(timestamp);

Returns:

A new OCStringRef with the current UTC timestamp in the format “YYYY-MM-DDTHH:MM:SSZ”. The caller is responsible for releasing the returned OCStringRef.

void cleanupConstantStringTable(void)

Cleans up the internal constant string table.

This function is used internally by OCTypesShutdown() to clean up resources associated with constant strings created via STR() macro.

Note

This is an internal function and should not be called directly by user code. Use OCTypesShutdown() instead.