String Struct Reference

#include <String.h>

Overview

Immutable UTF-8 strings.

Remarks

Because Strings are encoded using UTF-8, they must not be treated as ASCII C strings. That is, a single Unicode code point will often span multiple chars. Be mindful of this when executing Range operations.

Strings are locale-ready, but Objectively does not enable locale by default. Call setlocale to enable localization.

Definition at line 69 of file String.h.

Inheritance diagram for String:

Properties
char *	chars
	The backing null-terminated UTF-8 encoded character array. More...
size_t	length
	The length of the String in bytes. More...
Object	object
	The superclass. More...
Properties inherited from Object
Class *	clazz
	Every instance of Object begins with a pointer to its Class. More...

Methods
Class *	_String (void)
	The String archetype. More...
Order	compareTo (const String *self, const String *other, const Range range)
	Compares this String lexicographically to another. More...
Array *	componentsSeparatedByCharacters (const String *self, const char *chars)
	Returns the components of this String that were separated by chars. More...
Array *	componentsSeparatedByString (const String *self, const String *string)
	Returns the components of this String that were separated by string. More...
Data *	getData (const String *self, StringEncoding encoding)
	Returns a Data with this String's contents in the given encoding. More...
_Bool	hasPrefix (const String *self, const String *prefix)
	Checks this String for the given prefix. More...
_Bool	hasSuffix (const String *self, const String *suffix)
	Checks this String for the given suffix. More...
String *	initWithBytes (String *self, const uint8_t *bytes, size_t length, StringEncoding encoding)
	Initializes this String by decoding length of bytes. More...
String *	initWithCharacters (String *self, const char *chars)
	Initializes this String by copying chars. More...
String *	initWithContentsOfFile (String *self, const char *path, StringEncoding encoding)
	Initializes this String with the contents of the FILE at path. More...
String *	initWithData (String *self, const Data *data, StringEncoding encoding)
	Initializes this String with the given Data. More...
String *	initWithFormat (String *self, const char *fmt,...)
	Initializes this String with the specified format string. More...
String *	initWithMemory (String *self, const ident mem, size_t length)
	Initializes this String with the specified buffer. More...
String *	initWithVaList (String *self, const char *fmt, va_list args)
	Initializes this String with the specified arguments list. More...
String *	lowercaseString (const String *self)
MutableString *	mutableCopy (const String *self)
Range	rangeOfCharacters (const String *self, const char *chars, const Range range)
	Finds and returns the first occurrence of chars in this String. More...
Range	rangeOfString (const String *self, const String *string, const Range range)
	Finds and returns the first occurrence of string in this String. More...
String *	stringWithBytes (const uint8_t *bytes, size_t length, StringEncoding encoding)
	Returns a new String by decoding length of bytes to UTF-8. More...
String *	stringWithCharacters (const char *chars)
	Returns a new String by copying chars. More...
String *	stringWithContentsOfFile (const char *path, StringEncoding encoding)
	Returns a new String with the contents of the FILE at path. More...
String *	stringWithData (const Data *data, StringEncoding encoding)
	Returns a new String with the the given Data. More...
String *	stringWithFormat (const char *fmt)
	Returns a new String with the given format string. More...
String *	stringWithMemory (const ident mem, size_t length)
	Returns a new String with the given buffer. More...
String *	substring (const String *string, const Range range)
	Creates a new String from a subset of this one. More...
String *	trimmedString (const String *self)
	Creates a copy of this String with leading and trailing whitespace removed. More...
String *	uppercaseString (const String *self)
_Bool	writeToFile (const String *self, const char *path, StringEncoding encoding)
	Writes this String to path. More...
Methods inherited from Object
Class *	_Object (void)
	The Object archetype. More...
Object *	copy (const Object *self)
	Creates a shallow copy of this Object. More...
void	dealloc (Object *self)
	Frees all resources held by this Object. More...
String *	description (const Object *self)
int	hash (const Object *self)
Object *	init (Object *self)
	Initializes this Object. More...
_Bool	isEqual (const Object *self, const Object *other)
	Tests equality of the other Object. More...
_Bool	isKindOfClass (const Object *self, const Class *clazz)
	Tests for Class hierarchy membership. More...

Protected Attributes
StringInterface *	interface
	The interface. More...
Protected Attributes inherited from Object
ObjectInterface *	interface
	The interface. More...

Related Functions
OBJECTIVELY_EXPORT MutableString *	mstr (const char *fmt,...)
	A convenience function for instantiating MutableStrings. More...
OBJECTIVELY_EXPORT const char *	NameForStringEncoding (StringEncoding encoding)
OBJECTIVELY_EXPORT String *	str (const char *fmt,...)
	A convenience function for instantiating Strings. More...
OBJECTIVELY_EXPORT Order	StringCompare (const ident a, const ident b)
	A Comparator for sorting Strings. More...
OBJECTIVELY_EXPORT StringEncoding	StringEncodingForName (const char *name)

Property Details

chars

char* String::chars

The backing null-terminated UTF-8 encoded character array.

Definition at line 85 of file String.h.

interface

StringInterface* String::interface

protected

The interface.

Definition at line 80 of file String.h.

length

size_t String::length

The length of the String in bytes.

Definition at line 90 of file String.h.

object

Object String::object

The superclass.

Definition at line 74 of file String.h.

Method Details

_String()

Class * _String

(

void

)

The String archetype.

Returns

The String Class.

Definition at line 654 of file String.c.

                     {
    static Class *clazz;
    static Once once;
 
    do_once(&once, {
        clazz = _initialize(&(const ClassDef) {
            .name = "String",
            .superclass = _Object(),
            .instanceSize = sizeof(String),
            .interfaceOffset = offsetof(String, interface),
            .interfaceSize = sizeof(StringInterface),
            .initialize = initialize,
        });
    });
 
    return clazz;
}

compareTo()

Order compareTo	(	const String *	self,
		const String *	other,
		const Range	range
	)

Compares this String lexicographically to another.

Parameters

self	The String.
other	The String to compare to.
range	The character Range to compare.

Returns

The ordering of this String compared to other.

Definition at line 163 of file String.c.

                                                                                   {
 
    assert(range.location + range.length <= self->length);
 
    if (other) {
        const int i = strncmp(self->chars + range.location, other->chars, range.length);
        if (i == 0) {
            return OrderSame;
        }
        if (i > 0) {
            return OrderDescending;
        }
    }
 
    return OrderAscending;
}

componentsSeparatedByCharacters()

Array * componentsSeparatedByCharacters	(	const String *	self,
		const char *	chars
	)

Returns the components of this String that were separated by chars.

Parameters

self	The String.
chars	The separating characters.

Returns

An Array of substrings that were separated by chars.

Definition at line 184 of file String.c.

                                                                                     {
 
    assert(chars);
 
    MutableArray *components = $(alloc(MutableArray), init);
 
    Range search = { 0, self->length };
    Range result = $(self, rangeOfCharacters, chars, search);
 
    while (result.length) {
        search.length = result.location - search.location;
 
        String *component = $(self, substring, search);
        $(components, addObject, component);
        release(component);
 
        search.location = result.location + result.length;
        search.length = self->length - search.location;
 
        result = $(self, rangeOfCharacters, chars, search);
    }
 
    String *component = $(self, substring, search);
    $(components, addObject, component);
    release(component);
 
    return (Array *) components;
}

componentsSeparatedByString()

Array * componentsSeparatedByString	(	const String *	self,
		const String *	string
	)

Returns the components of this String that were separated by string.

Parameters

self	The String.
string	The separating String.

Returns

An Array of substrings that were separated by string.

Definition at line 217 of file String.c.

                                                                                    {
 
    assert(string);
 
    return $(self, componentsSeparatedByCharacters, string->chars);
}

getData()

Data * getData	(	const String *	self,
		StringEncoding	encoding
	)

Returns a Data with this String's contents in the given encoding.

Parameters

self	The String.
encoding	The desired StringEncoding.

Returns

A Data with this String's contents in the given encoding.

Definition at line 228 of file String.c.

                                                                  {
 
    Transcode trans = {
        .to = encoding,
        .from = STRING_ENCODING_UTF8,
        .in = self->chars,
        .length = self->length,
        .out = calloc(self->length, sizeof(Unicode) / sizeof(char)),
        .size = self->length * sizeof(Unicode)
    };
 
    assert(trans.out);
 
    const size_t size = transcode(&trans);
    assert(size <= trans.size);
 
    return $$(Data, dataWithMemory, trans.out, size);
}

hasPrefix()

_Bool hasPrefix	(	const String *	self,
		const String *	prefix
	)

Checks this String for the given prefix.

Parameters

self	The String.
prefix	The Prefix to check.

Returns

True if this String starts with prefix, false otherwise.

Definition at line 251 of file String.c.

                                                                 {
 
    if (prefix->length > self->length) {
        return false;
    }
 
    Range range = { 0, prefix->length };
    return $(self, compareTo, prefix, range) == OrderSame;
}

hasSuffix()

_Bool hasSuffix	(	const String *	self,
		const String *	suffix
	)

Checks this String for the given suffix.

Parameters

self	The String.
suffix	The suffix to check.

Returns

True if this String ends with suffix, false otherwise.

Definition at line 265 of file String.c.

                                                                 {
 
    if (suffix->length > self->length) {
        return false;
    }
 
    Range range = { self->length - suffix->length, suffix->length };
    return $(self, compareTo, suffix, range) == OrderSame;
}

initWithBytes()

String * initWithBytes	(	String *	self,
		const uint8_t *	bytes,
		size_t	length,
		StringEncoding	encoding
	)

Initializes this String by decoding length of bytes.

Parameters

self	The String.
bytes	The bytes.
length	The length of bytes to decode.
encoding	The character encoding.

Returns

The initialized String, or NULL on error.

Definition at line 279 of file String.c.

                                                                                                         {
 
    if (bytes) {
 
        Transcode trans = {
            .to = STRING_ENCODING_UTF8,
            .from = encoding,
            .in = (char *) bytes,
            .length = length,
            .out = calloc(length * sizeof(Unicode) + 1, sizeof(char)),
            .size = length * sizeof(Unicode) + 1
        };
 
        assert(trans.out);
 
        const size_t size = transcode(&trans);
        assert(size < trans.size);
 
        ident mem = realloc(trans.out, size + 1);
        assert(mem);
 
        return $(self, initWithMemory, mem, size);
    }
 
    return $(self, initWithMemory, NULL, 0);
}

initWithCharacters()

String * initWithCharacters	(	String *	self,
		const char *	chars
	)

Initializes this String by copying chars.

Parameters

self	The String.
chars	The null-terminated, UTF-8 encoded C string.

Returns

The initialized String, or NULL on error.

Definition at line 310 of file String.c.

                                                                   {
 
    if (chars) {
 
        ident mem = strdup(chars);
        assert(mem);
 
        const size_t length = strlen(chars);
        return $(self, initWithMemory, mem, length);
    }
 
    return $(self, initWithMemory, NULL, 0);
}

initWithContentsOfFile()

String * initWithContentsOfFile	(	String *	self,
		const char *	path,
		StringEncoding	encoding
	)

Initializes this String with the contents of the FILE at path.

Parameters

self	The String.
path	The path of the file to load.
encoding	The character encoding.

Returns

The initialized String, or NULL on error.

Definition at line 328 of file String.c.

                                                                                               {
 
    Data *data = $$(Data, dataWithContentsOfFile, path);
    if (data) {
        self = $(self, initWithData, data, encoding);
    } else {
        self = $(self, initWithMemory, NULL, 0);
    }
    release(data);
 
    return self;
}

initWithData()

String * initWithData	(	String *	self,
		const Data *	data,
		StringEncoding	encoding
	)

Initializes this String with the given Data.

Parameters

self	The String.
data	The Data object.
encoding	The character encoding.

Returns

The initialized String, or NULL on error.

Definition at line 345 of file String.c.

                                                                                     {
 
    assert(data);
 
    return $(self, initWithBytes, data->bytes, data->length, encoding);
}

initWithFormat()

String * initWithFormat	(	String *	self,
		const char *	fmt,
			...
	)

Initializes this String with the specified format string.

Parameters

self	The String.
fmt	The format string.

Returns

The initialized String, or NULL on error.

Definition at line 356 of file String.c.

                                                                  {
 
    va_list args;
    va_start(args, fmt);
 
    self = $(self, initWithVaList, fmt, args);
 
    va_end(args);
 
    return self;
}

initWithMemory()

String * initWithMemory	(	String *	self,
		const ident	mem,
		size_t	length
	)

Initializes this String with the specified buffer.

Parameters

self	The String.
mem	The dynamically allocated null-terminated, UTF-8 encoded buffer.
length	The length of mem in printable characters.

Returns

The initialized String, or NULL on error.

Remarks

The memory will be freed when this String is deallocated.

Definition at line 372 of file String.c.

                                                                            {
 
    self = (String *) super(Object, self, init);
    if (self) {
 
        if (mem) {
            self->chars = (char *) mem;
            self->length = length;
        }
    }
 
    return self;
}

initWithVaList()

String * initWithVaList	(	String *	self,
		const char *	fmt,
		va_list	args
	)

Initializes this String with the specified arguments list.

Parameters

self	The String.
fmt	The format string.
args	The format arguments.

Returns

The initialized String, or NULL on error.

See also

vasprintf(3)

Definition at line 390 of file String.c.

                                                                           {
 
    self = (String *) super(Object, self, init);
    if (self) {
 
        if (fmt) {
            const int len = vasprintf(&self->chars, fmt, args);
            assert(len >= 0);
 
            self->length = len;
        }
    }
 
    return self;
}

lowercaseString()

String * lowercaseString

(

const String *

self

)

Parameters

self	The String.

Returns

A lowercase representation of this String.

Definition at line 410 of file String.c.

                                                   {
 
    Data *data = $(self, getData, STRING_ENCODING_WCHAR);
    assert(data);
 
    const size_t codepoints = data->length / sizeof(Unicode);
    Unicode *unicode = (Unicode *) data->bytes;
 
    for (size_t i = 0; i < codepoints; i++, unicode++) {
        *unicode = towlower(*unicode);
    }
 
    String *lowercase = $$(String, stringWithData, data, STRING_ENCODING_WCHAR);
 
    release(data);
    return lowercase;
}

mutableCopy()

MutableString * mutableCopy

(

const String *

self

)

Parameters

self	The String.

Returns

A MutableString with the contents of this String.

Definition at line 432 of file String.c.

                                                      {
 
    return $(alloc(MutableString), initWithString, self);
}

rangeOfCharacters()

Range rangeOfCharacters	(	const String *	self,
		const char *	chars,
		const Range	range
	)

Finds and returns the first occurrence of chars in this String.

Parameters

self	The String.
chars	The characters to search for.
range	The Range in which to search.

Returns

A Range specifying the first occurrence of chars in this String.

Definition at line 441 of file String.c.

                                                                                         {
 
    assert(chars);
    assert(range.location > -1);
    assert(range.length > 0);
    assert(range.location + range.length <= self->length);
 
    Range match = { -1, 0 };
    const size_t len = strlen(chars);
 
    const char *str = self->chars + range.location;
    for (size_t i = 0; i < range.length; i++, str++) {
        if (strncmp(str, chars, len) == 0) {
            match.location = range.location + i;
            match.length = len;
            break;
        }
    }
 
    return match;
}

rangeOfString()

Range rangeOfString	(	const String *	self,
		const String *	string,
		const Range	range
	)

Finds and returns the first occurrence of string in this String.

Parameters

self	The String.
string	The String to search for.
range	The Range in which to search.

Returns

A Range specifying the first occurrence of string in this String.

Definition at line 467 of file String.c.

                                                                                        {
 
    assert(string);
 
    return $(self, rangeOfCharacters, string->chars, range);
}

stringWithBytes()

String * stringWithBytes	(	const uint8_t *	bytes,
		size_t	length,
		StringEncoding	encoding
	)

Returns a new String by decoding length of bytes to UTF-8.

Parameters

bytes	The bytes.
length	The length of bytes to copy.
encoding	The character encoding.

Returns

The new String, or NULL on error.

Definition at line 478 of file String.c.

                                                                                             {
 
    return $(alloc(String), initWithBytes, bytes, length, encoding);
}

stringWithCharacters()

String * stringWithCharacters

(

const char *

chars

)

Returns a new String by copying chars.

Parameters

chars

The null-terminated UTF-8 encoded C string.

Returns

The new String, or NULL on error.

Definition at line 487 of file String.c.

                                                       {
 
    return $(alloc(String), initWithCharacters, chars);
}

stringWithContentsOfFile()

String * stringWithContentsOfFile	(	const char *	path,
		StringEncoding	encoding
	)

Returns a new String with the contents of the FILE at path.

Parameters

path	A path name.
encoding	The character encoding.

Returns

The new String, or NULL on error.

Definition at line 496 of file String.c.

                                                                                   {
 
    return $(alloc(String), initWithContentsOfFile, path, encoding);
}

stringWithData()

String * stringWithData	(	const Data *	data,
		StringEncoding	encoding
	)

Returns a new String with the the given Data.

Parameters

data	A Data.
encoding	The character encoding.

Returns

The new String, or NULL on error.

Definition at line 505 of file String.c.

                                                                         {
 
    return $(alloc(String), initWithData, data, encoding);
}

stringWithFormat()

String * stringWithFormat

(

const char *

fmt

)

Returns a new String with the given format string.

Parameters

fmt	The format string.

Returns

The new String, or NULL on error.

stringWithMemory()

String * stringWithMemory	(	const ident	mem,
		size_t	length
	)

Returns a new String with the given buffer.

Parameters

mem	A dynamically allocated, null-terminated UTF-8 encoded buffer.
length	The length of mem in bytes.

Returns

The new String, or NULL on error.

Remarks

The memory will be freed when the returned String is deallocated.

Definition at line 530 of file String.c.

                                                                {
 
    return $(alloc(String), initWithMemory, mem, length);
}

substring()

String * substring	(	const String *	self,
		const Range	range
	)

Creates a new String from a subset of this one.

Parameters

self	The String.
range	The character Range.

Returns

The new String.

Definition at line 539 of file String.c.

                                                                {
 
    assert(range.location + range.length <= self->length);
 
    ident mem = calloc(range.length + 1, sizeof(char));
    assert(mem);
 
    strncpy(mem, self->chars + range.location, range.length);
 
    return $(alloc(String), initWithMemory, mem, range.length);
}

trimmedString()

String * trimmedString

(

const String *

self

)

Creates a copy of this String with leading and trailing whitespace removed.

Parameters

self	The String.

Returns

The trimmed String.

Definition at line 555 of file String.c.

                                                 {
 
    Range range = { .location = 0, .length = self->length };
 
    while (isspace(self->chars[range.location])) {
        range.location++;
        range.length--;
    }
 
    while (isspace(self->chars[range.length])) {
        range.length--;
    }
 
    return $(self, substring, range);
}

uppercaseString()

String * uppercaseString

(

const String *

self

)

Parameters

self	The String.

Returns

An uppercase representation of this String.

Definition at line 575 of file String.c.

                                                   {
 
    Data *data = $(self, getData, STRING_ENCODING_WCHAR);
    assert(data);
 
    const size_t codepoints = data->length / sizeof(Unicode);
    Unicode *unicode = (Unicode *) data->bytes;
 
    for (size_t i = 0; i < codepoints; i++, unicode++) {
        *unicode = towupper(*unicode);
    }
 
    String *uppercase = $$(String, stringWithData, data, STRING_ENCODING_WCHAR);
 
    release(data);
    return uppercase;
}

writeToFile()

_Bool writeToFile	(	const String *	self,
		const char *	path,
		StringEncoding	encoding
	)

Writes this String to path.

Parameters

self	The String.
path	The path of the file to write.
encoding	The character encoding.

Returns

true on success, false on error.

Definition at line 597 of file String.c.

                                                                                        {
 
    Data *data = $(self, getData, encoding);
    assert(data);
 
    const _Bool success = $(data, writeToFile, path);
 
    release(data);
    return success;
}

Related

mstr()

OBJECTIVELY_EXPORT MutableString * mstr ( const char *  fmt,   ...  )

related

A convenience function for instantiating MutableStrings.

Parameters

fmt	The format string.

Returns

A new MutableString, or NULL on error.

Definition at line 379 of file MutableString.c.

                                          {
 
    MutableString *string = $$(MutableString, string);
 
    va_list args;
    va_start(args, fmt);
 
    $(string, appendVaList, fmt, args);
 
    va_end(args);
    return string;
}

NameForStringEncoding()

OBJECTIVELY_EXPORT const char * NameForStringEncoding ( StringEncoding  encoding )

related

Parameters

encoding

A StringEncoding.

Returns

The canonical name for the given encoding.

Definition at line 674 of file String.c.

                                                           {
 
    switch (encoding) {
        case STRING_ENCODING_ASCII:
            return "ASCII";
        case STRING_ENCODING_LATIN1:
            return "ISO-8859-1";
        case STRING_ENCODING_LATIN2:
            return "ISO-8859-2";
        case STRING_ENCODING_MACROMAN:
            return "MacRoman";
        case STRING_ENCODING_UTF16:
            return "UTF-16";
        case STRING_ENCODING_UTF32:
            return "UTF-32";
        case STRING_ENCODING_UTF8:
            return "UTF-8";
        case STRING_ENCODING_WCHAR:
            return "WCHAR_T";
    }
 
    return "ASCII";
}

str()

OBJECTIVELY_EXPORT String * str ( const char *  fmt,   ...  )

related

A convenience function for instantiating Strings.

Parameters

fmt	The format string.

Returns

A new String, or NULL on error.

Definition at line 739 of file String.c.

                                  {
 
    va_list args;
    va_start(args, fmt);
 
    String *string = $(alloc(String), initWithVaList, fmt, args);
    assert(string);
 
    va_end(args);
 
    return string;
}

StringCompare()

OBJECTIVELY_EXPORT Order StringCompare ( const ident  a, const ident  b  )

related

A Comparator for sorting Strings.

Parameters

a	A String.
b	A String.

Returns

The Order of a to b.

Definition at line 721 of file String.c.

                                                  {
 
    if (a) {
        if (b) {
            const int i = strcmp(((String *) a)->chars, ((String *) b)->chars);
            if (i == 0) {
                return OrderSame;
            }
            if (i > 0) {
                return OrderDescending;
            }
        } else {
            return OrderDescending;
        }
    }
    return OrderAscending;
}

StringEncodingForName()

OBJECTIVELY_EXPORT StringEncoding StringEncodingForName ( const char *  name )

related

Parameters

name	The case-insensitive name of the encoding.

Returns

The StringEncoding for the given name.

Definition at line 698 of file String.c.

                                                       {
 
    if (strcasecmp("ASCII", name) == 0) {
        return STRING_ENCODING_ASCII;
    } else if (strcasecmp("ISO-8859-1", name) == 0) {
        return STRING_ENCODING_LATIN1;
    } else if (strcasecmp("ISO-8859-2", name) == 0) {
        return STRING_ENCODING_LATIN2;
    } else if (strcasecmp("MacRoman", name) == 0) {
        return STRING_ENCODING_MACROMAN;
    } else if (strcasecmp("UTF-16", name) == 0) {
        return STRING_ENCODING_UTF16;
    } else if (strcasecmp("UTF-32", name) == 0) {
        return STRING_ENCODING_UTF32;
    } else if (strcasecmp("UTF-8", name) == 0) {
        return STRING_ENCODING_UTF8;
    } else if (strcasecmp("WCHAR", name) == 0) {
        return STRING_ENCODING_WCHAR;
    }
 
    return STRING_ENCODING_ASCII;
}

---

The documentation for this struct was generated from the following files:

• Sources/Objectively/String.h
• Sources/Objectively/MutableString.h
• Sources/Objectively/String.c