pw_string/public/pw_string/util.h

// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
#pragma once
/// @file pw_string/util.h
///
/// @brief The `pw::string::*` functions provide safer alternatives to
/// C++ standard library string functions.

#include <cctype>
#include <cstddef>
#include <string_view>

#include "pw_assert/assert.h"
#include "pw_polyfill/language_feature_macros.h"
#include "pw_result/result.h"
#include "pw_span/span.h"
#include "pw_status/status.h"
#include "pw_status/status_with_size.h"
#include "pw_string/internal/length.h"
#include "pw_string/string.h"

namespace pw {
namespace string {
namespace internal {

PW_CONSTEXPR_CPP20 inline StatusWithSize CopyToSpan(
    const std::string_view& source, span<char> dest) {
  if (dest.empty()) {
    return StatusWithSize::ResourceExhausted();
  }

  const size_t copied = source.copy(dest.data(), dest.size() - 1);
  dest[copied] = '\0';

  return StatusWithSize(
      copied == source.size() ? OkStatus() : Status::ResourceExhausted(),
      copied);
}

}  // namespace internal

/// @brief Safe alternative to the `string_view` constructor that avoids the
/// risk of an unbounded implicit or explicit use of `strlen`.
///
/// This is strongly recommended over using something like C11's `strnlen_s` as
/// a `string_view` does not require null-termination.
constexpr std::string_view ClampedCString(span<const char> str) {
  return std::string_view(str.data(),
                          internal::ClampedLength(str.data(), str.size()));
}

constexpr std::string_view ClampedCString(const char* str, size_t max_len) {
  return ClampedCString(span<const char>(str, max_len));
}

/// @brief `pw::string::NullTerminatedLength` is a safer alternative to
/// `strlen` for calculating the null-terminated length of the
/// string within the specified span, excluding the null terminator.
///
/// Like `strnlen_s` in C11, the scan for the null-terminator is bounded.
///
/// @pre The string shall be at a valid pointer.
///
/// @returns the null-terminated length of the string excluding the null
/// terminator or `OutOfRange` if the string is not null-terminated.
constexpr Result<size_t> NullTerminatedLength(span<const char> str) {
  PW_DASSERT(str.data() != nullptr);

  const size_t length = internal::ClampedLength(str.data(), str.size());
  if (length == str.size()) {
    return Status::OutOfRange();
  }

  return length;
}

constexpr Result<size_t> NullTerminatedLength(const char* str, size_t max_len) {
  return NullTerminatedLength(span<const char>(str, max_len));
}

/// @brief `pw::string::Copy` is a safer alternative to `std::strncpy` as it
/// always null-terminates whenever the destination buffer has a non-zero size.
///
/// Copies the `source` string to the `dest`, truncating if the full string does
/// not fit. Always null terminates if `dest.size()` or `num` is greater than 0.
///
/// @pre The destination and source shall not overlap. The source
/// shall be a valid pointer.
///
/// @returns the number of characters written, excluding the null terminator. If
/// the string is truncated, the status is `RESOURCE_EXHAUSTED`.
template <typename Span>
PW_CONSTEXPR_CPP20 inline StatusWithSize Copy(const std::string_view& source,
                                              Span&& dest) {
  static_assert(
      !std::is_base_of_v<InlineString<>, std::decay_t<Span>>,
      "Do not use pw::string::Copy() with pw::InlineString<>. Instead, use "
      "pw::InlineString<>'s assignment operator or assign() function, or "
      "pw::string::Append().");
  return internal::CopyToSpan(source, std::forward<Span>(dest));
}

template <typename Span>
PW_CONSTEXPR_CPP20 inline StatusWithSize Copy(const char* source, Span&& dest) {
  PW_DASSERT(source != nullptr);
  return Copy(ClampedCString(source, std::size(dest)),
              std::forward<Span>(dest));
}

PW_CONSTEXPR_CPP20 inline StatusWithSize Copy(const char* source,
                                              char* dest,
                                              size_t num) {
  return Copy(source, span<char>(dest, num));
}

/// Assigns a `std::string_view` to a `pw::InlineString`, truncating if it does
/// not fit. The `assign()` function of `pw::InlineString` asserts if the
/// string's requested size exceeds its capacity; `pw::string::Assign()`
/// returns a `Status` instead.
///
/// @return `OK` if the entire `std::string_view` was copied to the end of the
/// `pw::InlineString`. `RESOURCE_EXHAUSTED` if the `std::string_view` was
/// truncated to fit.
inline Status Assign(InlineString<>& string, const std::string_view& view) {
  const size_t chars_copied =
      std::min(view.size(), static_cast<size_t>(string.capacity()));
  string.assign(view, 0, static_cast<string_impl::size_type>(chars_copied));
  return chars_copied == view.size() ? OkStatus() : Status::ResourceExhausted();
}

inline Status Assign(InlineString<>& string, const char* c_string) {
  PW_DASSERT(c_string != nullptr);
  // Clamp to capacity + 1 so strings larger than the capacity yield an error.
  return Assign(string, ClampedCString(c_string, string.capacity() + 1));
}

/// Appends a `std::string_view` to a `pw::InlineString`, truncating if it
/// does not fit. The `append()` function of `pw::InlineString` asserts if the
/// string's requested size exceeds its capacity; `pw::string::Append()` returns
/// a `Status` instead.
///
/// @return `OK` if the entire `std::string_view` was assigned.
/// `RESOURCE_EXHAUSTED` if the `std::string_view` was truncated to fit.
inline Status Append(InlineString<>& string, const std::string_view& view) {
  const size_t chars_copied = std::min(
      view.size(), static_cast<size_t>(string.capacity() - string.size()));
  string.append(view, 0, static_cast<string_impl::size_type>(chars_copied));
  return chars_copied == view.size() ? OkStatus() : Status::ResourceExhausted();
}

inline Status Append(InlineString<>& string, const char* c_string) {
  PW_DASSERT(c_string != nullptr);
  // Clamp to capacity + 1 so strings larger than the capacity yield an error.
  return Append(string, ClampedCString(c_string, string.capacity() + 1));
}

/// @brief Provides a safe, printable copy of a string.
///
/// Copies the `source` string to the `dest` string with same behavior as
/// `pw::string::Copy`, with the difference that any non-printable characters
/// are changed to `.`.
PW_CONSTEXPR_CPP20 inline StatusWithSize PrintableCopy(
    const std::string_view& source, span<char> dest) {
  StatusWithSize copy_result = Copy(source, dest);
  for (size_t i = 0; i < copy_result.size(); i++) {
    dest[i] = std::isprint(dest[i]) ? dest[i] : '.';
  }

  return copy_result;
}

}  // namespace string
}  // namespace pw