diff --git a/src/content/docs/Language Common/attributes.md b/src/content/docs/Language Common/attributes.md index 859435a..2b7597f 100644 --- a/src/content/docs/Language Common/attributes.md +++ b/src/content/docs/Language Common/attributes.md @@ -2,7 +2,7 @@ title: Attributes description: Attributes sidebar: - order: 67 + order: 68 --- Attributes are compile-time annotations on functions, types, global constants and variables. Similar to Java annotations, a decoration may also take arguments. A attribute can also represent a bundle of attributes. diff --git a/src/content/docs/Language Common/cinterop.md b/src/content/docs/Language Common/cinterop.md index 57b070a..f69378f 100644 --- a/src/content/docs/Language Common/cinterop.md +++ b/src/content/docs/Language Common/cinterop.md @@ -2,7 +2,7 @@ title: C Interoperability description: C Interoperability sidebar: - order: 68 + order: 69 --- C3 is C ABI compatible. That means you can call C from C3, and call C3 from C without having to @@ -90,4 +90,4 @@ the project file (e.g. `"linker-search-paths" = ["../mylibs/", "/extra-libs/"]`) replace it with a pointer to a sized array: `extern fn void test2(int[4]* b);` - Note that a pointer to an array is always implicitly convertable to a pointer to the first element For example, `int[4]*` may be implicitly converted to `int*`. - The C3 names of functions are name-spaced with the module by default when using `@export`, so when - exporting a function with `@export` that is to be used from C, specify an explicit external name. E.g. `fn void myfunc() @export("myfunc") { ... }`. \ No newline at end of file + exporting a function with `@export` that is to be used from C, specify an explicit external name. E.g. `fn void myfunc() @export("myfunc") { ... }`. diff --git a/src/content/docs/Language Common/contracts.md b/src/content/docs/Language Common/contracts.md index 2722457..60af849 100644 --- a/src/content/docs/Language Common/contracts.md +++ b/src/content/docs/Language Common/contracts.md @@ -2,7 +2,7 @@ title: Contracts description: Contracts sidebar: - order: 66 + order: 67 --- Contracts are optional pre- and post-conditions checks that the compiler may use for optimization and runtime checks. Note that _compilers are not obliged to process pre- and post-conditions at all_. However, violating either pre- or post-conditions is considered undefined behaviour, so a compiler may optimize as if they always hold – even if a potential bug may cause them to be violated. diff --git a/src/content/docs/Language Common/defer.md b/src/content/docs/Language Common/defer.md index 51c4a5a..8fddd8a 100644 --- a/src/content/docs/Language Common/defer.md +++ b/src/content/docs/Language Common/defer.md @@ -2,7 +2,7 @@ title: Defer and Cleanup description: Defer and Cleanup sidebar: - order: 65 + order: 66 --- # Defer diff --git a/src/content/docs/Language Common/optionals-advanced.md b/src/content/docs/Language Common/optionals-advanced.md index cd7e9d7..baa8858 100644 --- a/src/content/docs/Language Common/optionals-advanced.md +++ b/src/content/docs/Language Common/optionals-advanced.md @@ -2,7 +2,7 @@ title: Advanced Error Handling description: Advanced Error Handling sidebar: - order: 64 + order: 65 --- ### Optionals are only defined in certain code @@ -346,4 +346,4 @@ fn void! test() } anyfault excuse = @catch(test()); -``` \ No newline at end of file +``` diff --git a/src/content/docs/Language Common/optionals-essential.md b/src/content/docs/Language Common/optionals-essential.md index b19a6fe..59d41a7 100644 --- a/src/content/docs/Language Common/optionals-essential.md +++ b/src/content/docs/Language Common/optionals-essential.md @@ -2,7 +2,7 @@ title: Essential Error Handling description: Essential Error Handling sidebar: - order: 63 + order: 64 --- In this section we will go over the *essential* information about Optionals and safe methods for working with them, for example @@ -201,4 +201,4 @@ fn int! get_value(); // Corresponding C code: c3fault_t get_value(int *value_ref); ``` -The `c3fault_t` is guaranteed to be a pointer sized value. \ No newline at end of file +The `c3fault_t` is guaranteed to be a pointer sized value. diff --git a/src/content/docs/Language Common/strings.md b/src/content/docs/Language Common/strings.md new file mode 100644 index 0000000..bf0f48b --- /dev/null +++ b/src/content/docs/Language Common/strings.md @@ -0,0 +1,239 @@ +--- +title: Strings +description: Strings +sidebar: + order: 62 +--- +In C3, multiple string types are available, each suited to different use cases. + +### String + +```c3 + +distinct String = inline char[]; + +``` +\ +Strings are usually the typical type to use, they can be sliced , compared etc ... \ +It is possible to access the length of a `String` instance through the ` .len ` operator. + + +### ZString + +```c3 + +distinct ZString = inline char*; +``` + +\ +ZString is used when working with C code, which expects null-terminated C-style strings of type `char*`. it is a distinct type so converting to a `ZString` requires an explicit cast. This helps to remind the user to check there is appropriate `\0` termination of the string data. + +The [ZString methods](#zstring-member-functions) are outlined below. + +:::caution +Ensure the terminal `\0` when converting from `String` to `ZString`. +::: + +#### WString + +```c3 + +distinct WString = inline Char16*; +``` + +\ +The `WString` type is similar to `ZString` but uses `Char16*`, typically for UTF-16 encoded strings. This type is useful for applications where 16-bit character encoding is required. + +#### DString + +```c3 + +distinct DString (OutStream) = void*; +``` + +\ +`DString` is a dynamic string builder that supports various string operations at runtime, allowing for flexible manipulation without the need for manual memory allocation. + +## Member functions: + +### String Member Functions + +```c3 +fn Char16[]! String.to_new_utf16(s, Allocator allocator = allocator::heap()) +``` + +```c3 +fn Char16[]! String.to_temp_utf16(s); +``` + +```c3 +fn WString! String.to_wstring(s, Allocator allocator) +``` + +```c3 implementation +fn String String.free(&s, Allocator allocator = allocator::heap()) +``` + +```c3 implementation +fn String String.tcopy(s) => s.copy(allocator::temp()) @inline; +``` + +```c3 implementation +fn String String.copy(s, Allocator allocator = allocator::heap()) +``` + +```c3 implementation +fn String String.strip_end(string, String needle); +``` + +```c3 implementation +fn String String.strip(string, String needle); +``` + +```c3 implementation +fn String String.trim(string, String to_trim); +``` + +```c3 implementation +fn bool String.contains(string, String needle); +``` + +```c3 implementation +fn bool String.starts_with(string, String needle); +``` + +```c3 implementation +fn bool String.ends_with(string, String needle); +``` +```c3 implementation +fn usz! String.index_of_char(s, char needle); +``` + +```c3 implementation +fn usz! String.index_of(s, String needle) +``` + +```c3 +fn usz! String.rindex_of(s, String needle) +``` + +```c3 implementation +fn String[] String.split(s, String needle, usz max = 0, Allocator allocator = allocator::heap()); +``` + +```c3 implementation +fn String String.new_split(s, String needle, usz max = 0) => s.split(needle, max, allocator::heap()) @inline; +``` + +```c3 implementation +// temporary String split +fn String String.tsplit(s, String needle, usz max = 0) => s.split(needle, max, allocator::temp()); +``` + +```c3 implementation +fn String String.tconcat(s1, String s2); +``` + +```c3 implementation +fn String String.tconcat(s1, String s2) => s1.concat(s2, allocator::temp()); +``` +```c3 implementation +fn WString! String.to_temp_wstring(s) => s.to_wstring(allocator::temp()); +``` +```c3 implementation +fn WString! String.to_new_wstring(s) => s.to_wstring(allocator::heap()); +``` +```c3 implementation +fn int128! String.to_int128(s, int base = 10) => s.to_integer(int128, base); +``` +```c3 implementation +fn long! String.to_long(s, int base = 10) => s.to_integer(long, base); +``` +```c3 implementation +fn int! String.to_int(s, int base = 10) => s.to_integer(int, base); +``` +```c3 implementation +fn short! String.to_short(s, int base = 10) => s.to_integer(short, base); +``` +```c3 implementation +fn ichar! String.to_ichar(s, int base = 10) => s.to_integer(ichar, base); +``` +```c3 implementation +fn uint128! String.to_uint128(s, int base = 10) => s.to_integer(uint128, base); +``` +```c3 implementation +fn ulong! String.to_ulong(s, int base = 10) => s.to_integer(ulong, base); +``` +```c3 implementation +fn uint! String.to_uint(s, int base = 10) => s.to_integer(uint, base); +``` +```c3 implementation +fn ushort! String.to_ushort(s, int base = 10) => s.to_integer(ushort, base); +``` +```c3 implementation +fn char! String.to_uchar(s, int base = 10) => s.to_integer(char, base); +``` +```c3 implementation +fn double! String.to_double(s) => s.to_real(double); +``` +```c3 implementation +fn float! String.to_float(s) => s.to_real(float); +``` +```c3 implementation +fn String String.new_ascii_to_upper(s, Allocator allocator = allocator::heap()); +``` + +```c3 implementation +fn Char16[]! String.to_new_utf16(s, Allocator allocator = allocator::heap()); +``` + +```c3 implementation +fn Char16[]! String.to_temp_utf16(s); +``` + +```c3 implementation +fn Char32[]! String.to_utf32(s, Allocator allocator); +``` + +```c3 implementation +fn Char32[]! String.to_new_utf32(s) => s.to_utf32(allocator::heap()) @inline; +``` + +```c3 implementation +fn Char32[]! String.to_temp_utf32(s) => s.to_utf32(allocator::temp()) @inline; +``` + +```c3 implementation +fn WString! String.to_wstring(s, Allocator allocator); +``` + +```c3 +fn WString! String.to_new_wstring(s) => s.to_wstring(allocator::heap()); +``` +```c3 +fn WString! String.to_temp_wstring(s) => s.to_wstring(allocator::temp()); +``` +```c3 +fn StringIterator String.iterator(s); +``` + +### ZString Member Functions + +```c3 implementation +fn String ZString.str_view(str); +``` + +```c3 implementation +fn usz ZString.char_len(str); +``` + +```c3 implementation +fn usz ZString.len(str); + +``` +```c3 implementation +fn ZString String.zstr_copy(s, Allocator allocator = allocator::heap()) +``` +```c3 implementation +fn ZString String.zstr_tcopy(s) => s.zstr_copy(allocator::temp()) @inline; +``` diff --git a/src/content/docs/Language Common/vectors.md b/src/content/docs/Language Common/vectors.md index ea5b5aa..0f608f5 100644 --- a/src/content/docs/Language Common/vectors.md +++ b/src/content/docs/Language Common/vectors.md @@ -2,7 +2,7 @@ title: Vectors description: Vectors sidebar: - order: 62 + order: 63 --- Vectors - where possible - based on underlying hardware vector implementations. A vector is similar to an array, but @@ -74,4 +74,4 @@ char red = color.r; // red = 0x11 ## Array-like operations Like arrays, it's possible to make slices and iterate over vectors. It should be noted that the storage alignment of -vectors are often different from arrays, which should be taken into account when storing vectors. \ No newline at end of file +vectors are often different from arrays, which should be taken into account when storing vectors.