Strings

Files
file	gimbal_strings.h
file	gimbal_pattern.h
file	gimbal_pattern.hpp
file	gimbal_quark.h
file	gimbal_quark.hpp
file	gimbal_string.h
file	gimbal_string_buffer.h
file	gimbal_string_list.h
file	gimbal_string_ref.h
file	gimbal_string_view.h
file	gimbal_string_view.hpp

Data Structures
class	gbl::Pattern
class	gbl::Quark
struct	GblStringBuffer
struct	GblStringView
struct	gbl::StringView
struct	GblPattern

Typedefs
typedef uintptr_t	GblQuark
typedef GblRingList	GblStringList
typedef const char	GblStringRef

Detailed Description

Collection of specialized string types.

LibGimbal provides a rich set of string manipulation functions with API functionality taken from various languages such as C++ and Java.

Rather than create a single string type and API that is general-purpose and only "decent" at everything (such as C++'s std::string and most equivalents), libGimbal has taken the approach of creating various different string types, with each optimized for a particular use-case.

For a little bit of extra complexity, this has the added benefits of allowing for custom-tailored APIs that are well suited for such individual use-cases in addition to the performance benefit. If you're using libGimbal with a higher-level langauge such as C++ or Rust, you also gain more than just another generic string type which is already builtin to your language of choice.

Choosing the Right String

The following table can be referenced when deciding which string type to use:

Type	Use-cases	Header
GblStringView	Reading or immutable data processing	gimbal_string_view.h
GblStringBuffer	Writing or mutable data processing and building	gimbal_string_buffer.h
GblStringRef	Storing or managing ownership	gimbal_string_ref.h
GblQuark	Hashing or uniquely identifying	gimbal_quark.h

Typedef Documentation

GblQuark

typedef uintptr_t GblQuark

#include <gimbal_quark.h>

Uniquely identifiable interned string type.

Two quarks may be directly compared to one another for equality.

Note

To test whether a given GblQuark is valid or not, it can be compared to GBL_QUARK_INVALID.

Definition at line 67 of file gimbal_quark.h.

GblStringList

typedef GblRingList GblStringList

#include <gimbal_string_list.h>

List of strings with array-like API.

GblStringList is a dynamically resizable list of immutable strings. It is implemented as a GblRingBuffer where each entry is a GblStringRef.

Warning

Since each entry is a GblStringRef, it should not be directly modified, as this will modify the value of every other reference to the same string data. If you must modify an entry, use GblStringList_replaceStr to replace an existing entry with a new value.

Note

Since GblStringList is backed by GblRingList, it gains some interesting properties. The list can be rotated, reversed, and indexed from the opposite direction using negative values. Operations such as middle insertion/deletion and joining with another list do not require dynamically resizing or moving list entries. It also becomes a reference type with reference semantics.

Since each entry within the list is a GblStringRef, operations such as creating sublists, filtering, copying, and any operation that creates a new list from an existing list are optimized to not actually copy the values of each individual string. Instead, each derived list shares a reference to the same memory location.

Since each entry within the list is a GblStringRef, there is a duplicate API provided for when inserting entries into the list which are already GblStringRefs. Favor the methods ending with "Ref" for when you already have a reference type, and this will ellide copying.

See also

GblStringRef, GblRingBuffer

Definition at line 80 of file gimbal_string_list.h.

GblStringRef

typedef const char GblStringRef

#include <gimbal_string_ref.h>

Reference-counted, const char*-compatible string type.

GblStringRef is a const char*-compatible reference-counted, read-only string type allowing for the sharing of a single string allocation between multiple different locations.

See also

gimbal_string_ref.h

Definition at line 61 of file gimbal_string_ref.h.