Clownfish::String

Name

Clownfish::String – Immutable string holding Unicode characters.

Functions

utf8_valid

bool
cfish_Str_utf8_valid(
    char *ptr,
    size_t len
);

Return true if the string is valid UTF-8, false otherwise.

validate_utf8

void
cfish_Str_validate_utf8(
    char *text,
    size_t size,
    char *file,
    int line,
    char *func
);

Throws an error if the string isn’t valid UTF-8.

is_whitespace

bool
cfish_Str_is_whitespace(
    int32_t code_point
);

Returns true if the code point qualifies as Unicode whitespace.

new_from_utf8

cfish_String* // incremented
cfish_Str_new_from_utf8(
    char *utf8,
    size_t size
);

Return a String which holds a copy of the supplied UTF-8 character data after checking for validity.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

new_from_trusted_utf8

cfish_String* // incremented
cfish_Str_new_from_trusted_utf8(
    char *utf8,
    size_t size
);

Return a String which holds a copy of the supplied UTF-8 character data, skipping validity checks.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

init_from_trusted_utf8

cfish_String*
cfish_Str_init_from_trusted_utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Initialize a String which holds a copy of the supplied UTF-8 character data, skipping validity checks.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

new_steal_utf8

cfish_String* // incremented
cfish_Str_new_steal_utf8(
    char *utf8,
    size_t size
);

Return a String which assumes ownership of the supplied buffer containing UTF-8 character data after checking for validity.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

new_steal_trusted_utf8

cfish_String* // incremented
cfish_Str_new_steal_trusted_utf8(
    char *utf8,
    size_t size
);

Return a String which assumes ownership of the supplied buffer containing UTF-8 character data, skipping validity checks.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

init_steal_trusted_utf8

cfish_String*
cfish_Str_init_steal_trusted_utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Initialize a String which assumes ownership of the supplied buffer containing UTF-8 character data, skipping validity checks.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

new_wrap_utf8

cfish_String* // incremented
cfish_Str_new_wrap_utf8(
    char *utf8,
    size_t size
);

Return a String which wraps an external buffer containing UTF-8 character data after checking for validity. The buffer must stay unchanged for the lifetime of the String.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

new_wrap_trusted_utf8

cfish_String* // incremented
cfish_Str_new_wrap_trusted_utf8(
    char *utf8,
    size_t size
);

Return a String which wraps an external buffer containing UTF-8 character data, skipping validity checks. The buffer must stay unchanged for the lifetime of the String.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

init_wrap_trusted_utf8

cfish_String*
cfish_Str_init_wrap_trusted_utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Initialize a String which wraps an external buffer containing UTF-8 character data after checking for validity.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

new_from_char

cfish_String* // incremented
cfish_Str_new_from_char(
    int32_t code_point
);

Return a String which holds a single character.

code_point

Unicode code point of the character.

newf

cfish_String* // incremented
cfish_Str_newf(
    char *pattern
);

Return a String with content expanded from a pattern and arguments conforming to the spec defined by VCatF().

Note: a user-supplied pattern string is a security hole and must not be allowed.

pattern

A format string.

Methods

Cat

cfish_String* // incremented
cfish_Str_Cat(
    cfish_String *self,
    cfish_String *other
);

Return the concatenation of the String and other.

Cat_Utf8

cfish_String* // incremented
cfish_Str_Cat_Utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Return the concatenation of the String and the supplied UTF-8 character data after checking for validity.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

Cat_Trusted_Utf8

cfish_String* // incremented
cfish_Str_Cat_Trusted_Utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Return the concatenation of the String and the supplied UTF-8 character data, skipping validity checks.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

To_I64

int64_t
cfish_Str_To_I64(
    cfish_String *self
);

Extract a 64-bit integer from a decimal string. See BaseX_To_I64() for details.

BaseX_To_I64

int64_t
cfish_Str_BaseX_To_I64(
    cfish_String *self,
    uint32_t base
);

Extract a 64-bit integer from a variable-base stringified version. Expects an optional minus sign followed by base-x digits, stopping at any non-digit character. Returns zero if no digits are found. If the value exceeds the range of an int64_t, the result is undefined.

base

A base between 2 and 36.

To_F64

double
cfish_Str_To_F64(
    cfish_String *self
);

Convert a string to a floating-point number using the C library function strtod.

Starts_With

bool
cfish_Str_Starts_With(
    cfish_String *self,
    cfish_String *prefix
);

Test whether the String starts with prefix.

Starts_With_Utf8

bool
cfish_Str_Starts_With_Utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Test whether the String starts with a prefix supplied as raw UTF-8.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

Ends_With

bool
cfish_Str_Ends_With(
    cfish_String *self,
    cfish_String *suffix
);

Test whether the String ends with suffix.

Ends_With_Utf8

bool
cfish_Str_Ends_With_Utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Test whether the String ends with a suffix supplied as raw UTF-8.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

Contains

bool
cfish_Str_Contains(
    cfish_String *self,
    cfish_String *substring
);

Test whether the String contains substring.

Contains_Utf8

bool
cfish_Str_Contains_Utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Test whether the String contains a substring supplied as raw UTF-8.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

Find

cfish_StringIterator* // incremented
cfish_Str_Find(
    cfish_String *self,
    cfish_String *substring
);

Return a StringIterator pointing to the first occurrence of substring within the String, or NULL if the substring does not match.

Find_Utf8

cfish_StringIterator* // incremented
cfish_Str_Find_Utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Return a StringIterator pointing to the first occurrence of the substring within the String, or NULL if the substring does not match. The substring is supplied as raw UTF-8.

utf8

Pointer to UTF-8 character data.

size

Size of UTF-8 character data in bytes.

Equals

bool
cfish_Str_Equals(
    cfish_String *self,
    cfish_Obj *other
);

Equality test.

Returns: true if other is a String with the same character data as self.

Equals_Utf8

bool
cfish_Str_Equals_Utf8(
    cfish_String *self,
    char *utf8,
    size_t size
);

Test whether the String matches the supplied UTF-8 character data.

Length

size_t
cfish_Str_Length(
    cfish_String *self
);

Return the number of Unicode code points the String contains.

Get_Size

size_t
cfish_Str_Get_Size(
    cfish_String *self
);

Return the number of bytes occupied by the String’s internal content.

Get_Ptr8

char*
cfish_Str_Get_Ptr8(
    cfish_String *self
);

Return the internal backing array for the String if its internal encoding is UTF-8. If it is not encoded as UTF-8 throw an exception. The character data is not null-terminated.

To_Utf8

char*
cfish_Str_To_Utf8(
    cfish_String *self
);

Return a NULL-terminated copy of the string data in UTF-8 encoding. The buffer must be freed by the caller.

To_ByteBuf

cfish_ByteBuf* // incremented
cfish_Str_To_ByteBuf(
    cfish_String *self
);

Return a ByteBuf which holds a copy of the String.

Clone

cfish_String* // incremented
cfish_Str_Clone(
    cfish_String *self
);

Return a clone of the object.

Compare_To

int32_t
cfish_Str_Compare_To(
    cfish_String *self,
    cfish_Obj *other
);

Indicate whether one String is less than, equal to, or greater than another. The Unicode code points of the Strings are compared lexicographically. Throws an exception if other is not a String.

Returns: 0 if the Strings are equal, a negative number if self is less than other, and a positive number if self is greater than other.

To_String

cfish_String* // incremented
cfish_Str_To_String(
    cfish_String *self
);

Return a copy of the String.

Trim

cfish_String* // incremented
cfish_Str_Trim(
    cfish_String *self
);

Return a copy of the String with Unicode whitespace characters removed from both top and tail. Whitespace is any character that has the Unicode property White_Space.

Trim_Top

cfish_String* // incremented
cfish_Str_Trim_Top(
    cfish_String *self
);

Return a copy of the String with leading Unicode whitespace removed. Whitespace is any character that has the Unicode property White_Space.

Trim_Tail

cfish_String* // incremented
cfish_Str_Trim_Tail(
    cfish_String *self
);

Return a copy of the String with trailing Unicode whitespace removed. Whitespace is any character that has the Unicode property White_Space.

Code_Point_At

int32_t
cfish_Str_Code_Point_At(
    cfish_String *self,
    size_t tick
);

Return the Unicode code point located tick code points in from the top. Return CFISH_STR_OOB if out of bounds.

Code_Point_From

int32_t
cfish_Str_Code_Point_From(
    cfish_String *self,
    size_t tick
);

Return the Unicode code point located tick code points counting backwards from the end. Return CFISH_STR_OOB if out of bounds.

SubString

cfish_String* // incremented
cfish_Str_SubString(
    cfish_String *self,
    size_t offset,
    size_t length
);

Return a new substring containing a copy of the specified range.

offset

Offset from the top, in code points.

length

The desired length of the substring, in code points.

Top

cfish_StringIterator* // incremented
cfish_Str_Top(
    cfish_String *self
);

Return an iterator initialized to the start of the string.

Tail

cfish_StringIterator* // incremented
cfish_Str_Tail(
    cfish_String *self
);

Return an iterator initialized to the end of the string.

Inheritance

Clownfish::String is a Clownfish::Obj.