blc_conio.h

blc_conio.h 에는 윈도우 콘솔과 관련된 클래스와 전역 함수들이 포함되어 있습니다.

"blc_conio.h" 헤더 및 "blc_conio.cpp" 파일을 프로젝트에 추가한 후, 콘솔 프로그램을 실행시키면 콘솔 출력 문자 인코딩이 UTF-8로 변경됩니다. 그리고 이 콘솔 프로그램이 종료되면 콘솔 출력 문자 인코딩은 실행 전의 설정값으로 복원됩니다.

이 헤더에는 <Windows.h> 헤더가 포함되어 있으므로, 윈도우 환경에서만 사용이 가능하며, 이 헤더를 포함시키는 전처리문은 항상, 다른 헤더를 포함시키는 전처리문보다 위에 와야 합니다.

이 문서에서는 blc_conio.h에 포함된 클래스와 전역 함수들에 대해 설명합니다. 아래에 설명된 요소들은 모두 namespace blc::console 내부에 선언되어 있습니다.

class ConsoleOutputCP final

콘솔창의 출력 문자 인코딩 설정을 도와주는 클래스 입니다. 설정을 원하는 출력 문자 인코딩에 해당하는 번호를 넘겨주며 ConsoleOutputCP 객체를 생성하면, 해당 객체의 생존 시간동안, 콘솔창의 출력 문자 인코딩이 생성자로 넘겨준 값으로 유지됩니다. 이 클래스의 객체는 복사가 불가능합니다. 다음은 예제 코드입니다.

#include "blc/console/blc_conio.h"
#include "blc/ustr/blc_ustring.h"
#include "blc/ustr/encoding/blc_cp949_t.h"
#include <iostream>
#include <cstdlib>
int main()
{
using namespace blc::console;
using namespace blc::ustr;
using namespace blc::ustr::encoding;
using namespace std;
auto u8str0 = u8"\"blc_conio.h\" 헤더와 \"blc.conio.cpp\" 파일을"s;
auto u8str1 = u8"프로젝트에 추가하면 출력 문자 인코딩이 UTF-8로 설정됩니다."s;
auto u8str2 = u8"cp949 객체를 생성 후에는 cp949 객체가 소멸할 때 까지"s;
auto u8str3 = u8"출력 문자 인코딩이 CP949가 됩니다."s;
auto u8str4 = u8"cp949 객체가 소멸된 후에는 다시 출력 문자 인코딩은 UTF-8로 복원됩니다."s;
auto utf8_str0 = ConvertString<UTF8, string>(u8str0);
auto utf8_str1 = ConvertString<UTF8, string>(u8str1);
auto utf8_str2 = ConvertString<UTF8, string>(u8str2);
auto utf8_str3 = ConvertString<UTF8, string>(u8str3);
auto utf8_str4 = ConvertString<UTF8, string>(u8str4);
auto cp949_str2 = ConvertEncoding<CP949, UTF8>(utf8_str2, false);
auto cp949_str3 = ConvertEncoding<CP949, UTF8>(utf8_str3, false);
cout << utf8_str0 << endl;
cout << utf8_str1 << endl;
cout << endl;
{
ConsoleOutputCP cp949(ConsoleOutputCP::kCP949_);
cout << cp949_str2 << endl;
cout << cp949_str3 << endl;
cout << endl;
}
cout << utf8_str4 << endl;
system("PAUSE");
return 0;
}
// ※ 실행 결과
// "blc_conio.h" 헤더와 "blc.conio.cpp" 파일을
// 프로젝트에 추가하면 출력 문자 인코딩이 UTF - 8로 설정됩니다.
//
// cp949 객체를 생성 후에는 cp949 객체가 소멸할 때 까지
// 출력 문자 인코딩이 CP949가 됩니다.
//
// cp949 객체가 소멸된 후에는 다시 출력 문자 인코딩은 UTF - 8로 복원됩니다.
// Press any key to continue . . .

예제 코드에 사용된 "blc_ustring.h" 헤더에 관련된 내용은 다음을 참고하세요.
blc/ustr/blc_ustring.h

정적 멤버 상수
- static constexpr UINT kUTF8_
  65001의 정수값을 가지며, 이 값을 ConsoleOutputCP의 생성자로 넘겨주면 콘솔 출력 문자 인코딩이 UTF-8로 설정됩니다.
- static constexpr UINT kCP949_
  949의 정수값을 가지며, 이 값을 ConsoleOutputCP의 생성자로 넘겨주면 콘솔 출력 문자 인코딩이 CP949로 설정됩니다.
멤버 함수
- inline explicit ConsoleOutputCP(UINT cp) noexcept
  생성자 입니다. 콘솔 출력 문자 인코딩 값을 하나 받습니다. 먼저 기존 콘솔 출력 문자 인코딩 설정값을 멤버 변수에 담아둔 뒤, 콘솔 출력 문자 인코딩을 넘겨받은 값(매개변수 cp의 값)으로 변경합니다.
- inline ~ConsoleOutputCP()
  소멸자 입니다. 생성자가 콘솔 출력 문자 인코딩을 변경하기 전에 멤버 변수에 담아뒀던 설정 값을 복원시킵니다.

class ConsoleWindow final

내부 선언 타입
- using PosType
  short의 별칭이며, 이 타입은 콘솔창 커서의 좌표를 표현하는데 사용됩니다.
- enum class CursorType
  콘솔창 커서의 형태를 정의하는 타입입니다. 총 네 가지의 타입이 제공됩니다.
  1. kError: 올바르지 않은 커서 타입. 이 타입은 커서의 형태를 조사하는 함수에서 잘못된 결과(CursorType이 정의하는 범위 외의 커서)를 의미하는 값으로 반환될 수 있습니다.
  2. kNoCursor: 커서의 형태가 숨겨진 타입.
  3. kSolidCursor: 커서가 현재 위치를 가득 채우는 형태인 타입.
  4. kNormalCursor: 콘솔창 커서의 기본값. 두꺼운 밑줄처럼 생긴 타입.
- class CursorTypeManager final
  콘솔창의 커서 형태 설정을 도와주는 클래스 입니다. 이 클래스의 객체는 복사가 불가능합니다. 생성자에서 커서 타입을 하나 받고, 기존의 커서 타입을 멤버 변수에 저장한 후, 넘겨받은 커서 타입으로 변경합니다. 그리고 소멸자는, 생성자가 저장한 이전 설정 값을 복원합니다. 즉, class ConsoleOutputCP와 사용법이 동일합니다(public 멤버 함수가 생성자와 소멸자 뿐인 것도 동일합니다).
- class CursorPosManager final
  콘솔창의 커서 좌표 설정을 도와주는 클래스 입니다. 이 클래스의 객체는 복사가 불가능합니다. 생성자에서 커서의 좌표값(x좌표와 y좌표)을 받고, 기존 커서 위치의 좌표값을 멤버 변수에 저장한 후, 넘겨받은 좌표로 커서를 이동시킵니다. 그리고 소멸자는 생성자가 저장한 이전 좌표로 커서를 이동시킵니다. 즉, class ConsoleOutputCP와 사용법이 동일합니다(public 멤버 함수가 생성자와 소멸자 뿐인 것도 동일합니다).
- class Space final
  콘솔창 내의 공간을 표현하는 클래스 입니다. 이 공간 안에서만 문자열을 출력하거나, 문자열을 입력 받는 것이 가능합니다. 다음은 멤버 함수 목록입니다.
  - Space(...) noexcept
    생성자 입니다. 생성자는 세 가지 오버로딩 버전이 제공됩니다.
    1. inline Space() noexcept: 기본생성자 입니다. 왼쪽 위 꼭지점 좌표가 0, 0이고 가질 수 있는 최대의 폭과 최대의 높이를 갖도록 생성됩니다.
    2. inline Space(const Space&) noexcept: 복사생성자 입니다. 기본 동작(= default)을 수행합니다. 이동 연산의 이점이 없으므로 이동 연산은 별도로 정의되지 않습니다.
    3. Space(PosType x, PosType y, PosType width, PosType height) noexcept: 콘솔창 내의 공간을 나타내는 값을 가지고 생성하는 생성자 입니다. x, y는 Space 객체가 나타내는 공간의 왼쪽 위의 꼭지점 좌표를 의미하며, width는 공간의 폭, height는 공간의 높이를 의미합니다. assert 문으로 넘겨받은 값의 유효성을 검사합니다.
  - inline Space& operator =(const Space&) & noexcept
    복사 대입 연산자 입니다. 기본 동작( = default)을 수행합니다. 이동 연산의 이점이 없으므로 이동 연산은 별도로 정의되지 않습니다.
  - inline PosType get_x() const noexcept
    this가 표현하는 공간의 왼쪽 경계의 x좌표를 반환합니다.
  - inline PosType get_y() const noexcept
    this가 표현하는 공간의 윗쪽 경계의 y좌표를 반환합니다.
  - inline PosType get_width() const noexcept
    this가 표현하는 공간의 폭을 반환합니다.
  - inline PosType get_height() const noexcept
    this가 표현하는 공간의 높이를 반환합니다.
  - bool set_x(PosType x) noexcept
    this가 표현하는 공간의 왼쪽 경계의 x좌표를 변경하고 성공 여부를 반환합니다. 넘겨준 x좌표가 유효하지 않은 값이면 변경에 실패하고 false를 반환합니다. x좌표의 변경으로 인해 this가 표현하는 폭이 콘솔창의 출력 버퍼를 초과하는 경우, 자동으로 this가 표현하는 영역의 폭이 줄어듭니다.
  - bool set_y(PosType y) noexcept
    this가 표현하는 공간의 윗쪽 경계의 y좌표를 변경하고 성공 여부를 반환합니다. 넘겨준 y좌표가 유효하지 않은 값이면 변경에 실패하고 false를 반환합니다. y좌표의 변경으로 인해 this가 표현하는 높이가 콘솔창의 출력 버퍼를 초과하는 경우, 자동으로 this가 표현하는 영역의 높이가 줄어듭니다.
  - bool set_width(PosType width) noexcept
    this가 표현하는 공간의 폭을 변경하고 성공 여부를 반환합니다. 넘겨준 폭이 유효하지 않은 값이면 변경에 실패하고 false를 반환합니다.
  - bool set_height(PosType height) noexcept
    this가 표현하는 공간의 높이를 변경하고 성공 여부를 반환합니다. 넘겨준 높이가 유효하지 않은 값이면 변경에 실패하고 false를 반환합니다.
  - void CleanArea() const
    this가 표현하는 공간 전체를 공백 문자로 채웁니다.
  - inline size_t CalcArea() const noexcept
    this가 표현하는 공간의 넓이(폭 × 높이)를 구합니다.
  멤버 함수에 사용된 PosType에 대한 설명을 보려면 이 문장을 클릭하세요.
멤버 함수
- static bool GotoXY(PosType x, PosType y) noexcept
  커서의 좌표를 x, y로 옮깁니다. 옮기는 데 성공하면 true, 실패하면 false를 반환합니다.
- static PosType WhereX() noexcept
  현재 커서의 x좌표를 조사합니다.
- static PosType WhereY() noexcept
  현재 커서의 y좌표를 조사합니다.
- static bool SetCursorType(CursorType type) noexcept
  커서의 형태를 변경합니다. 변경에 성공하면 true를, 실패하면 false를 반환합니다.
  인자의 타입 CursorType에 대한 설명을 보려면 이 문장을 클릭하세요.
- static CursorType GetCursorType() noexcept
  현재 설정되어 있는 커서의 형태를 조사합니다.
  반환 타입 CursorType에 대한 설명을 보려면 이 문장을 클릭하세요.
- static int SetTitle(
  const std::wstring& title,
  const ustr::CheckCharFuncType& check_char = ustr::CheckCharFuncType()
  )
  윈도우 콘솔창의 제목표시줄에 표시되는 문자열을 수정합니다. 문자열은 std::wstring 타입을 받습니다. check_char를 통해 올바르지 않은 문자를 처리하는 함수를 지정할 수 있습니다. CheckCharFuncType에 대한 자세한 설명은 아래의 참고자료에서 볼 수 있습니다.
  참고자료
- static int SetWindowSize(PosType width, PosType height)
  윈도우 콘솔창의 크기를 폭: width, 높이: height 로 변경합니다.
- static bool SetBufferSize(PosType width = 80, PosType height = 300) noexcept
  윈도우 콘솔창의 버퍼 크기를 폭: width, 높이: height로 변경합니다. 변경에 성공하면 true, 실패하면 false를 반환합니다.
- static PosType GetBufferWidth() noexcept
  윈도우 콘솔창의 버퍼 폭을 조사합니다.
- static PosType GetBufferHeight() noexcept
  윈도우 콘솔창의 버퍼 높이를 조사합니다.
- static size_t PrintLimitWidth(
  const std::u8string& str,
  size_t limit,
  const ustr::CheckCharFuncType& check_char = ustr::CheckCharFuncType()
  )
  표준 문자열(std::u8string) 객체 str을 현재 커서의 위치에서 제한된 폭 limit에 맞추어 출력합니다. 문자열이 길어서 지정한 폭을 초과하는 경우 초과된 부분은 출력되지 않습니다. 상황에 따라서 설정한 폭보다 최대 2칸 더 사용할 수 있으며, 문자열은 반드시 UTF-8 인코딩으로 인코딩 되어 있어야 합니다(2022/11/18 버전부터는 std::string이 아니라 std::u8string타입 객체만 받습니다). check_char를 통해 올바르지 않은 UTF-8 문자를 처리하는 함수를 지정할 수 있습니다. CheckCharFuncType에 대한 자세한 설명은 아래의 참고자료에서 볼 수 있습니다.
  참고자료
- static void PrintLimitSpace(
  const std::u8string& str,
  const Space& space,
  PosType x_begin = 0,
  char32_t hide = 0,
  const ustr::CheckCharFuncType& check_char = ustr::CheckCharFuncType()
  )
  표준 문자열(std::u8string) 객체 str을 space로 표현된 공간 내부로 출력합니다. 문자열이 길어서 지정한 공간을 초과하는 경우 초과된 부분은 출력되지 않습니다. 상황에 따라서 설정한 폭보다 최대 2칸 더 사용할 수 있으며, 문자열은 반드시 UTF-8 인코딩으로 인코딩 되어 있어야 합니다(2022/11/18 버전부터는 std::string이 아니라 std::u8string타입 객체만 받습니다). space로 표현된 공간의 첫 줄은, x_begin 칸 만큼의 공백 다음부터 문자열 str이 출력됩니다. hide가 널 문자가 아닌 경우, str의 모든 문자가 hide로 지정한 문자로 바뀌어 출력됩니다(마치 비밀번호 입력칸 처럼). check_char를 통해 올바르지 않은 UTF-8 문자를 처리하는 함수를 지정할 수 있습니다. CheckCharFuncType에 대한 자세한 설명은 아래의 참고자료에서 볼 수 있습니다.
  참고자료
- static bool ModifyStr(
  std::u8string& str,
  const Space& space,
  std::function<bool(char32_t)> check_validation = nullptr,
  char32_t hide = 0,
  CursorType cursor_type = CursorType::kNormalCursor,
  const ustr::CheckCharFuncType& check_char = ustr::CheckCharFuncType()
  )
  표준 문자열(std::u8string) 객체 str의 내용을 수정합니다(2022/11/18 버전부터는 std::string이 아니라 std::u8string타입 객체만 받습니다). 문자열을 수정할 수 있는 공간은 space가 표현하는 공간으로 한정되며(상황에 따라 설정한 폭보다 최대 2칸 더 사용할 수 있음), check_validation 함수 객체(2022/11/18 버전부터는 check_validation 함수 객체는 uint32_t 대신 char32_t 타입의 변수를 받습니다)가 false를 반환하는 문자는 입력이 거부됩니다(입력 시 무반응). hide가 널 문자가 아닌 경우, 입력된 모든 문자는 hide가 갖는 문자로 출력됩니다(마치 비밀번호 입력칸 처럼). cursor_type을 통해 입력 도중 표시될 커서의 형태를 지정할 수 있습니다. 입력 완료 후, [Enter]키를 누른 경우 true를 반환하며 수정한 내용을 반영합니다. 반면 [ESC]키를 누르면, false를 반환하며 수정된 내용을 반영하지 않습니다(함수 호출 시 넘겨준 str 객체의 내용을 그대로 유지). 또한, check_char를 통해 올바르지 않은 UTF-8 문자를 처리하는 함수를 지정할 수 있습니다(ModifyStr 함수의 경우에는 InvalidCharCounter를 사용하여 카운트한 비정상 문자의 개수값이 올바르지 않습니다). CheckCharFuncType에 대한 자세한 설명은 아래의 참고자료에서 볼 수 있습니다.
  참고자료

전역 함수

int (*SetCharacterWidthFunc(int(*f)(char32_t)) noexcept)(char32_t)
특정한 문자(인수로 전달된 유니코드) 하나가 전각문자(반환값 2) 또는 반각문자(반환값 1)임을 식별하는 함수를 설정하는 함수입니다. 새로운 함수(포인터)를 매개변수 f를 통해 넘겨주면, 기존에 설정되어 있더 함수(포인터)를 반환하고 f를 통해 넘겨받은 함수를 현재 사용할 함수로 설정합니다. 새로운 함수(포인터) 대신 nullptr을 넘겨줄 경우, 현재 설정된 함수(포인터)를 변경 없이 그대로 반환합니다. 현재 설정된 함수의 기본값은 http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c 에서 가져온 mk_wcwidth(char32_t) 입니다. 한중일 문자 및 특수문자를 사용하는 경우 mk_wcwidth_cjk(char32_t) 함수를 사용하는 것이 바람직합니다.
inline int GetCharacterWidth(char32_t unicode) noexcept
매개변수 unicode를 통해 넘겨받은 문자가 전각문자(반환값 2) 또는 반각문자(반환값 1)임을 식별하는 함수입니다. 내부적으로 SetCharacterWidthFunc(nullptr)(unicode);를 호출합니다. 따라서, SetCharacterWidthFunc 함수를 통해 이 함수의 동작을 변경할 수 있습니다.
size_t GetStringLimitWidthLen(
const std::u8string& str,
size_t limit,
size_t* width,
const ustr::CheckCharFuncType& check_char = ustr::CheckCharFuncType()
)
폭이 limit로 제한된 공간을 벗어나지 않고 출력할 수 있는, str의 부분 문자열 end 인덱스를 계산합니다. width가 nullptr이 아닌 경우, 실제 출력된 문자열이 차지하는 폭을 width가 가리키는 정수형(size_t) 변수에 담아줍니다. 문자열의 인코딩은 UTF-8 이어야 하며(2022/11/18 버전부터는 std::string이 아니라 std::u8string타입 객체만 받습니다), 설정한 폭보다 최대 1칸 더 사용할 수 있습니다. check_char를 통해 올바르지 않은 UTF-8 문자를 처리하는 함수를 지정할 수 있습니다. CheckCharFuncType에 대한 자세한 설명은 아래의 참고자료에서 볼 수 있습니다.
참고자료

blc/console/blc_conio.h - C++ 윈도우 콘솔 라이브러리

[2022/11/18 및 이후 버전]