String

String represents the type of a string value.

Specifications

Type	Size	Possible Values	Memory Management Model	File
`String`	32 bytes	All strings	Ownership	`2.7/String.adept`
`StringView`	^	^	^	^

Definition

record String (array *ubyte, length usize, capacity usize, ownership StringOwnership)

alias StringView = String

Fields

Name	Type	Description
`array`	`*ubyte`	Pointer to raw array of characters, not null-terminated
`length`	`usize`	Length of `array` in characters
`capacity`	`usize`	Capacity of `array` in characters
`ownership`	`StringOwnership`	Whether this string is responsible for freeing `array`

Value Management Definitions

func __defer__(this *String) void
func __pass__(string POD String) String
func __assign__(this *String, other POD String) void
func __access__(this *String, index usize) *ubyte
func __equals__(lhs String, rhs String) bool
func __not_equals__(lhs String, rhs String) bool
func __add__(lhs String, rhs String) String
func __add__(lhs String, rhs ubyte) String
func __add__(lhs POD String, rhs $T~__primitive__) String
func __multiply__(lhs String, times int) String
func __modulus__(lhs POD String, rhs String) String
func __modulus__(lhs POD String, rhs int) String
func __modulus__(lhs POD String, rhs ptr) String
func __modulus__(lhs POD String, rhs bool) String
func __modulus__(lhs POD String, rhs $T~__primitive__) String
func __less_than__(lhs String, rhs String) bool
func __greater_than__(lhs String, rhs String) bool
func __less_than_or_equal__(lhs String, rhs String) bool
func __greater_than_or_equal__(lhs String, rhs String) bool
func __array__(this *String) *ubyte
func __length__(this *String) usize

String Literals

String literals are declared using double quotes.

food String = "Spaghetti"

String vs *ubyte

*ubyte	String
Null-Terminated	NOT Null-Terminated
Must be manually `free()`d or `delete`d	Automatically freed
No Standard Library Dependencies	Requires `2.7/String.adept`
Can only be string view for end of string	Can always be string view
Length is calculated	Length is stored

Memory Management

Strings are automatically freed when they run out of scope.

import basics

func main {
    name String = "Isaac".clone()
    
    // name is freed
}

In order to pass strings around to other scopes, you can use the commit() method. my_string.commit() gives up any ownership held by my_string and returns a copy with the original's ownership:

import basics

func main {
    outlives String
    
    if true {
        shortlived String = "Apple".clone()
        
        // Transfer ownership to 'outlives'
        // 'outlives' now is equal to 'shortlived', but has taken ownership away from it
        outlives = shortlived.commit()
    }
    
    // outlives is freed
}

String Scoping Rules:

Strings are freed when they go out of scope
Strings are freed when inside a value that goes out of scope
Strings can transfer scopes using new_scoped_string = old_scoped_string.commit()
Strings can force themselves to own a String using must_own_a_string.make()
Strings are freed when they are returned and never assigned
Strings reference the data of other Strings when assigned to them
Strings can be cloned using original.clone()
Strings can point to specific parts of other Strings
Variables/Parameters marked as POD will not have __pass__ and __defer__ calls automatically made
When add()ed to things like List, a reference will be used by default
To commit ownership of a string to a list, you must use list.add(string.commit())

String working as a String View

One special thing about String, is that it can be used both as a regular string and as a string view. The methods span and range return a StringView (which is an alias for String), where as methods sub and segment return a newly allocated String.

import basics

func main {
    original String = "Hello World".clone()
    
    view String = original.span(0, 5)
    copy String = original.sub(0, 5)
    
    print(view)
    print(copy)

    original[0] = 'Y'ub
    
    print(view)
    print(copy)
}

Hello
Hello
Yello
Hello

Functions

func String(null_terminated *ubyte) String

Creates a String value from a null-terminated string. The returned value will have ownership of a copy of the string.

[view src]
func String(array *ubyte, length usize) String

Creates a String value from a character array. The returned value will have ownership of a copy of the string.

[view src]
func StringView(null_terminated *ubyte) String

Creates a String value from a null-terminated string. The returned value will be a view of the memory supplied.

[view src]
func StringView(array *ubyte, length usize) String

Creates a String value from a character array. The returned value will be a view of the memory supplied.

[view src]
func stringConstant(null_terminated *ubyte) String

Creates a String value from a null-terminated string. The returned value will reference the memory supplied.

[view src]
func stringTake(null_terminated *ubyte) String

Creates a String value from a null-terminated string and takes ownership of freeing the supplied string. The returned value will have ownership of the memory supplied.

[view src]
func stringTake(null_terminated *ubyte, capacity usize) String

Creates a String value from a null-terminated string and takes ownership of freeing the supplied string. The returned value will have ownership of the memory supplied.

[view src]
func contains(haystack String, needle String) bool

Returns whether a string is contained within another string.

[view src]
func contains(haystack String, needle ubyte) bool

Returns whether a string contains a certain character.

[view src]
func startsWith(string String, other POD String) bool

Returns whether a string starts with the contents of another string.

[view src]
func endsWith(string String, other POD String) bool

Returns whether a string ends with the contents of another string.

[view src]
func longestLength(string String) usize

Returns the longest line length in a string. Lines are separated by '\n' characters.

[view src]
func count(string String, character ubyte) usize

Returns the number of occurrences of a certain character within a string.

[view src]
func count(string String, substring String) usize

Returns the number of occurrences of a substring within a string.

[view src]
func uppercase(string String) String

Returns an uppercased copy of a string.

[view src]
func lowercase(string String) String

Returns a lowercased copy of a string.

[view src]
func trim(string String) String

Returns a trimmed copy of a string.

[view src]
func toString(value POD String) String

Identity function that returns the supplied string.

[view src]

Methods

func compare(this *String, other String) int

Compares two strings.
- Returns -1 if this should come first alphabetically.
- Returns 1 if this should come second alphabetically.
- Returns 0 if this is equal to other.
[view src]
func commit(this *String) String

Changes the ownership of a String to be StringOwnership::REFERENCE. If the String previously had ownership, then a String value will be returned with StringOwnership::GIVEN, otherwise the original String will be returned. This method is used for transferring ownership of internal data of String values to other String values.

[view src]
func donate(this *String) String

If the String has ownership, then the subject's ownership will be changed to StringOwnership::DONOR and a String value will be returned with StringOwnership::GIVEN, otherwise the original String will be returned. This method is used for transferring ownership of internal data of String values to other String values. If ownership was transferred, then the subject value will be completely invalidated and will be unable to be used afterwards.

[view src]
func give() String

Like commit(), except requires ownership. Not having ownership will cause a runtime error.

[view src]
func first(this *String, character ubyte) long

Returns the index of the first occurrence of a character within a string. Returns -1 if none exists.

[view src]
func first(this *String, sub String) long

Returns the index of the first occurrence of a substring within a string. Returns -1 if none exists.

[view src]
func last(this *String, character ubyte) long

Returns the index of the last occurrence of a character within a string. Returns -1 if none exists.

[view src]
func last(this *String, sub String) long

Returns the index of the last occurrence of a substring within a string. Returns -1 if none exists.

[view src]
func reverse(this *String) void

Reverses a string.

[view src]
func reversed(this *String) String

Returns a reversed copy of a string.

[view src]
func sub(this *String, a, n usize) String

Returns a copy of a section of a string, starting at a and going on for n characters.

[view src]
func segment(this *String, a, b usize) String

Returns a copy of a section of a string, starting at a and ending at b characters.

[view src]
func span(this *String, a, n usize) StringView

Returns a view of a section of a string, starting at a and going on for n characters.

[view src]
func range(this *String, a, b usize) StringView

Returns a view of a section of a string, starting at a and ending at b characters.

[view src]
func reduce(this *String, amount usize) void

Removes the last amount characters from a string.

[view src]
func reduced(this *String, amount usize) String

Returns a copy of a string with the last amount characters removed.

[view src]
func reducedView(this *String, amount usize) StringView

Returns a view of a string with the last amount characters removed.

[view src]
func decapitate(this *String, amount usize) void

Removes the first amount characters from a string.

[view src]
func decapitated(this *String, amount usize) String

Returns a copy of a string with the first amount characters removed.

[view src]
func decapitatedView(this *String, amount usize) StringView

Returns a view of a string with the first amount characters removed.

[view src]
func remove(this *String, index usize) void

Removes a character from a string.

[view src]
func remove(this *String, a, n usize) void

Removes a section of characters from a string starting at a and going on for n characters.

[view src]
func removed(this *String, index usize) String

Returns a copy of a string with a character removed.

[view src]
func removed(this *String, a, n usize) String

Returns a copy of a string with a section of characters removed starting at a and going on for n characters.

[view src]
func omit(this *String, a, b usize) void

Removes a section of characters from a string starting at a and ending at b characters.

[view src]
func omitted(this *String, a, b usize) String

Returns a copy of a string with a section of characters removed starting at a and ending at b characters.

[view src]
func append(this *String, other String) void

Appends a string to another string.

[view src]
func append(this *String, other ubyte) void

Appends a character to a string.

[view src]
func append(this *String, other *ubyte) void

Appends a c-string to a string.

[view src]
func append(this *String, other $T~__primitive__) void

Converts a primitive value to string and appends it to a string.

[view src]
func appendOnce(this *String, other String) void

Appends a string to a string if the string doesn't already end with it.

[view src]
func prepend(this *String, other String) void

Prepends a string to another string.

[view src]
func prependOnce(this *String, other String) void

Prepends a string to another string if the string doesn't already start with it.

[view src]
func clone(this *String) String

Returns a copy of a string.

[view src]
func make(this *String) void

If a string doesn't have ownership, a copy will be made so that it does.

[view src]
func reference(this *String) String

Returns a string that references the internal data of another string.

[view src]
func replaceOnce(this *String, from ubyte, to String) String

Replaces the first occurrence of from with to in a string.

[view src]
func replaceOnce(this *String, from, to String) String

Replaces the first occurrence of from with to in a string.

[view src]
func replace(this *String, from ubyte, to String) String

Replaces all occurrences of from with to in a string.

[view src]
func replace(this *String, from, to String) String

Replaces all occurrences of from with to in a string.

[view src]
func equals(this *String, other POD String) bool

Returns whether two strings are equal.

[view src]
func cstr(this *String) *ubyte

Returns a heap-allocated c-string with the contents of a string.

[view src]
func startsWith(this *String, other String) bool

Returns whether a string starts with the contents of another string.

[view src]
func endsWith(this *String, other String) bool

Returns whether a string ends with the contents of another string.

[view src]
func longestLength(this *String) usize

Returns the longest line length in a string. Lines are separated by '\n' characters.

[view src]
func count(this *String, character ubyte) usize

Returns the number of occurrences of a certain character within a string.

[view src]
func count(this *String, substring String) usize

Returns the number of occurrences of a substring within a string.

[view src]
func clear(this *String)

Sets a string's length to zero.

[view src]
func clean(this *String)

Deletes the internal contents of a string if it has ownership, and then zero-initializes the string so that it's a fresh untouched string.

[view src]
func empty(this *String) bool

Returns whether a string's length is zero.

[view src]
func contains(this *String, needle String) bool

Returns whether a string is contained within another string.

[view src]
func contains(this *String, needle ubyte) bool

Returns whether a string contains a certain character.

[view src]
func uppercase(this *String) String

Returns an uppercased copy of a string.

[view src]
func lowercase(this *String) String

Returns an lowercased copy of a string.

[view src]
func trim(this *String) void

Modifies a string to remove leading and trailing whitespace.

[view src]
func trimmed(this *String) String

Returns a copy of a string with leading and trailing whitespace removed.

[view src]
func trimmedView(this *String) StringView

Returns a view of a string with leading and trailing whitespace removed.

[view src]

Settings

#default String_log_deletion false
#default String_error_on_donor_usage true
#default String_include_deprecated_modulus_formatting true
#default String_include_deprecated_equals true

Table of Contents

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

String

String

Specifications

Definition

Fields

Value Management Definitions

String Literals

String vs *ubyte

Memory Management

String Scoping Rules:

String working as a String View

Functions

Methods

Settings

Clone this wiki locally