Standard Library

v0.1.0-beta.1

String

A string represents some section of text. A string can represent a single character or an entire file. That said, it is important to understand when to use strings compared to other types. If you were to read a large file into a string you would eat ungodly amounts of memory so for this purpose you may want to reference the File class.

VSL strings are immutable. This means that you can't really 'modify' a string, you must create a new one. This is automatically done with string methods and operators such as +.

A good question is what happens with these old strings. VSL, unlike many other compiled languages, uses automatic memory management. This means that VSL will intelligently determine when to clean up old strings. That said, automatic memory management is not magic and it is reccomended not to construct strings in large loops. For this purpose use the string methods which have internal optimizations.

Internally strings are represented as their length and their value as a null- terminated UInt8 array. You can access these underlying methods using self.underlyingData and self.internalLength however this is reccomended against as in other implementations for other platforms these may not be available. Additionally use caution when using these, modifying any of these values can result in segfaults. If you are passing the underlyingData to a function which may modify it, create a copy of the underlyingData before you use it.

Initializers

  • public init(value: Pointer<UInt8>, byteLength: UInt32)

    Using this intializer REQUIRES a Pointer that is allocated by VSL. As a result this class WILL take control of the management for the data. To prevent this you will need to set the STRING_DEALLOC_OPT_OUT bit which can be done using the String#deallocOptOut function.

  • public init(value: Pointer<UInt8>)

    Using this intializer REQUIRES a Pointer that is allocated by VSL. As a result this class WILL take control of the management for the data. To prevent this you will need to set the STRING_DEALLOC_OPT_OUT bit which can be done using the String#deallocOptOut() function.

    This will calculate the string length of value until the first null-byte encountered.

  • public init(value: ByteSequence, byteLength: UInt32)

    Using this intializer REQUIRES a Pointer that is allocated by VSL. As a result this class WILL take control of the management for the data. To prevent this you will need to set the STRING_DEALLOC_OPT_OUT bit which can be done using the String#deallocOptOut function.

  • public init(value: ByteSequence)

    Using this intializer REQUIRES a Pointer that is allocated by VSL. As a result this class WILL take control of the management for the data. To prevent this you will need to set the STRING_DEALLOC_OPT_OUT bit which can be done using the String#deallocOptOut() function.

    This will calculate the string length of value until the first null-byte encountered.

  • public init(externalValue: Pointer<UInt8>, byteLength: UInt32)

    Creates from a pointer that is not allocated by VSL. This is the same as the other initializers except it already sets the STRING_DEALLOC_OPT_OUT bit.

  • public init(externalValue: Pointer<UInt8>)

    Creates from a pointer that is not allocated by VSL. This is the same as the other initializers except it already sets the STRING_DEALLOC_OPT_OUT bit. This also automatically calculates the string length using the strlen function,

  • public init(externalValue: ByteSequence, byteLength: UInt32)

    Creates from a pointer that is not allocated by VSL. This is the same as the other initializers except it already sets the STRING_DEALLOC_OPT_OUT bit.

  • public init(externalValue: ByteSequence)

    Creates from a pointer that is not allocated by VSL. This is the same as the other initializers except it already sets the STRING_DEALLOC_OPT_OUT bit. This also automatically calculates the string length using the strlen function,

Methods

  • public func toBytes() -> Pointer<UInt8>

    Returns the string as a byte pointer. This creates a copy that must be manually Pointer#free'd. This will have null-byte at the end and will be of length String#byteLength

  • public func append(string: String) -> Void

    Appends to the internal string buffer. Use of this is very much discouraged since strings should otherwise be immutable. There are very limited use cases for this and this likely would have unintended side effects.

  • public func deallocOptOut() -> Void

    Searches current string for the index of a substring. This returns -1 if the index was not found. public func findIndex(of substring: String) -> Int { // The substring can't be bigger than this string and have it exist. if substring.byteLength > self.internalLength { return -1 } } Prevents the backing buffer from being deallocated by VSL. Use this if you get the value from an external source

Static Methods

Subscripts

  • public subscript(at: Int32) -> String

    Access the nth BYTE in a string, returning a new string. If you which to access the nth character you'll need unicode strings enabled which is yet to be added.

  • public subscript(from: Int32, to: Int32) -> String

    Creates a substring from a string. This slices a string 0-indexed from [start, end). Negative parameters refer to the end of the array. This means -1 will refer to just before the last item.