AcediaCore/sources/Text/JSON/BaseJsonPointer.uc

/**
 * Author: dkanus
 * Home repo: https://www.insultplayers.ru/git/AcediaFramework/AcediaCore
 * License: GPL
 * Copyright 2021-2023 Anton Tarasenko
 *------------------------------------------------------------------------------
 * This file is part of Acedia.
 *
 * Acedia is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, version 3 of the License, or
 * (at your option) any later version.
 *
 * Acedia is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Acedia.  If not, see <https://www.gnu.org/licenses/>.
 */
class BaseJsonPointer extends AcediaObject
    abstract;

//! A base class for representing a JSON pointer as defined in
//! [RFC6901](https://tools.ietf.org/html/rfc6901).
//!
//! A JSON pointer is a string of tokens separated by the "/" character.
//! Each token represents a reference to an object's key or an array's index.
//! For example, the pointer "/foo/1/bar" corresponds to the key "bar" of the array element at
//! index 1 of the object with key "foo".
//!
//! This class provides a simple way to represent and access the components of a JSON pointer.
//! The Path "/a/b/c" will be stored as a sequence of components "a", "b" and "c", the path "/"
//! will be stored as a singular empty component "" and an empty path "" would mean that there are
//! no components at all.

/// A component of a Json pointer, which is a part of the pointer separated by
/// the slash character '/'
struct Component {
    // For arrays, a component is specified by a numeric index.
    // To avoid parsing the [`textRepresentation`] property multiple times, we record whether we
    // have already done so.
    var bool testedForBeingNumeric;
    // Numeric index represented by asText.
    // It is set to `-1` if it was already tested and found not to be a number.
    // Valid index values are always >= 0.
    var int numericRepresentation;
    // [`Text`] representation of the component.
    // Can be equal to `none` only if this component was specified via a numeric index.
    // This guarantees that [`testedForBeingNumeric`] is `true`.
    var Text textRepresentation;
};

// An array of components that make up the path for this Json pointer.
// Each component represents a part of the path separated by the slash character '/'.
// The array contains the sequence of components that this Json pointer was initialized with.
var protected array<Component> components;

var protected const int TSLASH, TJson_ESCAPE, TJson_ESCAPED_SLASH;
var protected const int TJSON_ESCAPED_ESCAPE;

protected function Finalizer() {
    local int i;

    for (i = 0; i < components.length; i += 1) {
        _.memory.Free(components[i].textRepresentation);
    }
    components.length = 0;
}

/// Checks whether this [`BaseJsonPointer`] instance is empty, meaning it points at the root value.
///
/// Returns `true` if it is empty; otherwise, returns `false`.
public final function bool IsEmpty() {
    return components.length == 0;
}

/// Returns the component of the path specified by the given index, starting from 0.
///
/// Returns the path's component as a [`Text`] unless the specified index is outside of the range of
/// `[0, GetLength() - 1]`. In that case, it returns `none`.
public final function Text GetComponent(int index) {
    local MutableText result;

    result = GetMutableComponent(index);
    if (result != none) {
        return result.IntoText();
    }
    return none;
}

/// Returns the component of the path specified by the given index, starting from 0.
///
/// Returns the path's component as a [`MutableText`] unless the specified index is outside of the
/// range of `[0, GetLength() - 1]`. In that case, it returns `none`.
public final function MutableText GetMutableComponent(int index) {
    if (index < 0)                  return none;
    if (index >= components.length) return none;

    // [`asText`] will store `none` only if we have added this component as numeric one
    if (components[index].textRepresentation == none) {
        components[index].textRepresentation =
            _.text.FromInt(components[index].numericRepresentation);
    }
    return components[index].textRepresentation.MutableCopy();
}

/// Returns the numeric component of the path specified by the given index, starting from `0`.
///
/// Returns the path's component as a non-negative `int` unless the specified index is outside of
/// the range of [0, GetLength() - 1]. In that case, it returns `-1`.
public final function int GetNumericComponent(int index) {
    local Parser parser;

    if (index < 0)                  return -1;
    if (index >= components.length) return -1;

    if (!components[index].testedForBeingNumeric)
    {
        components[index].testedForBeingNumeric = true;
        parser = _.text.Parse(components[index].textRepresentation);
        parser.MUnsignedInteger(components[index].numericRepresentation);
        if (!parser.Ok() || !parser.HasFinished()) {
            components[index].numericRepresentation = -1;
        }
        parser.FreeSelf();
    }
    return components[index].numericRepresentation;
}

/// Checks if the component at the given index can be used to index an array.
///
/// This method accepts numeric components and the "-" component, which can be used to point to
/// the element after the last one in a [`JsonArray`].
///
/// Returns `true` if a component with the given index exists and is either
/// a positive number or "-".
public final function bool IsComponentArrayApplicable(int index) {
    local bool appendElementAlias;
    local Text component;

    if (GetNumericComponent(index) >= 0) {
        return true;
    }
    component = GetComponent(index);
    appendElementAlias = P("-").IsEqual(component);
    _.memory.Free(component);
    return appendElementAlias;
}

/// Converts caller [`JsonPointer`] into it's [`Text`] representation.
public final function Text ToText() {
    return ToMutableText().IntoText();
}

/// Converts caller [`JsonPointer`] into it's [`MutableText`] representation.
public final function MutableText ToMutableText() {
    local int i;
    local Text nextComponent;
    local MutableText nextMutableComponent;
    local MutableText result;

    result = _.text.Empty();
    if (GetLength() <= 0) {
        return result;
    }
    for (i = 0; i < GetLength(); i += 1) {
        nextComponent = GetComponent(i);
        nextMutableComponent = nextComponent.MutableCopy();
        //  Replace (order is important)
        nextMutableComponent.Replace(T(TJson_ESCAPE), T(TJSON_ESCAPED_ESCAPE));
        nextMutableComponent.Replace(T(TSLASH), T(TJson_ESCAPED_SLASH));
        result.Append(T(TSLASH)).Append(nextMutableComponent);
        //  Get rid of temporary values
        nextMutableComponent.FreeSelf();
        nextComponent.FreeSelf();
    }
    return result;
}

/// Returns the number of path components in the caller JsonPointer.
public final function int GetLength() {
    return components.length;
}

/// Returns the number of intermediate path components in the caller JsonPointer
/// that do not directly correspond to a pointed value.
///
/// This number is calculated as Max(0, GetLength() - 1). For example, if the
/// Json pointer is "/user/Ivan/records/5/count", it refers to the value named
/// "count" that is nested inside 4 objects named "user", "Ivan", "records",
/// and "5". Therefore, the number of intermediate path components or "folds"
/// is equal to 4.
public final function int GetFoldsAmount() {
    return Max(0, components.length - 1);
}

/// Creates an immutable copy of the caller [`BaseJsonPointer`].
///
/// Copies components in the range `[startIndex; startIndex + maxLength - 1]`.
/// If the provided parameters `startIndex` and `maxLength` define a range that goes beyond
/// `[0; self.GetLength() - 1]`, then the intersection with a valid range will be used.
///
/// If [`maxLength`] is `0` (default value) or a negative value, the method extracts all components
/// to the right of `startIndex`.
public final function JsonPointer Copy(optional int startIndex, optional int maxLength) {
    local JsonPointer newPointer;

    newPointer = JsonPointer(_.memory.Allocate(class'JsonPointer'));
    _copyInto(newPointer, startIndex, maxLength);
    return newPointer;
}

/// Creates an mutable copy of the caller [`BaseJsonPointer`].
///
/// Copies components in the range `[startIndex; startIndex + maxLength - 1]`.
/// If the provided parameters `startIndex` and `maxLength` define a range that goes beyond
/// `[0; self.GetLength() - 1]`, then the intersection with a valid range will be used.
///
/// If [`maxLength`] is `0` (default value) or a negative value, the method extracts all components
/// to the right of `startIndex`.
public final function MutableJsonPointer MutableCopy(
    optional int startIndex,
    optional int maxLength
) {
    local MutableJsonPointer newPointer;

    newPointer = MutableJsonPointer(_.memory.Allocate(class'MutableJsonPointer'));
    _copyInto(newPointer, startIndex, maxLength);
    return newPointer;
}

/// Determines whether the given pointer corresponds to the beginning of the caller one.
///
/// A pointer starts with another one if it includes all of its fields from the beginning and in order.
/// For example, "/A/B/C" starts with "/A/B", but not with "/A/B/C/D", "/D/A/B/C" or "/A/B/CD".
///
/// Returns `true` if [`other`] is a prefix and `false` otherwise.
/// `none` is considered to be an empty pointer and therefore a prefix to any other pointer.
public final function bool StartsWith(BaseJsonPointer other) {
    local int i;
    local array<Component> otherComponents;

    // `none` is same as empty
    if (other == none)                              return true;
    otherComponents = other.components;
    // Not enough length
    if (components.length < otherComponents.length) return false;

    for (i = 0; i < otherComponents.length; i += 1) {
        // Compare numeric components if at least one is such
        if (components[i].testedForBeingNumeric || otherComponents[i].testedForBeingNumeric) {
            if (GetNumericComponent(i) != other.GetNumericComponent(i)) {
                return false;
            }
            // End this iteration for numeric component, but continue for text ones
            if (GetNumericComponent(i) >= 0) {
                continue;
            }
        }
        // We can reach here if:
        //
        // 1. Neither components have `testedForBeingNumeric` set to `true`,
        //  neither `asText` fields are `none` by the invariant;
        // 2. At least one had `testedForBeingNumeric`, but they tested negative for being numeric.
        if (!components[i].textRepresentation.Compare(otherComponents[i].textRepresentation)) {
            return false;
        }
    }
    return true;
}

/// Returns the last component of the caller [`MutableJsonPointer`].
///
/// For example, if the caller [`MutableJsonPointer`] corresponds to "/ab/c/d", this method
/// would return "d".
///
/// If the caller [`MutableJsonPointer`] is empty, the returned last component is `none`.
public final function Text Peek() {
    local MutableText mutableResult;

    mutableResult = PeekMutable();
    if (mutableResult != none) {
        return mutableResult.IntoText();
    }
    return none;
}

/// Returns the last component of the caller [`MutableJsonPointer`].
///
/// For example, if the caller [`MutableJsonPointer`] corresponds to "/ab/c/d", this method
/// would return "d".
///
/// If the caller [`MutableJsonPointer`] is empty, the returned last component is `none`.
public final function MutableText PeekMutable() {
    local int lastIndex;
    local MutableText result;

    if (components.length <= 0) {
        return none;
    }
    lastIndex = components.length - 1;
    //  Do not use `GetComponent()` to avoid unnecessary `Text` copying
    if (components[lastIndex].textRepresentation == none) {
        result = _.text.FromIntM(components[lastIndex].numericRepresentation);
    } else {
        result = components[lastIndex].textRepresentation.MutableCopy();
    }
    return result;
}

/// Returns the last numeric component of the caller [`MutableJsonPointer`].
///
/// For instance, if the caller [`MutableJsonPointer`] corresponds to "/ab/c/1", this method
/// would return `1`.
///
/// If the caller [`MutableJsonPointer`] does not end with a numeric component or is empty,
/// the returned value is `-1`.
public final function int PeekNumeric() {
    local int lastIndex;
    local int result;

    if (components.length <= 0) {
        return -1;
    }
    lastIndex = components.length - 1;
    result = GetNumericComponent(lastIndex);
    return result;
}

/// This method releases caller json pointer and returns immutable [`JsonPointer`] copy instead.
public function JsonPointer IntoJsonPointer() {
    local JsonPointer result;

    result = Copy();
    FreeSelf();
    return result;
}

/// This method releases caller json pointer and returns mutable [`MutableJsonPointer`] copy
/// instead.
public function MutableJsonPointer IntoMutableJsonPointer() {
    local MutableJsonPointer result;

    result = MutableCopy();
    FreeSelf();
    return result;
}

// Copies contents of caller into `copy` pointer.
// Assumes `copy` is freshly made: not `none`, but also no need to deallocate its components
private final function _copyInto(
    BaseJsonPointer copy,
    optional int startIndex,
    optional int maxLength
) {
    local int i, endIndex;
    local array<Component> newComponents;

    if (maxLength <= 0) {
        maxLength = components.length - startIndex;
    }
    endIndex = startIndex + maxLength;
    if (endIndex <= 0) {
        return;
    }
    startIndex = Max(startIndex, 0);
    endIndex = Min(endIndex, components.length);
    for (i = startIndex; i < endIndex; i += 1) {
        newComponents[newComponents.length] = components[i];
        if (components[i].textRepresentation != none) {
            newComponents[newComponents.length - 1].textRepresentation =
                components[i].textRepresentation.Copy();
        }
    }
    copy.components = newComponents;
}

defaultproperties {
    TSLASH                  = 0
    stringConstants(0)      = "/"
    TJson_ESCAPE            = 1
    stringConstants(1)      = "~"
    TJson_ESCAPED_SLASH     = 2
    stringConstants(2)      = "~1"
    TJSON_ESCAPED_ESCAPE    = 3
    stringConstants(3)      = "~0"
}