:toc: left
:sectnums:

= alignment

image:https://travis-ci.org/jiro4989/alignment.svg?branch=master["Build Status", link="https://travis-ci.org/jiro4989/alignment"]

alignment is a library to align strings.
The procedures consider multibyte strings (ex: あいうえお, 漢字).

== Overview

The goal of this library is resolving texts out of alignment.

A text will be out of alignment in terminal if you are padding with `strutils.align`.
This problem is occured by containing multibyte string.

See below.

[source,nim]
----
doAssert "a".len == 1
doAssert "あ".len == 3
----

This example shows that length of "a" is 1 and length of "あ" is 3.
`len` procedure returns a byte length, not count of characters.
Similarly, `strutils.alignLeft` is padding by byte length.

See below a example that a text is out of alignment.

[source,nim]
----
import strutils

doAssert "a".alignLeft(5) == "a    "
doAssert "あ".alignLeft(5) == "あ  "
doAssert "a".alignLeft(5).len == 5
doAssert "あ".alignLeft(5).len == 5
----

[source,nim]
----
import unicode

doAssert align("A", 4) == "   A"
doAssert align("あ", 4) == "   あ"
----

A byte length equals, but texts look width doesn't equal.
This will be a problem when draw ruled lines on the terminal.

This library is resolving one.
About usage of library, see usage section.

== Development

nim -v

  Nim Compiler Version 0.19.6 [Linux: amd64]
  Compiled at 2019-05-10
  Copyright (c) 2006-2018 by Andreas Rumpf

  git hash: c6f601d48ec81e0d6e052ba0d19a195b55cc68f2
  active boot switches: -d:release

nimble -v

  nimble v0.9.0 compiled at 2018-10-27 18:10:03
  git hash: couldn't determine git hash


== Usage

[source,nim]
----
import alignment

let s = @["abcde", "あいうえお", "ABC", "あ", "123456789"]
let aligned = s.alignCenter
doAssert aligned[0] == "  abcde   "
doAssert aligned[1] == "あいうえお"
doAssert aligned[2] == "   ABC    "
doAssert aligned[3] == "    あ    "
doAssert aligned[4] == "123456789 "

for line in aligned:
  echo "| ", line, " |"

## Output:
## |   abcde    |
## | あいうえお |
## |    ABC     |
## |     あ     |
## | 123456789  |
----

== Install

[source,bash]
nimble install alignment

== License

MIT

== Document

* https://jiro4989.github.io/alignment/alignment.html