Namefully class

A helper for organizing person names in a particular order, way, or shape.

Though namefully is easy to use, it does not magically guess which part of the name is what (prefix, suffix, first, last, or middle names). It relies actually on how the name parts are indicated (i.e., their roles) so that it can perform internally certain operations and saves us some extra calculations/processing. In addition, Namefully can be created using distinct raw data shapes. This is intended to give some flexibility to the developer so that he or she is not bound to a particular data format. By following closely the API reference to know how to harness its usability, this utility aims to save time in formatting names.

namefully also works like a trapdoor. Once a raw data is provided and validated, a developer can only access in a vast amount of, yet effective ways the name info. No editing is possible. If the name is mistaken, a new instance of Namefully must be created. Remember, this utility's primary objective is to help to handle a person name.

Note that the name standards used for the current version of this library are as follows: (prefix) firstName (middleName) lastName (suffix) The opening ( and closing ) symbols mean that these parts are optional. In other words, the most basic and typical case is a name that looks like this: John Smith, where John is the first name and Smith, the last name.

See https://departments.weber.edu/qsupport&training/Data_Standards/Name.htm for more info on name standards.

IMPORTANT: Keep in mind that the order of appearance matters and can be altered through configured parameters, which we will be seeing later on. By default, the order of appearance is as shown above and will be used as a basis for future examples and use cases.

Once imported, all that is required to do is to create an instance of Namefully and the rest will follow.

Some terminologies used across the library are:

namon: 1 piece of name (e.g., first name)
nama: 2+ pieces of name (e.g., first name + last name)

Happy name handling 😊!

Constructors

Namefully(String names, {Config? config}): Creates a name with distinguishable parts from a raw string content.
Namefully.from(FullName fullName): Creates a name from a FullName.
Namefully.fromJson(Map<String, String> names, {Config? config}): Creates a name from a json-like distinguishable name parts.
Namefully.fromList(List<String> names, {Config? config}): Creates a name from a list of distinguishable parts.
Namefully.fromParser(Parser parser, {Config? config}): Creates a name from a customized Parser.
Namefully.of(List<Name> names, {Config? config}): Creates a name from a list of Names.
Namefully.only({String? prefix, required String firstName, List<String>? middleName, required String lastName, String? suffix, Config? config}): Creates a name from specific name parts.

Properties

birth → String: The birth name.
no setter
config → Config: The current configuration.
no setter
derivative → NameDerivative: Starts name derivation.
no setter
first → String: The first name.
no setter
full → String: The entire name set.
no setter
hashCode → int: The hash code for this object.
no setterinherited
hasMiddle → bool: Returns true if any middleName's been set.
no setter
last → String: The last name.
no setter
length → int: The number of characters of the birthName, including spaces.
no setter
long → String: The longest version of a person name.
no setter
middle → String?: The first middle name if any.
no setter
parts → Iterable<Name>: Returns an Iterable of existing Names.
no setter
prefix → String?: The prefix part.
no setter
public → String: The first name combined with the last name's initial.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
salutation → String: A formal salutation.
no setter
short → String: The shortest version of a person name.
no setter
suffix → String?: The suffix part.
no setter

Methods

birthName([NameOrder? orderedBy]) → String: Gets the birth name ordered as configured, no prefix or suffix.
camel() → String: Transforms a birthName into camelCase.
dot() → String: Transforms a birthName into dot.case.
equal(Namefully other) → bool: Whether this name is equal to another one from a raw-string perspective.
firstName({bool withMore = true}) → String: Gets the first name part of the FullName.
flatten({int limit = 20, Flat by = Flat.middleName, bool withPeriod = true, bool recursive = false, bool withMore = false, Surname? surname}) → String: Flattens a long name using the name types as variants.
flip() → void: Flips definitely the name order from the preset/current config.
format(String pattern) → String: Formats the full name as desired.
fullName([NameOrder? orderedBy]) → String: Gets the full name ordered as configured.
has(Namon namon) → bool: Confirms that a name part has been set.
hyphen() → String: Transforms a birthName into hyphen-case (or kebab-case).
initials({NameOrder? orderedBy, bool withMid = false, NameType only = NameType.birthName}) → List<String>: Gets the initials of the FullName.
join([String separator = '']) → String: Joins the name parts of a birthName using a separator.
lastName({Surname? format}) → String: Gets the last name part of the FullName.
lower() → String: Transforms a birthName into lowercase.
middleName() → List<String>: Gets the middle Name part of the FullName.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
pascal() → String: Transforms a birthName into PascalCase.
shorten({NameOrder? orderedBy}) → String: Shortens a complex full name to a simple typical name, a combination of first and last name.
snake() → String: Transforms a birthName into snake_case.
split([RegExp? separator]) → List<String>: Splits a birthName using a separator.
toggle() → String: Transforms a birthName into ToGgLe CaSe.
toMap() → Map<String, String?>: Gets a Map or json-like representation of the full name.
toString() → String: Returns the full name as set.
override
upper() → String: Transforms a birthName into UPPERCASE.
zip({Flat by = Flat.midLast, bool withPeriod = true}) → String: Zips or compacts a name using different forms of variants.

Operators

operator ==(Object other) → bool: The equality operator.
inherited
operator [](Namon namon) → Object?: Fetches the raw form of a namon.

Static Methods

parse(String text) → Future<Namefully>: Constructs a Namefully instance from a text.
tryParse(String text) → Namefully?: Constructs a Namefully instance from a text.