std::basic_string::copy(3)

💖 std::basic_string::copy(3) — C++ Standard Libary 💖

🌸 NAME 🌸

std::basic_string::copy — std::basic_string::copy (yes bestie, it really said it twice 💅)

🦋 Synopsis 🦋

okay so here's the signature, copied exactly:

size_type copy( CharT* dest, size_type count, size_type pos
(constexpr since C++20)
= 0 ) const;

This one copies a substring [pos, pos + count) to the character string pointed to by dest. If the requested substring lasts past the end of the string, or if count == npos, the copied substring is [pos, size()).

The resulting character string is not null-terminated 😭 — no sneaky \0, bestie.

🎀 Parameters 🎀

• dest — pointer to the destination character string 🫶
• count — length of the substring ✨
• pos — position of the first character to include 💖

⭐ Return value ⭐

Number of characters copied. That's the whole vibe, periodt.

🚨 Exceptions 🚨

std::out_of_range if pos > size().

If an exception is thrown for any reason, this function has no effect — strong exception safety guarantee, icon behavior ✨.

🔥 Complexity 🔥

Linear in count. No cap.

🍓 Example 🍓

The example, with its // Run this code note:

#include <iostream>
#include <string>

int main()
{
    std::string foo("WINE");

    // brace-initialization initializes all characters to 0,
    // providing a null-terminator
    char bar[4]{};

    // do not copy the last char, to guarantee null-termination
    foo.copy(bar, sizeof bar - 1);

    std::cout << bar << '\n'; // requires bar to be null-terminated
}

🌈 Output 🌈

WIN

🩹 Defect reports 🩹

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 847 — applied to C++98; behavior as published: there was no exception safety guarantee; correct behavior: added strong exception safety guarantee.

👑 See also 👑

• substr — returns a substring (public member function)
• copy — copies characters (public member function of std::basic_string_view<CharT,Traits>)
• copy — copies a range of elements to a new location
• copy_if — (function template) (C++11)
• memcpy — copies one buffer to another (function)

source/version + date: cppreference.com — 2024.06.10 — mwah, bye bestie 💋🎀