Span

Identify an unowned contiguous memory range

Context

#include <xo/tokenizer/span.hpp>

• Identify a sequence of characters stored in contiguous memory.

• Lightweight, consists of a pair of pointers.

• Does not own storage. Lifetime management for target memory is up to the caller.

Class

template<typename CharT>
class span

A contiguous range of characters, without ownership.

Template Parameters:

CharT – type for elements referred to by this span.

Member Variables

group Span-instance-vars

Variables

CharT *lo_ = nullptr

start of span. Span comprises memory address between lo (inclusive) and hi (exclusive)

CharT *hi_ = nullptr

end of span. Span comprises memory address between lo (inclusive) and hi (exclusive)

Type Traits

group span type traits

Typedefs

using size_type = std::uint64_t

typealias for span size (in units of CharT)

using value_type = CharT

typealias for span elements

using iterator = CharT*

typealias for span iterators. a raw pointer, which models std::contiguous_iterator; that (with size()) is what makes span a std::ranges::contiguous_range.

Constructors

group span constructors

Functions

inline span()

null span

inline span(CharT *lo, CharT *hi)

Create span for the contiguous memory range [lo, hi)

template<typename CharU>
inline span(const span<CharU> &other, std::enable_if_t<std::is_convertible_v<CharU*, CharT*> && !std::is_same_v<CharU, CharT>>* = nullptr)

explicit conversion from span

span(const span &other) = default

copy ctor (explicit to avoid ambiguity with template ctor)

span &operator=(const span &other) = default

static inline span make_null()

Create a null span (i.e. with null lo, hi pointers) A null span can be concatenated with any other span without triggering matching-endpoint asserts.

static inline span from_cstr(const CharT *cstr)

create span for C-style string cstr

static inline span from_string(const std::string &str)

create span from std::string str

static inline span concat(const span &span1, const span &span2)

concatenate two contiguous spans

Access Methods

group Span-access-methods

Functions

inline CharT *lo() const

inline CharT *hi() const

inline iterator begin() const

inline iterator end() const

inline CharT *data() const

General Methods

group Span-general-methods

Functions

inline void discard_until_newline()

strip prefix until first occurence of ‘

’, including the newline

template<typename OtherT>
inline span<OtherT> cast() const

Create new span over supplied type, with identical (possibly misaligned) endpoints.

Warning

1. New span uses exactly the same memory addresses. Endpoint pointers may not be aligned.

2. Implementation assumes code compiled with

   -fno-strict-aliasing 
   

   enabled.

Template Parameters:

OtherT – element type for new span

inline span prefix(size_type z) const

create span including the first z members of this span.

inline span prefix_upto(CharT *p) const

create span representing prefix up to (but not including) *p

inline span after_prefix(size_type z) const

create span with first z members of this span removed

inline span after_prefix(const span &prefix) const

create span with prefix of this span removed

inline span suffix_from(CharT *p) const

Create span starting with position p. Does boundary checking; will return empty span if p is outside [lo_,hi)

inline bool is_null() const

true iff this span is null. distinct from empty.

inline bool empty() const

true iff this span is empty (comprises 0 elements).

inline size_type size() const

report the number of elements (of type CharT) in this span.

inline span &operator+=(const span &x)

increase extent of this spans to include x. Requires hi() == x.lo()

inline void print(std::ostream &os) const

print representation for this span on stream os

Operators

group Span-operators

Functions

template<typename CharT>
inline bool operator==(const span<CharT> &lhs, const span<CharT> &rhs)

compare spans for equality. Two spans are equal iff both endpoints match exactly.

template<typename CharT>
inline bool operator!=(const span<CharT> &lhs, const span<CharT> &rhs)

compare spans for inequality. Two spans are unequal if either paired endpoint differs.

template<typename CharT>
inline std::ostream &operator<<(std::ostream &os, const span<CharT> &x)

print a summary of x on stream os. Intended for diagnostics