JX Application Framework
Loading...
Searching...
No Matches
Public Types | Public Member Functions | List of all members
JStringIterator Class Reference

#include <JStringIterator.h>

Public Types

enum  Position {
  kStartAtBeginning ,
  kStartAtEnd ,
  kStartBeforeChar ,
  kStartAfterChar ,
  kStartBeforeByte ,
  kStartAfterByte
}
 
enum  Action {
  kStay = 0 ,
  kMove = 1
}
 

Public Member Functions

 JStringIterator (const JString &s, const Position start=kStartAtBeginning, const JIndex index=0)
 
 JStringIterator (JString *s, const Position start=kStartAtBeginning, const JIndex index=0)
 
 ~JStringIterator ()
 
bool IsValid () const
 
bool AtBeginning () const
 
bool AtEnd () const
 
JIndex GetPrevCharacterIndex () const
 
JIndex GetNextCharacterIndex () const
 
bool GetPrevCharacterIndex (JIndex *i) const
 
bool GetNextCharacterIndex (JIndex *i) const
 
const JString & GetString () const
 
void MoveTo (const Position newPosition, const JIndex characterIndex)
 
bool SkipPrev (const JSize characterCount=1)
 
bool SkipNext (const JSize characterCount=1)
 
void UnsafeMoveTo (const Position newPosition, const JIndex characterIndex, const JIndex byteIndex)
 
bool Prev (JUtf8Character *c, const Action move=kMove)
 
bool Next (JUtf8Character *c, const Action move=kMove)
 
bool Prev (const JString &str, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Prev (const JUtf8Byte *str, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Prev (const JUtf8Byte *str, const JSize byteCount, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Prev (const JUtf8Character &c, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Prev (const std::string &str, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Prev (const JRegex &pattern)
 
bool Next (const JString &str, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Next (const JUtf8Byte *str, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Next (const JUtf8Byte *str, const JSize byteCount, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Next (const JUtf8Character &c, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Next (const std::string &str, const JString::Case caseSensitive=JString::kCompareCase)
 
bool Next (const JRegex &pattern)
 
const JStringMatch & GetLastMatch () const
 
void BeginMatch ()
 
const JStringMatch & FinishMatch (const bool includeLastMatch=false)
 
bool SetPrev (const JUtf8Character &c, const Action move=kMove)
 
bool SetNext (const JUtf8Character &c, const Action move=kMove)
 
bool RemovePrev (const JSize characterCount=1)
 
bool RemoveNext (const JSize characterCount=1)
 
void RemoveAllPrev ()
 
void RemoveAllNext ()
 
void RemoveLastMatch ()
 
void ReplaceLastMatch (const JString &str, const bool matchCase=false)
 
void ReplaceLastMatch (const JString &str, const JCharacterRange &range, const bool matchCase=false)
 
void ReplaceLastMatch (const JUtf8Byte *str, const bool matchCase=false)
 
void ReplaceLastMatch (const JUtf8Byte *str, const JSize byteCount, const bool matchCase=false)
 
void ReplaceLastMatch (const JUtf8Byte *str, const JUtf8ByteRange &range, const bool matchCase=false)
 
void ReplaceLastMatch (const JUtf8Character &c, const bool matchCase=false)
 
void ReplaceLastMatch (const std::string &str, const bool matchCase=false)
 
void ReplaceLastMatch (const std::string &str, const JUtf8ByteRange &range, const bool matchCase=false)
 
void Insert (const JString &str)
 
void Insert (const JString &str, const JCharacterRange &range)
 
void Insert (const JUtf8Byte *str)
 
void Insert (const JUtf8Byte *str, const JSize byteCount)
 
void Insert (const JUtf8Byte *str, const JUtf8ByteRange &range)
 
void Insert (const JUtf8Character &c)
 
void Insert (const std::string &str)
 
void Insert (const std::string &str, const JUtf8ByteRange &range)
 
JIndex GetPrevByteIndex () const
 
JIndex GetNextByteIndex () const
 
bool GetPrevByteIndex (JIndex *i) const
 
bool GetNextByteIndex (JIndex *i) const
 
void ClearLastMatch ()
 
void Invalidate ()
 

Detailed Description

                    The JString Iterator Class

UTF-8 combines the worst of arrays and linked lists.  Search and
insertion are both O(N), and iteration is complicated by characters not
being a fixed number of bytes.

This iterator provides the most efficient, error-resistant way to loop
through the UTF-8 characters in a string:

    JString s;
    ...
    JStringIterator iterator(s);
    JUtf8Character  char;

    while (iterator.Next(&char))
    {
        <do something with the character>
    }

or

    while (iterator.Next("..."))
    {
        <do something with JStringMatch returned by GetLastMatch()>
    }

An iterator is robust in the face of insertions and deletions to
the JString it is working on.

    For simplicity, each JString can have only one iterator at a time,
    and any modification not done via the iterator will invalidate the
    iterator.

Refer to the docs for JListIterator for more details.

Member Enumeration Documentation

◆ Action

enum JStringIterator::Action
Enumerator
kStay 
kMove 

◆ Position

enum JStringIterator::Position
Enumerator
kStartAtBeginning 
kStartAtEnd 
kStartBeforeChar 
kStartAfterChar 
kStartBeforeByte 
kStartAfterByte 

Constructor & Destructor Documentation

◆ JStringIterator() [1/2]

JStringIterator::JStringIterator ( const JString &  s,
const Position  start = kStartAtBeginning,
const JIndex  index = 0 
)

◆ JStringIterator() [2/2]

JStringIterator::JStringIterator ( JString *  s,
const Position  start = kStartAtBeginning,
const JIndex  index = 0 
)

◆ ~JStringIterator()

JStringIterator::~JStringIterator ( )

Member Function Documentation

◆ AtBeginning()

bool JStringIterator::AtBeginning ( ) const
inline

Returns true if iterator is positioned at the beginning of the string or if the iterator has been invalidated.

◆ AtEnd()

bool JStringIterator::AtEnd ( ) const
inline

Returns true if iterator is positioned at the end of the string or if the iterator has been invalidated.

◆ BeginMatch()

void JStringIterator::BeginMatch ( )
inline

Marks the current position as the start of a match.

◆ ClearLastMatch()

void JStringIterator::ClearLastMatch ( )

◆ FinishMatch()

const JStringMatch & JStringIterator::FinishMatch ( const bool  includeLastMatch = false)

Finishes matching and sets itsLastMatch.

If includeLastMatch, includes the range currently stored in itsLastMatch. This is off by default to simplify extracting everything except end-of-token.

◆ GetLastMatch()

const JStringMatch & JStringIterator::GetLastMatch ( ) const

Explodes if there was no last match, because this makes the API simpler and it's really easy to know if you just got a match.

◆ GetNextByteIndex() [1/2]

JIndex JStringIterator::GetNextByteIndex ( ) const

asserts that there is a next byte

◆ GetNextByteIndex() [2/2]

bool JStringIterator::GetNextByteIndex ( JIndex *  i) const
inline

Returns true if there is a next character.

◆ GetNextCharacterIndex() [1/2]

JIndex JStringIterator::GetNextCharacterIndex ( ) const

asserts that there is a next character

◆ GetNextCharacterIndex() [2/2]

bool JStringIterator::GetNextCharacterIndex ( JIndex *  i) const
inline

Returns true if there is a next character.

◆ GetPrevByteIndex() [1/2]

JIndex JStringIterator::GetPrevByteIndex ( ) const

asserts that there is a previous byte

◆ GetPrevByteIndex() [2/2]

bool JStringIterator::GetPrevByteIndex ( JIndex *  i) const
inline

Returns true if there is a previous character.

◆ GetPrevCharacterIndex() [1/2]

JIndex JStringIterator::GetPrevCharacterIndex ( ) const

asserts that there is a previous character

◆ GetPrevCharacterIndex() [2/2]

bool JStringIterator::GetPrevCharacterIndex ( JIndex *  i) const
inline

Returns true if there is a previous character.

◆ GetString()

const JString & JStringIterator::GetString ( ) const
inline

Iterator must be valid.

◆ Insert() [1/8]

void JStringIterator::Insert ( const JString &  str)
inline

◆ Insert() [2/8]

void JStringIterator::Insert ( const JString &  str,
const JCharacterRange &  range 
)
inline

◆ Insert() [3/8]

void JStringIterator::Insert ( const JUtf8Byte *  str)
inline

◆ Insert() [4/8]

void JStringIterator::Insert ( const JUtf8Byte *  str,
const JSize  byteCount 
)
inline

◆ Insert() [5/8]

void JStringIterator::Insert ( const JUtf8Byte *  str,
const JUtf8ByteRange &  range 
)

Insert the given characters after the current position. 

Only allowed if iterator was constructed with non-const JString.

◆ Insert() [6/8]

void JStringIterator::Insert ( const JUtf8Character &  c)
inline

◆ Insert() [7/8]

void JStringIterator::Insert ( const std::string &  str)
inline

◆ Insert() [8/8]

void JStringIterator::Insert ( const std::string &  str,
const JUtf8ByteRange &  range 
)
inline

◆ Invalidate()

void JStringIterator::Invalidate ( )

◆ IsValid()

bool JStringIterator::IsValid ( ) const
inline

Return true if iterator has not been invalidated.

◆ MoveTo()

void JStringIterator::MoveTo ( const Position  newPosition,
const JIndex  characterIndex 
)

◆ Next() [1/7]

bool JStringIterator::Next ( const JRegex &  pattern)

Returns true if a match is found later in the string. Match details can be retrieved from GetLastMatch().

If a match is found, the cursor position is set beyond the end of the match. Otherwise the cursor position is moved to the end of the string.

◆ Next() [2/7]

bool JStringIterator::Next ( const JString &  str,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Next() [3/7]

bool JStringIterator::Next ( const JUtf8Byte *  str,
const JSize  byteCount,
const JString::Case  caseSensitive = JString::kCompareCase 
)

Returns true if a match is found later in the string. Match details can be retrieved from GetLastMatch().

If a match is found, the cursor position is set beyond the end of the match. Otherwise the cursor position is moved to the end of the string.

◆ Next() [4/7]

bool JStringIterator::Next ( const JUtf8Byte *  str,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Next() [5/7]

bool JStringIterator::Next ( const JUtf8Character &  c,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Next() [6/7]

bool JStringIterator::Next ( const std::string &  str,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Next() [7/7]

bool JStringIterator::Next ( JUtf8Character *  c,
const Action  move = kMove 
)

Returns true if there is a next character, fetching the next character in the list and (if requested) incrementing the iterator position. Otherwise returns false without fetching or incrementing.

◆ Prev() [1/7]

bool JStringIterator::Prev ( const JRegex &  pattern)

Returns true if a match is found earlier in the string. Match details can be retrieved from GetLastMatch().

If a match is found, the cursor position is set to the start of the match. Otherwise the cursor position is moved to the start of the string.

◆ Prev() [2/7]

bool JStringIterator::Prev ( const JString &  str,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Prev() [3/7]

bool JStringIterator::Prev ( const JUtf8Byte *  str,
const JSize  byteCount,
const JString::Case  caseSensitive = JString::kCompareCase 
)

Returns true if a match is found earlier in the string. Match details can be retrieved from GetLastMatch().

If a match is found, the cursor position is set to the start of the match. Otherwise the cursor position is moved to the start of the string.

◆ Prev() [4/7]

bool JStringIterator::Prev ( const JUtf8Byte *  str,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Prev() [5/7]

bool JStringIterator::Prev ( const JUtf8Character &  c,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Prev() [6/7]

bool JStringIterator::Prev ( const std::string &  str,
const JString::Case  caseSensitive = JString::kCompareCase 
)
inline

◆ Prev() [7/7]

bool JStringIterator::Prev ( JUtf8Character *  c,
const Action  move = kMove 
)

Returns true if there is a previous character, fetching the previous character in the string and (if requested) decrementing the iterator position. Otherwise returns false without fetching or decrementing.

◆ RemoveAllNext()

void JStringIterator::RemoveAllNext ( )

Removes all following characters. 

Only allowed if iterator was constructed with non-const JString.

◆ RemoveAllPrev()

void JStringIterator::RemoveAllPrev ( )

Removes all preceding characters. 

Only allowed if iterator was constructed with non-const JString.

◆ RemoveLastMatch()

void JStringIterator::RemoveLastMatch ( )
inline

Removes the characters from the last match. 

Match must exist.
Only allowed if iterator was constructed with non-const JString.

◆ RemoveNext()

bool JStringIterator::RemoveNext ( const JSize  characterCount = 1)

If there are enough following characters, removes them and returns true. Otherwise, removes all following characters and returns false. 

Only allowed if iterator was constructed with non-const JString.

◆ RemovePrev()

bool JStringIterator::RemovePrev ( const JSize  characterCount = 1)

If there are enough previous characters, removes them and returns true. Otherwise, removes all preceding characters and returns false. 

Only allowed if iterator was constructed with non-const JString.

◆ ReplaceLastMatch() [1/8]

void JStringIterator::ReplaceLastMatch ( const JString &  str,
const bool  matchCase = false 
)
inline

◆ ReplaceLastMatch() [2/8]

void JStringIterator::ReplaceLastMatch ( const JString &  str,
const JCharacterRange &  range,
const bool  matchCase = false 
)
inline

◆ ReplaceLastMatch() [3/8]

void JStringIterator::ReplaceLastMatch ( const JUtf8Byte *  str,
const bool  matchCase = false 
)
inline

◆ ReplaceLastMatch() [4/8]

void JStringIterator::ReplaceLastMatch ( const JUtf8Byte *  str,
const JSize  byteCount,
const bool  matchCase = false 
)
inline

◆ ReplaceLastMatch() [5/8]

void JStringIterator::ReplaceLastMatch ( const JUtf8Byte *  str,
const JUtf8ByteRange &  range,
const bool  matchCase = false 
)

Replaces the characters from the last match, optionally matching case. 

Match must exist.
Only allowed if iterator was constructed with non-const JString.

◆ ReplaceLastMatch() [6/8]

void JStringIterator::ReplaceLastMatch ( const JUtf8Character &  c,
const bool  matchCase = false 
)
inline

◆ ReplaceLastMatch() [7/8]

void JStringIterator::ReplaceLastMatch ( const std::string &  str,
const bool  matchCase = false 
)
inline

◆ ReplaceLastMatch() [8/8]

void JStringIterator::ReplaceLastMatch ( const std::string &  str,
const JUtf8ByteRange &  range,
const bool  matchCase = false 
)
inline

◆ SetNext()

bool JStringIterator::SetNext ( const JUtf8Character &  c,
const Action  move = kMove 
)

If there is a next character, sets it, (if requested) increments the iterator position, and returns true. Otherwise, returns false. 

Only allowed if iterator was constructed with non-const JString.

◆ SetPrev()

bool JStringIterator::SetPrev ( const JUtf8Character &  c,
const Action  move = kMove 
)

If there is a previous character, sets it, (if requested) decrements the iterator position, and returns true. Otherwise, returns false. 

Only allowed if iterator was constructed with non-const JString.

◆ SkipNext()

bool JStringIterator::SkipNext ( const JSize  characterCount = 1)

If there are enough following characters, skips them and returns true. Otherwise, moves iterator position to the end and returns false.

◆ SkipPrev()

bool JStringIterator::SkipPrev ( const JSize  characterCount = 1)

If there are enough previous characters, skips them and returns true. Otherwise, moves iterator position to the beginning and returns false.

◆ UnsafeMoveTo()

void JStringIterator::UnsafeMoveTo ( const Position  newPosition,
const JIndex  characterIndex,
const JIndex  byteIndex 
)

Intended for highly optimized code working with huge strings. Only accepts kJIteratorStartBefore/After, since others can be passed to MoveTo(). 

Assumes, but does not verify, that character index and byte index
point to the same location!
The documentation for this class was generated from the following files:
Generated on Thu Dec 7 2023 22:02:44 for JX Application Framework by doxygen 1.9.8